ExPilot

A multiplayer XPilot in the terminal, played over ssh. Classic block maps, newtonian ships, thrust and shields and fuel, cannons, wormholes, robots, items — mines, missiles, lasers, cloaks, ECM, transporters, tractor beams, deflectors, phasing, hyperjumps and the rest — teams, targets, capture the flag, races, a radar, and seven pieces of music written in Strudel that follow the fight — on cauldron_2d, drawn by drafter, heard through tuning_fork.

A tour of the game, with its music, is on YouTube.

The engine, the arenas, the robots' runner, the ledger, the beacon, the remote calls, the load test, the ssh and web servers and every client's screens are Cauldron's (Cauldron: cauldron_2d, cauldron_2d_drafter, cauldron_2d_net, cauldron_2d_wx, linocut); ExPilot is the rules, the maps, the art, the sound, the robots' judgement and its own pages.

mix ex_pilot.play                       # this terminal, this machine's speaker
mix ex_pilot.serve --port 2222          # over ssh and in the browser, one process
mix ex_pilot.maps                       # fetch the 132 classic maps into priv/maps

Every map under priv/maps is an arena in the lobby — Dogfight is bundled, the rest come from mix ex_pilot.maps — with its size and robot count beside its name (an arena with none is practice); robots never take every base, one is always left for you. A ship sits on its base facing away from the wall the base is on — up off a floor, down under a ceiling, sideways off a wall — and launches that way. The list scrolls (PgUp/PgDn, Home/End, the wheel); a click chooses a row and a second click joins it. An arena's world and robots start when someone joins it and stop again after two minutes with nobody in it.

In the browser

The same server serves the game to browsers — http://host:2280/ by default; --http N, -p N or PORT=N choose the port, --http 0 turns it off. Log in or make an account (the same accounts as ssh), pick an arena, and play on a canvas beside ssh players in the same world: a/d or the arrows turn, s/↑ or the right mouse button thrust, space or the left button fire, w/shift shield, the pointer steers, Enter steps through the ships when you are watching, m shows the frames a second (in every client), and ♪ in the bar switches the music off and on without touching the effects (kept in the browser). The pointer's aim follows the ship: it is worked out again from where the mouse sits after every draw, so a ship flying under a still mouse keeps aiming ahead of itself. On a phone or a tablet the arena is the game alone — no bars, nothing to scroll: a thumbstick steers and, pushed far, thrusts; buttons fire, shield, fire a missile and thrust; fuel and score ride over the world, ≡ opens the rest of the hud over it, ⇄ swaps the stick and the buttons between hands, ♪ switches the music, ⤢ goes full screen and ✕ leaves; the sound comes at 22 kHz mono, a quarter of the bytes of the 44.1 kHz stereo a desktop browser gets (one session's sound costs the server 0.39 of a core at 44 kHz and 0.22 at 22; use Cauldron2D.Net.Channel, audio: in ExPilot.Web.ArenaChannel is where to trade quality for sessions). The stick is analog: thrust grows with the push from its ring to its rim. The pages have a tab bar along the bottom instead of the top bar; "Add to Home Screen" opens the game without the browser's bars. ?touch=1 or ?touch=0 on any address forces the phone layout either way and is remembered. Every arena card offers a team or a plain join and watch; the guide page shows everything in the game with its sprite. Sound plays in the page, nothing to set up. The web client is cauldron_2d_net plus ExPilot.Web; the design is CAULDRON_WEB_DESIGN.md at the repository root.

On the desktop

mix ex_pilot.desktop opens a window (Erlang's wx) played with the keys like the ssh client: Enter from the title, pick where the arenas are — a server by its URL (log in or register, then fly over the same WebSocket a browser uses), a node (connect, then fly in its worlds across the connection), or this app — pick an arena, Enter joins, w watches, t picks a team; in the arena Esc or q returns to the lobby. s on the title or in the lobby, and Tab in the arena, is the settings: effects and music levels and whether the pointer steers, ←/→ change them, kept in the same $XDG_CONFIG_HOME/expilot/<player>.settings the ssh client reads, and Esc returns to where you were — from the arena, to your ship where it was. h on the title is the serve screen: ssh and web ports, interfaces, accounts file and robots, Enter starts or stops the server. --url, --name, --node, --cookie fill the fields in. Keys and the pointer are the browser's; sound plays through your speaker. The design is CAULDRON_WX_DESIGN.md at the repository root.

In a terminal, with everything

mix ex_pilot.terminal                       # play here, connect elsewhere, host, leaders
mix ex_pilot.terminal --name alice --url http://arcade:2280

The terminal has the desktop's flow: Enter plays the arenas this program carries, c connects — to a server by URL (log in or register, then fly over its WebSocket) or to a node — h hosts a server from inside (ssh, web, the node name and cookie others need, calling on the local network so their connect screens list it), l shows the leaders. mix ex_pilot.play is the same client with its own title and only the local arenas; mix ex_pilot.serve is the headless server.

Settings and your name

Sound levels, the pointer and keys are kept per kind of client — the terminal, the desktop, a browser, a phone or tablet — in $XDG_CONFIG_HOME/expilot/ and in your account, so what suits a phone does not follow you to the desktop. The web settings page also keeps a nickname, the name every client flies under and the boards show; the boards count by account, so changing it keeps your record.

Duels

From the browser's lobby, challenge a pilot on an arena, first to a number of kills: a private arena appears in every lobby — the two of you fly it, anyone can watch — and closes when it is won. +/- (the wheel, a pinch) zoom any view — terminal, browser, desktop — out to the whole arena and back, 0 puts it back; watching, the arrows or a drag pan the view, the wheel and a pinch zoom about the pointer, and 0 recentres it: watch a duel from above, or close in on it.

Leaders

Every round's result — kills, deaths, whether it was won, the best streak of kills without dying, the longest contact (seconds alive with an enemy within thirty tiles) — goes to a ledger on disk ($XDG_DATA_HOME/expilot/ledger.dets); robots' do not. The boards, today / this week / all time, by kills, kills a death, rounds won, streak, contact or laps, over every arena or one: /leaders in the browser, l in the terminal and on the desktop, GET /api/leaders for anything else. The load tool's accounts fly rounds like anyone else and land on the boards; mix ex_pilot.ledger --forget "load_*" (with the server stopped — the ledger is held by one process) drops their results, or any name's by pattern (ExPilot.Ledger.forget/1 while it runs).

Load testing

mix ex_pilot.serve --port 2422 --http 2480 --robots 4      # the server, here or on another machine
mix ex_pilot.load --url http://localhost:2480 --players 20 --watchers 50 --seconds 60
mix ex_pilot.load --url http://host:2480 --arenas Arena,Bali --players 10 --ramp 10 --every 10 --seconds 300
mix ex_pilot.load --players 10 --ramp 10 --audio off        # the worlds and the wire alone

mix ex_pilot.load runs Cauldron2D.Net.Load with ExPilot's actions: players (steering at random) and watchers join a running server over the same WebSocket a browser uses. Every few seconds a report: the sessions joined, the frames a second they get against the worlds' tick rate, the longest gap between frames, the node's busy share, run queue, processes and memory, then the three worlds with the longest ticks — mean, 95th percentile and longest against the tick's budget, and the share of ticks that ran behind (GET /api/stats has all of them). A report is degraded when a world's 95th-percentile tick is over its budget, a world ran behind on more than a fifth of its ticks, a session got under 80% of the frame rate or waited over a second for a frame; it says so and why. --ramp N adds N sessions every report until that happens, and the summary names the count before the last addition as the capacity. Every report and the summary go to a JSON-lines file ($XDG_DATA_HOME/expilot/load/<time>.jsonl, or --out) as the run goes, and Ctrl-C ends a run early with the summary so far. Run the generator on another machine when the number has to be exact; on the same one, its cores count too. The load accounts are load_1, load_2… (password load test), registered on the server as needed.

Sound is the server's largest cost a session: a synthesiser each at 44.1 kHz, a third of a core or so. mix ex_pilot.serve --music arena synthesises one music stage a world and mixes it under each session's own effects; --music dynamic keeps personal music but drops every session to 22.05 kHz while the node's schedulers are over 60% busy (back at under 30%, thirty seconds apart at least); --music static plays each session a piece of the repertoire arranged for its kind of arena (ExPilot.Music.Static, played from the MIDI scores under priv/scores: Paganini's Caprice No. 24 for a dogfight; Joplin's The Entertainer for capture the flag; Grieg's In the Hall of the Mountain King for a team battle; Mozart's Rondo alla Turca for a race; the Prelude to Bizet's Carmen for a duel — sixty to eighty bars each on the Salamander grand with a recorded bass (ExPilot.Music.Instruments, FreePats' and Karoryfer's through TuningFork.Sfz, fetched note by note the first time), a kit and a doubling instrument arranged under it, made to loop and never changing with the fight), all five rendered in the background as the server starts (a few minutes, once; a changed song is rendered again, an unchanged one is read from disk) and kept under $XDG_CACHE_HOME/expilot/music, looped as a recording at the cost of a copy a chunk; the layered pieces that follow the play are for the other modes; --music off and --sfx off do without. A browser or desktop that asks for no sound (audio: false on the join) costs nothing whatever the policy. Effects are rendered once a node in any mode and replayed with each listener's gain and pan.

Playing over ssh

ssh -p 2222 new@host                                       # register: pick a name and password, then play
ssh -p 2222 alice@host                                     # play
ssh -p 2222 -R 24713:127.0.0.1:4713 alice@host             # play with sound

Every account has its own sound port on the server — 24713 for the first account registered, 24714 for the next, and so on; the game's settings screen shows yours with the lines to use. The accounts are in $XDG_DATA_HOME/expilot/accounts.terms (~/.local/share/expilot/accounts.terms), a text file with one Erlang term per account — name, number, props — that you can read as it is (number 1 means port 24714). The game synthesises on the server and sends raw PCM (signed 16-bit, 44100 Hz, stereo) through the reverse tunnel to whatever listens on your machine's port 4713, on any OS with ffmpeg (brew install ffmpeg, winget install ffmpeg, apt install ffmpeg):

while :; do ffplay -nodisp -autoexit -fflags nobuffer -analyzeduration 0 -probesize 32 -f s16le -ar 44100 -ch_layout stereo -i "tcp://127.0.0.1:4713?listen"; done

ffplay ends when a session's connection closes, so the loop puts a fresh listener up for the next session; on Windows the loop is for /L %i in (1,0,2) do ffplay … in cmd and while ($true) { ffplay … } in PowerShell, with the same options. The title screen's "No sound?" (n, or a click) shows all three with your own port and ssh line; Esc closes it. Start either before or after the game; the server reconnects every two seconds until it is there. The server keeps 60 ms of audio in flight and, on connecting, sends the first frames and then nothing for 300 ms: ffplay opens its device before it reads in earnest, and anything sent meanwhile would sit in the socket and play first, as lag, for the whole session. Someone with Elixir and this project on their machine can run mix ex_pilot.listen instead of ffplay: it plays through the speaker about 100 ms behind the game and needs no such care. sox works too (sox -t raw -r 44100 -e signed -b 16 -c 2 - -d < <(nc -l 4713)), and on Linux pacat --raw --format=s16le --rate=44100 --channels=2 < <(nc -l 4713). A served game never plays through the server's own speaker; mix ex_pilot.play plays through this machine's.

Title → lobby (arenas, team, chat) → settings → arena. The defaults are WASD with the pointer steering: a/d turn (and the ship follows the mouse until a turn key is pressed), s or the right mouse button thrust, space or the left mouse button fire, w or left shift shield — a shielded ship shows a ring; settings offers arrows and vi presets, rebinding (↑/↓ to the action, Enter then a key or mouse button adds it, Backspace removes the last), pointer steering, effects and music levels, display (pixels where the terminal has them, braille, or glyphs) and frame rate (auto is the terminal's best: 15 on iTerm2 and sixel terminals, where every frame is a whole image; 30 elsewhere), and keeps them under $XDG_CONFIG_HOME/expilot/<player>.settings. The arena shows your ship's status and the scores beside the world; ? shows the keys (tap to keep, hold to peek); Esc or q goes back to the lobby, ^Q quits. A ship sits on its base until it thrusts. Held turn keys take over from the pointer until it moves again. A ship that has just appeared on its base — joined, respawned or at a new round — cannot be hit for three seconds and shows its shield meanwhile. With limited lives, a ship out of lives watches the nearest ship still flying — Enter steps to the next one, for a spectator too — and the round ends as in XPilot when one ship (one team) is left standing among two or more (alone in an arena you fly for practice; nothing is won or lost): it is told it won, everyone is back on their bases four seconds later, and for you it is a summary — Victory or Defeat with the standings. Enter after a Victory joins the next arena in the list, after a Defeat the same one again; Esc returns to the lobby. Robots launch off their bases, hunt the nearest enemy anywhere in the arena along the clearest heading toward it, brake off walls, fire within reach and go for a fuel station when the tank runs low. Each robot is seated with a skill of its own, drawn at random: the sharp ones aim tight, fire from far and react in three frames, the dull ones spray, wait for a closer shot, hesitate on the trigger and think three times slower. A player who finds every base taken gets a robot's, and the robot comes back when there is room again. The hud counts the enemies still in the round and the radar marks every ship: you in yellow, teammates blue, enemies red, bases grey. A tank that has been empty for ten seconds loses the ship, on the base or off it. Ships that fly into each other crash unless shielded; shielded ships bounce apart. Walls bounce a ship that touches them slowly or with its shield up — an unshielded bounce costs fuel — and crash one that hits them faster; the map's maxunshieldedwallbouncespeed, maxshieldedwallbouncespeed and wallbouncefueldrainmult set the numbers.

Items appear on the map and are picked up by flying over them; the hud lists what you carry, 1 drops a mine, 2 fires a missile (n picks torpedo, smart or heat), 3 fires the laser, c cloaks, e jams, r steals with the transporter, g/b pull and push with the tractor beam, x deflects, p phases through walls, u hyperjumps, [/] emergency shield and thrust, o autopilot, v drops the ball. On a team map (teamplay: yes) teammates' shots pass through each other, the ! targets take three hits, and carrying the other team's ball from its * treasure into your own scores: the ball hangs on a string that tugs the ship and snaps when overstretched, and falls, drifts and bounces on its own when loose. Map headers set the rest of the rules XPilot's do — allowshields, initialfuel and the initial… kit, shotswallbounce, friction, allowplayercrashes, targetkillteam, treasurekillteam, dropitemonkillprob, laserisstungun, shieldeditempickup, gravityangle, gravitypoint… — the full list is in ExPilot.Map. A racemode map runs laps over the A–Z checkpoints. h on the title or in the lobby opens the guide: everything you can meet in an arena, drawn beside a line on what it does and the key that uses it. The music follows the kind of arena — a dogfight, capture the flag, a team battle and a race each have their own cruising and combat pieces (ExPilot.Music). The hud is a column down the left as in XPilot: the radar on top, then you, your items and the scores, with the arena's messages along the bottom; t talks to the arena. Your own shipshape is read from $XDG_CONFIG_HOME/expilot/<player>.shipshape. On a terminal that reports key releases (kitty, Ghostty, WezTerm, foot, Alacritty, iTerm2 3.5+) keys are held; elsewhere (Terminal.app, Alacritty) the key repeat stands in: a tap turns a step or gives a short burst of thrust or shield, and holding the key holds it until about 150 ms after you let go.

What is here

Not yet: items, treasures and capture-the-flag, race mode, team scoring.

License

MIT. The classic maps are community contributions with no stated licence and are fetched rather than shipped; the XPilot source is GPL and was read, not copied.

The scores under priv/scores are LilyPond engravings from the Mutopia Project (mutopiaproject.org) of music long in the public domain: Grieg's In the Hall of the Mountain King (Coyau), Joplin's The Entertainer (Chris Sawer) and Mozart's Rondo alla Turca (Rune Zedeler, Chris Sawer) are released to the public domain; the Prelude to Bizet's Carmen (Alex O'S) is under Creative Commons Attribution-ShareAlike 2.5 and Paganini's Caprice No. 24 (Samuel Rummel) under Creative Commons Attribution-ShareAlike 4.0, so the renders made from those two carry their engravers' names and the same terms. The piano is the Salamander grand, CC BY 3.0 by Alexander Holm; the basses are FreePats' fingered and picked electric bass and Karoryfer Samples' meatbass, all CC0.