🚀 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, sling-shot around celestial bodies, and engage in high-stakes combat where positioning and velocity are just as crucial as firepower.

Check out our Lore & Visual Direction Guide for ship aesthetics and hard-sci-fi technology grounding.

📚 Documentation Guide

Use the docs by role so the same decision is not maintained in three places:

• SPEC.md: gameplay rules, scenario behavior, protocol shapes, state concepts, and implementation status
• ARCHITECTURE.md: implementation structure, data flow, Durable Object design, replay/recovery model, and the current client reactive/session architecture
• COORDINATED_RELEASE_CHECKLIST.md: schema/protocol bump and deploy steps (single version line)
• CODING_STANDARDS.md: coding conventions, refactoring guidance, and shared implementation patterns
• CONTRIBUTING.md: contributor workflow, pre-commit behavior, verification commands, and local environment gotchas
• MANUAL_TEST_PLAN.md: release/regression manual checks across gameplay, UX, and recovery flows
• SIMULATION_TESTING.md: headless AI simulation, websocket load/chaos testing, and the agent bridge
• AGENTS.md: practical agent quick start (MCP vs bridge, contracts, reliability checklist, tuning loop)
• AGENT_SPEC.md: deep agent protocol/design reference and roadmap
• DELTA_V_MCP.md: MCP tool reference and host configuration details
• SECURITY.md: competitive integrity, abuse/cost controls, deployment hardening, and retention/security posture
• OBSERVABILITY.md: runtime signals, D1 queries, and incident triage
• A11Y.md: DOM accessibility audit checklist and manual process
• PRIVACY_TECHNICAL.md: technical storage behavior only; not user-facing policy text
• BACKLOG.md: remaining actionable work only, in one global priority order
• REVIEW_PLAN.md: recurring cross-cutting review cadence; concrete follow-up work belongs in the backlog
• LORE.md: ship aesthetics, technology pillars, concept art, and colour direction

🌟 Features

☄️ Realistic Vector Physics Spaceflight

• Vector Movement Engine: Your velocity persists between turns. Plan your burns carefully; there's no friction to stop you.
• Orbital Mechanics: Planetary gravity deflects your course. Master "Weak" and "Full" gravity wells to execute slingshot maneuvers.
• Continuous Rendering vs Discrete Logic: The visual rendering provides a smooth, continuous-space aesthetic, whilst all game logic acts on a strict, pure axial hex-coordinate system.

⚔️ Deep Tactical Combat

• Odds-Based Combat: Gun combat utilizes a classic odds-based dice resolution system, influenced by relative velocity and range modifiers.
• Ordnance Management: Equip and deploy mines, torpedoes, and devastating nukes.
• Damage & Repairs: Complex damage tracking (disabled turns vs. cumulative elimination). Find safe harbor at planetary bases for repairs and resupply.

🎮 Multiple Game Modes

• 9 Playable Scenarios: Bi-Planetary, Escape, Lunar Evacuation, Convoy, Duel, Blockade Runner, Fleet Action, Interplanetary War, and Grand Tour.
• Local AI Opponent: Test your skills offline against an AI component with configurable difficulty levels.
• Online Multiplayer: WebSocket-based remote play with tokenized reconnects and spectator support.

---

🛠️ Architecture

Delta-V has three runtime layers:

src/
├── shared/   # Side-effect-free game engine and shared types
├── server/   # Cloudflare Worker + Durable Object authority
├── client/   # Session orchestration, Canvas renderer, DOM UI
└── scripts/  # Simulation, load, and agent tooling

The shared engine is side-effect-free. The server is authoritative and event-sourced. The client uses reactive session/UI state where it removes duplicate mirrors or imperative fan-out, while input, transport, and transient presentation events stay explicit.

For module inventory, diagrams, dependency maps, and the full client/server data flow, see ARCHITECTURE.md.

For project conventions and refactoring guidance, see CODING_STANDARDS.md.

---

🚀 Quick Start

Get your thrusters firing locally in seconds:

1. Use the Project Node Version

   nvm use

   Uses .nvmrc (25); CI matches .github/workflows/ci.yml.

2. Install Dependencies

   npm install

3. Install Playwright's Chromium Browser

   npx playwright install chromium

   Required for the browser smoke tests that now run in pre-commit and CI.

4. Start the Local Development Server

   npm run dev

   This starts the Wrangler server.

5. Play the Game

   • Open your browser to http://localhost:8787
   • Open a second tab or window to the same URL.
   • Create a game in tab 1, then join from tab 2 using the copied room link or the 5-character room code.

CLI Commands

Command	Description
npm run dev	Start local development server (Wrangler/esbuild)
npm run build	Build the client bundle
npm run lint	Run Biome lint + format check on src/, scripts/, e2e/, and config files
npm run typecheck	Typecheck application code (src/ via tsconfig.json)
npm run typecheck:all	Typecheck app + tooling (scripts/, e2e/, root TS configs via tsconfig.tools.json)
npm test	Run all unit tests via Vitest
npm run test:coverage	Run tests with a coverage report under coverage/
npm run test:e2e	Run Playwright browser smoke tests against a local Wrangler server
npm run test:e2e:headed	Run the same Playwright suite with a visible browser
npm run test:watch	Run Vitest in continuous watch mode
npm run verify	Pre-release sweep: lint, typecheck:all, coverage, build, e2e smoke, a11y e2e, and AI simulations
npm run simulate -- [scenario] [iterations] [--ci]	Run headless AI vs AI matches to test engine stability and scenario balance
npm run load:test -- --games 20 --concurrency 5	Run the websocket load / chaos harness against a Wrangler or deployed server
npm run deploy	Deploy straight to Cloudflare Workers

Pass simulation arguments after npm's --, for example npm run simulate -- all 25 -- --ci.

Test Strategy

Delta-V uses three complementary automated test layers:

• Vitest is the main regression net. Keep engine, protocol, client helper, and server logic covered with direct unit / property tests close to the source.
• AI simulation (npm run simulate) covers scenario-wide engine stability and balance much more cheaply than browser automation.
• Playwright stays intentionally small and fast. It is a browser smoke suite, not a full scenario matrix. Use it for a few end-to-end contracts that only a real browser can prove, such as booting the app, starting a match, basic multiplayer join/chat/reconnect, and other thin UI integration checks.
• Playwright + axe (npm run test:e2e:a11y) provides a focused DOM accessibility baseline for menu/lobby/HUD/help and keyboard focus behavior.

When deciding where a new test belongs:

• If the assertion is about rules, combat, movement, scenario logic, or protocol validation, prefer Vitest.
• If the assertion is about broad scenario behavior over many turns, prefer headless simulation.
• If the assertion requires a real browser, multiple pages, storage, layout, or websocket wiring, consider Playwright.

Keep Playwright additions focused on browser-only risks so the suite remains fast and easy to maintain.

---

📜 Game Rules Reference

For the comprehensive ruleset detailing movement edge cases, damage tables, and specific scenario rules, refer to SPEC.md.

Open engineering work lives in BACKLOG.md.

🔗 External References

• Cloudflare Workers and Durable Objects
• MDN Canvas API and MDN Service Worker API
• web.dev Learn PWA
• TypeScript Handbook: Narrowing

---

📄 License

All rights reserved.