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

v0.8.2 — every district opens on a Depot, and the docs are pages now

Browse Source 
A second-digit bump for a playtest read back against the save file. Nine questions
were asked of one three-Day game; three were bugs, three were the rules working
and undocumented, three were decisions. Every save on the test server was replayed
against this build BEFORE release, which is how the cost of each rule was known
before it was chosen rather than discovered after.

EVERY DISTRICT OPENS ON A DEPOT. A Whistle Post has one A/D track and is not a
Passenger Facility, so the opening of every game was spent unable to work a
passenger and one arrival away from a collision. Two A/D tracks and passengers
from Stage 1 now; "Players start with Whistle Posts, not Depots" is the harder
game, set when the game is created. The deck follows the choice — starting on
Depots the four Depot upgrade cards are left out, because an upgrade must be to
the next tier and a Depot card at a table of Depots is a dead draw. How much
easier it is showed up as a test failure rather than an argument: the cue-coverage
pool needed widening from 24 seeded games to 60 before it held one collision.

NO SAVE WAS STRANDED BY IT, which took care. This is the one house rule that
changes how a game is DEALT rather than how it plays, so replaying a save under
the wrong opening is a different railroad from intent one — silently, with no
error. `withSavedOpening` fills it on the replay paths ONLY. Putting it in the
resolver instead made a fresh Cutthroat game deal Whistle Posts and read as
Custom, which is how the distinction was found.

THREE BUGS, ALL REPORTED FROM ONE GAME AND ALL CONFIRMED ON ITS SAVE.

An Office held TWO TRAINS ON ONE A/D TRACK. The capacity test passed with nothing
standing, the train the Interlocking had been holding at the Limits was moved into
the free slot, and the arriving train was pushed in after it without anyone asking
again whether there was room — so the collision §8.3 calls for never happened. The
held train keeps priority; the newcomer now takes the consequence it would have
met had the held train arrived first.

THE HISTORY FROZE, permanently, and the log cap was not really the cause. Each
seat's "what have I sent you" bookmark was an INDEX into an array the game trims,
so once a seat's bookmark reached the limit the slice returned nothing for the
rest of the game — at a different moment per seat, because each holds its own.
That game's log ended at exactly the cap. Lines carry a sequence number now, which
survives trimming; proven by pushing twice the cap through a simulated seat.

§8.1 ASKED THE WRONG QUESTION TWICE. "Trains may pass" returned `clear` before the
Subdivision was looked at, so a train entering a Double Track was released however
busy the rest of it was — that, not anything about Control Points, is what let
Train 8 out with no ruling. And a train standing at an Office was invisible to the
scan, so one about to re-enter the very Subdivision being entered counted for
nothing. Capacity is the test, not presence: a Depot with a track free is not in
the way; a Whistle Post with its one track taken is.

THINGS THAT HAPPENED SILENTLY NOW SAY SO — a train held against a facing one, a
train released from the Limits (a side effect of somebody else's arrival, so it
simply appeared at the Office), and the train an Interlocking is holding, whose
explanatory tooltip has existed since #99 with NO renderer ever reading the flag.

WHERE A MOVE IS REFUSED, AND WHY. `exploreMoves` decides where the rails go and the
pick-up restrictions are enforced afterwards in `check`, so a square the rails
reached and the card forbade was reachable, un-offered, and absent from the block
list with nothing said. Those squares are blocked with the rule that blocks them
now, and the reasons are got by ASKING `check` rather than re-deriving: a second
implementation of the rules is exactly the failure the block list exists to avoid.
A train may also always recover its own caboose — X13 prints "may drop but not
pick up anything", and a train needs its caboose to be made up, so one that parted
with it could never legally leave again.

RULES DECIDED IN SEPTEMBER AND APPLIED HERE. A Modifier must sit square against its
host, no diagonals. A passenger Modifier may not be played at a Whistle Post. Both
were built, measured, held back for a fortnight so a playtest could finish, and
applied now. A Second Section costs its card: `SECOND_SECTION` was declared in
content.ts and never dealt, so the action was free and the bot ordered 26
accidental ones in a measured round. The card is dealt and spent — gating on a card
the deck never holds would have deleted the mechanic rather than fixed it.

THE DOCUMENTATION IS A SET OF PAGES, not five text files served as text/plain — a
card reference is mostly tables, and as plain text a table is rows of pipes.
Markdown is still the one copy; the build renders it, and publishes the .md beside
each page. No Markdown library: this project has no runtime dependencies and one
would be a poor first. The pages add what Markdown cannot carry without drifting —
a nav across the set, a contents list built from the headings actually rendered,
an anchor on every heading, a 70-character measure, and tables that are tables.
They print as ink on paper.

The references caught up with the rules, checked rather than assumed: two
statements had gone from stale to misleading (the Quickstart told a new player to
"get a Depot down as soon as one appears"), and four rules nobody could look up
are written down — the Office tier table, §8.1 in practice, what the Circus Train
pays for, and that a Realignment can be a card with no legal target.

Adding one card to the deck reshuffles every seeded deal, which broke five
fixtures. Each was a seed meaning "a game like this" — TODO #84, exactly — so
seeds moved and pools widened rather than assertions weakening, and the clearance
fixture pins its terrain the way `enhancements.test.ts` already does. The three
published replays were re-recorded.

Closes TODO #40, #42a, #108, #109 and #110.

1046 fast tests and 35 sim tests pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MUizFYCMHRWhbWwXhp7WPR
This commit is contained in:
Jesse.Markowitz
2026-09-23 07:07:21 -04:00
co-authored by Claude Opus 5
parent 517238a727
commit 3befc420da
66 changed files with 6828 additions and 3324 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/rules/as-built.md
-260
View File
@@ -1,260 +0,0 @@
# Station Master — the cards as built
> **Generated from `src/engine/content.ts` by `scripts/build-card-reference.ts`. Do not edit by
> hand** — `npm run build:cards` rewrites it, and `test/card-reference.test.ts` fails if this file
> and the code disagree.
This is the one file in `docs/rules/` that describes the game **as it currently is**. Everything
else in this directory is a historical record and marked as such: [`rules-v0.1.md`](rules-v0.1.md)
transcribes the prototype PDFs, [`open-questions.md`](open-questions.md) tracks how the gaps in
them were decided, and [`rules-v0.2.md`](rules-v0.2.md) and
[`card-reference.md`](card-reference.md) both describe superseded card sets. Read those for the
reasoning; read this for the numbers.
The engine instantiates from the same constants this is emitted from, so a disagreement between
this page and the game is a bug in the generator, not a stale table.
**No card counts appear here, deliberately** (TODO #15a, Jesse 2026-08-22): the counts move with
play balance, so a document that prints them is answering a question that will have a different
answer next retune. Where a count matters it is a yes/no — whether the deck deals the card at
all — which is a fact about the design rather than about the current tuning.
---
## Trains
12 timetabled and 10 Extras, 22 in all.
Odd numbers run west, even run east; a pair shares a class and is the same card face in two
directions. A Crew Tray holds four pieces and a caboose counts toward the four, which is why no
train with a caboose carries more than three revenue cars.
### Timetabled
| # | Class | Speed | Runs | Consist | Printed rules |
| ---: | --- | --- | --- | --- | --- |
| 1 | Crack Limited | fast | west | 2 coaches (2 pieces) | terminals only; no switching; expedite; *"Stop at Terminals only."* |
| 2 | Crack Limited | fast | east | 2 coaches (2 pieces) | terminals only; no switching; expedite; *"Stop at Terminals only."* |
| 3 | Express | fast | west | 2 freight (2 pieces) | one freight per location; expedite; *"May drop or pick up one freight car at every location."* |
| 4 | Express | fast | east | 2 freight (2 pieces) | one freight per location; expedite; *"May drop or pick up one freight car at every location."* |
| 5 | The Sparrow | fast | west | 3 coaches (3 pieces) | no switching; expedite |
| 6 | The Sparrow | fast | east | 3 coaches (3 pieces) | no switching; expedite |
| 7 | Local | slow | west | 1 freight + 1 coach (2 pieces) | coach stays on station track; *"Maximum one freight, one coach."* |
| 8 | Local | slow | east | 1 freight + 1 coach (2 pieces) | coach stays on station track; *"Maximum one freight, one coach."* |
| 9 | Heavy Freight | slow | west | 3 freight + 1 caboose (4 pieces) | — |
| 10 | Heavy Freight | slow | east | 3 freight + 1 caboose (4 pieces) | — |
| 11 | Drag Freight | slow | west | 2 freight + 1 caboose (3 pieces) | — |
| 12 | Drag Freight | slow | east | 2 freight + 1 caboose (3 pieces) | — |
### Extras
| # | Class | Speed | Runs | Consist | Printed rules |
| ---: | --- | --- | --- | --- | --- |
| X13 | Appleseed Extra | slow | player's choice | 3 freight + 1 caboose (4 pieces), empties only | drop only; *"May drop MTs but not pick up anything."* |
| X14 | Fruit Growers Express | fast | player's choice | 2 reefers + 1 caboose (3 pieces) | expedite; *"Reefers only. May pick up one extra loaded reefer."* |
| X15 | Yard Xfer | slow | player's choice | 2 freight + 1 caboose (3 pieces) | — |
| X16 | Light Engine Move | fast | player's choice | engine only | no switching; *"No cars at all."* |
| X17 | Campaign Train | fast | player's choice | 1 coach (1 piece) | no switching; stop then expedite; stop earns point; must run loaded; *"One turn at station (speeches) then expedite. Earns a point per Office Area if the candidate is aboard."* |
| X18 | Circus Train | slow | player's choice | 2 freight + 1 coach + 1 caboose (4 pieces) | no switching; stop earns point; must run loaded; *"One turn stopped in an Office Area (circus set-up) earns 1 point, once per Area, if fully loaded."* |
| X19 | Military Train | slow | player's choice | 1 freight + 2 coaches (3 pieces) | no switching; no passenger work; expedite; must run loaded; *"Troops and materiel: runs loaded where the yard can supply it."* |
| X20 | Director's private car | slow | player's choice | 2 freight + 1 coach (3 pieces) | no passenger work |
| X21 | Freight Extra | slow | player's choice | 3 freight + 1 caboose (4 pieces) | — |
| X22 | Pee-Dee | slow | player's choice | 1 caboose (1 piece) | pick up empties only; *"Per-diem train. May only pick up MTs."* |
---
## Mainline cards
A card is divided into **regions**, and a train advances one region per Stage — so the regions a
card prints are what it costs to cross. Where a train *enters* is what the rules move: a fast
train on Hilly, a Heavy Grade with Helpers, or a card whose back region is a siding rather than
part of the road all change the entry point rather than the card's length.
| Card | Regions | Default entry | Fast / slow entry | Trains may pass | Extra may start |
| --- | ---: | ---: | --- | :---: | :---: |
| Plains | 1 | 0 | — | — | — |
| Curves | 2 | 0 | — | — | — |
| Hilly | 2 | 0 | 1 / 0 | — | — |
| Heavy Grade | 3 | 0 | — | — | — |
| Double Track | 1 | 0 | — | yes | — |
| Uncontrolled Siding | 2 | 1 | — | — | — |
| Tunnel | 2 | 0 | — | — | — |
| Trestle | 1 | 0 | — | — | — |
| Interchange | 2 | 1 | — | — | yes |
The Mainline deck is 10 cards; the two Division Points are the fixed ends of
the Division and are not dealt. What each card does, in the words the game uses on screen:
- **Plains** — 1 region — one Stage each. · 1 Stage for every train. · One train at a time — anything following has to wait for it to clear.
- **Curves** — 2 regions — one Stage each. · 2 Stages for every train. · One train at a time — anything following has to wait for it to clear.
- **Hilly** — 2 regions — one Stage each. · This card reads the train's FAST/SLOW rating: a fast train starts further along and crosses in 1 Stage, a slow one in 2 Stages. No other card cares which it is. · One train at a time — anything following has to wait for it to clear.
- **Heavy Grade** — 3 regions — one Stage each. · A grade, climbing eastward. 3 Stages to climb it and 3 Stages to run down, before help. Helpers start an UPHILL train a region further on; Brakeman does the same DOWNHILL and Airbrakes another again, and Airbrakes cannot be played without Brakeman. Never less than one Stage. · One train at a time — anything following has to wait for it to clear.
- **Double Track** — 1 region — one Stage each. · 1 Stage for every train. · TRAINS MAY PASS — two trains may stand on this card at once, so a following train is not held behind a slower one.
- **Uncontrolled Siding** — 2 regions — one Stage each. · A train with the card to itself starts past the back region and is across in 1 Stage. · UNCONTROLLED SIDING — arrive to find a train already here and you take the siding, a region behind it. You are not in the same place, so you do not run into it; it costs you the extra Stage instead. · One train at a time — anything following has to wait for it to clear.
- **Tunnel** — 2 regions — one Stage each. · 2 Stages for every train. · One train at a time — anything following has to wait for it to clear.
- **Trestle** — 1 region — one Stage each. · 1 Stage for every train. · One train at a time — anything following has to wait for it to clear.
- **Interchange** — 2 regions — one Stage each. · A train with the card to itself starts past the back region and is across in 1 Stage. · An Extra beginning its run here starts in the back region and takes the extra Stage. · One train at a time — anything following has to wait for it to clear. · This is the one Mainline card with a yard, so an Extra Train may be made up and started here. Its printed car-sorting is NOT implemented — a consist is re-ordered at a Small Yard in a district.
---
## Office cards
Upgrades are strictly sequential — no skipping a tier — so a Terminal needs all three cards in
order. Green slots are outbound passengers, red are inbound, and the design gives slots **equal**
to Porters rather than one more.
| Office | Control point | Passenger facility | A/D tracks | Porters | Green | Red |
| --- | :---: | :---: | ---: | ---: | ---: | ---: |
| Whistle Post | — | — | 1 | 0 | 0 | 0 |
| Depot | yes | yes | 2 | 1 | 1 | 1 |
| Station | yes | yes | 3 | 2 | 2 | 2 |
| Terminal | yes | yes | 4 | 3 | 3 | 3 |
Whistle Posts are a fixed supply of 4 outside the deck, and Limits signs a
supply of 8.
---
## Freight facilities
Each lists the car types it works, which way its traffic flows, and the industries it may not sit
beside. **Every lockout pair is a producer and the consumer of the same commodity** — you may
build one end of a chain or the other, never both, which is what forces traffic to run between
districts rather than in circles inside one. No two of the same industry may share an Office Area,
and that rule is enforced for every kind rather than repeated in each row.
| Industry | Cars | Flow | Green | Red | Laborers | Locked out with |
| --- | --- | --- | ---: | ---: | ---: | --- |
| Freight House | boxcar | both | 1 | 1 | 1 | Grocer's Warehouse |
| Mine Tipple | hopper | outbound | 1 | 0 | 1 | Power Plant |
| Refinery | tank | outbound | 1 | 0 | 1 | Power Plant |
| Power Plant | hopper, tank | inbound | 0 | 1 | 1 | Mine Tipple, Refinery |
| Packing Sheds | reefer | outbound | 1 | 0 | 1 | Grocer's Warehouse |
| Grocer's Warehouse | boxcar, reefer | inbound | 0 | 1 | 1 | Packing Sheds, Freight House |
---
## Modifier cards
Each sits beside a host and raises one of its capacities. `office` as a host means any Passenger
Facility — so a modifier that adds a green slot to an Office adds nothing to a Whistle Post, which
is not one.
| Modifier | Hosts | +Green | +Red | +Laborers | +Porters |
| --- | --- | ---: | ---: | ---: | ---: |
| Waiting area | any Passenger Facility | 1 | — | — | 1 |
| Restaurant | any Passenger Facility | 1 | — | — | 1 |
| Hotel | any Passenger Facility | 1 | — | — | 1 |
| Truck dock | Freight House, Packing Sheds, Grocer's Warehouse | — | 1 | — | — |
| Railroad Express Agency | Freight House | 1 | — | 1 | — |
| Forklifts | Freight House, Packing Sheds | 1 | — | 1 | — |
| Prep Plant | Mine Tipple | 1 | — | 1 | — |
| Coal Piles | Mine Tipple | 1 | — | 1 | — |
| Conveyor Belts | Mine Tipple | 1 | — | 1 | — |
| Pipelines | Refinery | 1 | — | 1 | — |
| Oil Depot | Refinery | 1 | — | 1 | — |
| Viscosity breakers | Refinery | 1 | — | 1 | — |
| Transmission lines | Power Plant | — | — | 1 | — |
| Rotary Dumps | Power Plant | — | — | 1 | — |
| Steam Turbines | Power Plant | — | — | 1 | — |
| Ice House | Packing Sheds, Grocer's Warehouse | 1 | — | 1 | — |
| Local small groceries | Grocer's Warehouse | — | — | 1 | — |
---
## Track cards
Track is **in the Home Office deck** and is drawn and played like any other card — not a separate
per-player supply. Operational Rail is the flag that says a train may stop on the card; a turnout
may be run through but not stopped on.
| Track | Geometry | Hand | Operational rail | Move cost | Dealt |
| --- | --- | --- | :---: | ---: | :---: |
| Straight track | straight | none | yes | 1 | yes |
| Curved track (right) | curved | right | yes | 1 | yes |
| Curved track (left) | curved | left | yes | 1 | yes |
| Sharp Curved Track (right) | sharpCurved | right | yes | 2 | no |
| Sharp Curved Track (left) | sharpCurved | left | yes | 2 | no |
| Turnout (right) | turnout | right | — | 1 | yes |
| Turnout (left) | turnout | left | — | 1 | yes |
A row marked "no" is a shape the engine understands but the deck does not currently print.
---
## Enhancements
The column that only the implementation can fill in: **whether the printed effect actually
resolves yet.** `live` is read during play; `dormantSolo` is implemented at the point of attack
but the attack is an opponent-directed card held out of every deck, so nothing reaches it in a
solitaire game; `unbuilt` means the effect is recorded and nothing reads it. A transcription
cannot carry this column, which is the argument for generating the page rather than writing it.
| Enhancement | Placement | Requires | Effect resolves |
| --- | --- | --- | :---: |
| Interlocking | runningTrackStraight | — | **live** |
| Facing Point Locks | onCard | interlocking in the district | **dormantSolo** |
| Yard Office | secondaryTrackStraight | — | **live** |
| Small Yard | secondaryTrackStraight | — | **live** |
| Water Column | runningTrackStraight | — | **dormantSolo** |
| Overpass | onCard | — | **unbuilt** |
| Telegraph | runningTrackStraight | — | **live** |
| Telephone | onCard | telegraph on the same card | **live** |
| Radio | onCard | telephone on the same card | **live** |
| ABS Signals | mainlineCard | — | **live** |
---
## Opponent-directed cards, and what answers them
**None of these is dealt in any deck today.** A card that can only be played at another player
has no legal target in a solitaire game, and a defence with nothing to defend against is as dead
a draw as the attack — so both halves are held out until the attacks are implemented. They are
listed because they are the design, and because what a defence answers is the only record of why
it exists.
### Action cards — opponent-directed
| Card | Played on | Effect | Answers |
| --- | --- | --- | --- |
| Derail | a moving train in the Local Phase | That train must stop for the remainder of the turn. | — |
| Broken coupler | a moving train in the Mainline Phase | That train must stop and not move. | — |
| Railroad crossing | any Secondary Track Straight | May not be used as a stop point for switching. May not become an Industry. | — |
| Per Diem inventory | another player | Lose one point per 2 empty cars on Secondary Tracks. | — |
| Demurrage charge | another player | Lose one point per 2 loaded freight cars on Secondary Tracks. | — |
| Customer complaints | another player | Lose one point per 2 coaches in loading boxes. | — |
| Vandalism | another player | A train passing a Hobo Jungle has a boxcar looted (converted to empty). | — |
| Hotbox | another player | A train just arrived must set one car (chooser’s pick) onto Secondary Track until it departs. | — |
| Outlawed | another player | A train just arrived may not depart for one turn — the crew’s hours have expired. | — |
### Space-use cards — opponent-directed
| Card | Played on | Effect | Answers |
| --- | --- | --- | --- |
| Bean house | adjacent to any straight, curve, turnout, Limit | Burns tablespace. | — |
| Flop house | adjacent to any straight, curve, turnout | Burns tablespace. | — |
| Watertower | adjacent to any straight, turnout on Running Track | Burns tablespace. | — |
| Hobo Jungle | adjacent to any straight, turnout, Limit on Running Track | Burns tablespace. Vandalism can loot a boxcar passing it. | — |
| Section House | adjacent to any straight, curve, turnout | Burns tablespace. | — |
| City blocks | adjacent to any straight, curve, turnout, Limit | Burns tablespace. | — |
| Engine Shops | adjacent to any straight, curve, turnout | Burns tablespace. | — |
| Tenderloin District | adjacent to any straight, curve, turnout, Limit | Burns tablespace. | — |
| Engineer cemetery | adjacent to any straight, curve, turnout, Limit | Burns tablespace. | — |
### Maneuver cards
| Card | Played on | Effect | Answers |
| --- | --- | --- | --- |
| Red Flags | any time | A stopped train is prevented from being hit; the approaching train is prevented from moving. | — |
| Flying Switch | any time | Break a cut of cars away from behind the engine and roll them into an industry. | — |
| Poling | any time | TBD in the source. | — |
Mainline modifier cards, for completeness — these ARE dealt:
| Card | Played on | Effect | Answers |
| --- | --- | --- | --- |
| Brakeman | a GRADE Mainline card | Faster passage downhill. | — |
| Airbrakes | a GRADE Mainline card | Faster passage downhill. Brakeman must be in effect. | — |
| Helpers | a GRADE Mainline card | Faster passage uphill. | — |
| Realignment | a Mainline card | Convert one Mainline type to another. Not while a train is on it. | — |
| Facing Point Locks | adjacent to Interlocking | Prevents Derail being played on you. | Derail |