537 lines
20 KiB
TypeScript
537 lines
20 KiB
TypeScript
/**
|
|
* Plain-English narration for the replay viewer.
|
|
*
|
|
* Two jobs, and the second matters more than it looks:
|
|
*
|
|
* 1. `narrate()` — turn each engine event into a sentence a person can read.
|
|
* 2. `impediments()` — say what is currently BLOCKED and why.
|
|
*
|
|
* Actions are easy to show. Blocked states are what diagnosis actually needs: the open questions
|
|
* are all of the form "why is nothing happening?" — why is a train at the Office only 18% of
|
|
* Stages, why do Laborers sit idle, why does a facility stop working. A log of things that did
|
|
* happen answers none of those.
|
|
*
|
|
* The impediment checks call the engine's own predicates rather than reimplementing them, so the
|
|
* panel cannot drift from the rules.
|
|
*/
|
|
|
|
import { adTrackCount, coordKey } from '../engine/state.ts';
|
|
import type { GameState, GridCoord, RollingStock, TrayId } from '../engine/state.ts';
|
|
import { canAdvanceLoad, canStartLoad, facilityCarType, laborersLeft, portersLeft } from '../engine/apply.ts';
|
|
import type { GameEvent } from '../engine/events.ts';
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Small formatters
|
|
// ---------------------------------------------------------------------------
|
|
|
|
const CLOCK: readonly string[] = [
|
|
'Midnight', '2:00 AM', '4:00 AM', '6:00 AM', '8:00 AM', '10:00 AM',
|
|
'Noon', '2:00 PM', '4:00 PM', '6:00 PM', '8:00 PM', '10:00 PM',
|
|
];
|
|
|
|
export function clockTime(stage: number): string {
|
|
return CLOCK[stage - 1] ?? `Stage ${stage}`;
|
|
}
|
|
|
|
export function carLabel(c: RollingStock): string {
|
|
// A caboose carries the crew, not freight, so "loaded caboose" is nonsense on the page even
|
|
// though the supply marks every caboose loaded. Name it plainly.
|
|
if (c.type === 'caboose') return 'caboose';
|
|
return `${c.loaded ? 'loaded' : 'empty'} ${c.type}`;
|
|
}
|
|
|
|
export function carsLabel(cars: RollingStock[]): string {
|
|
if (cars.length === 0) return 'nothing';
|
|
return cars.map(carLabel).join(', ');
|
|
}
|
|
|
|
const at = (c: GridCoord): string => `(${c.row},${c.col})`;
|
|
|
|
const BOX_NAMES = ['MEN', 'AT', 'WORK'] as const;
|
|
const boxName = (i: number): string => BOX_NAMES[i] ?? `box ${i}`;
|
|
|
|
export function phaseLabel(phase: string): string {
|
|
switch (phase) {
|
|
case 'localOps':
|
|
return 'Local Operations';
|
|
case 'newTrain':
|
|
return 'New Train';
|
|
case 'mainline':
|
|
return 'Mainline';
|
|
case 'loadUnload':
|
|
return 'Load / Unload';
|
|
case 'shiftChange':
|
|
return 'Shift Change';
|
|
default:
|
|
return phase;
|
|
}
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Event narration
|
|
// ---------------------------------------------------------------------------
|
|
|
|
export type Narration = {
|
|
text: string;
|
|
/** Colours the line in the viewer. */
|
|
tone: 'plain' | 'good' | 'bad' | 'clock' | 'quiet';
|
|
/** Board cell to highlight, if the event happened somewhere. */
|
|
where?: GridCoord;
|
|
};
|
|
|
|
/**
|
|
* Every member of `GameEvent` must produce a specific sentence. A test asserts the fallback is
|
|
* never reached, so adding an event type without narrating it fails the build rather than quietly
|
|
* degrading the replay.
|
|
*/
|
|
export type NarrateContext = {
|
|
/** Resolves a card id to something a person can read, e.g. "Mine Tipple" or "Train 8". */
|
|
cardName?: (id: string) => string;
|
|
/**
|
|
* Resolves a Crew Tray id to the train riding it. Without this the §8.1 clearance question read
|
|
* "may tray2 follow tray3 into the next Subdivision?" — the most consequential decision in the
|
|
* game, phrased in internal identifiers.
|
|
*/
|
|
trainName?: (trayId: TrayId) => string;
|
|
};
|
|
|
|
export function narrate(e: GameEvent, ctx: NarrateContext = {}): Narration {
|
|
const card = (id: string): string => ctx.cardName?.(id) ?? 'a card';
|
|
const train = (id: TrayId): string => ctx.trainName?.(id) ?? String(id);
|
|
|
|
switch (e.type) {
|
|
// -- clock
|
|
case 'stageBegan':
|
|
return { tone: 'clock', text: `── Day ${e.day}, Stage ${e.stage} — ${clockTime(e.stage)} ──` };
|
|
case 'phaseBegan':
|
|
return { tone: 'quiet', text: `${phaseLabel(e.phase)}` };
|
|
case 'actorChanged':
|
|
return {
|
|
tone: 'quiet',
|
|
text: e.player === null ? 'No player acts — automatic phase' : `Player ${e.player} to act`,
|
|
};
|
|
|
|
// -- local operations
|
|
case 'localOpsOptionChosen':
|
|
return {
|
|
tone: 'plain',
|
|
text:
|
|
e.option === 'switch'
|
|
? 'Chose to SWITCH — six Moves to shunt cars around the yard. Watch the crew chip on the grid: it carries its consist with it, and cars it passes over are coupled automatically.'
|
|
: e.option === 'draw'
|
|
? 'Chose to DRAW a card'
|
|
: 'Chose FREIGHT AGENT work — one car moved to or from a facility',
|
|
};
|
|
case 'trayMoved':
|
|
return {
|
|
tone: 'plain',
|
|
where: e.to,
|
|
text: `CREW moved ${at(e.from)} → ${at(e.to)} — ${e.movesRemaining} of 6 Moves left. The crew chip on the grid carries the whole train with it.`,
|
|
};
|
|
case 'carsCoupled':
|
|
return {
|
|
tone: 'plain',
|
|
where: e.at,
|
|
text:
|
|
`Coupled ${e.stock.length} car(s) at ${at(e.at)} ${e.toNose ? 'ONTO THE NOSE' : 'behind the train'}` +
|
|
`: ${carsLabel(e.stock)}`,
|
|
};
|
|
case 'consistSorted':
|
|
return {
|
|
tone: 'good',
|
|
where: e.at,
|
|
text: `SMALL YARD — consist re-ordered from [${carsLabel(e.before)}] to [${carsLabel(e.after)}], so the right car is now on the end and can be spotted`,
|
|
};
|
|
case 'carsDropped':
|
|
return {
|
|
tone: 'plain',
|
|
where: e.at,
|
|
text: `Dropped ${carsLabel(e.stock)} at ${at(e.at)}`,
|
|
};
|
|
|
|
// -- cards
|
|
case 'cardDrawn':
|
|
return {
|
|
tone: 'plain',
|
|
text:
|
|
e.source === 'homeOffice'
|
|
? `Drew ${card(e.cardId)} from the Home Office deck`
|
|
: `Took ${card(e.cardId)} from Department slot ${(e.slot ?? 0) + 1}`,
|
|
};
|
|
case 'cardPlayed':
|
|
return {
|
|
tone: 'plain',
|
|
...(e.placement ? { where: e.placement } : {}),
|
|
text: e.placement
|
|
? `Played ${card(e.cardId)} onto ${at(e.placement)}`
|
|
: `Played ${card(e.cardId)}`,
|
|
};
|
|
case 'mainlineModified':
|
|
return {
|
|
tone: 'plain',
|
|
text: e.became
|
|
? `Realignment: Mainline card ${e.node} converted to ${e.became}`
|
|
: `Played ${e.key} on Mainline card ${e.node}`,
|
|
};
|
|
case 'redFlagsSet':
|
|
return {
|
|
tone: 'good',
|
|
text: `Red Flags set out to protect train ${e.trayId} on Mainline card ${e.node} — an approaching train must stop`,
|
|
};
|
|
case 'flyingSwitch':
|
|
return {
|
|
tone: 'good',
|
|
where: e.to,
|
|
text: `Flying Switch — ${e.stock.length} car(s) cut loose and rolled into the industry at ${at(e.to)} without the engine entering`,
|
|
};
|
|
case 'trackLaid':
|
|
return {
|
|
tone: 'plain',
|
|
where: e.at,
|
|
text: `Laid ${e.hand === 'none' ? '' : e.hand + '-hand '}${e.geometry} track at ${at(e.at)} — ${e.remaining} left in the supply`,
|
|
};
|
|
case 'officeUpgraded':
|
|
return { tone: 'good', text: `OFFICE UPGRADED — ${e.from} → ${e.to}` };
|
|
case 'cardDiscarded':
|
|
return {
|
|
tone: 'quiet',
|
|
text: `Discarded ${card(e.cardId)} face-up to Department slot ${e.toSlot + 1}`,
|
|
};
|
|
case 'deckReshuffled':
|
|
return { tone: 'quiet', text: 'Home Office deck ran out — Salvage Yard reshuffled back in' };
|
|
case 'departmentRefilled':
|
|
return {
|
|
tone: 'quiet',
|
|
text: `Department slot ${e.slot + 1} refilled with ${card(e.cardId)}`,
|
|
};
|
|
|
|
// -- train lifecycle
|
|
case 'extraQueued':
|
|
return {
|
|
tone: 'good',
|
|
text: `Extra X${e.trainNumber} played — it is NOT scheduled; it runs once as soon as a Crew Tray frees up, then its card is gone`,
|
|
};
|
|
case 'enhancementPlaced':
|
|
return {
|
|
tone: 'good',
|
|
where: e.at,
|
|
text: `ENHANCEMENT built: ${e.key.replace(/([A-Z])/g, ' $1')} at ${at(e.at)}`,
|
|
};
|
|
case 'secondSectionOrdered':
|
|
return {
|
|
tone: 'bad',
|
|
text: `SECOND SECTION ordered on Train ${e.trainNumber} — an identical train will run right behind it, which forces the Superintendent to rule on a following train (§8.1)`,
|
|
};
|
|
case 'trainMadeUp':
|
|
return {
|
|
tone: 'good',
|
|
text: `${e.isExtra ? `EXTRA X${e.trainNumber}` : `TRAIN ${e.trainNumber}`} MADE UP at the ${e.at}, running ${e.direction} — crew assigned, now taking cars`,
|
|
};
|
|
case 'trainHeld':
|
|
return {
|
|
tone: 'bad',
|
|
text: `Train ${e.trainNumber} was due out but is HELD — ${e.reason}`,
|
|
};
|
|
case 'trainHighballed':
|
|
return {
|
|
tone: 'plain',
|
|
text: `Train ${e.trainNumber} HIGHBALLED — departed ${e.from} onto ${e.to}`,
|
|
};
|
|
case 'trainArrived':
|
|
return {
|
|
tone: 'plain',
|
|
text: `Train ${e.trainNumber} ARRIVED at the ${e.office} carrying ${carsLabel(e.consist)} — it will highball again next Mainline Phase, so any work must happen now`,
|
|
};
|
|
case 'trainDiverted':
|
|
return {
|
|
tone: 'good',
|
|
text: `Train ${e.trainNumber} DIVERTED to ${e.to} — ${e.reason}`,
|
|
};
|
|
case 'trainCompleted':
|
|
return {
|
|
tone: 'quiet',
|
|
text:
|
|
`Train ${e.trainNumber} finished its run and left the Division carrying ` +
|
|
`${carsLabel(e.consist)} — the crew is free again`,
|
|
};
|
|
|
|
// -- freight agent
|
|
case 'stockToOutbound':
|
|
return {
|
|
tone: 'plain',
|
|
where: e.at,
|
|
text: `Freight Agent put a ${carLabel(e.stock)} into the green Outbound box at ${at(e.at)}`,
|
|
};
|
|
case 'inboundCleared':
|
|
return {
|
|
tone: 'plain',
|
|
where: e.at,
|
|
text: `Freight Agent cleared a ${carLabel(e.stock)} from the red Inbound box at ${at(e.at)}`,
|
|
};
|
|
case 'facilityUnjammed':
|
|
return {
|
|
tone: 'bad',
|
|
where: e.at,
|
|
text: `UNJAMMED ${at(e.at)} — pulled a ${carLabel(e.stock)} out of ${e.from} to free the facility`,
|
|
};
|
|
|
|
// -- trains
|
|
case 'trainScheduled': {
|
|
// §7 — roll 1D12 for the slot; if it is taken, work down the column. Reporting only the roll
|
|
// makes a bumped train look like an arithmetic error.
|
|
const bumped = e.slot + 1 !== e.roll;
|
|
return {
|
|
tone: 'good',
|
|
text: bumped
|
|
? `Train ${e.trainNumber} SCHEDULED at Stage ${e.slot + 1} — rolled ${e.roll}, but Stage ${e.roll} was already taken, so it moved down the column to the next free Stage (§7)`
|
|
: `Train ${e.trainNumber} SCHEDULED to depart at Stage ${e.slot + 1} (rolled ${e.roll}) — it will run at this time EVERY Day from now on`,
|
|
};
|
|
}
|
|
case 'carPlacedOnTrain':
|
|
return { tone: 'plain', text: `Added a ${carLabel(e.stock)} to the train being made up` };
|
|
case 'carPassed':
|
|
return { tone: 'quiet', text: 'Passed — no suitable car in the Division Yard' };
|
|
case 'dispatchBonusUsed':
|
|
return {
|
|
tone: 'good',
|
|
text: `${e.key.toUpperCase()} used (+${e.bonus}) — Train ${e.trainNumber} wins the meet against Train ${e.againstTrain}, which now counts as number ${e.againstTrain + e.bonus}. Once a Day only.`,
|
|
};
|
|
case 'trainsDestroyed': {
|
|
// Say what hit what, where, and what was written off. "COLLISION: NO FREE A/D TRACK" told a
|
|
// player the score had changed and nothing else.
|
|
const why =
|
|
e.reason === 'no free A/D track'
|
|
? `it arrived at ${e.where} with every A/D track already occupied — there was nowhere to put it (§8.3)`
|
|
: e.reason === 'cars fouling the Running Track'
|
|
? `it ran into cars left standing on ${e.where} between the Limits and the Office (§8.3)`
|
|
: e.reason;
|
|
const wrecked = e.trains
|
|
.map((t) => `${t.label} (${t.consist.length ? carsLabel(t.consist) : 'no cars'})`)
|
|
.join(' and ');
|
|
return {
|
|
tone: 'bad',
|
|
text:
|
|
`COLLISION — ${wrecked} destroyed: ${why}. Engines and cabooses go back to the Division ` +
|
|
`Yard, all other cars to the Classification Yard (§10). A Timetabled train card returns ` +
|
|
`to its slot and runs again next Day; an Extra is gone for good.`,
|
|
};
|
|
}
|
|
|
|
case 'clearanceRequested':
|
|
return {
|
|
tone: 'bad',
|
|
text:
|
|
`SUPERINTENDENT MUST RULE (§8.1): ${train(e.trainId)} wants to enter the Mainline card ` +
|
|
`that ${train(e.occupiedBy)} is still crossing. Allow it and ${train(e.trainId)} may run ` +
|
|
`into the back of ${train(e.occupiedBy)} — a collision costs 5 Revenue. Hold it and it ` +
|
|
`waits where it is, losing time but safe.`,
|
|
};
|
|
case 'clearanceGiven':
|
|
return {
|
|
tone: e.allow ? 'bad' : 'plain',
|
|
text: e.allow
|
|
? `Clearance GRANTED — ${train(e.trainId)} follows into the occupied Subdivision`
|
|
: `Clearance DENIED — ${train(e.trainId)} holds where it is`,
|
|
};
|
|
|
|
// -- passengers
|
|
// §9.2 — "One Porter will allow you to do any ONE of the following actions", so a Depot with a
|
|
// single Porter works exactly one coach per Stage. That is a limit, not a bug.
|
|
case 'passengersBoarded':
|
|
return {
|
|
tone: 'good',
|
|
where: e.at,
|
|
text: `Porter boarded passengers at ${at(e.at)} — one coach per Porter per Stage (§9.2)`,
|
|
};
|
|
case 'passengersDetrained':
|
|
return {
|
|
tone: 'good',
|
|
where: e.at,
|
|
text: `Porter de-trained passengers at ${at(e.at)} — one coach per Porter per Stage (§9.2)`,
|
|
};
|
|
|
|
// -- freight pipeline
|
|
case 'loadStarted':
|
|
return {
|
|
tone: 'plain',
|
|
where: e.at,
|
|
text: `Laborer moved a ${e.carType} load from the green box onto MEN`,
|
|
};
|
|
case 'loadAdvanced':
|
|
return {
|
|
tone: 'plain',
|
|
where: e.at,
|
|
text: `Laborer advanced the load ${boxName(e.fromBox)} → ${boxName(e.toBox)}`,
|
|
};
|
|
case 'loadCompleted':
|
|
return {
|
|
tone: 'good',
|
|
where: e.at,
|
|
text: `LOAD FINISHED — ${e.carType} loaded onto the spotted car`,
|
|
};
|
|
case 'unloadBegan':
|
|
return {
|
|
tone: 'plain',
|
|
where: e.at,
|
|
text: `Laborer began unloading a ${e.carType} — load lifted onto WORK`,
|
|
};
|
|
case 'unloadCompleted':
|
|
return {
|
|
tone: 'good',
|
|
where: e.at,
|
|
text: `UNLOAD FINISHED — ${e.carType} delivered into the red Inbound box`,
|
|
};
|
|
|
|
// -- consequences
|
|
case 'revenueChanged':
|
|
return e.delta < 0
|
|
? { tone: 'bad', text: `${e.reason.toUpperCase()} · ${e.delta} Revenue (now ${e.total})` }
|
|
: { tone: 'good', text: `+${e.delta} Revenue (now ${e.total}) — ${e.reason}` };
|
|
case 'phaseEnded':
|
|
return { tone: 'quiet', text: `Player ${e.player} finished ${phaseLabel(e.phase)}` };
|
|
}
|
|
}
|
|
|
|
/** Events that change nothing a viewer can see. Skipped when capturing frames. */
|
|
export function isVisible(e: GameEvent): boolean {
|
|
return e.type !== 'actorChanged';
|
|
}
|
|
|
|
/**
|
|
* A phase that ended with nothing done needs saying so explicitly. "Player 0 finished Load/Unload"
|
|
* with no preceding action reads as a gap in the replay when it is actually the game reporting that
|
|
* there was no work available.
|
|
*/
|
|
export function idleNote(phase: string): string {
|
|
switch (phase) {
|
|
case 'loadUnload':
|
|
return 'Nothing to do this Load/Unload — no load ready to advance, and no train at the platform with passengers to work.';
|
|
case 'localOps':
|
|
return 'Nothing useful to do this Local Operations.';
|
|
default:
|
|
return `Nothing to do this ${phaseLabel(phase)}.`;
|
|
}
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Impediments — "why is nothing happening?"
|
|
// ---------------------------------------------------------------------------
|
|
|
|
export type Impediment = { where: string; why: string; severity: 'stuck' | 'waiting' | 'risk' };
|
|
|
|
/**
|
|
* Everything currently preventing progress. Derived live from engine predicates, never cached.
|
|
*
|
|
* This is the panel that should answer the standing questions: whether facilities jam, whether
|
|
* trains are held for want of a crew, whether the Office is about to cause a collision.
|
|
*/
|
|
export function impediments(s: GameState, player = 0): Impediment[] {
|
|
const out: Impediment[] = [];
|
|
const area = s.officeAreas.get(player);
|
|
if (!area) return out;
|
|
|
|
for (const [key, card] of area.grid) {
|
|
const f = card.facility;
|
|
if (!f || f.kind !== 'freight') continue;
|
|
const name = card.geometry.kind === 'facility' ? card.geometry.facility : 'facility';
|
|
const want = facilityCarType(f);
|
|
|
|
// A load that cannot move, with Laborers standing by, is the worst state a facility reaches:
|
|
// it also strips the industry track of Operational Rail status (§9.3), so no car can be
|
|
// brought in to rescue it.
|
|
for (let box = 0; box < f.menAtWork.length; box++) {
|
|
const load = f.menAtWork[box];
|
|
if (!load || canAdvanceLoad(f, box)) continue;
|
|
const reason =
|
|
laborersLeft(f) < 1
|
|
? 'all Laborers already used this Stage'
|
|
: load.dir === 'out'
|
|
? `no empty ${want} spotted to load onto`
|
|
: 'red Inbound box is full';
|
|
out.push({
|
|
where: `${name} ${key}`,
|
|
why: `load STUCK on ${boxName(box)} — ${reason}`,
|
|
severity: laborersLeft(f) < 1 ? 'waiting' : 'stuck',
|
|
});
|
|
}
|
|
|
|
if (f.outboundBox.length > 0 && !canStartLoad(f) && laborersLeft(f) > 0) {
|
|
out.push({
|
|
where: `${name} ${key}`,
|
|
why: 'green box has a load but MEN is occupied',
|
|
severity: 'waiting',
|
|
});
|
|
}
|
|
|
|
if (f.allows.outbound && f.outboundBox.length === 0) {
|
|
out.push({
|
|
where: `${name} ${key}`,
|
|
why: 'green box empty — nothing to load (needs a Freight Agent action)',
|
|
severity: 'waiting',
|
|
});
|
|
}
|
|
|
|
if (f.industryTrack.cars.length >= f.industryTrack.length) {
|
|
out.push({
|
|
where: `${name} ${key}`,
|
|
why: `industry track full (${f.industryTrack.length} cars) — no room to spot another`,
|
|
severity: 'stuck',
|
|
});
|
|
}
|
|
}
|
|
|
|
// Trains held for want of a Crew Tray (§7) — the scarcity mechanic, made visible.
|
|
const due = s.timetable[s.clock.stage - 1];
|
|
if (due !== null && due !== undefined && s.freeTrays.length === 0) {
|
|
out.push({
|
|
where: `Train ${due}`,
|
|
why: 'due to depart but HELD — no free Crew Tray',
|
|
severity: 'stuck',
|
|
});
|
|
}
|
|
|
|
// A full Office means the next arrival is an automatic collision (Gap 2d).
|
|
const cap = adTrackCount(s, player);
|
|
if (area.adOccupancy.length >= cap) {
|
|
out.push({
|
|
where: 'Office',
|
|
why: `all ${cap} A/D track(s) occupied — the next arrival COLLIDES`,
|
|
severity: 'risk',
|
|
});
|
|
}
|
|
|
|
if (s.clock.pendingDecision) {
|
|
out.push({
|
|
where: 'Superintendent',
|
|
why: 'must rule on a following-train clearance before the Mainline Phase continues',
|
|
severity: 'waiting',
|
|
});
|
|
}
|
|
|
|
return out;
|
|
}
|
|
|
|
/** A one-line summary of where every train currently is. */
|
|
export function trainPositions(s: GameState): { id: TrayId; label: string; where: string }[] {
|
|
const out: { id: TrayId; label: string; where: string }[] = [];
|
|
for (const [id, tray] of s.trays) {
|
|
const label = tray.trainNumber === null ? 'local crew' : `Train ${tray.trainIsExtra ? 'X' : ''}${tray.trainNumber}`;
|
|
let where: string;
|
|
switch (tray.position.at) {
|
|
case 'divisionPoint':
|
|
where = `${tray.position.side === 'west' ? 'West' : 'East'} Division Point`;
|
|
break;
|
|
case 'mainline':
|
|
where = `Mainline card ${tray.position.index}`;
|
|
break;
|
|
case 'grid':
|
|
where = `Office Area ${at(tray.position.coord)}`;
|
|
break;
|
|
}
|
|
out.push({ id, label, where });
|
|
}
|
|
return out;
|
|
}
|
|
|
|
export { coordKey };
|