🚀 Delta-V

Play now at delta-v.tre.systems

Delta-V is an online turn-based multiplayer tactical space combat and racing game featuring realistic vector movement and orbital gravity mechanics across the inner Solar System.

Command your fleet, master astrogation trajectories, slingshot around celestial bodies, and engage in high-stakes combat where positioning and velocity matter as much as firepower.

🌟 Features

• Vector physics spaceflight — velocity persists between turns; burn fuel to alter course; gravity deflects you one turn later.
• Orbital mechanics — planetary gravity wells enable slingshot maneuvers; "weak" gravity at moons is a player choice.
• Tactical combat — odds-based dice resolution with range and relative-velocity modifiers; mines, torpedoes, and nukes with per-scenario availability.
• Eight player-facing scenarios — Bi-Planetary, Duel, Blockade Runner, Grand Tour, Escape, Convoy, Fleet Action, Interplanetary War. Lunar Evacuation remains available to replay, simulation, and agent tooling but is hidden from the public picker while balance work continues.
• Play modes — local AI at three difficulties, online multiplayer via 5-character room codes, quick-match queue, spectator mode, and a machine-native agent API (/agents).
• Public leaderboard — unified Glicko-2 ladder for humans and agents (/leaderboard); no login required.
• Continuous rendering, discrete logic — HTML5 Canvas paints a smooth space view while the engine operates on a strict axial hex grid.

🛠️ Architecture

src/
├── shared/   # Side-effect-free engine and shared types (no I/O)
├── server/   # Cloudflare Worker + Durable Objects (authoritative rooms)
└── client/   # Canvas renderer, DOM UI, reactive session state
scripts/      # Simulation, load, agent, and MCP tooling

The shared engine is side-effect-free. The server is authoritative and event-sourced. See ARCHITECTURE.md for module inventories, data flow, and the Durable Object model.

📚 Documentation

Each topic has one owner doc to keep decisions from drifting.

If you're new, read in this order:

1. CONTRIBUTING.md — set up, pre-commit, verify
2. ARCHITECTURE.md §1–2 — layer overview and the Durable Objects
3. CODING_STANDARDS.md — Core Principles section (first screen) only at this stage
4. One pattern chapter that matches the area you'll touch (client / engine / protocol / testing / scenarios / types)
5. SPEC.md if you're touching game rules; PROTOCOL.md if you're touching the wire format

Doc index by purpose, grouped by theme:

Design reference

Doc	Purpose
SPEC.md	Game rules and scenarios
PROTOCOL.md	Wire format, state shapes, hex math, HTTP/WS routes
ARCHITECTURE.md	Module inventory, data flow, Durable Object design, replay/recovery
AI.md	Built-in AI architecture, intent-first planning, and tuning workflow

Code and contribution

Doc	Purpose
CODING_STANDARDS.md	Conventions and refactoring guidance
AGENTS.md	Root working guide for AI coding agents in this repository
patterns/	Design-pattern walk-through: why the code looks the way it does
CONTRIBUTING.md	Contributor workflow, pre-commit, verification

Operations

Doc	Purpose
SECURITY.md	Integrity, abuse controls, rate limits, data retention
OBSERVABILITY.md	Telemetry events, D1 queries, incident triage
PRIVACY_TECHNICAL.md	What the stack stores (technical, not legal)
A11Y.md	DOM accessibility audit checklist

Testing

Doc	Purpose
MANUAL_TEST_PLAN.md	Release / regression manual checks
SIMULATION_TESTING.md	Headless AI simulation and WebSocket load harness
EXPLORATORY_TESTING.md	Open-ended discovery-pass toolkit and probe recipes

Release and planning

Doc	Purpose
REVIEW_METHODS.md	Reusable review types and how to run them
REVIEW_PLAN.md	Recurring cross-cutting review checklist
COORDINATED_RELEASE_CHECKLIST.md	Protocol/schema version bump steps
BACKLOG.md	Remaining actionable work, in priority order

Agents and visual identity

Doc	Purpose
AGENTS.md	Practical guide for building Delta-V agents
DELTA_V_MCP.md	MCP tool reference and host configuration
AGENT_SPEC.md	Deep agent protocol and design reference
LORE.md	Ship aesthetics and visual direction

Compiled Documentation Book

The documentation book compiles every doc in this index into a single consolidated PDF with a cover, parts-break, and table of contents. It is rebuilt with npm run docs:book.

File	Purpose
docs/delta-v-documentation-book.pdf	Full book: every canonical Markdown doc and the visual concept boards under docs/assets/. Use for reading, printing, or archiving.

Glossary

Term	Meaning
Room	A game lobby identified by a 5-character code. One room can host multiple matches via rematch.
Match	A single game session within a room. Has a stable gameId like ROOM1-m2.
Seat	Slot for a player (0 or 1). Protected by a playerToken for reconnection.
Session	On the server: the authoritative GameDO instance. On the client: ClientSession aggregate (signals, planning, transport).
Phase	The authoritative GameState.phase — fleetBuilding, astrogation, ordnance, combat, logistics, gameOver.
Client state	The UI-layer ClientState — finer-grained (e.g. playing_movementAnim) derived from phase.
Event	An append-only domain fact in the match stream (EngineEvent) — not a DOM event.
Checkpoint	A full GameState snapshot saved at turn boundaries. Speeds up projection.
Projection	Reconstructing GameState from checkpoint + event tail. Used for reconnects, parity, replay.
Agent	Any non-browser player (script, LLM, RL) connected via MCP, bridge, or raw WebSocket. Identified with playerKey prefix agent_.
Burn	A fuel-costing course shift during astrogation (1 hex normally, 2 hex for warship overload).
Overload	A 2-fuel warship course shift, usable once between maintenance stopovers.

🚀 Quick Start

1. Use the project Node version — .nvmrc pins 25 (matched by .github/workflows/ci.yml).

   nvm use

2. Install dependencies.

   npm install

3. Install Playwright's Chromium (pre-push and CI use it for browser smoke tests).

   npx playwright install chromium

4. Local Worker overrides (first run). Copy .dev.vars.example to .dev.vars so DEV_MODE=1 can engage the dev agent-token placeholder when AGENT_TOKEN_SECRET is not set (Wrangler merges .dev.vars over wrangler.toml [vars]).

5. Run the dev server.

   npm run dev

6. Play. Open http://localhost:8787, create a game in tab 1, copy the room link or 5-character code, and join from tab 2.

CLI Commands

Command	Description
npm run dev	Start local development (Wrangler + esbuild; see .dev.vars.example)
npm run build	Build the client bundle
npm run lint	Biome lint + format check
npm run typecheck	Typecheck src/
npm run typecheck:all	Typecheck app + tooling (scripts/, e2e/, configs)
npm test	Run all unit tests via Vitest
npm run test:coverage	Run client and server/shared coverage passes sequentially (enforced thresholds on engine, server, MCP adapter, and client)
npm run test:e2e	All Playwright specs against a local Wrangler server
npm run test:e2e:smoke	Playwright browser smoke without the dedicated a11y spec
npm run test:e2e:a11y	Playwright + axe accessibility baseline
npm run test:e2e:headed	Same smoke suite with a visible browser
npm run test:watch	Vitest in watch mode
npm run verify:quick	Fast local gate (lint, typecheck, build)
npm run verify / npm run verify:full	Full pre-release sweep (lint, typecheck, coverage, build, e2e smoke, a11y, simulation)
npm run simulate -- [scenario] [iterations] [--ci]	Headless AI-vs-AI matches
npm run simulate:smoke	Short all-scenarios AI smoke run for local push checks
npm run mcp:sandbox-smoke	Two-seat sandbox MCP smoke against the configured SERVER_URL
npm run load:test -- --games 20 --concurrency 5	WebSocket load / chaos harness
npm run deploy	Deploy to Cloudflare Workers

Pass simulation arguments after the npm --, e.g. npm run simulate -- all 25 --ci.

Test Strategy

Three complementary layers keep the regression net cheap to run:

• Vitest — engine, protocol, client-helper, and server-logic unit / property tests. This is the main regression net.
• Headless AI simulation (npm run simulate) — scenario-wide engine stability and balance sweeps; much cheaper than the browser.
• Playwright — an intentionally thin browser smoke suite for boot, core multiplayer, and a11y baselines (test:e2e and test:e2e:a11y).

When deciding where a new test belongs: rules/combat/protocol assertions → Vitest; broad scenario behavior across many turns → simulation; anything that requires a real browser, multiple pages, storage, or WebSocket wiring → Playwright. See SIMULATION_TESTING.md for simulation detail and CONTRIBUTING.md for verification flow.

📜 Game Rules

The canonical ruleset — movement edge cases, damage tables, scenario-specific rules — lives in SPEC.md. Open engineering work lives in BACKLOG.md.

🔗 External References

• Cloudflare Workers · Durable Objects · Durable Objects WebSocket hibernation
• MDN Canvas API · MDN Service Worker API
• TypeScript Handbook: Narrowing

📄 License

All rights reserved.