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

v0.6.2 — an Extra starts where you put it, a train card is never discarded

Browse Source 
Three more from the v0.4.9e gameplay-testing round, filed as Gitea issues, plus two bugs found
underneath them. Gitea#2 is diagnosed but NOT fixed: it needs a ruling, and the reasoning is in
TODO.md under Play Balance.

GITEA#4 — AN EXTRA STARTS WHERE THE PLAYER PUTS IT. Only one Division Point was ever offered,
chosen by number parity. The number no longer decides an Extra's direction — the start does, which
supersedes the recorded ruling that "the number decides, like everything else on the timetable".
The two cannot both hold: an odd, westbound Extra placed at the WEST end would leave the Division
on its first move having crossed nothing, and be paid for the run. Either end now runs the train
away from itself; at an Interchange or a Control Point the player picks the direction. The
Interchange start is a YARD, off the running line, which is what makes the Superintendent clause
work: placing it can never force a collision, a guaranteed one holds it there for another Stage,
and a potential one is the Superintendent's to rule on — exactly evaluateClearance's `blocked` and
`ask`, so nothing new decides collisions. Where an Extra may start is now a house rule
(divisionPointsOnly / ownOffice / anyOffice, defaulting to what the engine already did). The
legacy `atSeat` intent field still replays as it always meant.

FOUND UNDERNEATH IT: an Extra started away from a Division Point ran empty. isBeingMadeUp tested
position alone, so the Control Point start has been shipping since it was added with a train that
could never be given a consist. Found by playing it, not by the tests, which had only asserted
where the tray landed.

FOUND UNDERNEATH IT: collide left the wrecks on the card. Destroyed trains kept their Transit
entries, and evaluateClearance counts every transit as an occupant, so one rear-end collision
permanently poisoned that Mainline card for every later train.

THE MAINLINE CARDS WERE ROLLED, NOT DEALT — drawn from the nine types with replacement, so a
Division could hold two Interchanges and Plains carried the weight of a card printed once. "An
Extra may start at the Interchange if one is on the board" only reads as a rule if the board holds
at most one. Now dealt from the printed deck without replacement, verified over 1600 deals. This
re-deals every seed: the published replays were re-recorded, and the saved games in docs/ are
retired too — two of those were already dead before this release and nobody had noticed.

GITEA#6 — A TRAIN CARD IS NEVER DISCARDED, Timetabled and Extra alike. The forced play needed no
mechanism: nothing discardable plus a hand over the limit leaves exactly one legal way to end the
turn, and playing a train is unconditionally legal, so the corner cannot trap anyone. The bot
needed no rule either. 400/400 games finished, revenue unmoved, trains scheduled 1.2 -> 1.3. The
player is told on the card and on the button.

GITEA#7 — COACH COUNTS. 1/2 Crack Limited 3 -> 2, 5/6 The Sparrow 2 -> 3. A change to the cards,
so Trains3.pdf and the transcription keep the original numbers with a footnote while content.ts
and the Home Deck reference carry what the game plays.

CONTENT.TS COMMENT PASS — no data changed, only comments. Four were factually wrong, including an
office table naming counts doubled long ago and a pointer to a DEALT_DECK_SIZE that has never
existed. Every Enhancement row cited its implementation by line number and every citation had
rotted; they name functions now. Card counts came out of the comments, since they move with play
balance; source-sheet figures and dated measurements stayed.

TODO.md gains an item for a card reference generated from content.ts, in six sections, so the
documentation cannot disagree with the game.

715 tests pass, tsc clean, site builds.
This commit is contained in:
Jesse.Markowitz
2026-08-22 19:51:40 -04:00
parent 83a5450866
commit 7804756f11
29 changed files with 3907 additions and 2127 deletions
Download Patch File Download Diff File Expand all files Collapse all files
test/advance.test.ts
+283 -36
View File
@@ -8,12 +8,12 @@ import { describe, it } from 'node:test';
import assert from 'node:assert/strict';
import { advance, pump } from '../src/engine/advance.ts';
import { applyIntent, areaOf, check } from '../src/engine/apply.ts';
import { EXPEDITE_FAULT_PENALTY, HAND_LIMIT, STAGES_PER_DAY, TOTAL_ROLLING_STOCK } from '../src/engine/content.ts';
import { applyIntent, areaOf, check, isBeingMadeUp } from '../src/engine/apply.ts';
import { EXPEDITE_FAULT_PENALTY, HAND_LIMIT, MAX_CONSIST, STAGES_PER_DAY, TOTAL_ROLLING_STOCK } from '../src/engine/content.ts';
import { legalActions } from '../src/engine/legal.ts';
import { createGame } from '../src/engine/setup.ts';
import { developerBot } from '../src/sim/bot.ts';
import type { CrewTray, GameConfig, GameState } from '../src/engine/state.ts';
import type { CrewTray, DivisionNode, GameConfig, GameState } from '../src/engine/state.ts';
import { coordKey, railFacingOf } from '../src/engine/state.ts';
const baseConfig = (over: Partial<GameConfig> = {}): GameConfig => ({
@@ -1019,15 +1019,20 @@ describe('the history says WHY a train moved, and says it truthfully', () => {
// ---------------------------------------------------------------------------
describe('an Extra starts where its number sends it, or at a Control Point', () => {
describe('an Extra starts where the player puts it (Gitea#4)', () => {
/**
* REPORTED: "Extras should start at Eastern or Western Division point based on their numbers. Even
* trains run to the east (start at western DP), odd run to the west (start at eastern DP). They
* can also start at a control point (any office except whistlepost) at player's choice."
* REPORTED, v0.4.9e: "When extras are played the player doing so may choose where the extra
* starts. They may choose either division point. And if the interchange mainline card has been
* played, they may start the extra on that card and choose the direction from there. If there is
* potential for conflict with other trains in that area the superintendent may hold the extra."
*
* Every Extra used to launch eastbound from the West Division Point, hardcoded, with the
* simplification flagged in a comment — so half the Extras ran the wrong way and the Control Point
* option did not exist at all.
* This SUPERSEDES the earlier ruling these tests used to assert — "the number decides, like
* everything else on the timetable" — for Extras only. The number still decides for a timetabled
* train. The reason the two cannot both hold: an odd (westbound) Extra placed at the WEST end
* would leave the Division on its first move having crossed nothing, and be paid for the run.
*
* So: the start decides the direction. A Division Point runs the train away from itself; in the
* middle of the railroad — an Interchange, a Control Point — the player says which way.
*/
const pending = (trainNumber: number, tier?: 'depot' | 'station'): GameState => {
const s = game(11);
@@ -1045,6 +1050,14 @@ describe('an Extra starts where its number sends it, or at a Control Point', ()
return tray;
};
/** Turn one Mainline card into an Interchange, and say which node it is. */
const withInterchange = (s: GameState): number => {
const i = s.division.nodes.findIndex((n) => n.kind === 'mainline');
const node = s.division.nodes[i]!;
if (node.kind === 'mainline') node.card = 'interchange';
return i;
};
it('stops for the decision instead of launching the train itself', () => {
const s = pending(17);
assert.equal(s.clock.phase, 'newTrain');
@@ -1055,36 +1068,46 @@ describe('an Extra starts where its number sends it, or at a Control Point', ()
);
});
it('sends an odd Extra west from the EASTERN Division Point', () => {
// §2.3 — odd runs west. It therefore starts at the end it runs away from.
it('offers BOTH Division Points, not the one the number would dictate', () => {
const s = pending(17);
assert.ok(applyIntent(s, 0, { type: 'newTrain.startExtra', trainNumber: 17, atSeat: null }).ok);
const tray = started(s);
assert.equal(tray.direction, 'west');
assert.equal(tray.position.at === 'divisionPoint' && tray.position.side, 'east');
const sides = legalActions(s, 0)
.filter((i) => i.type === 'newTrain.startExtra' && i.start?.kind === 'divisionPoint')
.map((i) => (i.type === 'newTrain.startExtra' && i.start?.kind === 'divisionPoint' ? i.start.side : ''));
assert.deepEqual([...sides].sort(), ['east', 'west']);
});
it('sends an even Extra east from the WESTERN Division Point', () => {
const s = pending(18);
assert.ok(applyIntent(s, 0, { type: 'newTrain.startExtra', trainNumber: 18, atSeat: null }).ok);
const tray = started(s);
assert.equal(tray.direction, 'east');
assert.equal(tray.position.at === 'divisionPoint' && tray.position.side, 'west');
it('runs an Extra AWAY from the Division Point it was placed at, whatever its number', () => {
// X17 is odd. Under the superseded rule it could only ever start at the East end and run west.
for (const [side, direction] of [['west', 'east'], ['east', 'west']] as const) {
const s = pending(17);
const r = applyIntent(s, 0, {
type: 'newTrain.startExtra', trainNumber: 17, start: { kind: 'divisionPoint', side },
});
assert.ok(r.ok, `the ${side} Division Point was refused: ${r.ok ? '' : r.code}`);
const tray = started(s);
assert.equal(tray.direction, direction, `an Extra at the ${side} end must run ${direction}`);
assert.equal(tray.position.at === 'divisionPoint' && tray.position.side, side);
}
});
it('refuses a Whistle Post, which is not a Control Point', () => {
const s = pending(18);
assert.equal(s.officeAreas.get(0)!.tier, 'whistlePost');
assert.equal(
check(s, 0, { type: 'newTrain.startExtra', trainNumber: 18, atSeat: 0 }),
'NOT_A_CONTROL_POINT',
);
it('refuses a Whistle Post, which is not a Control Point, at every setting of the house rule', () => {
for (const extraStart of ['divisionPointsOnly', 'ownOffice', 'anyOffice'] as const) {
const s = pending(18);
s.config = { ...s.config, houseRules: { ...s.config.houseRules, extraStart } };
assert.equal(s.officeAreas.get(0)!.tier, 'whistlePost');
const code = check(s, 0, {
type: 'newTrain.startExtra', trainNumber: 18, start: { kind: 'office', seat: 0 }, direction: 'east',
});
assert.ok(code !== null, `a Whistle Post was allowed under ${extraStart}`);
}
});
it('starts at a Control Point when the player picks one, taking an A/D track', () => {
// Upgrading the Office is what buys this: a Depot is a Control Point, a Whistle Post is not.
const s = pending(18, 'depot');
const r = applyIntent(s, 0, { type: 'newTrain.startExtra', trainNumber: 18, atSeat: 0 });
const r = applyIntent(s, 0, {
type: 'newTrain.startExtra', trainNumber: 18, start: { kind: 'office', seat: 0 }, direction: 'west',
});
assert.ok(r.ok, `starting at the Depot was refused: ${r.ok ? '' : r.code}`);
const tray = started(s);
const area = s.officeAreas.get(0)!;
@@ -1095,16 +1118,240 @@ describe('an Extra starts where its number sends it, or at a Control Point', ()
'the Extra did not start on the Office card',
);
assert.ok(area.adOccupancy.includes(tray.id), 'it did not take an A/D track');
assert.equal(tray.direction, 'east', 'an even Extra still runs east from wherever it starts');
// The point of the change: an EVEN Extra running WEST, because the player said so.
assert.equal(tray.direction, 'west', 'the direction the player chose was not honoured');
});
it('needs a direction anywhere that is not an end of the Division', () => {
const s = pending(18, 'depot');
assert.equal(
check(s, 0, { type: 'newTrain.startExtra', trainNumber: 18, start: { kind: 'office', seat: 0 } }),
'NO_DIRECTION_CHOSEN',
);
});
it('honours the extraStart house rule for Office starts, and never for the shared ground', () => {
for (const [extraStart, code] of [
['divisionPointsOnly', 'OFFICE_STARTS_NOT_ALLOWED'],
['anyOffice', null],
] as const) {
const s = pending(18, 'depot');
s.config = { ...s.config, houseRules: { ...s.config.houseRules, extraStart } };
assert.equal(
check(s, 0, {
type: 'newTrain.startExtra', trainNumber: 18, start: { kind: 'office', seat: 0 }, direction: 'east',
}),
code,
`office start under ${extraStart}`,
);
// The Division Points belong to nobody, so no setting ever closes them.
assert.equal(
check(s, 0, { type: 'newTrain.startExtra', trainNumber: 18, start: { kind: 'divisionPoint', side: 'west' } }),
null,
);
}
});
it('starts at an Interchange in the players yard, not out on the running line', () => {
const s = pending(18);
const node = withInterchange(s);
const r = applyIntent(s, 0, {
type: 'newTrain.startExtra', trainNumber: 18, start: { kind: 'mainline', node }, direction: 'east',
});
assert.ok(r.ok, `the Interchange was refused: ${r.ok ? '' : r.code}`);
const tray = started(s);
const card = s.division.nodes[node]!;
assert.equal(tray.direction, 'east');
assert.deepEqual(tray.position, { at: 'mainline', index: node });
assert.ok(card.kind === 'mainline' && card.holding?.includes(tray.id), 'it is not in the yard');
assert.equal(card.kind === 'mainline' && card.transits.length, 0, 'it was put on the running line');
});
it('refuses any Mainline card that is not an Interchange', () => {
const s = pending(18);
const plains = s.division.nodes.findIndex((n) => n.kind === 'mainline');
const node = s.division.nodes[plains]!;
if (node.kind === 'mainline') node.card = 'plains';
assert.equal(
check(s, 0, { type: 'newTrain.startExtra', trainNumber: 18, start: { kind: 'mainline', node: plains }, direction: 'east' }),
'NOT_AN_INTERCHANGE',
);
});
it('may be started at an Interchange however busy the card is — the yard forces no collision', () => {
const s = pending(18);
const node = withInterchange(s);
const card = s.division.nodes[node]!;
// Nose to tail with opposing traffic. §7: placing here still must not force a collision.
if (card.kind === 'mainline') {
card.transits.push({ tray: 'tray9', stagesRemaining: 2, stagesTotal: 2, direction: 'west' });
}
assert.equal(
check(s, 0, { type: 'newTrain.startExtra', trainNumber: 18, start: { kind: 'mainline', node }, direction: 'east' }),
null,
);
});
/**
* §7's last clause, and the reason the Interchange start is modelled as a yard at all: "If there
* is potential for conflict with other trains in that area the superintendent may hold the extra."
*
* Jesse's split: a GUARANTEED collision holds the train at the Interchange for another Stage and
* it tries again; a POTENTIAL one is the Superintendent's to rule on. Those are exactly §8.1's
* two answers, so the Extra highballs out of the yard through `evaluateClearance` — the same
* check a train leaving a Division Point goes through — rather than through anything new.
*/
describe('highballing out of the Interchange yard', () => {
/** A pending X18 sitting in the yard of an Interchange, with the terrain pinned. */
const inYard = (): { s: GameState; node: number; tray: CrewTray } => {
const s = pending(18);
const node = withInterchange(s);
const r = applyIntent(s, 0, {
type: 'newTrain.startExtra', trainNumber: 18, start: { kind: 'mainline', node }, direction: 'east',
});
assert.ok(r.ok, `the Interchange was refused: ${r.ok ? '' : r.code}`);
s.clock.phase = 'mainline';
s.movedThisPhase = new Set();
return { s, node, tray: started(s) };
};
const card = (s: GameState, node: number): Extract<DivisionNode, { kind: 'mainline' }> => {
const n = s.division.nodes[node]!;
assert.equal(n.kind, 'mainline');
return n as Extract<DivisionNode, { kind: 'mainline' }>;
};
it('pulls out onto the card at the next Mainline Phase when the Subdivision is clear', () => {
const { s, node, tray } = inYard();
advance(s);
const n = card(s, node);
assert.deepEqual(n.holding, [], 'it never left the yard');
assert.ok(n.transits.some((t) => t.tray === tray.id), 'it is not on the running line');
});
it('is held in the yard by a facing train, and tries again the next Stage', () => {
const { s, node, tray } = inYard();
// Westbound, against an eastbound Extra: §8.1 calls that an absolute bar, not a judgment call.
card(s, node).transits.push({ tray: 'facing', stagesRemaining: 2, stagesTotal: 2, direction: 'west' });
s.trays.set('facing', {
id: 'facing', trainNumber: 3, trainIsExtra: false, engineAt: 0, consist: [],
direction: 'west', position: { at: 'mainline', index: node }, movesUsed: 0,
});
const r = advance(s);
assert.equal(r.needsInput ?? false, false, 'a guaranteed collision is not a question to ask');
assert.equal(s.clock.pendingDecision, null);
assert.ok(card(s, node).holding?.includes(tray.id), 'it was not held in the yard');
assert.ok(
!card(s, node).transits.some((t) => t.tray === tray.id),
'it pulled out in front of a train coming the other way',
);
assert.ok(s.trays.has(tray.id), 'the Extra was destroyed rather than held');
// AND IT TRIES AGAIN. The Extra waits in the yard, not on the pending list, so once the road
// clears the next Mainline Phase takes it out with no further intervention.
s.trays.delete('facing');
card(s, node).transits = [];
s.clock.phase = 'mainline';
s.movedThisPhase = new Set();
advance(s);
assert.deepEqual(card(s, node).holding, [], 'it did not try again once the road was clear');
assert.ok(card(s, node).transits.some((t) => t.tray === tray.id), 'it never pulled out');
});
it('puts a following train to the Superintendent rather than holding it automatically', () => {
const { s, node, tray } = inYard();
// Same direction: §8.1's judgment call, which is what "may hold the extra" means.
card(s, node).transits.push({ tray: 'ahead', stagesRemaining: 2, stagesTotal: 2, direction: 'east' });
s.trays.set('ahead', {
id: 'ahead', trainNumber: 4, trainIsExtra: false, engineAt: 0, consist: [],
direction: 'east', position: { at: 'mainline', index: node }, movesUsed: 0,
});
const r = advance(s);
assert.equal(r.needsInput, true, 'the phase must stop and ask');
assert.equal(s.clock.pendingDecision?.train, tray.id);
assert.equal(s.clock.pendingDecision?.occupiedBy, 'ahead');
// HOLD keeps it in the yard.
assert.ok(applyIntent(s, s.clock.superintendent, { type: 'mainline.clearance', allow: false }).ok);
advance(s);
assert.ok(card(s, node).holding?.includes(tray.id), 'the Superintendent held it and it left anyway');
});
});
/**
* FOUND BY PLAYING IT, not by the tests above: an Extra started anywhere but a Division Point was
* never offered a car and ran empty.
*
* `isBeingMadeUp` asked only "is this tray standing at a Division Point", which was the whole
* truth while that was the only place to build a train. The Control Point start has therefore
* shipped since it was added with a train that could not be loaded, and the Interchange start
* would have shipped the same way — against Jesse's report, which says an Extra started at the
* Interchange "would be Loaded with cars".
*/
describe('an Extra started away from a Division Point can still be made up', () => {
const fill = (s: GameState): string[] => {
for (let i = 0; i < MAX_CONSIST + 1; i++) {
const options = legalActions(s, s.clock.currentActor ?? 0).filter((a) => a.type === 'newTrain.placeCar');
if (options.length === 0) break;
assert.ok(applyIntent(s, s.clock.currentActor ?? 0, options[0]!).ok);
}
return started(s).consist.map((c) => c.type);
};
it('takes a consist in the Interchange yard', () => {
const s = pending(18);
const node = withInterchange(s);
assert.ok(applyIntent(s, 0, {
type: 'newTrain.startExtra', trainNumber: 18, start: { kind: 'mainline', node }, direction: 'east',
}).ok);
assert.ok(fill(s).length > 0, 'the Extra was never offered a car and would have run empty');
});
it('takes a consist at a Control Point', () => {
const s = pending(18, 'depot');
assert.ok(applyIntent(s, 0, {
type: 'newTrain.startExtra', trainNumber: 18, start: { kind: 'office', seat: 0 }, direction: 'east',
}).ok);
assert.ok(fill(s).length > 0, 'the Extra was never offered a car and would have run empty');
});
it('stops being made up the moment it starts running', () => {
// Otherwise a train out on the Mainline could be handed cars from the Division Yard — the
// "cars appearing on a train nobody was making up" bug `isBeingMadeUp` exists to prevent.
const s = pending(18);
const node = withInterchange(s);
assert.ok(applyIntent(s, 0, {
type: 'newTrain.startExtra', trainNumber: 18, start: { kind: 'mainline', node }, direction: 'east',
}).ok);
const tray = started(s);
s.clock.phase = 'mainline';
s.movedThisPhase = new Set();
advance(s);
assert.equal(s.trays.get(tray.id)?.beingMadeUp, undefined, 'a running train is still being made up');
assert.equal(isBeingMadeUp(s.trays.get(tray.id)!), false);
});
});
it('replays a save written before the choice existed exactly as it meant it', () => {
/**
* A save is a seed and a list of intents, so an intent whose meaning moves is a save that
* quietly replays as a different game. The legacy shape carried only `atSeat`: null meant the
* Division Point the NUMBER sent it to, running in the number's direction.
*/
const s = pending(17);
assert.ok(applyIntent(s, 0, { type: 'newTrain.startExtra', trainNumber: 17, atSeat: null }).ok);
const tray = started(s);
assert.equal(tray.direction, 'west', 'the legacy intent stopped meaning what it meant');
assert.equal(tray.position.at === 'divisionPoint' && tray.position.side, 'east');
});
it('takes the Extra off the pending list once, whichever end it started from', () => {
const s = pending(17);
assert.ok(applyIntent(s, 0, { type: 'newTrain.startExtra', trainNumber: 17, atSeat: null }).ok);
const at = { type: 'newTrain.startExtra', trainNumber: 17, start: { kind: 'divisionPoint', side: 'east' } } as const;
assert.ok(applyIntent(s, 0, at).ok);
assert.deepEqual(s.pendingExtras, []);
assert.equal(
check(s, 0, { type: 'newTrain.startExtra', trainNumber: 17, atSeat: null }),
'NO_EXTRA_PENDING',
);
assert.equal(check(s, 0, at), 'NO_EXTRA_PENDING');
});
});