Implement combat system with damage tracking and phase cycling

- Add gun combat engine (combat.ts): odds-based damage table, range/velocity
  modifiers, counterattack system, cumulative disabled turns, elimination
- Add asteroid hazard rolls during movement (Other Damage table)
- Implement proper phase cycling: astrogation -> combat -> resupply -> next player
- Disabled ships drift without maneuvering, damage recovers 1 turn per game turn
- Wire combat/skipCombat messages through server DO
- Add combat phase UI with skip combat button
- Add 42 combat unit tests (112 total)
- Add README.md, rename spec.md to SPEC.md

Author: rgilks

README.md

@@ -0,0 +1,94 @@
+# Delta-V
+
+An online multiplayer implementation of [Triplanetary](https://en.wikipedia.org/wiki/Triplanetary_(board_game)) -- space combat with vector movement and gravity across the inner Solar System.
+
+## What is it?
+
+Two players command ships racing between planets. Ships move using realistic vector physics on a hex grid: velocity persists between turns, fuel is burned to accelerate, and planetary gravity deflects your course. Combat uses odds-based dice resolution with range and velocity modifiers.
+
+The game renders as a smooth, continuous-space experience (no visible hex grid) while using axial hex coordinates internally for all game logic.
+
+## Quick Start
+
+```bash
+npm install
+npm run dev        # Start local dev server (wrangler)
+```
+
+Open two browser tabs to `http://localhost:8787`. Create a game in one tab, join with the code in the other.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start local development server |
+| `npm run build` | Build client bundle |
+| `npm run typecheck` | Run TypeScript type checking |
+| `npm test` | Run all tests |
+| `npm run test:watch` | Run tests in watch mode |
+| `npm run deploy` | Deploy to Cloudflare Workers |
+
+## Architecture
+
+Full TypeScript stack: Cloudflare Workers + Durable Objects on the server, HTML5 Canvas on the client.
+
+```
+src/
+  shared/           Shared game logic (server + client)
+    hex.ts           Axial hex math library
+    movement.ts      Vector movement + gravity engine
+    combat.ts        Gun combat, damage tables, dice
+    game-engine.ts   Pure game state machine (no IO)
+    map-data.ts      Solar system map + scenarios
+    types.ts         All type definitions
+    constants.ts     Ship stats, game constants
+  server/
+    index.ts         Worker entry (HTTP + WebSocket routing)
+    game-do.ts       Durable Object (game state, turn lifecycle)
+  client/
+    main.ts          Client state machine + WebSocket
+    renderer.ts      Canvas rendering + camera + animation
+    input.ts         Mouse/touch input, burn planning
+    ui.ts            HTML overlay UI (menus, HUD, game over)
+```
+
+The game engine (`game-engine.ts`) is a pure-function module with no IO, making it fully unit-testable. The Durable Object (`game-do.ts`) is a thin wrapper handling WebSocket lifecycle and storage.
+
+## Game Rules
+
+See [SPEC.md](SPEC.md) for the full game specification including movement, combat, damage, and scenario rules.
+
+### Implemented
+
+- Vector movement with velocity persistence
+- Planetary gravity (full and weak)
+- Fuel management and resupply at bases
+- Overload maneuver (warships burn 2 fuel for 2-hex acceleration)
+- Landing and takeoff mechanics
+- Gun combat with odds-based damage table
+- Counterattack system
+- Damage tracking (disabled turns, cumulative elimination)
+- Asteroid hazard rolls
+- Phase cycling (astrogation -> combat -> resupply -> next player)
+- Bi-Planetary scenario (Mars vs Venus race)
+
+### Planned
+
+- Combat target selection UI
+- Ordnance (mines, torpedoes)
+- Additional scenarios (Escape, Merchant, Piracy, Fleet)
+- Full solar system map with asteroid belt
+- Detection and fog of war
+
+## Tech Stack
+
+- **Runtime**: Cloudflare Workers + Durable Objects
+- **Language**: TypeScript (full stack)
+- **Rendering**: HTML5 Canvas 2D
+- **Build**: esbuild (client), wrangler (server)
+- **Testing**: vitest
+- **CI**: GitHub Actions (typecheck + test + build)
+
+## License
+
+All rights reserved.

spec.md SPEC.mdspec.md renamed to SPEC.md

@@ -10,6 +10,7 @@ type ClientState =
   | 'connecting'
   | 'waitingForOpponent'
   | 'playing_astrogation'
+  | 'playing_combat'
   | 'playing_movementAnim'
   | 'playing_opponentTurn'
   | 'gameOver';
@@ -40,6 +41,7 @@ class GameClient {
     this.ui.onCreate = () => this.createGame();
     this.ui.onJoin = (code) => this.joinGame(code);
     this.ui.onConfirm = () => this.confirmOrders();
+    this.ui.onSkipCombat = () => this.sendSkipCombat();
     this.ui.onRematch = () => this.sendRematch();
     this.ui.onExit = () => this.exitToMenu();
 
@@ -90,6 +92,11 @@ class GameClient {
         this.renderer.frameOnShips();
         break;
 
+      case 'playing_combat':
+        this.ui.showHUD();
+        this.updateHUD();
+        break;
+
       case 'playing_movementAnim':
         this.ui.showHUD();
         this.ui.showMovementStatus();
@@ -180,16 +187,20 @@ class GameClient {
         });
         break;
 
+      case 'combatResult':
+        this.gameState = this.deserializeState(msg.state);
+        this.renderer.setGameState(this.gameState);
+        this.input.setGameState(this.gameState);
+        // After combat resolves, transition based on new state
+        this.transitionToPhase();
+        break;
+
       case 'stateUpdate':
         this.gameState = this.deserializeState(msg.state);
         this.renderer.setGameState(this.gameState);
         this.input.setGameState(this.gameState);
         if (this.state !== 'playing_movementAnim') {
-          if (this.gameState.activePlayer === this.playerId) {
-            this.setState('playing_astrogation');
-          } else {
-            this.setState('playing_opponentTurn');
-          }
+          this.transitionToPhase();
         }
         break;
 
@@ -240,16 +251,30 @@ class GameClient {
   }
 
   private onAnimationComplete() {
+    if (!this.gameState) return;
+    this.transitionToPhase();
+  }
+
+  private transitionToPhase() {
     if (!this.gameState) return;
     if (this.gameState.phase === 'gameOver') return;
 
-    if (this.gameState.activePlayer === this.playerId) {
+    const isMyTurn = this.gameState.activePlayer === this.playerId;
+
+    if (this.gameState.phase === 'combat' && isMyTurn) {
+      this.setState('playing_combat');
+    } else if (this.gameState.phase === 'astrogation' && isMyTurn) {
       this.setState('playing_astrogation');
     } else {
       this.setState('playing_opponentTurn');
     }
   }
 
+  private sendSkipCombat() {
+    if (!this.gameState || this.state !== 'playing_combat') return;
+    this.send({ type: 'skipCombat' });
+  }
+
   private sendRematch() {
     this.send({ type: 'rematch' });
   }

src/client/main.ts

@@ -8,6 +8,7 @@ export class UIManager {
   onCreate: (() => void) | null = null;
   onJoin: ((code: string) => void) | null = null;
   onConfirm: (() => void) | null = null;
+  onSkipCombat: (() => void) | null = null;
   onRematch: (() => void) | null = null;
   onExit: (() => void) | null = null;
 
@@ -44,6 +45,7 @@ export class UIManager {
     });
 
     document.getElementById('confirmBtn')!.addEventListener('click', () => this.onConfirm?.());
+    document.getElementById('skipCombatBtn')!.addEventListener('click', () => this.onSkipCombat?.());
     document.getElementById('rematchBtn')!.addEventListener('click', () => this.onRematch?.());
     document.getElementById('exitBtn')!.addEventListener('click', () => this.onExit?.());
   }
@@ -87,13 +89,19 @@ export class UIManager {
     const confirmBtn = document.getElementById('confirmBtn')!;
     confirmBtn.style.display = isMyTurn && phase === 'astrogation' ? 'inline-block' : 'none';
 
+    const skipCombatBtn = document.getElementById('skipCombatBtn')!;
+    skipCombatBtn.style.display = isMyTurn && phase === 'combat' ? 'inline-block' : 'none';
+
     const statusMsg = document.getElementById('statusMsg')!;
     if (!isMyTurn) {
       statusMsg.textContent = 'Waiting for opponent...';
       statusMsg.style.display = 'block';
     } else if (phase === 'astrogation') {
       statusMsg.textContent = 'Select your ship and set a burn direction, then confirm';
       statusMsg.style.display = 'block';
+    } else if (phase === 'combat') {
+      statusMsg.textContent = 'Combat phase — skip or engage enemy ships';
+      statusMsg.style.display = 'block';
     } else {
       statusMsg.style.display = 'none';
     }

src/client/ui.ts

@@ -1,8 +1,8 @@
 import { DurableObject } from 'cloudflare:workers';
-import type { GameState, C2S, S2C, AstrogationOrder } from '../shared/types';
+import type { GameState, C2S, S2C, AstrogationOrder, CombatAttack } from '../shared/types';
 import { getSolarSystemMap, SCENARIOS, findBaseHex } from '../shared/map-data';
 import { INACTIVITY_TIMEOUT_MS } from '../shared/constants';
-import { createGame, processAstrogation } from '../shared/game-engine';
+import { createGame, processAstrogation, processCombat, skipCombat } from '../shared/game-engine';
 
 export interface Env {
   ASSETS: Fetcher;
@@ -103,6 +103,12 @@ export class GameDO extends DurableObject {
       case 'astrogation':
         await this.handleAstrogation(playerId, ws, msg.orders);
         break;
+      case 'combat':
+        await this.handleCombat(playerId, ws, msg.attacks);
+        break;
+      case 'skipCombat':
+        await this.handleSkipCombat(playerId, ws);
+        break;
       case 'rematch':
         await this.initGame();
         break;
@@ -148,21 +154,47 @@ export class GameDO extends DurableObject {
       return;
     }
 
-    // Broadcast movement results
-    this.broadcast({ type: 'movementResult', movements: result.movements, state: result.state });
+    this.broadcast({ type: 'movementResult', movements: result.movements, events: result.events, state: result.state });
+    this.broadcastEndOrUpdate(result.state);
+    await this.saveGameState(result.state);
+  }
+
+  private async handleCombat(playerId: number, ws: WebSocket, attacks: CombatAttack[]) {
+    const gameState = await this.getGameState();
+    if (!gameState) return;
+
+    const result = processCombat(gameState, playerId, attacks);
+
+    if ('error' in result) {
+      this.send(ws, { type: 'error', message: result.error });
+      return;
+    }
+
+    this.broadcast({ type: 'combatResult', results: result.results, state: result.state });
+    this.broadcastEndOrUpdate(result.state);
+    await this.saveGameState(result.state);
+  }
+
+  private async handleSkipCombat(playerId: number, ws: WebSocket) {
+    const gameState = await this.getGameState();
+    if (!gameState) return;
+
+    const result = skipCombat(gameState, playerId);
 
-    if (result.state.phase === 'gameOver') {
-      this.broadcast({
-        type: 'gameOver',
-        winner: result.state.winner!,
-        reason: result.state.winReason!,
-      });
+    if ('error' in result) {
+      this.send(ws, { type: 'error', message: result.error });
+      return;
     }
 
+    this.broadcast({ type: 'stateUpdate', state: result.state });
     await this.saveGameState(result.state);
+  }
 
-    if (result.state.phase !== 'gameOver') {
-      this.broadcast({ type: 'stateUpdate', state: result.state });
+  private broadcastEndOrUpdate(state: GameState) {
+    if (state.phase === 'gameOver') {
+      this.broadcast({ type: 'gameOver', winner: state.winner!, reason: state.winReason! });
+    } else {
+      this.broadcast({ type: 'stateUpdate', state });
     }
   }