Jesse.Markowitz/station-master
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Expand game engine, replay, tests, and documentation

Browse Source
This commit is contained in:
Jesse
2026-07-31 08:10:54 -04:00
parent e7bc07df85
commit 401b879140
30 changed files with 2253 additions and 552 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/sim/replay.ts
+188 -34
View File
@@ -21,14 +21,14 @@ import { writeFileSync } from 'node:fs';
import { advance } from '../engine/advance.ts';
import { applyIntent, areaOf, facilityCarType, laborersLeft, portersLeft } from '../engine/apply.ts';
import type { GameLength } from '../engine/content.ts';
import { lengthProfile, officeProfile } from '../engine/content.ts';
import { MAINLINE_PROFILES, lengthProfile, officeProfile } from '../engine/content.ts';
import type { GameEvent } from '../engine/events.ts';
import { legalActions } from '../engine/legal.ts';
import { createGame } from '../engine/setup.ts';
import type { GameConfig, GameState } from '../engine/state.ts';
import { developerBot } from './bot.ts';
import type { Impediment } from './narrate.ts';
import { carLabel, clockTime, impediments, isVisible, narrate, phaseLabel } from './narrate.ts';
import { carLabel, clockTime, idleNote, impediments, isVisible, narrate, phaseLabel } from './narrate.ts';
// ---------------------------------------------------------------------------
// Frame shape — only what the viewer draws
@@ -60,7 +60,8 @@ export type FacilityView = {
porters: string;
};
export type DivisionView = { kind: string; label: string; trains: string[][] };
export type TrainChip = { label: string; consist: string[] };
export type DivisionView = { kind: string; label: string; trains: TrainChip[][] };
export type Frame = {
day: number;
@@ -72,11 +73,16 @@ export type Frame = {
revenue: number;
lines: { text: string; tone: string }[];
where: { row: number; col: number } | null;
/** Origin of a Move, so the crew's journey is visible rather than a chip teleporting. */
whereFrom: { row: number; col: number } | null;
division: DivisionView[];
cells: CellView[];
facilities: FacilityView[];
hand: number;
hand: string[];
deck: number;
departments: string[];
/** 12 slots; the train number due out at each Stage, or null. */
timetable: (number | null)[];
blocked: Impediment[];
trains: { label: string; where: string }[];
};
@@ -93,14 +99,22 @@ const FACILITY_NAMES: Record<string, string> = {
powerPlant: 'Power Plant',
};
function facilityView(card: { geometry: { kind: string; facility?: string }; facility: NonNullable<CellView['facility']> extends never ? never : unknown }): FacilityView | null {
function facilityView(
card: { geometry: { kind: string; facility?: string }; facility: unknown },
officeName: string,
): FacilityView | null {
const f = (card as { facility: import('../engine/state.ts').Facility | null }).facility;
if (!f || f.kind !== 'freight') return null;
// Passenger facilities were excluded entirely, so the Office's green and red slots never
// appeared — which is why stocking a coach into the green box looked like nothing happening.
if (!f) return null;
if (f.kind === 'passenger' && f.porters === 0 && f.capacity.outbound === 0) return null;
const key = card.geometry.kind === 'facility' ? (card.geometry.facility ?? '') : '';
return {
name: FACILITY_NAMES[key] ?? key,
name: f.kind === 'passenger' ? officeName + ' (passengers)' : (FACILITY_NAMES[key] ?? key),
commodity: facilityCarType(f) ?? '?',
flow: f.allows.outbound && f.allows.inbound ? 'both' : f.allows.outbound ? 'ships out' : 'receives',
flow: f.kind === 'passenger'
? 'passengers on and off'
: f.allows.outbound && f.allows.inbound ? 'both' : f.allows.outbound ? 'ships out' : 'receives',
green: f.outboundBox.map(carLabel),
greenCap: f.capacity.outbound,
maw: f.menAtWork.map((l) => (l ? `${l.type} ${l.dir === 'out' ? '→' : '←'}` : null)),
@@ -117,13 +131,15 @@ function snapshot(
s: GameState,
lines: { text: string; tone: string }[],
where: { row: number; col: number } | null,
whereFrom: { row: number; col: number } | null = null,
): Frame {
const area = areaOf(s, 0);
const trayAt = new Map<string, string>();
for (const [id, tray] of s.trays) {
if (tray.position.at === 'grid') {
const label = tray.trainNumber === null ? 'crew' : `T${tray.trainIsExtra ? 'X' : ''}${tray.trainNumber}`;
trayAt.set(`${tray.position.coord.row},${tray.position.coord.col}`, label);
const carrying = tray.consist.length ? ` [${tray.consist.map(carLabel).join(', ')}]` : ' [empty]';
trayAt.set(`${tray.position.coord.row},${tray.position.coord.col}`, label + carrying);
}
}
@@ -137,9 +153,10 @@ function snapshot(
if (g.kind === 'office') label = officeProfile(area.tier).name;
else if (g.kind === 'limits') label = 'Limits';
else if (g.kind === 'facility') label = FACILITY_NAMES[g.facility] ?? g.facility;
else label = g.geometry === 'runAround' ? 'run-around' : g.geometry;
else if (g.kind === 'modifier') label = MODIFIER_NAMES[g.modifier] ?? g.modifier;
else label = g.geometry === 'sharpCurved' ? 'sharp curve' : g.geometry;
const fv = facilityView(card as never);
const fv = facilityView(card as never, officeProfile(area.tier).name);
if (fv) facilities.push(fv);
cells.push({
@@ -163,10 +180,16 @@ function snapshot(
};
}
if (n.kind === 'mainline') {
// Crossing time is in Stages now, so a Mainline card shows its terrain and the trains on it
// with how long each still has to run.
const name = MAINLINE_PROFILES.find((m) => m.kind === n.card)?.name ?? n.card;
return {
kind: 'ml',
label: 'Mainline',
trains: n.regions.map((r) => (r.occupant ? [trainChip(s, r.occupant)] : [])),
label: name,
trains: [n.transits.map((t) => {
const chip = trainChip(s, t.tray);
return { ...chip, label: `${chip.label} (${t.stagesRemaining})` };
})],
};
}
return {
@@ -186,11 +209,14 @@ function snapshot(
revenue: s.players[0]?.revenue ?? 0,
lines,
where,
whereFrom,
division,
cells,
facilities,
hand: (s.decks.hands.get(0) ?? []).length,
hand: (s.decks.hands.get(0) ?? []).map((id) => cardName(s, id)),
deck: s.decks.homeOffice.length,
departments: s.decks.departments.map((id) => (id ? cardName(s, id) : '—')),
timetable: [...s.timetable],
blocked: impediments(s, 0),
trains: [...s.trays.values()].map((t) => ({
label: t.trainNumber === null ? 'local crew' : `Train ${t.trainIsExtra ? 'X' : ''}${t.trainNumber}`,
@@ -198,16 +224,59 @@ function snapshot(
t.position.at === 'divisionPoint'
? `${t.position.side} Division Point`
: t.position.at === 'mainline'
? `Mainline ${t.position.index}, region ${t.position.region + 1}`
? `Mainline card ${t.position.index}`
: `Office Area (${t.position.coord.row},${t.position.coord.col})`,
})),
};
}
function trainChip(s: GameState, id: string): string {
/** A card id turned into something a person can read. */
export function cardName(s: GameState, id: string): string {
const k = s.cards.get(id)?.kind;
if (!k) return 'a card';
switch (k.kind) {
case 'timetabledTrain':
return `Train ${k.number}`;
case 'extraTrain':
return `Extra X${k.number}`;
case 'office':
return `${k.tier.replace(/([A-Z])/g, ' $1').replace(/^./, (c) => c.toUpperCase())} upgrade`;
case 'freightFacility':
return FACILITY_NAMES[k.facility] ?? k.facility;
case 'modifier':
return MODIFIER_NAMES[k.modifier] ?? k.modifier;
case 'track':
return k.geometry === 'sharpCurved' ? 'Sharp curve' : `${k.geometry} track`;
case 'spaceUse':
case 'enhancement':
case 'mainlineModifier':
case 'maneuver':
case 'action':
return prettyKey(k.key);
}
}
/** camelCase key → readable name, for the card categories that carry only a key. */
function prettyKey(key: string): string {
return key.replace(/([A-Z])/g, ' $1').replace(/^./, (c) => c.toUpperCase());
}
const MODIFIER_NAMES: Record<string, string> = {
teamTrack: 'Team Track',
loadingDock: 'Loading Dock',
storageShed: 'Storage Shed',
extraPlatform: 'Extra Platform',
sectionGang: 'Section Gang',
};
/** A train on the board, with what it is carrying — otherwise a run looks identical empty or full. */
function trainChip(s: GameState, id: string): TrainChip {
const t = s.trays.get(id);
if (!t) return id;
return t.trainNumber === null ? 'crew' : `T${t.trainIsExtra ? 'X' : ''}${t.trainNumber}`;
if (!t) return { label: id, consist: [] };
return {
label: t.trainNumber === null ? 'crew' : `T${t.trainIsExtra ? 'X' : ''}${t.trainNumber}`,
consist: t.consist.map(carLabel),
};
}
// ---------------------------------------------------------------------------
@@ -230,16 +299,40 @@ export function record(seed: number, length: GameLength, maxSteps = 100_000): Re
};
const s = createGame({ id: `replay-${seed}`, seed, config, playerNames: ['player'] });
const frames: Frame[] = [];
const narrateCtx = { cardName: (id: string) => cardName(s, id) };
// Tracks whether a phase did anything, so an empty one can say so rather than ending silently.
let didSomething = false;
const push = (events: GameEvent[]): void => {
const visible = events.filter(isVisible);
if (visible.length === 0) return;
const narrated = visible.map(narrate);
const where = narrated.find((n) => n.where)?.where ?? null;
frames.push(snapshot(s, narrated.map((n) => ({ text: n.text, tone: n.tone })), where ?? null));
const lines: { text: string; tone: string }[] = [];
for (const e of visible) {
if (e.type === 'phaseBegan') didSomething = false;
if (e.type === 'phaseEnded' && !didSomething) {
lines.push({ text: idleNote(e.phase), tone: 'quiet' });
}
if (
e.type !== 'phaseBegan' &&
e.type !== 'phaseEnded' &&
e.type !== 'stageBegan'
) {
didSomething = true;
}
const n = narrate(e, narrateCtx);
lines.push({ text: n.text, tone: n.tone });
}
const where = visible.map((e) => narrate(e, narrateCtx)).find((n) => n.where)?.where ?? null;
const moved = visible.find((e) => e.type === 'trayMoved');
const from = moved && moved.type === 'trayMoved' ? moved.from : null;
frames.push(snapshot(s, lines, where ?? null, from));
};
frames.push(snapshot(s, [{ text: 'Game begins — the Division has just been spiked down.', tone: 'clock' }], null));
frames.push(
snapshot(s, [{ text: 'Game begins — the Division has just been spiked down.', tone: 'clock' }], null),
);
for (let step = 0; step < maxSteps; step++) {
const r = advance(s);
@@ -299,6 +392,10 @@ h2{font-size:11px;letter-spacing:.09em;text-transform:uppercase;color:var(--dim)
.cell{border:1px solid var(--line);border-radius:5px;padding:6px;min-height:64px;background:#20252c}
.cell.run{border-color:#4a545f;background:#252b33}
.cell.hl{outline:2px solid var(--warn);outline-offset:1px}
.cell.from{outline:2px dashed #6b7480;outline-offset:1px}
/* The crew is the thing you follow around the yard, so it gets the loudest treatment on the card. */
.crew{background:var(--warn);color:#0d1117;font-weight:700;border-radius:4px;padding:3px 6px;
margin-top:5px;font-size:11px;line-height:1.35}
.cell .nm{font-weight:700;font-size:11px}
.cell .cars{color:var(--dim);font-size:10.5px;margin-top:3px}
.cell .tray{display:inline-block;margin-top:4px}
@@ -313,13 +410,27 @@ h2{font-size:11px;letter-spacing:.09em;text-transform:uppercase;color:var(--dim)
.t-quiet{color:var(--dim)}.t-plain{color:var(--fg)}
.blocked li{margin-bottom:4px}
.sev-stuck{color:var(--bad)}.sev-risk{color:var(--warn)}.sev-waiting{color:var(--dim)}
footer{position:sticky;bottom:0;background:var(--bg);border-top:1px solid var(--line);padding:9px 14px;
display:flex;gap:8px;align-items:center;flex-wrap:wrap;z-index:5}
/* FIXED, not sticky: a sticky footer shifts as panel heights change, so the mouse cannot stay
parked on one button and keep clicking. */
footer{position:fixed;left:0;right:0;bottom:0;background:var(--bg);border-top:1px solid var(--line);
padding:9px 14px;display:flex;gap:8px;align-items:center;flex-wrap:nowrap;z-index:10;overflow-x:auto}
body{padding-bottom:64px}
button{background:#2a3038;color:var(--fg);border:1px solid var(--line);border-radius:5px;padding:5px 11px;
font:inherit;cursor:pointer}
button:hover{background:#343b45}
input[type=range]{flex:1;min-width:180px}
.legend{font-size:11px;color:var(--dim);padding:0 14px 14px}
kbd{background:#2a3038;border:1px solid var(--line);border-radius:3px;padding:0 4px;font-size:10px}
.tt{display:grid;grid-template-columns:repeat(12,1fr);gap:3px}
.tt div{border:1px solid var(--line);border-radius:3px;padding:3px 2px;text-align:center;font-size:10.5px}
.tt div.due{background:var(--clock);color:#0d1117;font-weight:700}
.tt div.now{outline:2px solid var(--warn)}
.card{display:inline-block;border:1px solid var(--line);border-radius:3px;padding:1px 6px;margin:2px 3px 0 0;font-size:11px;background:#20252c}
.consist{font-size:10px;color:var(--dim);margin-top:2px}
.mini{margin-top:4px;font-size:9.5px;line-height:1.8}
.mini .box{padding:0 4px;font-size:9.5px}
.cell.office{border-color:var(--clock)}
.cell.modifier{border-style:dashed;opacity:.85}
</style></head><body>
<header>
@@ -329,7 +440,7 @@ input[type=range]{flex:1;min-width:180px}
<span>phase <b id="phase">—</b></span>
<span class="dim">actor <span id="actor">—</span> · fedora <span id="super">—</span></span>
<span>revenue <b class="big" id="rev">0</b></span>
<span class="dim">hand <span id="hand">0</span> · deck <span id="deck">0</span></span>
<span class="dim">deck <span id="deck">0</span></span>
<span class="dim">frame <span id="fno">0</span>/<span id="ftot">0</span></span>
</div>
</header>
@@ -339,9 +450,14 @@ input[type=range]{flex:1;min-width:180px}
<section><h2>Division — west to east</h2><div class="div-strip" id="division"></div></section>
<section><h2>Office Area</h2><div class="grid" id="grid"></div></section>
<section><h2>Facilities</h2><div id="facs"></div></section>
<section><h2>Timetable — which train is due out at each Stage</h2><div id="tt"></div></section>
</div>
<div>
<section><h2>What just happened</h2><div id="now"></div></section>
<section><h2>Cards</h2>
<div><span class="dim">your hand:</span> <span id="hand">—</span></div>
<div style="margin-top:5px"><span class="dim">face-up Department slots:</span> <span id="depts">—</span></div>
</section>
<section><h2>Blocked — why nothing is moving</h2><ul class="blocked" id="blocked"></ul></section>
<section><h2>Trains in play</h2><div id="trains" class="dim"></div></section>
<section><h2>History</h2><div class="log" id="log"></div></section>
@@ -349,7 +465,13 @@ input[type=range]{flex:1;min-width:180px}
</div>
<div class="legend">
Running Track is the lighter row. <span class="chip">T4</span> is a train. Green box = outbound loads waiting ·
<b>Keyboard:</b> <kbd>←</kbd>/<kbd>→</kbd> step · <kbd>space</kbd> play/pause ·
<kbd>Home</kbd>/<kbd>End</kbd> first/last · <kbd>S</kbd> next Stage · <kbd>R</kbd> next revenue change ·
<kbd>C</kbd> next collision.<br>
Running Track is the lighter row. <span class="chip">T4</span> is a train on the Division;
<span style="background:var(--warn);color:#0d1117;font-weight:700;border-radius:3px;padding:0 4px">🚂 T4</span>
is the crew in your yard — it carries the whole train with it as it moves, and a dashed outline
marks where it came from. Green box = outbound loads waiting ·
MEN / AT / WORK = the three-step loading track (→ outbound, ← inbound) · red box = delivered loads.
Laborers and Porters show remaining/total for this Stage.
</div>
@@ -364,7 +486,8 @@ input[type=range]{flex:1;min-width:180px}
<button id="crash">next collision ⚠</button>
<input type="range" id="scrub" min="0" value="0">
<select id="speed">
<option value="600">slow</option>
<option value="3000">extra slow</option>
<option value="1200">slow</option>
<option value="250" selected>normal</option>
<option value="90">fast</option>
<option value="20">very fast</option>
@@ -377,6 +500,17 @@ let i = 0, timer = null;
const $ = (id) => document.getElementById(id);
const esc = (s) => String(s).replace(/[&<>]/g, (c) => ({'&':'&amp;','<':'&lt;','>':'&gt;'}[c]));
// The green / MEN|AT|WORK / red boxes drawn on the card itself, so a Freight Agent action or a
// Porter boarding shows up where it happened rather than only in a side panel.
function miniFacility(x) {
let h = '<div class="mini">';
if (x.greenCap > 0) h += '<span class="dim">grn </span>' + boxes(x.green, x.greenCap, 'g');
if (x.trackCap > 0) h += '<br><span class="dim">work </span>' +
x.maw.map((m) => '<span class="box ' + (m ? 'm' : 'empty') + '">' + (m ? esc(m) : '·') + '</span>').join('');
if (x.redCap > 0) h += '<br><span class="dim">red </span>' + boxes(x.red, x.redCap, 'r');
return h + '</div>';
}
function boxes(items, cap, cls) {
let h = '';
for (let k = 0; k < Math.max(cap, items.length); k++) {
@@ -394,15 +528,27 @@ function render() {
$('super').textContent = 'P' + f.superintendent;
$('rev').textContent = f.revenue;
$('rev').className = 'big ' + (f.revenue < 0 ? 't-bad' : f.revenue > 0 ? 't-good' : '');
$('hand').textContent = f.hand;
$('deck').textContent = f.deck;
$('hand').innerHTML = f.hand.length
? f.hand.map((c) => '<span class="card">' + esc(c) + '</span>').join('')
: '<span class="dim">empty</span>';
$('depts').innerHTML = f.departments.map((c) => '<span class="card">' + esc(c) + '</span>').join('');
$('tt').innerHTML = '<div class="tt">' + f.timetable.map((t, k) =>
'<div class="' + (t !== null ? 'due ' : '') + (k + 1 === f.stage ? 'now' : '') + '">' +
'S' + (k + 1) + '<br>' + (t !== null ? 'T' + t : '·') + '</div>').join('') + '</div>' +
'<div class="dim" style="margin-top:5px">The NUMBER of a train is its seniority and direction ' +
'(odd = westbound, even = eastbound). The Stage it departs is set by a 1D12 roll when its card ' +
'was played — so Train 8 leaving at Stage 6 is normal.</div>';
$('fno').textContent = i;
$('scrub').value = i;
$('division').innerHTML = f.division.map((n) =>
'<div class="node ' + (n.kind === 'office' ? 'office' : '') + '"><div class="nm">' + esc(n.label) + '</div>' +
'<div class="regions">' + n.trains.map((r) =>
'<div class="region">' + r.map((t) => '<span class="chip">' + esc(t) + '</span>').join('') + '</div>').join('') +
'<div class="region">' + r.map((t) =>
'<span class="chip">' + esc(t.label) + '</span>' +
'<div class="consist">' + (t.consist.length ? esc(t.consist.join(', ')) : 'empty') + '</div>'
).join('') + '</div>').join('') +
'</div></div>').join('');
const rows = f.cells.map((c) => c.row), cols = f.cells.map((c) => c.col);
@@ -415,11 +561,14 @@ function render() {
const cell = f.cells.find((x) => x.row === r && x.col === c);
if (!cell) { cellsHtml += '<div></div>'; continue; }
const hl = f.where && f.where.row === r && f.where.col === c;
cellsHtml += '<div class="cell ' + (cell.running ? 'run ' : '') + (hl ? 'hl' : '') + '">' +
const wasHere = f.whereFrom && f.whereFrom.row === r && f.whereFrom.col === c;
cellsHtml += '<div class="cell ' + (cell.running ? 'run ' : '') + (cell.kind === 'office' ? 'office ' : '') +
(cell.kind === 'modifier' ? 'modifier ' : '') + (hl ? 'hl ' : '') + (wasHere ? 'from' : '') + '">' +
'<div class="nm">' + esc(cell.label) + '</div>' +
'<div class="dim" style="font-size:10px">(' + r + ',' + c + ')</div>' +
(cell.tray ? '<span class="chip tray">' + esc(cell.tray) + '</span>' : '') +
(cell.cars.length ? '<div class="cars">' + cell.cars.map(esc).join('<br>') + '</div>' : '') +
(cell.tray ? '<div class="crew">🚂 ' + esc(cell.tray) + '</div>' : '') +
(cell.facility ? miniFacility(cell.facility) : '') +
(cell.cars.length ? '<div class="cars">siding: ' + cell.cars.map(esc).join('<br>') + '</div>' : '') +
'</div>';
}
}
@@ -476,8 +625,13 @@ $('play').onclick = () => {
$('speed').onchange = () => { if (timer) { $('play').click(); $('play').click(); } };
document.onkeydown = (e) => {
if (e.key === 'ArrowRight') go(i + 1);
if (e.key === 'ArrowLeft') go(i - 1);
if (e.key === ' ') { e.preventDefault(); $('play').click(); }
else if (e.key === 'ArrowLeft') go(i - 1);
else if (e.key === 'Home') go(0);
else if (e.key === 'End') go(FRAMES.length - 1);
else if (e.key === 's' || e.key === 'S') $('stage').click();
else if (e.key === 'r' || e.key === 'R') $('money').click();
else if (e.key === 'c' || e.key === 'C') $('crash').click();
else if (e.key === ' ') { e.preventDefault(); $('play').click(); }
};
render();
</script></body></html>`;