This is the process for turning a game-story idea into a buildable MPF mode, and the structured
way we track where each feature is in that process. It replaces board Overviews.xlsx's "Modes"
sheet as the living source for new feature design — the xlsx stays as a historical
hardware-planning reference, not deleted.
Every fact has one home (CHANGES.md #49): physical parts in the registry
(tools/hw_console/data/components.yaml — label, summary, playfield area, pins, build status),
game features in design/features/<id>.md, the narrative in design/STORY.md, the agreed shot
list and the owner's playfield walkthrough in shots.md. The overview
tables are generated from those, never hand-written: overview.md (features × parts
× CAD × status, plus the parts no feature uses yet) and playfield.md (every part by
area).
Shots per chapter: the design is the toy table in rule-sheets.md; what the
mode configs actually do, per chapter and per shot, is the generated shot-map.md
("Per chapter" puts the two side by side). The owner reviews the whole chain story -> chapters ->
modes -> shots on research/story-chain/review.html (the final review; the workshop is backup.html) (see research/story-chain/README.md).
Every feature decomposes into 5 layers. Moving a feature from top to bottom is the workflow:
design/STORY.md; once confirmed for a feature, copy it into that feature's ## Story.components.yaml. LEDs are listed per feature (leds:, by name from hardware-leds.yaml).tests/test_design_docs.py checks every part and LED actually exists.shot, shot_group, counter, accrual,sequence, achievement/achievement_group, ball_save, drop_target_bank, ...) and themachinefolder/modes/<name>/. Pick the device that matches the mechanic rather thanaccrual (or a sequence), a staged progression isachievements, a group of lanes or targets is a shot_group (its shot profile states givemachinefolder/modes/<name>/slides|shows).design/features/<id>.md: a YAML front-matter header between --- lines, then a Markdown
body.
design/schema/feature.schema.json: id, name, status, mode and parts (a list of{part, role}) are required; cad (Onshape names), leds ({ref, role}) and devices{type, name}) are optional. Copying _template.md and filling in nothing but id should## Story, ## Rules (with ### Scoring), ## Presentation,## Notes (open questions, gaps). It renders as a normal page in the wiki.status is the tracking field — a feature's position in the workflow is visible at a glance in
the generated overview:
idea -> designed -> implementing -> implemented -> tested -> live
Run python -m unittest discover tests (from the repo root, venv active — see
docs/testing-strategy.md) any time to validate every feature file and cross-check its parts,
LEDs and mode.
IDEAS.md first (already the user's freeform space — no processdesign/features/_template.md to design/features/<id>.md. status: idea.TODO.md instead of designing around hardware that isn't there.status: designed.design/SCREENS.md for the canonical catalog of screens/slides across alldesign/LIGHTING.mdmachinefolder/modes/<name>/config/<name>.yaml (+ slide/show),base/attract pattern, and add the mode to config.yaml's modes:status: implementing while in progress. Implementation detail belongs in the modempf -X -t -b (Tier 1) and a new tests/test_<name>.pydocs/testing-strategy.md. Set status: implemented once the mode boots clean,tested once it has a passing automated test.status: live once confirmed working on the cabinet. Log anything decision-worthy inCHANGES.md.The 8 features from the resumption roadmap's feature phase (CHANGES.md #3) — lanes, orbits,
slings, skillshot, dropbank, aerial, portal, ramps — all have a feature file and a
built mode with an automated test, at status: implementing. None is live yet: most of their
switches are still in hardware-draft.yaml, not wired. Open questions in each file's
## Notes are real gaps, left for a design pass rather than invented.
See overview.md for every feature's CAD names, parts, pins, LEDs and status, plus
the parts no feature uses yet, and playfield.md for every part by playfield area.
Both are generated by tools/hw_console/generate_docs.py, so edit the feature file or the
registry part, not the page.