Add Grand Tour race scenario

Checkpoint-based race where each player's corvette must pass through
gravity hexes of all 8 major bodies (Sol, Mercury, Venus, Terra, Mars,
Jupiter, Io, Callisto) and return home. No combat allowed; shared fuel
bases on Terra, Venus, Mars, and Callisto.

New engine features: visitedBodies/totalFuelSpent on PlayerState,
combatDisabled/checkpointBodies/sharedBases on ScenarioRules,
updateCheckpoints() helper in engine-victory, combat gating in
engine-combat. 10 new tests covering the full scenario lifecycle.

Author: rgilks

src/client/game-client-helpers.ts

@@ -41,6 +41,12 @@ function getSelectedShip(state: GameState, playerId: number, selectedId: string
 
 function getObjective(state: GameState, playerId: number): string {
   const player = state.players[playerId];
+  if (state.scenarioRules.checkpointBodies) {
+    const visited = player.visitedBodies?.length ?? 0;
+    const total = state.scenarioRules.checkpointBodies.length;
+    if (visited >= total) return `⬡ Return to ${player.homeBody}`;
+    return `⬡ Tour: ${visited}/${total} bodies visited`;
+  }
   const hasFugitiveShip = state.ships.some((ship) => ship.owner === playerId && ship.hasFugitives);
   const facingFugitives = state.scenarioRules.hiddenIdentityInspection;
   if (player.escapeWins) {
@@ -146,6 +152,12 @@ export function getScenarioBriefingLines(state: GameState, playerId: number): st
   const myShips = state.ships.filter((ship) => ship.owner === playerId);
   const shipNames = myShips.map((ship) => SHIP_STATS[ship.type]?.name ?? ship.type).join(', ');
   const lines = [`Your fleet: ${shipNames}`];
+  if (state.scenarioRules.checkpointBodies) {
+    lines.push(`Objective: Visit all ${state.scenarioRules.checkpointBodies.length} major bodies, then land on ${player.homeBody}`);
+    lines.push('No combat — race only');
+    lines.push('Press ? for controls help');
+    return lines;
+  }
   const hasFugitiveShip = myShips.some((ship) => ship.hasFugitives);
   const facingFugitives = state.scenarioRules.hiddenIdentityInspection;
   if (hasFugitiveShip) {

src/shared/__tests__/game-engine.test.ts

@@ -4,6 +4,7 @@ import { buildSolarSystemMap, SCENARIOS, findBaseHex, findBaseHexes } from '../m
 import { SHIP_STATS, ORDNANCE_MASS } from '../constants';
 import { hexKey, hexEqual, hexDistance } from '../hex';
 import { resolveBaseDefense } from '../combat';
+import { updateCheckpoints, checkImmediateVictory } from '../engine-victory';
 import type { GameState, ScenarioDefinition, SolarSystemMap, AstrogationOrder, OrdnanceLaunch, Ordnance, Ship } from '../types';
 
 let map: SolarSystemMap;
@@ -2480,3 +2481,147 @@ describe('fleet building (MegaCredit economy)', () => {
     }
   });
 });
+
+describe('Grand Tour', () => {
+  let tourState: GameState;
+
+  beforeEach(() => {
+    tourState = createGame(SCENARIOS.grandTour, map, 'TOUR1', findBaseHex);
+  });
+
+  it('initializes checkpoint tracking', () => {
+    expect(tourState.scenarioRules.checkpointBodies).toEqual(
+      ['Sol', 'Mercury', 'Venus', 'Terra', 'Mars', 'Jupiter', 'Io', 'Callisto'],
+    );
+    expect(tourState.scenarioRules.combatDisabled).toBe(true);
+    expect(tourState.players[0].visitedBodies).toBeDefined();
+    expect(tourState.players[0].totalFuelSpent).toBe(0);
+    expect(tourState.players[1].visitedBodies).toBeDefined();
+    expect(tourState.players[1].totalFuelSpent).toBe(0);
+  });
+
+  it('pre-marks starting body as visited', () => {
+    // Player 0 starts at Terra, Player 1 at Mars
+    expect(tourState.players[0].visitedBodies).toContain('Terra');
+    expect(tourState.players[1].visitedBodies).toContain('Mars');
+  });
+
+  it('gives both players shared bases for fuel', () => {
+    // Both players should have bases on Terra, Venus, Mars, and Callisto
+    const terraBaseKeys = findBaseHexes(map, 'Terra').map(h => hexKey(h));
+    const venusBaseKeys = findBaseHexes(map, 'Venus').map(h => hexKey(h));
+    const marsBaseKeys = findBaseHexes(map, 'Mars').map(h => hexKey(h));
+    const callistoBaseKeys = findBaseHexes(map, 'Callisto').map(h => hexKey(h));
+
+    for (const key of [...terraBaseKeys, ...venusBaseKeys, ...marsBaseKeys, ...callistoBaseKeys]) {
+      expect(tourState.players[0].bases).toContain(key);
+      expect(tourState.players[1].bases).toContain(key);
+    }
+  });
+
+  it('updates checkpoints when path crosses gravity hexes', () => {
+    // Find a Mercury gravity hex
+    const mercuryGravityHex = [...map.hexes.entries()]
+      .find(([, hex]) => hex.gravity?.bodyName === 'Mercury');
+    expect(mercuryGravityHex).toBeDefined();
+
+    const [keyStr] = mercuryGravityHex!;
+    const [q, r] = keyStr.split(',').map(Number);
+
+    updateCheckpoints(tourState, 0, [{ q, r }], map);
+    expect(tourState.players[0].visitedBodies).toContain('Mercury');
+    // Player 1 should be unaffected
+    expect(tourState.players[1].visitedBodies).not.toContain('Mercury');
+  });
+
+  it('does not duplicate visited bodies', () => {
+    const mercuryGravityHex = [...map.hexes.entries()]
+      .find(([, hex]) => hex.gravity?.bodyName === 'Mercury');
+    const [keyStr] = mercuryGravityHex!;
+    const [q, r] = keyStr.split(',').map(Number);
+
+    updateCheckpoints(tourState, 0, [{ q, r }], map);
+    updateCheckpoints(tourState, 0, [{ q, r }], map);
+    const count = tourState.players[0].visitedBodies!.filter(b => b === 'Mercury').length;
+    expect(count).toBe(1);
+  });
+
+  it('wins when all checkpoints visited and landed at home', () => {
+    // Mark all checkpoints as visited for player 0
+    tourState.players[0].visitedBodies = [...tourState.scenarioRules.checkpointBodies!];
+
+    // Land the ship at a Terra base
+    const ship = tourState.ships.find(s => s.owner === 0)!;
+    const terraBase = findBaseHexes(map, 'Terra')[0];
+    ship.position = terraBase;
+    ship.landed = true;
+    ship.destroyed = false;
+
+    // Run astrogation with no burns (ship is already landed)
+    // Directly test checkImmediateVictory by importing it
+    checkImmediateVictory(tourState, map);
+
+    expect(tourState.winner).toBe(0);
+    expect(tourState.winReason).toContain('Grand Tour complete');
+  });
+
+  it('does not win with incomplete checkpoints', () => {
+    // Mark only some checkpoints as visited
+    tourState.players[0].visitedBodies = ['Terra', 'Mercury', 'Venus'];
+
+    const ship = tourState.ships.find(s => s.owner === 0)!;
+    const terraBase = findBaseHexes(map, 'Terra')[0];
+    ship.position = terraBase;
+    ship.landed = true;
+    ship.destroyed = false;
+
+    checkImmediateVictory(tourState, map);
+
+    expect(tourState.winner).toBeNull();
+  });
+
+  it('does not win at wrong home body', () => {
+    // All checkpoints visited but landed at Mars (not home for player 0)
+    tourState.players[0].visitedBodies = [...tourState.scenarioRules.checkpointBodies!];
+
+    const ship = tourState.ships.find(s => s.owner === 0)!;
+    const marsBase = findBaseHexes(map, 'Mars')[0];
+    ship.position = marsBase;
+    ship.landed = true;
+    ship.destroyed = false;
+
+    checkImmediateVictory(tourState, map);
+
+    expect(tourState.winner).toBeNull();
+  });
+
+  it('skips combat phase when combatDisabled', () => {
+    // Move player 0's ship next to player 1's ship
+    const ship0 = tourState.ships.find(s => s.owner === 0)!;
+    const ship1 = tourState.ships.find(s => s.owner === 1)!;
+    ship0.position = { q: 0, r: 0 };
+    ship0.landed = false;
+    ship0.velocity = { dq: 0, dr: 0 };
+    ship1.position = { q: 1, r: 0 };
+    ship1.landed = false;
+    ship1.velocity = { dq: 0, dr: 0 };
+
+    // Process a turn — should skip combat
+    const result = processAstrogation(tourState, 0, [{ shipId: ship0.id, burn: null }], map);
+    // After movement, phase should not be 'combat'
+    expect(tourState.phase).not.toBe('combat');
+  });
+
+  it('tracks fuel consumption', () => {
+    const ship = tourState.ships.find(s => s.owner === 0)!;
+    ship.landed = false;
+    ship.velocity = { dq: 0, dr: 0 };
+    tourState.phase = 'astrogation';
+    tourState.activePlayer = 0;
+
+    const initialFuel = tourState.players[0].totalFuelSpent;
+    resolveAstrogationMovement(tourState, 0, [{ shipId: ship.id, burn: 0 }]);
+
+    expect(tourState.players[0].totalFuelSpent).toBe(initialFuel! + 1);
+  });
+});

src/shared/engine-combat.ts

@@ -78,6 +78,10 @@ export function processCombat(
     return { results, state };
   }
 
+  if (state.scenarioRules.combatDisabled && attacks.length > 0) {
+    return { error: 'Combat is not allowed in this scenario' };
+  }
+
   const committedAttackers = new Map<string, string>();
   const committedTargets = new Set<string>();
   const attackGroups = new Map<string, {
@@ -260,6 +264,9 @@ export function shouldEnterCombatPhase(state: GameState, map: SolarSystemMap): b
     return true;
   }
 
+  // No gun/base combat in race scenarios (asteroid hazards still resolve above)
+  if (state.scenarioRules.combatDisabled) return false;
+
   if (isPlanetaryDefenseEnabled(state) && hasBaseDefenseTargets(state, map)) {
     return true;
   }
@@ -274,6 +281,7 @@ function shouldRemainInCombatPhase(state: GameState, map?: SolarSystemMap): bool
   })) {
     return true;
   }
+  if (state.scenarioRules.combatDisabled) return false;
   if (!map) {
     return hasAnyEnemyShips(state);
   }

src/shared/engine-victory.ts

@@ -1,5 +1,5 @@
 import type { GameState, Ship, SolarSystemMap, MovementEvent } from './types';
-import { hexKey, hexVecLength, hexDistance, hexEqual } from './hex';
+import { type HexCoord, hexKey, hexVecLength, hexDistance, hexEqual } from './hex';
 import { SHIP_STATS, SHIP_DETECTION_RANGE, BASE_DETECTION_RANGE } from './constants';
 import { rollD6, lookupOtherDamage, applyDamage } from './combat';
 import {
@@ -28,12 +28,51 @@ export function advanceTurn(state: GameState): void {
   state.phase = 'astrogation';
 }
 
+/**
+ * Update checkpoint body visits for race scenarios.
+ * Checks each hex in the path for gravity or surface belonging to a checkpoint body.
+ */
+export function updateCheckpoints(state: GameState, playerId: number, path: HexCoord[], map: SolarSystemMap): void {
+  const checkpoints = state.scenarioRules.checkpointBodies;
+  const visited = state.players[playerId].visitedBodies;
+  if (!checkpoints || !visited) return;
+
+  for (const hex of path) {
+    const mapHex = map.hexes.get(hexKey(hex));
+    if (!mapHex) continue;
+    const bodyName = mapHex.gravity?.bodyName ?? mapHex.body?.name;
+    if (bodyName && checkpoints.includes(bodyName) && !visited.includes(bodyName)) {
+      visited.push(bodyName);
+    }
+  }
+}
+
 /**
  * Check immediate movement-based victory conditions.
  */
 export function checkImmediateVictory(state: GameState, map?: SolarSystemMap): void {
   if (!map) return;
 
+  // Checkpoint race victory: all bodies visited + landed at home
+  if (state.scenarioRules.checkpointBodies) {
+    for (const ship of state.ships) {
+      if (ship.destroyed || !ship.landed) continue;
+      const player = state.players[ship.owner];
+      if (!player.visitedBodies) continue;
+      const allVisited = state.scenarioRules.checkpointBodies.every(
+        b => player.visitedBodies!.includes(b),
+      );
+      if (!allVisited) continue;
+      const hex = map.hexes.get(hexKey(ship.position));
+      if (hex?.base?.bodyName === player.homeBody || hex?.body?.name === player.homeBody) {
+        state.winner = ship.owner;
+        state.winReason = `Grand Tour complete! Visited all ${state.scenarioRules.checkpointBodies.length} bodies.`;
+        state.phase = 'gameOver';
+        return;
+      }
+    }
+  }
+
   for (const ship of state.ships) {
     if (ship.destroyed || !ship.landed) continue;
     const targetBody = state.players[ship.owner].targetBody;

src/shared/game-engine.ts

@@ -15,7 +15,7 @@ import {
 } from './engine-util';
 import {
   advanceTurn, checkGameEnd, checkImmediateVictory,
-  updateEscapeMoralVictory,
+  updateEscapeMoralVictory, updateCheckpoints,
   checkRamming, checkInspection, checkCapture,
   checkOrbitalBaseResupply, applyResupply, updateDetection,
 } from './engine-victory';
@@ -70,6 +70,17 @@ function getScenarioStartingCredits(scenario: ScenarioDefinition, playerId: numb
     : scenario.startingCredits;
 }
 
+function getStartingVisitedBodies(ships: Ship[], playerId: number, map: SolarSystemMap): string[] {
+  const visited = new Set<string>();
+  for (const ship of ships) {
+    if (ship.owner !== playerId) continue;
+    const hex = map.hexes.get(hexKey(ship.position));
+    if (hex?.gravity?.bodyName) visited.add(hex.gravity.bodyName);
+    if (hex?.body?.name) visited.add(hex.body.name);
+  }
+  return [...visited];
+}
+
 function assertScenarioPlayerCount(scenario: ScenarioDefinition): void {
   if (scenario.players.length !== 2) {
     throw new Error(`Scenario must define exactly 2 players, got ${scenario.players.length}`);
@@ -145,6 +156,21 @@ export function createGame(
   const ships: Ship[] = [];
   const playerBases = scenario.players.map(player => resolveControlledBases(player, map));
 
+  // Shared bases: add fuel-body bases to both players (Grand Tour race)
+  if (scenario.rules?.sharedBases) {
+    const sharedBaseKeys = new Set<string>();
+    for (const [key, hex] of map.hexes) {
+      if (hex.base && scenario.rules.sharedBases.includes(hex.base.bodyName)) {
+        sharedBaseKeys.add(key);
+      }
+    }
+    for (const bases of playerBases) {
+      for (const key of sharedBaseKeys) {
+        if (!bases.includes(key)) bases.push(key);
+      }
+    }
+  }
+
   for (let p = 0; p < scenario.players.length; p++) {
     for (let s = 0; s < scenario.players[p].ships.length; s++) {
       const def = scenario.players[p].ships[s];
@@ -214,6 +240,13 @@ export function createGame(
       planetaryDefenseEnabled: scenario.rules?.planetaryDefenseEnabled ?? true,
       hiddenIdentityInspection: scenario.rules?.hiddenIdentityInspection ?? false,
       escapeEdge: scenario.rules?.escapeEdge ?? 'any',
+      combatDisabled: scenario.rules?.combatDisabled,
+      checkpointBodies: scenario.rules?.checkpointBodies
+        ? [...scenario.rules.checkpointBodies]
+        : undefined,
+      sharedBases: scenario.rules?.sharedBases
+        ? [...scenario.rules.sharedBases]
+        : undefined,
     },
     escapeMoralVictoryAchieved: false,
     turnNumber: 1,
@@ -234,6 +267,10 @@ export function createGame(
         bases: playerBases[0],
         escapeWins: scenario.players[0].escapeWins,
         credits: getScenarioStartingCredits(scenario, 0),
+        ...(scenario.rules?.checkpointBodies ? {
+          visitedBodies: getStartingVisitedBodies(ships, 0, map),
+          totalFuelSpent: 0,
+        } : {}),
       },
       {
         connected: true,
@@ -243,6 +280,10 @@ export function createGame(
         bases: playerBases[1],
         escapeWins: scenario.players[1].escapeWins,
         credits: getScenarioStartingCredits(scenario, 1),
+        ...(scenario.rules?.checkpointBodies ? {
+          visitedBodies: getStartingVisitedBodies(ships, 1, map),
+          totalFuelSpent: 0,
+        } : {}),
       },
     ],
     winner: null,
@@ -512,6 +553,19 @@ function resolveMovementPhase(
     }
   }
 
+  // Track checkpoint visits and fuel for race scenarios
+  if (state.scenarioRules.checkpointBodies) {
+    for (const m of movements) {
+      const ship = state.ships.find(s => s.id === m.shipId);
+      if (ship && !ship.destroyed) {
+        updateCheckpoints(state, ship.owner, m.path, map);
+        if (state.players[ship.owner].totalFuelSpent !== undefined) {
+          state.players[ship.owner].totalFuelSpent! += m.fuelSpent;
+        }
+      }
+    }
+  }
+
   checkOrbitalBaseResupply(state, playerId);
   checkInspection(state, playerId);
   checkCapture(state, playerId, events);