CMD Space Rider

Ctrl + click to view cmd-space-rider documentation

A retro DOS-style terminal space tunnel game. Pilot your ship through an endless neon warp tunnel, dodge obstacles, collect energy orbs, and chase the high score — right in your command line or browser.

Ctrl + click to play game in the browser.

Features

• DOS terminal graphics — Pseudo-3D tunnel rendered with Unicode block elements, box-drawing characters, and 256-color ANSI palette. No graphical window required.
• Browser preview — Open index.html in any browser to play the same game rendered as a canvas-based terminal emulator. No build step, no server, no dependencies.
• Cross-platform — Runs on Windows, macOS, and Linux. Any terminal that supports 256 colors and Unicode.
• Neon warp tunnel — Perspective-scrolling walls, animated ring stripes, a parallax starfield, and a warp transition every minute.
• Asteroid field sections — Every two and a half minutes the walls come down for fifteen seconds and the rocks arrive across the whole screen, then the tunnel returns.
• Boss encounters — Every three minutes a >> WARNING << banner holds the HUD, then a large mine closes on the ship under its own power and shoots back. Twenty pulse hits bring it down for three pickups; let it reach you and it rams.
• Ship controls — Steer, boost, fire a pulse cannon, and barrel roll out of trouble.
• Three ways in — Keyboard, touch, or a standard gamepad, all feeding the same controls.
• Progressive difficulty — Speed, obstacle density and mines all escalate with distance.
• Leaderboard - A run that makes the top ten is named with three characters, arcade style, and the table is drawn on the title screen.
• Replay ghost - The run you just flew comes back as a grey ship on the next one, flying the path you flew, so you can see where you are ahead.
• Split screen (browser) - V on the title screen seats two pilots at one keyboard, each flying their own run in half the grid. The same tunnel, separate scores, and the higher score takes the round.
• Performance mode - A device that cannot hold 30 frames a second has its starfield and its debris thinned automatically, and gets them back when it can.

The full list covers powerups, combo scoring, the leaderboard and the replay ghost, retro sound, the CRT overlay, touch and gamepad controls, the two-pilot split screen, light mode, performance mode, and the five debug scenarios.

Getting Started

Open index.html in any modern browser, or play the hosted build. That is the whole browser install.

For the terminal, with Node.js v16 or later:

git clone https://github.com/isocialPractice/cmd-space-rider.git
cd cmd-space-rider
npm install
npm run build
npm start

See Getting Started for the browser debug parameters and the rest, or the Quickstart for the short version.

Usage (CLI)

space-rider                          Start in normal mode
space-rider --debug                  Open the debug scenario menu
space-rider --mode <mode>            Start a specific debug mode directly
space-rider --help                   Show help

Input	Action
W / A / S / D or Arrow keys	Steer ship
Space	Fire pulse cannon
F or Shift (browser)	Boost
Q / E	Barrel roll
P	Pause / resume a run
V (browser, title screen)	Open a two-pilot split-screen round
Arrows + Enter on the name entry screen	Spell a three-character name for a top-ten run
Gamepad: left stick / A / B / triggers	Steer / fire or confirm / boost / barrel roll

The Usage page carries the full control table, the key repeat and deadzone behaviour, the gameplay rules, and the five debug modes. The Cheatsheet puts every key, flag and figure on one page.

Project Structure

cmd-space-rider/
  index.html        # Browser version (canvas terminal emulator, zero dependencies)
  src/              # CLI entry point, input, engine, renderer, menus, screen buffer
  test/             # Both builds, the agreement between them, the site, and the probes
  docs/             # This project's documentation site
  icon.svg          # Ship icon, inlined into index.html as the favicon
  package.json      # CLI tool manifest and dependencies

Every file under src/, test/ and docs/ is listed on the Project Structure page, with the root files the game and the site are built from.

Development

npm run build      # Compile TypeScript to out/
npm run start      # Run the compiled game
npm run dev        # Build and run in one step
npm run debug      # Build and run in debug mode
npm run watch      # Watch mode for development
npm test           # Build, then run the test suite
npm run probe      # Build, then run a measurement probe

The Development page covers the line ending policy, how the suite reaches both builds, and what the probes measure and why they are seeded.

Terminal Requirements

• Minimum size: 60 columns x 20 rows. The browser holds the same floor and shrinks the font to reach it.
• Color support: 256-color ANSI (most modern terminals)
• Unicode support: Box-drawing and block element characters
• Recommended terminals: Windows Terminal, iTerm2, GNOME Terminal, Alacritty, Kitty

How It Works

The terminal build draws through a custom double-buffered screen renderer built on raw ANSI escape codes, flushed to stdout as a single optimized write per frame. The browser build reproduces the same game as a canvas character grid, running identical game logic. Six things differ between them, each because the medium allows or demands it, and the How It Works page sets out all six.

Documentation

The full documentation is a site built from this README:

Page	What it covers
Quickstart	The shortest path to flying
Features	Everything the game does
Getting Started	Browser and terminal install
Usage (CLI)	Controls, gameplay, debug modes
Project Structure	Every file and what it holds
Development	Scripts, tests, probes
Terminal Requirements	Size, colour and Unicode support
How It Works	The two renderers
Cheatsheet	Every key, flag and figure

The site's look is recorded in DESIGN_LANGUAGE.md.

License

MIT. See LICENSE.