JesseMarkowitzandClaude Opus 5
1d4ac0fdbd
Seventeen events across the mailroom: ordinary days, Marlene Hobb and Trevor Pike, a misrouted envelope that can be delivered or kept, and a hard-times branch that fires on negative money and always leaves an ungated way out. Writing real content turned up two things the engine could not express. Per-turn upkeep (`pack.upkeep`): the MVP spec wants recurring income and costs, but effects only run when a player chooses something, and baking wages into every option would be tedious and easy to get wrong. Upkeep entries carry their own conditions, which turned out to be enough for the loan service charge to be a three-step function that escalates with the size of the debt — no multiply operation, no engine change. Upkeep changes are recorded separately from choice changes so the UI can distinguish them. Per-character starting relationships: Trevor starts below the pack default on `likes_you` because he arrived two weeks earlier and has priced that in. Characterisation as data rather than as an opening cutscene. Nobody starts feared, either — `fears_you` defaults to 10, since a midpoint default would mean every new hire arrives already intimidating. The content suite plays 60 seeded runs and asserts every event fires and every option is taken at least once. That caught real dead content: Trevor's favour chain sat behind a gate no plausible player could reach, taking two events and a hard-times escape route with it, and debt could pass 5,500 while the service charge stayed flat, so the failure spiral flattened out instead of tightening. Both fixed in the data — the gate softened and given another route up, the loan capped and its charge tiered. The validator also gained a real fix: it counted an event with a cooldown as a stage's fallback, but a cooldown can exclude it, so a stage could still run dry. 86 tests. Reasoning in docs/DECISIONS.md §11-13, including the seeding trap that makes a correlated chooser look exactly like a content bug. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VMSFHyVPitUoosW5wyEADj
7.3 KiB
Architecture decisions
Why the code is shaped the way it is. Append to this file as decisions are made; the reasoning is worth more later than the conclusion.
1. All game state is addressable by path
Every value in a run — money, skills.negotiation,
relationships.boss.likes_you, flags.took_loan — is reachable by a dotted
path string, and conditions and effects are expressed against those paths.
The planning docs' schema had requires: { skill, min } and
effects: { money, skills, relationships }. Both hardcode the state shape into
the engine: the first gate that wants a relationship threshold, a money floor
or a flag, and the first effect that touches a fourth kind of state, means
editing engine code. Path addressing costs one getPath/setPath pair and
removes the whole class of change.
Everything else in the engine is built on this primitive: option gates, event triggers, the soft-failure branch, and — later — promotion tiers.
2. Conditions and effects are data, evaluated generically
A condition is { path, op, value } or a combinator (all / any / not).
An effect is { path, op, value } with add / set / push / remove.
The engine knows the operators; it never knows what a path means.
Bounds live in the pack's state declaration (min / max) and are applied by
the effect layer, so clamping is content's decision, not the engine's.
3. There is no such thing as a "random event"
Every turn, the engine filters the entire event pool by stage and conditions,
then draws by weight. A routine turn is a high-weight event with loose
conditions; a rare interruption is a low-weight one; the hard-times branch is
an event whose conditions include a money threshold. The engine branches on
none of it, which is what the planning docs asked for in
03-claude-code-build-prompt.md §3 — but achieved by deleting the category
rather than by carefully not special-casing it.
Consequence: every stage needs at least one event that no exclusion rule can
remove (no requires, no once, no cooldown), or the pool can run dry
mid-run. The validator enforces this.
4. The engine owns some state; content may read it but not write it
turn, stage, seen, lastSeen, history and meta are engine
bookkeeping. Content can read them in conditions — "only after day 10", "only
if this event has never fired" — which is useful and safe. Writing them is a
validation error, so data cannot corrupt the loop.
seen.<eventId> is a count and lastSeen.<eventId> a turn number, which is
why event ids must be valid path segments.
5. Seeded, serializable RNG
Not in the planning docs; added because it is nearly free and pays three ways: tests are deterministic, playtest reports are reproducible from seed plus choice sequence, and the feedback log becomes replayable rather than merely descriptive. mulberry32 was chosen because its entire state is one uint32, so the generator's position round-trips through JSON with no special handling.
The seed and position live in meta inside the save file. Nothing about a run
exists outside its state object.
6. The turn loop is a pure function
takeTurn(pack, state, optionId) -> { state, record }. No mutable game object,
no hidden state. A saved game resumes into exactly the run it left — there is a
test that plays 30 turns straight, plays the same 30 turns with a JSON round
trip in the middle, and deep-equals the results.
7. Content is validated at load, not discovered at play
validatePack checks that every path referenced by a condition or effect is
declared, every character id resolves, ids are usable as path segments, no
event is unreachable, and every stage has a fallback. Without it, a typo in
content fails silently forty turns into a playthrough — the exact failure mode
that makes "just add data" unsafe for a non-programmer.
8. Distribution: ES modules in dev, one inlined file to ship
Chrome and Firefox block ES module imports and fetch over file://, so
"open the HTML file" and "modular JS with JSON content" are in direct conflict.
Resolved by serving during development (npm run serve) and inlining
everything into a single self-contained HTML file for distribution
(npm run build).
Related: content is authored as .js modules exporting plain objects rather
than .json. Same data, but comments and multiline strings are available —
which matters a great deal for narrative text — and it sidesteps fetch
entirely.
9. Tuning values live in the content pack
Relationship stats run 0–100 starting at 50, clamped; typical choice effects are a few points, so one choice matters but several turns of consistent behaviour are needed to move someone. Money is dollars. Turn is a day.
None of these are engine constants. They are declared in the pack manifest, so retuning the game — or a pack that runs on weeks instead of days — touches no code.
10. Naming
The product is The Ladder; the default content pack is Corporate Ladder. The planning docs use "Corporate Ladder" as the working title for both, which would have baked one setting into the product name, against the explicit goal that corporate is one pack among many.
11. Per-turn upkeep is declared by the pack
The MVP spec wants "basic income and basic recurring costs", but effects only run when a player chooses something. Baking wages and rent into every option would be tedious and easy to get wrong.
pack.upkeep is a list of { label, requires?, effects } applied at the end of
each turn, after the choice lands. It is still data — the engine reads it and
knows nothing about wages — and the conditions make it expressive enough to be
useful: Corporate Ladder's loan service charge is three conditional entries
forming a step function that escalates with the size of the debt, which needed
no multiply operation and no engine change.
Upkeep changes are recorded separately from choice changes in the turn record, so the UI can show "you chose this" and "and then the month happened" as different things.
12. Characters may start somewhere other than the pack default
relationshipStats sets the defaults; a character's startingRelationship
overrides individual stats. Trevor starts below the default on likes_you
because he arrived two weeks before you and has priced that in — which is
characterisation expressed as data rather than as an opening cutscene.
Nobody starts feared: fears_you defaults to 10 rather than 50, because a
midpoint default would mean every new hire arrives already intimidating.
13. Content is tested for reachability, not just validity
validatePack proves a pack can run. It does not prove any of it is ever
seen. The content suite plays 60 seeded runs and asserts that every event fires
and every option is taken at least once — dead content is otherwise invisible,
and two whole events plus a hard-times escape route were in fact unreachable on
the first pass because Trevor's gate sat above anything a player could
plausibly reach.
A trap that cost a cycle: the chooser's RNG must be seeded differently from the game's. Both draw exactly one number per turn from the same generator, so a shared seed correlates the choice index with the event draw and makes whole option combinations structurally unreachable. It presents as a content bug and is not one. Any headless playtest harness written later has to know this.