A modernization of XPilot NG 4.7.3, the multiplayer space war game whose last release was in 2010. The goal is a codebase that builds and runs cleanly on current Linux while staying compatible with thirty years of maps, recordings and the original network protocol.
This is a fork of the archival mirror kekyo/xpilot-ng. Upstream has seen no
development since 2010 and is kept here only as a provenance link.
The original project README is preserved as
README— it carries the authors' names and copyright, and nothing here replaces their work.
Ready-to-run builds for all four targets are on the Releases page.
Use r7 or later. Earlier releases let a server overwrite the client's stack through the texture package its map names, just by being joined. See Bugs found and fixed.
| Platform | Installer | Or unpack it yourself |
|---|---|---|
| Windows (x86-64) | *-setup-x86_64.exe |
*-windows-x86_64.zip |
| macOS (Apple Silicon) | *-macos-arm64.dmg |
*-macos-arm64.tar.gz |
| macOS (Intel) | *-macos-x86_64.dmg |
*-macos-x86_64.tar.gz |
| Linux (Debian/Ubuntu, x86-64) | xpilot-ng_*_amd64.deb |
— |
The Windows installer adds Start Menu shortcuts and an entry in Add/Remove
Programs. The .dmg holds an XPilot NG.app to drag to Applications. On
Linux: sudo apt install ./xpilot-ng_*_amd64.deb, which puts the binaries in
/usr/games — on the default PATH, so xpilot-ng-sdl just works.
Releases also carry *-ppa-source.tar.gz: the .dsc, .orig.tar.gz and
.debian.tar.xz that a Launchpad PPA takes. They are bundled because GitHub
rewrites ~ in an asset name, and the .dsc names its files exactly.
BUILDING.md has the upload steps.
The zip and both tarballs are self-contained — every library ships alongside
the binaries, and the game finds its data wherever you put it, so there is
nothing to install first. On macOS use the .tar.gz as it is; repacking it as
a zip drops the executable bit.
Each release names what was actually verified and what was not. If you would
rather build from source, see BUILDING.md.
| Phase | What | Status |
|---|---|---|
| 0 | Builds at all on modern Linux | Done |
| 1 | autotools → CMake | Done — autotools removed |
| 2 | SDL 1.2 → SDL2 | Done — Wayland unverified |
| 3 | Audio: OpenAL/freealut → SDL2_mixer | Done — not yet judged by ear |
| 4 | Quality of life | Done — keybind defaults left alone deliberately |
| 4b | Graphics modernization | Done to the stretch line |
| 5 | Network & hosting | Done — including a self-hostable metaserver |
| 6a | Python bot SDK | Done — both packet streams decoded |
| 6b | Gymnasium RL environment | Done — accelerated and parallel |
| 6c | Learned agents | PPO trains and benchmarks; ahead of random on the server's own score |
| — | Windows and macOS | Done — server and SDL client, verified running in CI |
| — | Installers | Done — Windows setup and macOS .dmg, both run from an installed copy |
| — | Debian packaging | Done — lintian clean, built and installed in CI; PPA source published |
Full detail, including everything deliberately not done and why, is in
ROADMAP.md.
Linux is the reference platform and builds everything. Windows and macOS build the server and the SDL client; the X11 client, replay tool and map editor are Xlib programs and are not built there.
| Linux | Windows | macOS | |
|---|---|---|---|
| server | ✅ | ✅ | ✅ |
| SDL client | ✅ | ✅ | ✅ |
| X11 client, replay, map editor | ✅ | — | — |
Both are built by CI on real windows-latest and macos-latest runners, and
each job starts the server and checks it is listening. That check was not
ceremony: the Windows server built and linked perfectly while being incapable
of running for more than a few seconds, and only the runtime check caught it.
Every CI run attaches the same builds as artifacts, and releases publish them
as the downloads above. Both are made self-contained: the Windows one carries its mingw DLLs, the macOS one
has its Homebrew dylibs bundled and its load commands rewritten to
@executable_path. Each is checked for completeness before upload, because
the first versions of both shipped broken — the Windows build without
libexpat-1.dll, the macOS one pointing at /opt/homebrew — while every CI
job reported success.
That kind of check has a blind spot worth knowing about. Homebrew's sdl2 is
sdl2-compat, which loads SDL3 with dlopen rather than linking it, so no load
command names it: dylibbundler did not bundle it, the "nothing points at
Homebrew" check did not miss it, and a full Mach-O scan of the published
.dmg called the app self-contained. It was not — without SDL3 the client
raised a modal alert from inside dyld and hung before main(). Nothing static
catches a dlopen; only running the thing did. CI now installs the app to
/Applications and requires it to join a game.
macOS is published for both architectures — xpilot-ng-macos-arm64 for
Apple Silicon and xpilot-ng-macos-x86_64 for Intel. Separate builds rather
than one universal binary, because Homebrew installs for the host
architecture only.
sudo apt install build-essential cmake libx11-dev libsm-dev libice-dev \
libgl-dev libglu1-mesa-dev libsdl2-dev libsdl2-ttf-dev libsdl2-image-dev \
libexpat1-dev zlib1g-dev
cmake -B build -S .
cmake --build build -j"$(nproc)"
# a server with four robots
./build/bin/xpilot-ng-server -map lib/maps/blood-music.xp2 \
-maxRobots 4 -minRobots 4 -port 15345 -noQuit -idleRun &
# and a client
./build/bin/xpilot-ng-sdl -join -name you -port 15345 localhost-noQuit -idleRun are not optional decoration: without them the server exits
the moment the last human disconnects. BUILDING.md covers that
and the other traps.
62 commits since the 4.7.3 import; 185 files, +17,600 / −52,800 lines. The deletions are most of the story — a lot of this was removing things rather than adding them.
Build. autotools replaced by CMake and then deleted outright: configure,
configure.ac, 27 Makefile.am, the aux scripts. Install output was diffed
against the old build to prove parity at 99 files. A .deb builds via CPack.
GitHub Actions builds, installs, and smoke-tests the server, both clients, the
sound path and a Python bot on every push.
Client. Ported to SDL2 and verified by A/B screenshot against the pre-port
build — identical rendering, no new warnings. scrap.c, 651 lines of raw-X11
clipboard shim, deleted in favour of SDL2's clipboard.
Interface. Smooth zoom on + and - (rebindable, animated, tunable via
zoomSmoothing). 4.7.3 had two fixed zoom settings and a key to swap
between them, but shipped that key unbound — so zoom could not be changed
mid-game at all. A uiScale option that auto-detects from display DPI, because
SDL2 on X11 reports a scale of 1.0 no matter how dense the panel is — so the
HiDPI problem people actually have is a font-scaling problem, not a drawable
one. XDG config directories with migration. Gamepad support. In-client key
rebinding through console commands.
Graphics. Additive glow, a parallax starfield, and particle trails — each
individually switchable at runtime, with a classicRender switch that restores
the original look. Classic mode was measured, not asserted: it differs from the
pre-effects build by fewer pixels than that build differs from itself between
runs.
Audio. OpenAL and the long-dead freealut replaced by SDL2_mixer. CI asserts that nothing links freealut any more.
Network. The protocol is documented and audited for NAT. The dead
metaservers have a replacement — dependency-free, and
speaking the original protocol so unmodified clients and servers can use it.
-metaServerHost on both ends means you can actually point at one; the
addresses used to be compiled in.
Bots. ai/ is a dependency-free Python client that speaks
the original protocol, so bots play against unmodified servers seeing only what
a human's client sees. Both of the game's packet streams are decoded: the
frame stream into world state — own ship, other ships, shots, items — and the
reliable sub-stream into players, messages and scores. The second one matters
more than it sounds, because nothing about a game's outcome is on the frame
stream at all; decoding it is what made kills and scores measurable.
On top of that sits a Gymnasium environment that runs faster than realtime and in parallel, PPO curriculum training, and a benchmark that compares any policy against acting at random — including on the server's own score, which is computed by the game and owes nothing to the reward function.
Several of these had been in the code for decades:
- Undefined behaviour in the packet parser, found by fuzzing.
charis signed, soptr[j++] << 24shifts a negative value for any byte ≥ 0x80 — reachable pre-authentication. The fix was verified not to change wire decoding at all. (tests/) - The reliable sub-stream hides inside frame packets. Before play it arrives as datagrams of its own; once frames start the server appends it to the end of a frame update, so a client checking only the first byte goes deaf exactly when the game begins. Nothing errors — scores and kills simply never arrive, and the server quietly drops the connection with a retransmit timeout that reads like a network fault.
- A client that never sends
PKT_TURNSPEEDhas a ship that cannot turn.MIN_PLAYER_TURNSPEEDis 0.0 and players start at the minimum, so the turn keys are accepted, acknowledged, and do nothing — no error anywhere. Engine power behaves the same way, sitting at 5.0 instead of 55.0. Easy to mistake for bad flying. - The Windows server could never have run, in any version of this tree. Three faults in one function: its timer installed a callback that exists nowhere in the source, the tick consumer never invoked the frame handler, and the scheduler had no loop — one pass and it fell through to shutdown. It builds, links, loads the map, prints "Server runs at 50 frames per second", and exits. Nothing but running it would have found this.
- A joined ship ignores the controls for ~5 seconds. Keyboard packets are accepted and acknowledged in every frame the whole time; the ship simply does not move. Re-sending does not help — the server skips any key update whose change counter it has already seen, so only a real press or release counts.
- The world wraps, and the protocol never says so. Most maps set
edgeWrap="yes", so subtracting two positions returns the long way round once they are more than half a map apart. Measured on a live game, that made 40% of "which opponent is nearest" answers wrong and put the average bearing out by 81°. The map size needed to correct it exists only in the setup blob at the head of the reliable stream. - Shots are not sent as coordinates.
PKT_FASTSHOT's type byte is an index into a grid of 256-pixel tiles over the player's view, not a colour. Read it as a colour and every shot in the game piles into one corner of the map. - Dying does not stop the frame stream. The C client's own comment
suggests a frame without
PKT_SELFmeans the player is dead, so that is where death detection naturally goes. Measured against a live server, an idle bot died ten times in ninety seconds without a single frame missing itsPKT_SELF. Together with the bug above, this is why "the robots never kill the bot" was believed for so long. They kill it constantly; nobody was listening. PKT_PLAYERis mis-sized by the obvious reading of the protocol. It carries two ship-shape strings, not one, and the reliable stream is undelimited — so reading one string turns everything after it into garbage. Both findings are indocs/protocol.md.- Maps loaded without their textures, everywhere. A map names a texture
package for the client to download, and the maps in circulation point at an
http://mirror that now redirects tohttps://. The client's own downloader could do neither, so those maps came up with bare walls on every platform. It now uses libcurl — restricted tohttpandhttps, redirects included, with a size cap, because the URL is chosen by the server. And an installed Windows copy could never download them at all: with nowhere writable in Program Files it fell back toHOME, which Windows does not set. It now uses%LOCALAPPDATA%. - Map textures smeared instead of tiling. Once r7 made texture downloads work, walls drew as a single pixel column streaked along their length and turrets vanished. Every uploaded image had been clamped to its edge — right for a sprite, wrong for a texture that fills a wall by repeating, and invisible for as long as the textures never arrived. Textures now repeat, and a tile that is not a power of two is scaled to fill its slot so the repeat holds no padding.
- A server could overwrite the client's stack. The package's file list was
parsed with an unbounded
sscanf("%s")into a 256-byte buffer, so a package with a long enough name — from any server a player joined — overflowed it. The same extractor accepted..\traversal on Windows and would unpack a decompression bomb without limit. Proven with AddressSanitizer against the old code before being rewritten;tests/mapdata/now runs every one of those cases against a hostile server in CI. - A script that could not run was installed for years.
mapconvert.pyis Python 2 — 74printstatements, and it does not parse under Python 3 — and its shebang asks for/usr/bin/python, which a stock Ubuntu does not have. Autotools shipped it and the CMake rules copied that faithfully. Found by Lintian complaining about the interpreter, which turned out to be the least of it. - The
.debinstalled a game that could not find its own files. It was built with the default/usr/localprefix, baking that path into the binaries, while CPack laid the package out under/usr. It looked fine on any machine that had also beencmake --installed by hand, because the binaries then read that copy — which is exactly how the first two releases were "verified". - An installed copy found no data unless it was started from its own
folder. Windows and macOS compile a relative data path, so a Start Menu
shortcut, a Finder launch or a shell anywhere else came up with no maps,
textures, fonts or sounds. The macOS archives had it worse: they pointed at
/usr/local/share/xpilot-ng/while shipping their data beside the binary. Startup now anchors the working directory to the executable. - The macOS app could never start. Homebrew's
sdl2is sdl2-compat, a shim that loads SDL3 withdlopen— so no load command names SDL3,dylibbundlernever bundled it, and the shim's library initialiser raised a modal alert from inside dyld, waiting forever for a click. Silent, because the error went to a dialog rather than stderr. Three separate self-containment checks passed the bundle; none of them can see adlopen. longjmpout of the system resolver. Both name lookups boundedgethostbyname()withalarm()and jumped out of the signal handler, unwinding through the resolver while it held its own locks. Undefined behaviour that needs a machine with slow DNS to show itself — it crashed the macOS server, and had been in the tree for years.- The SDL client drew nothing where a wall texture was missing. Maps flag a
polygon style as textured and then name a bitmap they never declare —
blood-music.xp2, shipped with the game, does it on all 32 of its walls. The X11 client falls back to the style's colour; the SDL client left texturing enabled with nothing bound, so walls filled black and you flew into a map that looked empty. The radar draws walls by another path and kept showing them, which made it look like a collision bug rather than a drawing one. - A map download shortened the texture search path.
strtokwas run directly over the path list every later texture lookup walks, so the first call truncated it to one entry — dropping the directory the map's own bitmaps had just been extracted into. - Sound was never built on Linux.
XPILOT_SOUNDdefaulted off and only the Windows and macOS CI jobs turned it on, so the packaged Linux build had neither the audio code nor the samples — their install rule is gated on the same option. The option now follows the library: sound is on when SDL2_mixer is installed. Confirmed by recording the audio device, not by ear: 41% of full scale while firing, against a silent baseline. - The Windows client killed its own connection. It quit about a second
after entering a game. Winsock reports through
WSAGetLastError(), noterrno, and its codes are different numbers: the code storedWSAEWOULDBLOCK(10035) intoerrnoand compared it againstEWOULDBLOCK(140) andEAGAIN(11), so a non-blocking read with no data yet could never be recognised as such. Every idle poll looked like a dead socket. - Windows builds could not report their own errors. Every
error(),warn()andfatal()funnelled into a function whose MessageBox was commented out and whose only other output expands to nothing outside debug builds. A Windows client could quit for a carefully worded reason and leave an empty log. Console_printcrashed on any format argument, passing ava_listto a variadic function. Every existing caller passed a bare string, so it had never fired.strncatbounded by the source length in three places, making it exactly equivalent tostrcat. One overflows a 128-byte buffer with the game's own prompt.HAVE_SDLIMAGEwas misspelled, soIMG_Loadwas never compiled in and console fonts were silently BMP-only.- A startup race where the client built its OpenGL context inside the server's login timeout — invisible on hardware, fatal under software rendering.
ROADMAP.md |
plan, status, and what is deliberately undone |
BUILDING.md |
dependencies, options, and the traps |
docs/protocol.md |
wire protocol and NAT audit |
docs/build-audit.md |
what autotools did, for the CMake port |
docs/sdl2-port-audit.md |
the SDL 1.2 → SDL2 surface |
docs/warnings-debt.md |
the 52 remaining warnings, ranked |
ai/README.md |
the Python bot SDK |
metaserver/README.md |
the self-hosted metaserver |
packaging/ |
systemd units and Dockerfile |
Stated plainly, because they decide what is safe to rely on:
- Nobody has run any of this on a Mac they own. CI does start the macOS app
from
/Applicationson both architectures and require it to join a game, so the path is exercised on real hardware — but no person has double-clicked it in the Finder. - The Windows client has only ever been run under Wine. Everything works
there — the installer, a Start Menu launch from outside the install folder,
joining a game, sound, and a clean uninstall. On real Windows, CI starts the
server and runs the client's map data download — over HTTPS, from an
unpacked copy, with no
HOME— but has never started the client itself. - The PPA has not been uploaded to. The source package is built and checked on every CI run, but publishing it needs a Launchpad account and key, so nobody has yet seen Launchpad build it.
- Wayland is untested. The default game loop needs an X11 video driver and
says so; native Wayland needs
-DXPILOT_SDL_GAMELOOP=ONverified. - Audio has never been listened to. It demonstrably reaches the device on both the Linux and Windows builds — measured at about 41% of full scale while firing, against a silent baseline recorded with the client stopped — but whether it sounds right is unverified.
- Positional audio is not implementable as the roadmap describes. The audio packet carries a sound index and a volume, and no position.
- The 144 fps target is unmeasured, because the reference machine was under heavy unrelated load whenever it was tried.
- Bots perceive, but the example bot is not good. Frame decoding is
complete; the
hunterexample aims better than chance and no more. - Death detection has never fired in a real game. It works on synthetic frames, but the built-in robots did not kill the bot in thousands of steps and self-destruct did not either, so the live path is unproven.
GPLv2, as the original. See COPYING.