Extract client AI phase planning helpers

Author: rgilks

src/client/game-client-ai-flow.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { buildSolarSystemMap } from '../shared/map-data';
+import type {
+  AstrogationOrder,
+  CombatAttack,
+  GameState,
+  OrdnanceLaunch,
+  PlayerState,
+  Ship,
+} from '../shared/types';
+import { deriveAIActionPlan } from './game-client-ai-flow';
+
+function createShip(overrides: Partial<Ship> = {}): Ship {
+  return {
+    id: 'ship-1',
+    type: 'packet',
+    owner: 1,
+    position: { q: 0, r: 0 },
+    velocity: { dq: 0, dr: 0 },
+    fuel: 10,
+    cargoUsed: 0,
+    nukesLaunchedSinceResupply: 0,
+    resuppliedThisTurn: false,
+    landed: false,
+    destroyed: false,
+    detected: true,
+    damage: { disabledTurns: 0 },
+    ...overrides,
+  };
+}
+
+function createPlayers(): [PlayerState, PlayerState] {
+  return [
+    { connected: true, ready: true, targetBody: 'Mars', homeBody: 'Terra', bases: [], escapeWins: false },
+    { connected: true, ready: true, targetBody: 'Terra', homeBody: 'Mars', bases: [], escapeWins: false },
+  ];
+}
+
+function createState(overrides: Partial<GameState> = {}): GameState {
+  return {
+    gameId: 'AI',
+    scenario: 'test',
+    scenarioRules: {},
+    escapeMoralVictoryAchieved: false,
+    turnNumber: 2,
+    phase: 'astrogation',
+    activePlayer: 1,
+    ships: [
+      createShip({ id: 'player-ship', owner: 0, position: { q: 3, r: 0 } }),
+      createShip({ id: 'ai-ship', owner: 1 }),
+    ],
+    ordnance: [],
+    pendingAstrogationOrders: null,
+    pendingAsteroidHazards: [],
+    destroyedAsteroids: [],
+    destroyedBases: [],
+    players: createPlayers(),
+    winner: null,
+    winReason: null,
+    ...overrides,
+  };
+}
+
+describe('game-client-ai-flow', () => {
+  it('returns none when there is no active AI turn', () => {
+    const map = buildSolarSystemMap();
+
+    expect(deriveAIActionPlan(null, 0, map, 'normal')).toEqual({ kind: 'none' });
+    expect(deriveAIActionPlan(createState({ activePlayer: 0 }), 0, map, 'normal')).toEqual({ kind: 'none' });
+    expect(deriveAIActionPlan(createState({ phase: 'gameOver' }), 0, map, 'normal')).toEqual({ kind: 'none' });
+  });
+
+  it('derives astrogation actions from the injected generator', () => {
+    const map = buildSolarSystemMap();
+    const orders: AstrogationOrder[] = [{ shipId: 'ai-ship', burn: 2 }];
+    const astrogation = vi.fn(() => orders);
+
+    expect(deriveAIActionPlan(createState({ phase: 'astrogation' }), 0, map, 'normal', {
+      astrogation,
+      ordnance: vi.fn(() => []),
+      combat: vi.fn(() => []),
+    })).toEqual({
+      kind: 'astrogation',
+      aiPlayer: 1,
+      orders,
+      errorPrefix: 'AI astrogation error:',
+    });
+  });
+
+  it('derives ordnance actions, skip behavior, and log entries', () => {
+    const map = buildSolarSystemMap();
+    const launches: OrdnanceLaunch[] = [{ shipId: 'ai-ship', ordnanceType: 'mine' }];
+
+    expect(deriveAIActionPlan(createState({ phase: 'ordnance' }), 0, map, 'normal', {
+      astrogation: vi.fn(() => []),
+      ordnance: vi.fn(() => launches),
+      combat: vi.fn(() => []),
+    })).toEqual({
+      kind: 'ordnance',
+      aiPlayer: 1,
+      launches,
+      logEntries: ['AI: Packet launched mine'],
+      skip: false,
+      errorPrefix: 'AI ordnance error:',
+    });
+
+    expect(deriveAIActionPlan(createState({ phase: 'ordnance' }), 0, map, 'normal', {
+      astrogation: vi.fn(() => []),
+      ordnance: vi.fn(() => []),
+      combat: vi.fn(() => []),
+    })).toEqual({
+      kind: 'ordnance',
+      aiPlayer: 1,
+      launches: [],
+      logEntries: [],
+      skip: true,
+      errorPrefix: 'AI skip ordnance error:',
+    });
+  });
+
+  it('derives combat actions, including pending-hazard start and skip paths', () => {
+    const map = buildSolarSystemMap();
+    const attacks: CombatAttack[] = [{ attackerIds: ['ai-ship'], targetId: 'player-ship' }];
+
+    expect(deriveAIActionPlan(createState({
+      phase: 'combat',
+      pendingAsteroidHazards: [{ shipId: 'ai-ship', hex: { q: 0, r: 0 } }],
+    }), 0, map, 'normal')).toEqual({
+      kind: 'beginCombat',
+      aiPlayer: 1,
+      errorPrefix: 'AI combat start error:',
+    });
+
+    expect(deriveAIActionPlan(createState({ phase: 'combat' }), 0, map, 'normal', {
+      astrogation: vi.fn(() => []),
+      ordnance: vi.fn(() => []),
+      combat: vi.fn(() => attacks),
+    })).toEqual({
+      kind: 'combat',
+      aiPlayer: 1,
+      attacks,
+      skip: false,
+      errorPrefix: 'AI combat error:',
+    });
+
+    expect(deriveAIActionPlan(createState({ phase: 'combat' }), 0, map, 'normal', {
+      astrogation: vi.fn(() => []),
+      ordnance: vi.fn(() => []),
+      combat: vi.fn(() => []),
+    })).toEqual({
+      kind: 'combat',
+      aiPlayer: 1,
+      attacks: [],
+      skip: true,
+      errorPrefix: 'AI skip combat error:',
+    });
+  });
+
+  it('falls back to transition for non-action AI phases', () => {
+    const map = buildSolarSystemMap();
+
+    expect(deriveAIActionPlan(createState({ phase: 'resupply' }), 0, map, 'normal')).toEqual({
+      kind: 'transition',
+      aiPlayer: 1,
+    });
+  });
+});

src/client/game-client-ai-flow.ts

@@ -0,0 +1,124 @@
+import { aiAstrogation, aiCombat, aiOrdnance, type AIDifficulty } from '../shared/ai';
+import { SHIP_STATS } from '../shared/constants';
+import { filterStateForPlayer } from '../shared/game-engine';
+import type {
+  AstrogationOrder,
+  CombatAttack,
+  GameState,
+  OrdnanceLaunch,
+  SolarSystemMap,
+} from '../shared/types';
+import { hasOwnedPendingAsteroidHazards } from './game-client-local';
+
+export interface AIDecisionGenerators {
+  astrogation: typeof aiAstrogation;
+  ordnance: typeof aiOrdnance;
+  combat: typeof aiCombat;
+}
+
+export type AIActionPlan =
+  | { kind: 'none' }
+  | {
+      kind: 'astrogation';
+      aiPlayer: number;
+      orders: AstrogationOrder[];
+      errorPrefix: 'AI astrogation error:';
+    }
+  | {
+      kind: 'ordnance';
+      aiPlayer: number;
+      launches: OrdnanceLaunch[];
+      logEntries: string[];
+      skip: boolean;
+      errorPrefix: 'AI ordnance error:' | 'AI skip ordnance error:';
+    }
+  | {
+      kind: 'beginCombat';
+      aiPlayer: number;
+      errorPrefix: 'AI combat start error:';
+    }
+  | {
+      kind: 'combat';
+      aiPlayer: number;
+      attacks: CombatAttack[];
+      skip: boolean;
+      errorPrefix: 'AI combat error:' | 'AI skip combat error:';
+    }
+  | {
+      kind: 'transition';
+      aiPlayer: number;
+    };
+
+function buildAIOrdnanceLogEntries(state: GameState, launches: OrdnanceLaunch[]): string[] {
+  return launches.map((launch) => {
+    const ship = state.ships.find((candidate) => candidate.id === launch.shipId);
+    const name = ship ? (SHIP_STATS[ship.type]?.name ?? ship.type) : launch.shipId;
+    return `AI: ${name} launched ${launch.ordnanceType}`;
+  });
+}
+
+export function deriveAIActionPlan(
+  state: GameState | null,
+  playerId: number,
+  map: SolarSystemMap,
+  difficulty: AIDifficulty,
+  generators: AIDecisionGenerators = {
+    astrogation: aiAstrogation,
+    ordnance: aiOrdnance,
+    combat: aiCombat,
+  },
+): AIActionPlan {
+  if (!state || state.phase === 'gameOver') {
+    return { kind: 'none' };
+  }
+
+  const aiPlayer = state.activePlayer;
+  if (aiPlayer === playerId) {
+    return { kind: 'none' };
+  }
+
+  if (state.phase === 'astrogation') {
+    return {
+      kind: 'astrogation',
+      aiPlayer,
+      orders: generators.astrogation(filterStateForPlayer(state, aiPlayer), aiPlayer, map, difficulty),
+      errorPrefix: 'AI astrogation error:',
+    };
+  }
+
+  if (state.phase === 'ordnance') {
+    const launches = generators.ordnance(filterStateForPlayer(state, aiPlayer), aiPlayer, map, difficulty);
+    return {
+      kind: 'ordnance',
+      aiPlayer,
+      launches,
+      logEntries: buildAIOrdnanceLogEntries(state, launches),
+      skip: launches.length === 0,
+      errorPrefix: launches.length > 0 ? 'AI ordnance error:' : 'AI skip ordnance error:',
+    };
+  }
+
+  if (state.phase === 'combat') {
+    if (hasOwnedPendingAsteroidHazards(state, aiPlayer)) {
+      return {
+        kind: 'beginCombat',
+        aiPlayer,
+        errorPrefix: 'AI combat start error:',
+      };
+    }
+
+    const attacks = generators.combat(filterStateForPlayer(state, aiPlayer), aiPlayer, map, difficulty);
+    return {
+      kind: 'combat',
+      aiPlayer,
+      attacks,
+      skip: attacks.length === 0,
+      errorPrefix: attacks.length > 0 ? 'AI combat error:' : 'AI skip combat error:',
+    };
+  }
+
+  return {
+    kind: 'transition',
+    aiPlayer,
+  };
+}