feat: v0.7.0 — server-authoritative sim engine: tick-on-read clock (time-scale + pause via POST /api/sim), contract expiry + market spawn, analytic plane movement/finalization

2026-09-17 12:38:52 +00:00
parent 7fdc43bc7e
commit 96835e935d
22 changed files with 1393 additions and 55 deletions
@@ -6,6 +6,7 @@ import {
  buildSeed,
  CONTRACT_COUNT_MAX,
  CONTRACT_COUNT_MIN,
+  generateContract,
  HUB_ICAO,
  mulberry32,
  REWARD_PER_KM,
@@ -88,7 +89,8 @@ describe('buildSeed', () => {
  it('seeds the starting account and sim state', () => {
    const seed = seedWith(42);
    expect(seed.account).toEqual({ cash: STARTING_CASH, reputation: STARTING_REPUTATION });
-    expect(seed.simState).toEqual({ clockMs: NOW, timeScale: 1, paused: false });
+    // lastRealTickMs starts at the seed moment so the first tick-on-read advances ~0.
+    expect(seed.simState).toEqual({ clockMs: NOW, timeScale: 1, paused: false, lastRealTickMs: NOW });
  });

  it('is fully deterministic for a fixed RNG and inputs', () => {
@@ -108,3 +110,57 @@ describe('buildSeed', () => {
    expect(rewardForDistanceKm(1000)).toBe(Math.round(BASE_REWARD + REWARD_PER_KM * 1000));
  });
 });
+
+describe('generateContract (shared seed/spawn builder)', () => {
+  it('builds an open contract between distinct fixture airports with the reward formula', () => {
+    const c = generateContract({ id: 'c-x', airports: AIRPORTS, rng: mulberry32(42), nowMs: NOW });
+
+    expect(c.id).toBe('c-x');
+    expect(c.status).toBe('open');
+    expect(c.planeId).toBeNull();
+    expect(c.createdSimTime).toBe(NOW);
+    const icaoSet = new Set(AIRPORTS.map((a) => a.icao));
+    expect(icaoSet.has(c.originIcao)).toBe(true);
+    expect(icaoSet.has(c.destIcao)).toBe(true);
+    expect(c.originIcao).not.toBe(c.destIcao);
+
+    const o = AIRPORTS.find((a) => a.icao === c.originIcao)!;
+    const d = AIRPORTS.find((a) => a.icao === c.destIcao)!;
+    expect(c.reward).toBe(Math.round(BASE_REWARD + REWARD_PER_KM * haversineKm(o.lat, o.lon, d.lat, d.lon)));
+
+    // Same 6–72h game-time deadline window as the seed.
+    expect(c.deadlineSimTime).toBeGreaterThan(NOW + 6 * 3_600_000 - 1);
+    expect(c.deadlineSimTime).toBeLessThanOrEqual(NOW + 72 * 3_600_000);
+  });
+
+  it('is deterministic for a fixed RNG and honors the id/nowMs inputs', () => {
+    const a = generateContract({ id: 'c-1', airports: AIRPORTS, rng: mulberry32(7), nowMs: NOW });
+    const b = generateContract({ id: 'c-1', airports: AIRPORTS, rng: mulberry32(7), nowMs: NOW });
+    expect(a).toEqual(b);
+
+    const c = generateContract({ id: 'c-2', airports: AIRPORTS, rng: mulberry32(8), nowMs: NOW + 1000 });
+    expect(c.id).toBe('c-2');
+    expect(c.createdSimTime).toBe(NOW + 1000);
+    expect(c.deadlineSimTime).not.toBe(a.deadlineSimTime); // different RNG/now → different contract
+  });
+
+  it('deadlineOffsetMs pins the deadline to now + offset (e2e expiry hook)', () => {
+    const c = generateContract({ id: 'c-hook', airports: AIRPORTS, rng: mulberry32(1), nowMs: NOW, deadlineOffsetMs: 10_000 });
+    expect(c.deadlineSimTime).toBe(NOW + 10_000);
+  });
+
+  it('buildSeed contracts are exactly the shared builder output (spawn matches seed)', () => {
+    const rngA = mulberry32(42);
+    const count = CONTRACT_COUNT_MIN + Math.floor(rngA() * (CONTRACT_COUNT_MAX - CONTRACT_COUNT_MIN + 1));
+    const expected: string[] = [];
+    for (let i = 0; i < count; i++) {
+      expected.push(JSON.stringify(generateContract({ id: `contract-${i + 1}`, airports: AIRPORTS, rng: rngA, nowMs: NOW })));
+    }
+    const seed = buildSeed({ airports: AIRPORTS, rng: mulberry32(42), nowMs: NOW });
+    expect(seed.contracts.map((c) => JSON.stringify(c))).toEqual(expected);
+  });
+
+  it('rejects an airport list too small to form a route', () => {
+    expect(() => generateContract({ id: 'c-x', airports: AIRPORTS.slice(0, 1), rng: mulberry32(42), nowMs: NOW })).toThrow();
+  });
+});
@@ -57,7 +57,7 @@ export interface SeedData {
  plane: SeedPlane;
  contracts: SeedContract[];
  account: { cash: number; reputation: number };
-  simState: { clockMs: number; timeScale: number; paused: false };
+  simState: { clockMs: number; timeScale: number; paused: false; lastRealTickMs: number };
 }

 // --- Tunables (documented so future revenue/cost work can build on them) ---
@@ -73,6 +73,10 @@ export const HUB_ICAO = 'EDDF'; // Frankfurt Main
 export const CONTRACT_COUNT_MIN = 8;
 export const CONTRACT_COUNT_MAX = 12; // inclusive

+// Market target (v0.7.0): the sim engine tops open contracts back up to this
+// count after expiries, so the job board never runs dry.
+export const MARKET_TARGET_OPEN_CONTRACTS = 10;
+
 // Reward formula (v0.6.0 — deliberately simple; real revenue/cost modeling is a
 // later increment): reward = BASE_REWARD + REWARD_PER_KM * great-circle km.
 export const BASE_REWARD = 500;
@@ -88,6 +92,50 @@ export function rewardForDistanceKm(km: number): number {
  return Math.round(BASE_REWARD + REWARD_PER_KM * km);
 }

+// Shared contract generator, used by BOTH the first-run seed and the runtime
+// market spawn (v0.7.0) so spawned contracts match seeded ones exactly: random
+// distinct airports from the dataset, distance-based reward, cargo flavor,
+// deadline now + 6–72h game time (or now + deadlineOffsetMs when given — used by
+// the e2e test hook to force a near-term expiry). The RNG call order per contract
+// is fixed: origin, dest, cargoType, cargoCount, [deadline window].
+export function generateContract(input: {
+  id: string;
+  airports: SeedAirport[];
+  rng: Rng;
+  nowMs: number;
+  deadlineOffsetMs?: number;
+}): SeedContract {
+  const { airports, rng, nowMs } = input;
+  if (airports.length < 2) throw new Error('contract generation needs at least two airports');
+
+  const oi = Math.floor(rng() * airports.length);
+  let di = Math.floor(rng() * airports.length);
+  if (di === oi) di = (di + 1) % airports.length;
+  const origin = airports[oi];
+  const dest = airports[di];
+
+  const km = haversineKm(origin.lat, origin.lon, dest.lat, dest.lon);
+  const cargoType = CARGO_TYPES[Math.floor(rng() * CARGO_TYPES.length)];
+  // Passengers up to the ATR 72's ~68 seats; other cargo in pallets.
+  const cargoCount =
+    cargoType === 'Passengers' ? 1 + Math.floor(rng() * 68) : 1 + Math.floor(rng() * 50);
+  const deadlineMs =
+    input.deadlineOffsetMs ?? (DEADLINE_MIN_HOURS + rng() * (DEADLINE_MAX_HOURS - DEADLINE_MIN_HOURS)) * 3_600_000;
+
+  return {
+    id: input.id,
+    originIcao: origin.icao,
+    destIcao: dest.icao,
+    reward: rewardForDistanceKm(km),
+    cargoType,
+    cargoCount,
+    deadlineSimTime: Math.round(nowMs + deadlineMs),
+    status: 'open',
+    planeId: null,
+    createdSimTime: nowMs,
+  };
+}
+
 function pickHub(airports: SeedAirport[]): SeedAirport {
  return airports.find((a) => a.icao === HUB_ICAO) ?? airports[0];
 }
@@ -116,41 +164,19 @@ export function buildSeed(input: {
  };

  const count = CONTRACT_COUNT_MIN + Math.floor(rng() * (CONTRACT_COUNT_MAX - CONTRACT_COUNT_MIN + 1));
+  // Stable index-based ids for the seed set; runtime-generated entities must use
+  // random UUIDs to avoid colliding with these.
  const contracts: SeedContract[] = [];
  for (let i = 0; i < count; i++) {
-    // Stable index-based ids for the seed set; runtime-generated entities must
-    // use random UUIDs to avoid colliding with these.
-    const oi = Math.floor(rng() * airports.length);
-    let di = Math.floor(rng() * airports.length);
-    if (di === oi) di = (di + 1) % airports.length;
-    const origin = airports[oi];
-    const dest = airports[di];
-
-    const km = haversineKm(origin.lat, origin.lon, dest.lat, dest.lon);
-    const cargoType = CARGO_TYPES[Math.floor(rng() * CARGO_TYPES.length)];
-    // Passengers up to the ATR 72's ~68 seats; other cargo in pallets.
-    const cargoCount =
-      cargoType === 'Passengers' ? 1 + Math.floor(rng() * 68) : 1 + Math.floor(rng() * 50);
-    const deadlineMs = (DEADLINE_MIN_HOURS + rng() * (DEADLINE_MAX_HOURS - DEADLINE_MIN_HOURS)) * 3_600_000;
-
-    contracts.push({
-      id: `contract-${i + 1}`,
-      originIcao: origin.icao,
-      destIcao: dest.icao,
-      reward: rewardForDistanceKm(km),
-      cargoType,
-      cargoCount,
-      deadlineSimTime: Math.round(nowMs + deadlineMs),
-      status: 'open',
-      planeId: null,
-      createdSimTime: nowMs,
-    });
+    contracts.push(generateContract({ id: `contract-${i + 1}`, airports, rng, nowMs }));
  }

  return {
    plane,
    contracts,
    account: { cash: STARTING_CASH, reputation: STARTING_REPUTATION },
-    simState: { clockMs: nowMs, timeScale: 1, paused: false },
+    // lastRealTickMs starts at the seed moment so the first tick-on-read advances
+    // by ~0 instead of treating "time since install" as elapsed play time.
+    simState: { clockMs: nowMs, timeScale: 1, paused: false, lastRealTickMs: nowMs },
  };
 }
@@ -1,6 +1,9 @@
 import { loadAirportsGeoJson } from '@/lib/airports';
+import { haversineKm } from '@/lib/geo';
 import { getGameDb } from '@/lib/db/client';
 import * as schema from '@/lib/db/schema';
+import { PLANE_TYPES } from './catalog';
+import { fuelAt, progressAt, positionAt } from '@/lib/sim/movement';

 // Read-only game-state snapshot for client polling (GET /api/state).

@@ -27,7 +30,7 @@ export interface ContractState {
  cargoType: string;
  cargoCount: number;
  deadlineSimTime: number;
-  status: 'open' | 'accepted' | 'completed';
+  status: 'open' | 'accepted' | 'completed' | 'expired';
  planeId: string | null;
  createdSimTime: number;
 }
@@ -57,22 +60,42 @@ export async function getStateSnapshot(): Promise<StateSnapshot> {
  const fc = await loadAirportsGeoJson();
  const nameByIcao = new Map(fc.features.map((f) => [f.properties.icao, f.properties.name]));
  const nameOf = (icao: string) => nameByIcao.get(icao) ?? icao;
+  const coordsByIcao = new Map(fc.features.map((f) => [f.properties.icao, f.properties]));
+
+  // Analytic movement (v0.7.0): a flying plane's stored lat/lon/fuel are its
+  // departure values — live position and fuel are pure functions of the clock.
+  const contractById = new Map(contractRows.map((c) => [c.id, c]));
+  const livePlane = (p: schema.PlaneRow) => {
+    if (p.status !== 'flying' || p.departureSimTime == null || !p.contractId) return null;
+    const contract = contractById.get(p.contractId);
+    const type = PLANE_TYPES[p.model];
+    const from = contract ? coordsByIcao.get(contract.originIcao) : undefined;
+    const to = contract ? coordsByIcao.get(contract.destIcao) : undefined;
+    if (!contract || !type || !from || !to) return null;
+    const distanceKm = haversineKm(from.lat, from.lon, to.lat, to.lon);
+    const progress = progressAt(p.departureSimTime, distanceKm, type.speedKmh, simRow.clockMs);
+    const pos = positionAt(from.lat, from.lon, to.lat, to.lon, progress);
+    return { ...pos, fuel: fuelAt(p.fuel, type.burnPerKm, distanceKm, progress) };
+  };

  return {
    account: { cash: accountRow.cash, reputation: accountRow.reputation },
    simState: { clockMs: simRow.clockMs, timeScale: simRow.timeScale, paused: simRow.paused },
-    planes: planeRows.map((p) => ({
-      id: p.id,
-      model: p.model,
-      status: p.status,
-      fuel: p.fuel,
-      maxFuel: p.maxFuel,
-      locationIcao: p.locationIcao,
-      locationName: nameOf(p.locationIcao),
-      contractId: p.contractId,
-      lat: p.lat,
-      lon: p.lon,
-    })),
+    planes: planeRows.map((p) => {
+      const live = livePlane(p);
+      return {
+        id: p.id,
+        model: p.model,
+        status: p.status,
+        fuel: live?.fuel ?? p.fuel,
+        maxFuel: p.maxFuel,
+        locationIcao: p.locationIcao,
+        locationName: nameOf(p.locationIcao),
+        contractId: p.contractId,
+        lat: live?.lat ?? p.lat,
+        lon: live?.lon ?? p.lon,
+      };
+    }),
    contracts: contractRows.map((c) => ({
      id: c.id,
      originIcao: c.originIcao,