Terminal Starfield is a space-combat roguelite drawn with ANSI text, for people who want a game in the terminal or a seeded text renderer they can test. The same Python package runs in a local TTY and, on Pyodide, in the browser at terminal-starfield.vercel.app.
StatusShipped, v4.0.0 release and web build
RuntimePython 3.9+ with no runtime dependencies, Pyodide in the browser
Proof hooks--snapshot, --state-snapshot JSON, 128 unittest cases

How it works

Flight in cli.py is one session’s game loop. Each call to Flight.step(events, dt, width, height) applies decoded input, advances the simulation by dt and returns the next ANSI frame, or None when the player quits. It does no terminal I/O itself. Two front ends feed it. In a terminal, TerminalSession puts stdin in cbreak mode, switches to the alternate screen, traps SIGWINCH and SIGTERM, and restores the TTY on normal exit, Ctrl+C and SIGTERM. run_interactive reads stdin bytes, hands them to KeyDecoder, and writes the frame at the --fps rate. In the browser, web/src/game.worker.js loads Pyodide from jsDelivr, writes the unmodified terminal_starfield/*.py files (bundled by Vite at build time) into the Pyodide filesystem, and imports web/src/web_tty.py. That 31-line BrowserTTY class builds the same Flight from the same argument parser and steps it with bytes and a size from xterm.js. The page passes --mouse on laptops and --auto-fire on touch devices, per main.js. Simulation in model.py advances in fixed steps of 1/120 s regardless of frame rate, and keeps separate random.Random instances for combat and for cosmetic stars, so star density or theme changes do not consume combat randomness. A seed with the same ship, ruleset and inputs at the same simulation times reproduces a run. A seed is not a saved input replay. The snapshot flags skip the interactive loop. --snapshot WxH and --state-snapshot build a Simulation (seed 42 if none is given), advance it 2.2 s, optionally stage a preview screen with --snapshot-screen, and print either one rendered frame or the state as sorted JSON. Neither reads nor writes the flight log. The game has four modes. Campaign runs 15 waves across three sectors with three flagships. Endless keeps going after that. Zen Drift is the HUD-free starfield, and Voyage (start it with --mode voyage) is a signal-and-debris run. Three hulls (Vanguard, Wraith, Aegis) change starting shields and weapons.

Verify it

Run these from a clone. All four were run on 23 October 2026 at commit 3765e27 with Python 3.15 on macOS.
The unittest run reported Ran 128 tests and OK. The snapshot printed an 80×24 ASCII frame, and the state snapshot printed one JSON object with keys including enemies, player, route_history, run_stats, target and weapons. The test workflow runs the same unittest command on Ubuntu and macOS with Python 3.9 and 3.13. Use unittest (or python3 -m pytest). A bare pytest fails at collection with ModuleNotFoundError: No module named 'terminal_starfield', because the repo has no pytest config that puts its root on sys.path. To install the starfield command, install from Git:
The README’s pipx install terminal-starfield fails today because the package isn’t on PyPI (https://pypi.org/pypi/terminal-starfield/json returns 404). A release workflow that publishes to PyPI on the next published GitHub release was added after v4.0.0. To run the browser build locally, cd web && npm ci && npm run dev serves it on port 4231. The web build wasn’t run locally for this page. The live site returned HTTP 200 on 23 October 2026.

Limits

  • Interactive play needs a TTY on macOS or Linux, or Windows Terminal through WSL. Without a TTY the game exits with code 2 and suggests --snapshot.
  • No runtime dependencies means no Python packages. Python and a terminal with box-drawing and Braille glyphs are still required; --ascii covers terminals without them.
  • A seed fixes random draws, not timing. Live keyboard input at different simulation times produces a different run.
  • Snapshot output shows layout and state for staged screens. It says nothing about frame rate.
  • The browser build downloads the Pyodide runtime (about 6 MB per the README) from jsDelivr on first launch, exposes only --mouse, --auto-fire and --demo, and keeps the flight log in that browser’s IndexedDB.
  • Flight records are local to one machine or one browser. Nothing is uploaded.

Source

Replay a seeded starfield

Render the same seeded frame twice, compare it byte for byte, and read the state snapshot.