space-invaders-tui

STARFALL — a roguelite shmup in your terminal. You fly, the sky falls on you, and every level-up offers three random perks. Ten levels in you are cutting a laser through the swarm while two drones cover your flanks.

Play

Straight from your terminal, no install:

ssh -p 2222 invaders.m2-webvision.de

Or run it locally:

npx space-invaders-tui

Needs a terminal of at least 44x22 characters.

| Key | Action | | --- | --- | | ← / → or A / D | Fly (the ship has inertia — it drifts) | | Space | Fire | | 1 / 2 / 3 | Pick a perk on level-up | | P | Pause | | R | Restart after game over | | Q / Ctrl+C | Quit |

A run

Enemies arrive in a continuous stream, not in a formation: drifters fall straight, weavers snake, divers drop fast, gunners hold their line and shoot at you, brutes soak up damage. The longer you survive, the denser and tougher the mix gets.

Every kill gives score and experience. Enough experience and the game stops for a moment and offers three perks out of thirteen — rapid fire, spread shot, a laser beam, auto-aim, homing rockets, piercing shots, heavier shots, escort drones, extra hull, a rechargeable shield, crit chance, thrusters, more experience per kill. Perks stack, so the run compounds: the build you end with is never the build you planned.

Hits cost hull. A shield absorbs one hit and recharges when you stay clean. At zero hull the run ends, you type three letters arcade-style, and your score joins the global table — you are playing against everyone who ever ssh'd in.

Let an LLM play

The game logic is pure TypeScript with no terminal dependency, so it also ships as an MCP server. Point any MCP client at it and let a model fly:

claude mcp add starfall -- npx -y space-invaders-tui mcp

Four tools: start a run, look at the current frame (ASCII plus structured state), hold inputs for a number of frames, and pick a perk when a level-up interrupts the run. The MCP server runs on plain Node, so it starts without the runtime detour the game itself needs.

Install size

npx space-invaders-tui pulls roughly 130 MB. Almost all of it is the bundled Bun runtime: OpenTUI's renderer is a native library loaded through FFI, which plain Node cannot do. Shipping Bun as a dependency is what makes the one-line npx start work without asking you to install anything first. The MCP server does not touch the renderer, so it runs on your own Node instead.

How it works

• src/game.ts — pure game logic: spawning, ballistics, perks, collisions, experience. No rendering, no I/O, an injectable random source, fully unit-tested.
• src/perks.ts — the perk catalog as plain data plus a roll function; the only thing that touches the player's modifiers.
• src/render.ts / src/app.ts — rendering and input wiring on top of OpenTUI. Uses the kitty keyboard protocol (press/release events) where available and falls back to impulse-based movement elsewhere, which is why the ship glides instead of stuttering.
• mcp/server.ts — MCP server on top of the pure core, running on plain Node.
• bin/cli.js — the npx launcher: it resolves the bundled Bun binary for the game and starts the MCP server in the Node you already have.
• server/ssh-server.ts — the SSH arcade. Every connection gets its own in-process OpenTUI renderer writing ANSI straight into the SSH channel: no shell, no PTY subprocess, no auth. Hardened with session caps, idle timeouts, dimension clamping and backpressure limits.
• server/leaderboard-api.ts — small Bun + SQLite service behind the global high-score table, with validation, plausibility checks, rate limiting and the landing page at invaders.m2-webvision.de.

Source, self-hosting, development

The npm package ships only what a player needs: the launcher, the game, the MCP server. Everything below lives in the repository at github.com/Avee4k/space-invaders-tui — clone it to follow along.

git clone https://github.com/Avee4k/space-invaders-tui
cd space-invaders-tui
npm install
npm start           # play locally
npm test            # game logic + MCP server (node) and a headless render smoke test (bun)
npm run test:server # SSH arcade and leaderboard API (bun)
npm run typecheck

Self-hosting the arcade, also from the clone:

cd deploy && docker compose up -d

That runs the SSH arcade and the leaderboard API as one hardened container stack; see deploy/ for details. In the game, LEADERBOARD_URL="" disables the global leaderboard and LEADERBOARD_URL=https://… points it at your own instance.

The test suite plays the game headlessly through OpenTUI's test renderer, and the SSH server is tested end-to-end with a real ssh2 client against an in-memory session.

License

MIT