Pocket Wormhole

A native Android port of Project Wormhole (xftl), the clean-room reimplementation of the FTL: Faster Than Light engine by Campbell Suter (ZNix) and contributors. The engine is re-implemented from scratch and loads all game assets directly from your own ftl.dat — the exact file that ships with your Steam/GOG copy of FTL.

No FTL assets are included. You must own the game. FTL: Faster Than Light is © Subset Games; this project is not affiliated with or endorsed by them.

<p align="center"> <img src="docs/images/screenshot-beacon.jpg" width="90%" alt="FTL running on Android — the Kestrel at a beacon, FTL drive ready to jump" /> <br /><br /> <img src="docs/images/screenshot-combat.jpg" width="90%" alt="Combat against a pirate scout in an asteroid field, touch power UI at the bottom" /> </p>

Installing

1. Grab the latest APK from GitHub Releases (or build it — see below), copy it to your phone and install it (allow "install from unknown sources").
2. Copy ftl.dat from your PC's FTL install (FTL Faster Than Light\ftl.dat, ~280 MB) to the phone — anywhere you like.
3. Launch the app. On first run it asks you to pick ftl.dat with the system file picker. It copies the file into the app's private storage (one time, needs ~280 MB free) and then starts.

Controls

Action	Result
Tap	Left click
Drag	Mouse drag
Long-press (~0.5 s)	Right click (move crew, power down systems, cancel)
Two-finger drag ↕	Scroll wheel (ship lists, options)
Back button	Escape (opens the pause/escape menu)
Physical keyboard	Space/Enter/arrows/Tab/Escape/letters reach the game
Tap a crewmember	Selects them and auto-pauses in room-selection mode — tap a room to send them there, tap empty space to cancel
Tap a system icon	Opens a power panel with big +/− buttons (drones get on/off toggles); the game auto-pauses
Tap a weapon to fire	Auto-pauses in targeting mode — your ship shrinks out of the way and the enemy ship goes full-size; tap rooms to target (drag for beams), long-press to cancel
In the store, maps & upgrades	First tap on an item just inspects it (highlights + shows its description); tap the same item again to buy/sell/jump/confirm. Tapping a different item moves the highlight, tapping empty space clears it. Event choices and the pause menu stay single-tap

Saves & data

Everything lives in the app's internal private storage (Context.filesDir, /data/data/com.pocketwormhole.android/files/), which file managers can't open without root:

• ftl.dat — the copied game data
• ProjectWormhole/save-profile.xml — profile (unlocks, achievements, options)
• ProjectWormhole/run-save.xml — your in-progress run
• ProjectWormhole/ftl-path.txt — pointer to the copied ftl.dat
• ProjectWormhole/mods/ — mods, loaded like on desktop (with an order.txt listing them); since the folder is private, there's currently no way to put mods there on an unrooted phone
• log-session-*.txt — session logs (useful for bug reports); these are also written to /Android/data/com.pocketwormhole.android/files/, which you can reach over USB or with a file manager on most Android versions

Save + Quit (escape menu) saves your run; the next time you open the app the run resumes automatically, exactly where you left it. Starting a new run or dying discards the saved one, as in vanilla FTL.

Moving runs between devices (EXPORT / IMPORT SAVE)

The pause menu can EXPORT your run as a vanilla-compatible continue.sav (loadable by vanilla FTL 1.6.14+ with AE, or another Pocket Wormhole install) and IMPORT such a file back.

⚠️ READ THIS BEFORE USING — these are hard limitations, not fine print:

• Move runs at the start of a sector. The EXPORT button only exists while you stand on the newly arrived sector's entry beacon, because that is the one state that transfers faithfully. There is no way to pin a mid-sector position across engines.
• The map layout reshuffles on every transfer. Ship, crew, weapons, scrap, sector number, visited route, stores, quests and fleet progress all carry over — but the beacon geometry is re-rolled by whichever engine imports the save, so everything sits in different places.
• In-flight state is dropped: an active battle (enemy ship and projectiles), open event dialogs, hacking effects and crew waiting in the clonebay do not survive a transfer.
• Exports from v0.2.4 or older are broken and will hang vanilla FTL on load. Re-export the run with v0.2.5 or newer.
• Lifetime profile statistics are zeroed in exports (vanilla keeps its own totals in its prof.sav anyway).
• run-save.xml — the engine-native autosave — is not a transfer format. It only works between Pocket Wormhole installs.

In short: jump to a new sector, EXPORT, move the file, IMPORT (or drop it next to vanilla's saves), and continue there.

Known limitations

• XSLT-based mod patches are unsupported (Saxon doesn't run on Android); vanilla data and most Slipstream mods work fine.
• Requires Android 8.0+ (API 26) and a GLES 3.0 GPU (everything from ~2014 on).
• The hangar ship editor UI is mouse-centric; it works with touch but is fiddly.
• Hover-dependent desktop UI (tooltips) only shows while you're touching — except in the store, maps and upgrades, where a tap keeps the info up (see tap-to-confirm above).

Building from source

Prerequisites: JDK 17, Android SDK (platform 34, build-tools 34.0.0).

./gradlew assembleDebug        # Linux/macOS
gradlew.bat assembleDebug      # Windows

The APK lands in app/build/outputs/apk/debug/.

local.properties is created by Android Studio, or write it yourself: sdk.dir=<path to your Android SDK>.

How it works

The engine (xyz.znix.xftl), Slipstream (net.vhati.*) and patched jorbis/PNGDecoder sources are compiled into the app; the desktop LWJGL layer is replaced by small Android-backed shims:

• org.lwjgl.opengl.* — GL11..GL30 → android.opengl.GLES30 (the engine's renderer is GL 3.0-core, mapping 1:1 onto GLES 3); each frame is drawn into an offscreen framebuffer with a guaranteed depth+stencil attachment
• org.lwjgl.openal.* — a software OpenAL implementation (SoftAL) mixing to an AudioTrack, including buffer-queue streaming for music and AL_SEC_OFFSET seeking
• org.lwjgl.glfw.GLFW — key constants; windowing is replaced by AndroidGameContainer (GLSurfaceView) and AndroidInput (touch → mouse, with a one-frame click deferral so the engine's draw-time hover state is correct for instant taps)
• org.newdawn.slick.* — the Slick2D classes the engine uses (decoders, listeners, geometry), with Android-backed implementations

Patches to the upstream engine are kept minimal; see the source comments and git history.

Credits & licences

See NOTICE.md for the full list. In short:

• Project Wormhole — Campbell Suter (ZNix) and contributors (GPL-2.0+)
• Slipstream Mod Manager — Vhati and contributors (GPL-2.0)
• JOrbis/JOgg — JCraft (LGPL-2.1)
• PNGDecoder — Matthias Mann (BSD-3-clause)
• FTL: Faster Than Light — © Subset Games. This project ships none of its assets; load them from your own copy.

Licence

This project is free software: you may redistribute and/or modify it under the terms of the GNU General Public License v2.0, or (at your option) any later version.