station-master/docs/design.md

Station Master — design index

Station Master is a tabletop railroad-operations game set in the era of timetable-and-train-order railroading (1840–1950), being developed into a multiplayer digital game: players connect from a web browser and an authoritative server manages lobbies and game state.

Source of record

• StationMasterPrototypeRules.pdf — the original prototype rules
• StationMaster-PrototypeTurnChart.pdf — the 12-Stage turn chart
• Deck cards2.xlsx — the complete card list (115-card deck, 104 track pieces, 12 start cards)
• Mainline Cards.pdf — the ten Mainline card types with their speeds and entry points
• Trains3.pdf — all 22 train cards with names, speed class, consist and operating rules
• tracks.png — card art for track and industry cards

These stay as-is. Everything below is derived from them.

The last four arrived after the engine was built and expand the game roughly threefold. See rules/implications.md: much of what is recorded below as decided was a placeholder for exactly this material, and the balance measurements in Gap 12 were taken against a ruleset that does not match the design.

Rules

Document	What it is
rules/rules-v0.1.md	Faithful markdown transcription of the PDFs. No corrections. The baseline everything diffs against.
rules/rules-v0.2.md	The working ruleset. v0.1 with all ten gaps resolved, each change marked with its gap number.
rules/card-reference.md	What is printed on every card, plus the economy summary. The spec an engine or a print-and-play layout consumes.
rules/glossary.md	Every defined term, alphabetized.
rules/open-questions.md	All thirteen gaps, each with the options considered, the decision, and the rationale.
rules/implications.md	Read this first. What the four recovered design files (Deck cards2.xlsx, Mainline Cards.pdf, Trains3.pdf, tracks.png) change — and which decisions they supersede.

Architecture

Target is small self-hosted scale: a handful of concurrent games, hosted on a website or as a StartOS service. Stack is deliberately undecided; these documents describe what any implementation must do.

Document	What it is
architecture/components.md	The project plan. All 20 buildable pieces — where each runs, when, MVP vs finished size — plus dependency graph and build order.
architecture/overview.md	Why the server is authoritative; state/intent/event split; transport; the rules-engine boundary.
architecture/game-state.md	The entity model, and the constraints that are easy to lose.
architecture/protocol.md	Intents, events, and per-player view redaction.
architecture/lobby-and-sessions.md	Create/join, seating, reconnection, persistence.
architecture/deployment.md	Plain web host vs StartOS service — and the one constraint that differs.

Current status

Rules formalized, card faces specified, architecture documented, and the rules engine built and simulated. Eleven of thirteen gaps are closed; Gap 12 (balance variance) and Gap 13 (deck scaling) remain open, both with data behind them.

Gaps 8–13 were all found by working the design forward — building it or simulating it — rather than by reading the PDFs. None arises in tabletop play, where a person simply does the sensible thing.

The economy, in one line: Local Operations actions are the main currency — one per Stage, twelve per Day — but inbound work bypasses them, which is where the game's variance comes from. See card-reference.md §7.

Wanted, not yet designed: post-game replay — watching a finished game back at speed. The architecture already produces what it needs (an ordered append-only event log plus a stored seed), so the note in architecture/overview.md exists to keep the capability from being designed out. It is explicitly not scheduled.

Provisional numbers — the victory targets are now confirmed at the mean by simulation. Still untested by play: Crew Tray count, Laborer counts, and whether the variance in Gap 12 is a flaw.

Next steps. The specification is complete enough to build against or to play on paper.

The build path is laid out in architecture/components.md — 20 components, a dependency graph, and a twelve-step order. Its MVP is solitaire: one Office, a fixed number of Days, a server talking to a single browser, display functional rather than pretty. The milestones worth knowing:

• Step 4 — a full solitaire game runs to completion headless, proving the rules before a pixel is drawn.
• Step 6 — the balance harness validates or retunes the provisional numbers, while changing them is still free.
• Step 10 — MVP complete; a human plays end to end.

Stack: TypeScript, chosen so the engine runs in both the server and the browser — one implementation of the movement rules, and instant affordances without a round-trip. Node 22 runs TypeScript natively, so there is no build step during development.

The recovered design files are now transcribed and the nine open questions answered — see rules/implications.md §1b for exactly what is implemented. The deck is 115 cards (93 in solitaire), Mainline cards have terrain and crossing times, and the balance numbers below predate all of it.

Steps 1–6 are done — the rules engine (components 1–7), heuristic bots (17) and the balance harness (18), with 134 tests passing.

The step 4 milestone is met: a full solitaire game runs to completion, headless. Games are reproducible from a seed, terminate from every seed tried, conserve all 62 rolling stock pieces, and develop properly.

End-of-game statistics (src/sim/stats.ts) report revenue by source, traffic, development, action mix and strategy buckets — plus an anomaly detector that treats "this event never fired" as a finding. It caught two bugs on its first run.

The step 6 milestone is met, with a caveat. The harness found five engine bugs that no test had caught, and once they were fixed the numbers came good: ~35% win rate and 5.0 Revenue/player/Day, matching the Gap 10e prediction of 5-6.

The caveat is large: those numbers were themselves measured against a scoring bug, since fixed. Honest figures are ~0.9 Revenue/Day and a 0% win rate — the targets are currently unreachable. The bot is still the prime suspect (it uses ~10 Laborer actions per game out of ~900 available), so this is Gap 12 and remains open. One genuine signal did emerge: mixed freight/passenger strategies outscore pure ones, with pure freight much the worst.

Gap 11 is decided — track orientation is chosen on placement, settled by measurement. Gap 13 answers the deck-size question: do not double it; scale only the buildable cards with player count.

Next: step 7 begins the server (components 8, 9, 20).

Run the harness with node src/sim/harness.ts [games] [length].

Watch a game: node src/sim/replay.ts --seed 1234 [--length standard] [--out replay.html] writes a self-contained HTML file — open it in any browser and step through the game. It shows the Division, the Office Area grid, every facility's boxes and MEN|AT|WORK track, plain-English narration of each event, and a Blocked panel explaining why nothing is moving.

Running alongside, and independent of all of it: print-and-play components. card-reference.md specifies every card face, so layout and art are the only remaining work before a table playtest — which answers the one question simulation cannot, whether it is fun.