Rough items noticed while working, not necessarily in scope for the current task. Checked off
when fixed; cleanup passes move checked-off items to TODO-done.md (last done 2026-11-04, CHANGES
#233; before that 2026-10-25, #152 and #140; 2026-10-24, #134, and 2026-10-08, #67), so resolution history stays visible — except where a cleanup
pass has explicitly moved that history into CHANGES.md/docs/testing-strategy.md/design/features/*.md
instead (2026-09-13; see CHANGES.md entries 5-8 and 11-14, and docs/testing-strategy.md's Tier 2
addendum).
What waits on the owner: anything to read, listen to or decide is on the story chain review page
(design/research/story-chain/serve.py: a decision as a card in options.md, anything else as a row on
its topic's tab; the To review tab was removed 2026-11-01); the cabinet sessions, physical work and
things outside the repo are in HumanToDo.md.
Structure (2026-10-25, owner: "rewrite the todo in that structure"): what a complete
single-player game still needs, from the analysis of 2026-10-25. The trunk's five periods, every
ending and every choice are built on the virtual platform; what's left is presentation (lights,
music, sound), real numbers, hardware, and a handful of smaller story pieces.
A. Must-have for single player, software only - buildable now.
B. Build work waiting on the owner's answers (the answers themselves are on the review page).
C. Blocked on hardware (software stand-ins work today).
D. Polish - the game is complete without it.
E. Not part of single player (the Wheatley branch, co-op, tools, the sound library).
Proposed order (revised 2026-11-04, CHANGES #233): since the first order (2026-10-25) the music
carousel (A3), the D34 picks (A10), the Wheatley branch (B1/E1), the speaker bar and the art (D2/D3) were
built. What's left of A is mostly wiring what's already picked. (1) A cabinet smoke test with the owner -
the trough → plunger transfer (C0), then one full game on the real machine; it was first on the list a
week and a half ago and still hasn't happened, and every tuning item (C8) and A1's light choice wait on
it. (2) A4 + D10, the picked sounds and Cave bites (picked, not wired). (3) A9's cleanup (retire mb_dropbank/super_wizard, the shot map's rows) and A8's playtest gaps. (4) A1 lights per period.
(5) A5, A6, A11, A12. Open owner questions: ball holds now as a software stand-in or after the VUKs (C2);
lights now or after the cabinet check (A1).
¶ A. Must-have for single player (software, buildable now)
A1. Lights per period (the plan: design/LIGHTING.md, drafted 2026-10-31, its options picked 2026-11-01
(CHANGES #174), the lights and shows to OK on the review page's Lighting tab; design/rule-sheets.md's "Not built yet" per period): no
story mode has a show or light player yet - only the major shots' inserts light (major_shots,
40 lights). A show per chapter, the hurry-ups (the neurotoxin clocks, the choice windows), the
multiballs, the endings.
A2. Scoring and jackpot values per period (docs/scoring.md): put
the table into every story mode, check the choice and DECISIVE values. All scoring is DRAFT
placeholder values, not tuned - in particular the bonus tally (100/shot), the multiball start
bonus (+3000), the 3 wizard-mode tier groupings and their scores, portal's per-stage exit_open
bonuses, dropbank's bank-completion escalation (+500/repeat), and the sling combo window (3 s
sliding). Tuning with real numbers waits on the cabinet (C8).
A3b. The music, the rest (the carousel was built 2026-11-03, CHANGES #217; A3 is in TODO-done.md): design/MUSIC.md's "Not built yet" - the Faith Plate's and the Hard Light Bridge's cues in period 1 (their
moment needs a pick), period 2's gel symphony per decade, the last core's low pulse; listening on the
cabinet. (Co-op's carousel is E2, Robots FTW waits for an extra ball.)
- Three songs kept for later (owner, 2026-10-22, from E3's candidates; design/callouts.md
"Kept for later"): Bring Your Daughter to Work Day's 16 s cut, Reconstructing More Science
(8 s) and Some Assembly Required (7 s), all _RT short cuts that end on their own. music-plan.md proposes moments for all three (Reconstructing More Science at game start, Bring Your Daughter at the science fair, Some Assembly Required on a co-op drain); move them
into those callouts rows (still not in the music mode, 2026-11-04).
A4. Wire the picked sounds:
- [ ] The 2026-10-24 sound picks (design/callouts.md, marked "sound library" and D32/D33):
the effects table (the button blips, the turret fire while turrets are lit, the long-fall
landing on a Faith Plate launch or VUK eject, the crusher in period 2, the potato power-up, the
tube pop on the slings), the new voice rows (the escape hatch, the neurotoxin start, the new
pools), and the cut A23 (GLaDOS waking).
(2026-10-31: the slings and the Faith Plate keep their draft sounds, owner on the To review tab -
the tube pop and the long-fall landing aren't wired there; the long fall may still suit a VUK eject.)
- [ ] The six replaced draft effects (owner, 2026-10-31, CHANGES #163): skillshot_test_chamber_pos, dropbank_incinerator, lanes_turret_chirp, multiball_ball_lock, portal_dropper_whoosh and portal_exit_chime (.wav + .import in machinefolder/sounds/sfx/) no longer play anywhere;
delete them once the owner OKs it.
- [ ] Period 1 sounds (owner, 2026-10-18/19; callouts): A15 at the first transfer, A16's
long version at ball 1's lock; live fire's lead-in line; the incinerator escort line always
plays; the cube's "never threaten to stab you" in the hold is dropped; the fling (one line),
the funnel (a pool of 2), the laser relay's three sounds and LIE complete's voice pool (6,
incl. A18).
- [ ] The "lost you" lines (owner, 2026-10-18; callouts rule 12): ball search's lines also
play, rarely, in Rattmann's passage (with the hints layer), on a portal transfer
(story_p1/portal sound players) and when the ball is held ~8 s with nothing happening.
Ball search's own lines aren't wired yet either.
- [ ] Drains, still open (modes/drains): the "one shot from finishing" line (the Wheatley
branch's pool is E1, period 5's falling scrawl D).
- [ ] Hook up the cut-but-unwired PA lines as their features arrive: the hurry-ups (H1-H5,
e.g. period 3's neurotoxin clock - built 2026-10-25), the lucky-save P34, the turret-wave
P30/P31, P67 on the route-choice timeout, B4 for the chapter select, A1/A5's light shows
(portal and turret LEDs, with A1). Ball-saver taunts: the ball save exists in software; the
tilt taunts wait for the tilt switch (C1).
A5. Skill shot per period (owner's toy note 2026-10-19): the skillshot mode still takes any top lane. The design: a top lane made from the plunge with Up1
down - Up1 is a draft (C3), so build the per-period software part now with any top lane.
A6. LIE and CAKE completion as parallel modes running from 1A (owner's toy note,
2026-10-19; today lanes scores them, story_layers holds the cake).
A7. The meter and memory, the rest (the plan meter-and-memory.md, retired 2026-11-03): the file
card's art (D) and the moon rock's file row (waits for the moon rock) are what's left; the attract
"COMPLY OR DEFY" page's text was picked (CD2) and set 2026-11-01 (CHANGES #182). Built
2026-10-31 (CHANGES #161): the two-page file, the E8 memory; the attract stats fix was already
in #138 (config/machine-stats.yaml counts the last core's shot). The card's art was built
2026-11-04 (D3, CHANGES #224), so only the moon rock's file row is left - it goes with A9's moon rock.
A11. HOW TO PLAY, the explanation mode (H92): an attract page / flipper-hold explainer with each
period's sign rules, no developer commentary clips (owner, 2026-11-01, CHANGES #181). Not built yet;
it was the last open step of the retired plan finish-open-plans.md.
A12. D34, the rest (CHANGES #218): H123's answer to 1B's first camera line and the blind spot's +5 s
passage (once the camera line and CAMERAS BLIND are built); H126's sign words (SUBJECT POOL: 1 / VOLUNTEERS /
PAID / MANDATORY on the signs); H139's three-on-the-sign cycling; (H138's drain word was dropped
2026-11-04 with "what the ball is" - its question for the owner is in D11);
H130's SUBJECTS OF RECORD and ADMINISTRATOR ACCESS titles (custom high-score and service screens); H132's rule
that the turret bank stays down until LEAVE FOR GOOD's window closes; H136 with the Wheatley branch.
A8. Screens and playtests:
- [ ] Refresh tools/art/sign_icon_plan_sheet.py after the sign-icon build (CHANGES #92;
its unchanged icons still show the old 8% crop). The screens review itself is current (the
review page's Screens tab). The plan sheet is untouched since 2026-10-10 - check whether anything
still reads it before refreshing; if not, retire it.
- [ ] Playtests that follow the difficulty level: the scenarios are scripted shot by shot
for Advanced Testing's counts, so playtests/base.py runs them at difficulty=2 unless --setting difficulty=N; at level 0, period 1 (1A ends on the 2nd test) and period 4 (the
super lights on the 3rd jackpot) fail their scripted steps. Make the steps read dl_*.
- [ ] No playtest reaches the lemons multiball (found 2026-10-19 with A19): period_2 stops
at 2C's start, so the lemon speech, the rant at the super jackpot lit, the payoff at the super
jackpot and meet yourself (A21, its slide; story_p2) are only checked by tests/test_story_p2.py (the events) and the config refs (the files) - extend the scenario
through the lemons to hear them play in GMC.
- [ ] Measure the meter's lean in playtests (critic panel, 2026-10-24; D32 fixed the
lock-in: +9 to -15, keeping the cube no longer locks in BURN): an even meter still lights BURN -
check how often it ends even.
A9. Cleanup:
- [ ] Mode headers behind the design (the 2026-10-24 readability pass; story_p2's part was
found fixed 2026-11-04): story_p4's header says it starts "when period 3 ended in E2 or the
dive", but its start_events also start it after period 5 (p3_ending>=4 and p5_chapter==5).
Fix the header; check the other story modes' headers against their start events the same way.
- [ ] Retire mb_dropbank (modes/multiball) once the story trunk is live: it's the feature
phase's placeholder multiball; it's now kept out of 1C and everything from 2C on.
- [ ] Retire super_wizard: it still runs on its old progression gate with a flat score;
its design (D28, the jackpot tour) is built in modes/story_p3 (CHANGES #66). See the
jackpot-tour idea in IDEAS.md and design/research/outside-perspective.md's note on Pat
Lawlor-style thematic tie-ins.
- [ ] The shot map's per-chapter "not in the config yet" rows (2026-10-16): mostly the
layers (LIE, CAKE, Rattmann's hint passage in periods 1-3, the standups' side uses) and 1C's
jackpots; check them against what's built rather than building them one by one.
- [ ] Period 2's moon rock (design/rule-sheets.md, period 2): the last software
extra of period 2 still open.
¶ B. Waiting on the owner's answers (on the review page)
Build work that starts when the answer comes in; the questions themselves are cards or entries on
the review page.
B4. The "president Doug Rattmann" line (period 4, design/rule-sheets.md's Period 4 build note): no file found in
the catalogue - the owner to point at it.
B7. The away reviews' follow-ups (docs/reviews/2026-10-25-1-*, -2-*), each on the owner's yes:
a stage 1 check that fails on a real hold coil at default_hold_power: 1.0 (the diverters and
magnet are parked at 1.0 in hardware-draft.yaml; the flippers' 1.0 in hardware-coils.yaml would
need an exception); find out whether OPP firmware 2.x exists for chain 2's PSOC boards (1.0.0.4
today - the wing pairing rule and software lamp fading come from it); turn off the trough
devices' debug: true (hardware-devices.yaml) once the C0 smoke test is done. (The coil
templates were already gone, #157.)
The naming renames and ledtag3 were done 2026-10-25 (#153, docs/naming-conventions.md).
¶ C. Blocked on hardware (software stand-ins work today)
Flippers, start/launch buttons, the plunger-lane/trough-eject coil migration to the Cobra board,
and the sling/ball-saver bring-up (including the pin swaps found, pulse tuning, and the
ball-saver's weak-spring root cause) are all done — see CHANGES.md entries 11-14 for the full
history, or docs/wiring-guide.md for current pin numbers/status per component.
C0. Trough→plunger ball transfer not confirming - check first (found 2026-09-06 during the
first live real-hardware game start): bd-trough's eject to bd-plunger pulses c-trough-eject and then fails/retries every ~10s (balldevice_bd-trough_ball_eject_failed)
indefinitely — the plunger-lane eject-confirm switch likely isn't registering the ball's
arrival. The trough itself works since 2026-10-04, but this was never closed: if it's still
broken no real game starts, so it's the first thing at the cabinet smoke test.
C1. Tilt: no tilt switch exists at all yet — needs a physical switch installed before any
config can follow. Per design/research/outside-perspective.md, MPF ships a complete built-in tilt
mode — once the switch exists, the MPF-side work is modes: [tilt] plus tagging the
tilt-bob switch tilt_warning and slam-tilt switch slam_tilt (gets warnings-to-tilt,
settle_time, multiple_hit_window for free). Then the tilt taunts and Still Alive's "I'm not
even angry" on the first warning (D).
An accelerometer instead (owner question, TS-12, 2026-10-06): MPF's accelerometers: device
only supports the MMA8451 over I2C (smbus2, Linux, or a P3-ROC); OPP has no I2C and MPF runs
on Windows here, so a plumb bob + slam switch on OPP inputs is the practical route
(design/research/story-brainstorm/notes-response.md).
C2. Ball holds and the VUK locks: the only real ball devices are the trough and the plunger
lane; the VUKs are drafts, so the held moments (chapter cards, the super jackpots, C5, period 4
and 5's holds) carry on with the ball in play, and the locks count switches. Needs the core locks
(VUK5/7/8 with ball switches), the Blue Portal's own VUK (a registry part in hardware-draft.yaml
once its place is decided), VUK1-4. Open question: a software stand-in now (the ball held in the
plunger lane, or the flippers off for a few seconds)?
- Leftovers from the shot list's implied changes (design/shots.md, 2026-10-05; CHANGES
#71): balls_installed: 4 in hardware-basic.yaml while the trough holds 6; the portal
pre-load logic (Up3 drops a ball into Portal A's VUK, a replacement auto-launches, a shot into
another portal VUK releases it); the drop bank resetting targets dropped too early unless the
exit's conditions are met, with the turret firing/dying sounds; each physical lock
auto-launching a replacement ball. Check each against the rule sheets before building it.
- portal.md describes the old ball-dropper model (found 2026-10-04): the portal mode is
the sequence s-vuk6 → s-portal-r → s-portal-m → s-exit-success, from August's CAD reading.
The owner's description since: Div1 → VUK6 (the lock) → the see-through ball dropper box →
servo gate Servo1 drops the ball onto the playfield, no switches on the path. Plus Portal A
(ball lock by the right ramp) and Portal B (an upkicker on the left) in design/STORY.md.
Needs the open questions in STORY.md answered (what s-portal-r/-m and s-exit-success
are, which part Portal A is) before portal.md and the mode can be redesigned.
C3. The story's posts and toys: KD1 (sabotage knocks a turret down), Up2 (period 3's
shortcut gate), Up4 (the Incinerator post), Up1 (the skill shot, A5), the magnet (2C's Adhesion
Gel hold), the shaker (the climax), the lemon target Pull1 (2C: until it has a switch the Super
Button is the super jackpot shot and the ramps score the lemon jackpots, story_p2.yaml), the
7th standup (Rattmann's count).
C4. The spinner has no use in any mode yet (design/shot-map.md, 2026-10-09): s-spin1 is
still in hardware-draft.yaml (not installed). Once it is: a spinners: device, a score, and its
rule-sheet role (period 5's secret test, PA-D7).
C5. Attract: the turrets waking now and then (design/STORY.md's Attract, lights): waits
for turret LEDs - none are wired (CHANGES #74 step 7 built the portals breathing).
C6. Hardware ideas from the story work (2026-10-06): 22 candidate parts (standup before the
Super Button, drop post at the Incinerator via Up4, LED strips on the free incandescent outputs,
dropper auto-reload, 3 special locks via VUK5/7/8, shaker, plumb-bob tilt, magnet, servo toys...)
with an I/O budget (~11 coil outputs left after the drafted parts, 3 servos, 16 lamp channels
free) are in design/research/story-brainstorm/hardware-ideas.md. The ones the story uses were
registered as ideas on 2026-10-07 (KD1, LED strips, hint row, Mag1, shaker, tilt, small
screen; plans/story-to-build.md step 5, (retired, CHANGES #160)); open check: which S-Target label sits between the
button and the Incinerator. Decided 2026-10-06: Up4 = Incinerator post, Up2 = period 3 shortcut
gate, the dropper auto-reload gets a launch-lane diverter (registry launch-lane-diverter,
idea only).
C6b. The owner's hardware notes of 2026-10-25 (HW-26..30 in design/research/story-brainstorm/hardware-ideas.md, all ideas in the registry, all need a
playfield change): launch-lane-diverter-2 and orbit-top-diverter (portal loaders), panel-ramp (moving-panel ramp on a BSv1-type post), funnel-exit-post (the funnel's two
exits), hidden-side-sensor (inductive proximity). All but the sensor (a sound on the review page) are idea_only: true since 2026-11-04 (CHANGES #234): the story doesn't use them yet. First checks before building: can an
auto-launched ball reach each diverter, and does the sensor's 12-24 V NPN output suit an OPP
input. The placements go to the cabinet session with the other playfield decisions (HumanToDo.md,
owner's answer of 2026-10-25, #143).
C7. Right ramp diverter + subway: CAD-confirmed real mechanism, electrically drafted
(dv-ramp-diverter, c-ramp-diverter coil, all in hardware-draft.yaml) but not wired for
real. Now diverter Div1 in the "Ball dropper" feature group; the CAD subway switches turned
out not to exist and were removed 2026-10-04.
C8. Tuning with real numbers (after the cabinet runs):
- Re-check the scoring (CHANGES #89, docs/scoring.md): the table is calibrated against
the simulator's guessed shot rates and ball times; once the cabinet's audits measure them, put
them in tools/sim/playthrough.py SKILLS and re-run tools/sim/scoring.py. Also the owner's
call on the targets themselves.
- The scoring sim has no combo/trick category (2026-10-16, scoring-benchmark.md): add the
ramp and sling combos (docs/scoring.md 2) to tools/sim/scoring.py as their own share, so
story vs trick vs toy can be measured; needs a combo-rate guess per skill until the cabinet.
- Later (owner, D29): numbers per difficulty level (H96): re-run tools/sim/playthrough.py with each level's dials; STORY.md's "25-30 min" and "a beat
within ~5 shots" then name their level, with level 0's figures next to them, and the
high-score file shows the level.
C9. Service mode: the nav switches (sw_service_enter/esc/up/down) are electrically
drafted, not wired (owner 2026-10-04: buttons not obtained yet - optional, only needed to open
MPF's service menu without a laptop; registry parts Service-Enter/Esc/Up/Down), and there are no
service-mode slides (MPF's service mode is enabled, but the display shows nothing for it, so the
menu is only usable from a laptop, mpf service).
C10. OPP wiring checklist (from design/research/outside-perspective.md's community research,
apply before any DRAFT item above gets wired for real): confirm every driver + the switch that
triggers it via a hardware rule (done for the flippers and slings, all on chain0-0x20; still
to do for the pop bumpers, the Mid-Flipper and the BSv2 kickback) land on the same physical OPP board/CPU — OPP/CobraPin hardware rules don't cross board boundaries, so
a switch and its coil on different boards in the chain silently fail to produce a working
rule. Also run the grounding/flyback-diode checklist from pinballmakers.com's OPP wiki page
(all grounds tied together at the power supplies; 4004-type flyback diodes across every
coil) — a floating ground can damage boards.
Optional: retest the old 520-7001-00A trough opto board with the corrected bridge
firmware - its "dead U1" was most likely the same RCK polarity bug. The rest of the
trough opto story is solved (the trough fully works since 2026-10-04): history in TODO-done.md and docs/stern-spike-trough-opto.md.
Once physical multiball is wired and playtested for real: MPF's own "Common Issues" doc
says a ~10s pause when adding a ball during multiball is expected — the launcher waits for
the ball device's eject_timeouts config, not a playfield-switch confirm (that method
doesn't work with >1 ball in play). Worth remembering so a slow multiball ball-add reads as
an eject_timeouts tuning task, not a bug hunt.
Archive the Portal Wiki pages behind the online screenshots (CHANGES #201): it rate-limited (HTTP 429)
after a few requests. Still to save, one every few seconds, with the script's logic in tools/art/online_shots.py's
API: Aerial Faith Plate, Doug Rattmann, Emergency Intelligence Incinerator, GLaDOS, Handheld Portal Device,
Propulsion Gel, Repulsion Gel, Wheatley (picks' sources), Help:Taking Screenshots, List of useful console commands,
Companion Cube (cited by plans/game-screenshots.md).
D1. Period 1-3's smaller layers (rule sheets 1B "Smaller"): catch me (the dropper's release
as Wheatley's rail), the hacking easter egg, the oracle turret, Rattmann's 7th-standup count (C3),
the singing turret's ✂ serenade; and GLaDOS naming the sabotage count by number (story_p3_side
shows it, no voice). Built 2026-10-24 in modes/story_layers: Wheatley's visits, sabotage, the
singing turret, the laser relay, The Surprise, LIE / CAKE.
D11. The speaker bar and the art list, the rest (CHANGES #224):
- Hear and see it on the cabinet: the bar polls GMC's voice bus each frame; check the pages keep pace with
long lines (Cave's 17 s ones) and that a queued line takes over cleanly.
- The Space, Fact and Adventure cores borrow Wheatley's turned render (no render of their own yet: tools/art/render_toys.py with their eye colours); ATLAS and P-body have no voice lines yet (co-op).
- Some story lines' words come from speech-to-text (text_source: stt in the catalogue) or an edit's
shortened note ("Demand to see life's manager! ... burn your house down"): read them on the bar.
- H138's drain word (TODO A12) was to follow what the ball is (OW-3), dropped 2026-11-04: it needs a rule of
its own (the period's thing: CUBE in period 1, CORE in period 3 ...) or goes too - ask the owner.
- The art list's blocked items (the retired plans/art-and-screens.md): the recap cards with their stated defaults (D27) wait for
the chapter select (E1b), co-op's courses for co-op (E2), the small playfield screen for its hardware
(HW-20, C6).
D4. Still Alive:
- Cut a short slice for E1 (owner, 2026-10-24): the song's start, played at the surface and
cut off by the radio's crackle; the full song stays for the credits lap.
- Later (owner, D29): wire the song (H97): music_portal_still_alive.ogg (176.5 s) to E1
and the credits lap (placeholder credits, no music today); a vocal slice "I'm not even angry"
for period 3's first tilt warning once a tilt switch exists (C1).
D5. Audio cuts:
- STORY.md's "Open points: Audio edits" (owner, 2026-10-24): the broken PA fragments and the
momentum line's cut, below (the faster Space Core copies are the branch's, E). The listens are
on the review page.
- The momentum line's two bites (D29, edit A11): made 2026-10-31 (CHANGES #165); to wire:
the live bite on 1A's Left Orbit test in place of the whole line, the held one at the next plunge.
- Cut "Cave Johnson. We're done here." (D29, edit A12) made 2026-10-31 (CHANGES #164);
no moment plays it yet (period 2's dismissal).
- The Fine Print's Cave bites made and wired 2026-10-31 (A29, CHANGES #164).
- Period 4's ✂ cuts of the long DLC lines the boot (28 s -> 6.7 s), the door and both
glitches made and wired 2026-10-31 (A28, CHANGES #164); the dial clicks' and the ride's era
bites wait on the Cave bite picks.
- The script's other named Cave cuts (A28, made 2026-10-31): the tilt warning, extra ball lit,
2B's gel test done and the risky shot wait for their moments to be built/wired.
- Period 5's scrambled PA words (A4; modes/story_p5 header) and the single broken PA
words: need word timings - faster-whisper in the portal-stt venv
(tools/sounds/transcribe.py), or by ear. The candidates are listed in design/sounds/pa-snippets.md (owner to pick and add requests; W and S cuts can be made now, T
cuts wait on the timings). Word timings work on the PC since 2026-10-07 (edit group A9).
- Audio edits the story needs (2026-10-06): pre-made variants of real files - period 5's
broken PA fragments: six announcer lines cut off mid-sentence with radio static over them, plus
single words cut from them ("Button", "System", "Turret", "Testing", "Portal", "Cube", "Exit",
"Warning!"...) (design/research/story-brainstorm/period5-rattmann.md, P5-17); also the
attract wake-up cut (D28). Made 2026-10-07 by tools/sounds/edits.py into assets/sounds/edits/ (list in design/sounds/edits.csv); still to do: each one's listen and
cut adjustment (on the review page), the single PA words, the cuts marked ✂ in design/callouts.md.
D6. Period 5's standard moments as sounds and its falling scrawl on screen at a drain
(modes/story_p5 header, modes/drains).
D10. Cut and wire the OK'd Cave bites (2026-11-01): all 28 picks on the Cave's bites tab
(design/sounds/cave-bite-proposals.yaml, marked picked: period 4's, 2B's orbits and C1b's from round 1;
period 2's gel tests, blue and yellow lines, drain, ball search, ball start, bonus and 2C's card from round 2)
still need their own files (tools/sounds/edits.py), their rows in design/callouts.md and their moments wired.
Six review-page blocks without a plain summary (seen 2026-11-04): the Wheatley, GLaDOS, Cave,
Caroline and Rattmann threads' "Where and when" and Rattmann's "Act I: wake up" (chain_review.py --plain-todo).
E1b. The Wheatley branch, the rest (CHANGES #219): the chapter select's two branch chapters
(no chapter select yet); PotatOS's comply verdict as a bite (glados_potatos_caroline_ohmygod08 plays
whole, the cut before "Can you handle..." isn't made); Portal 2's finish on the branch's E1 (Cara Mia
Addio, the cube thrown out after you, Want You Gone - the branch's C3 is story_p3's today; the branch's background on C3's
screens: done 2026-11-04, CHANGES #221); the corrupted cores seated in their own
locks and E7's magnet grab (hardware, HW-15); the reactor clock's "mash" (a timeout only warns); held from
D32: H112 (in 3B Wheatley remembers a missed catch, and after 3+ visits "Do you remember when we were
friends?") and R2 (C0's lit side by his visits found, once 1C's visit triggers exist).
E2. Co-op (the design's Play modes).
E3. GMC's voice bus (needs a fix in mpf-gmc itself; the endings work around it):
- The first-portal line plays twice in the period 1 playtest (found 2026-10-19, playtest-runs/20261019-133237-period_1/; also in older runs): MPF posts logicblock_t1a_portal_complete once (13:32:54), but GMC's voice bus plays glados_01_part1_get_portal_gun-2_trim again at 13:33:03, between the 1B cube-chain lines
that arrive in a burst at fast speed. Looks like a queue replay on the sequential voice bus;
check whether it happens at watch speed and on the cabinet before fixing.
- After a voice-bus stop, the bus queue no longer moves on (found 2026-10-09 with GMC's sound
debug log, [gmc] logging_sound_player=10 in gmc.cfg): a line queued after a bus_player
stop never plays, and one sent in the same moment as the stop gets queued. The small endings
work around it (a 1 s gap, the second line chained on the first's events_when_stopped).
Worth a GMC repro (docs/gmc-bugs.md).
- Sound speed/pitch: GMCChannel.gd has no pitch or playback-speed setting, so a story idea
that plays a line faster each time (SC-S10 v2, the Space Core on repeated orbits) needs
pre-rendered faster copies of the files, or pitch_scale support added to GMC's sound
settings (Godot's AudioStreamPlayer has it).
E4. The sound library's catalogue:
- Commentary has no text in the catalogue (2026-10-06): the 83 kind=commentary rows in catalog.csv have an empty text. Both games ship it in their caption files
(#commentary\... keys); tools/sounds/scripts.py already reads it into design/sounds/commentary-*.md, so captions.py could fill the catalogue the same way.
Related: captions.py doesn't read Portal 2's update\ folder, where the Peer Review DLC's
co-op lines are (scripts.py does); Portal 1's commentary audio isn't in the rip, only the
text is; the com-arg.wav node (sp_a2_pull_the_rug) has no caption text in the installed
files.
- Mis-tagged lines found by the story brainstorm (2026-10-06), to fix in tag-overrides.yaml (to listen on the sound library's own review page, tools/sounds/review_page.py): wheatley_temp_wheatley_crush.ogg is GLaDOS's chapter-2 line ("...For science. You
monster."), probably a temp recording; glados_escape_01_death_nag01-1's caption holds a
stage direction ("On entry to boss room:"); speech-to-text invented "Thanks for watching!" on 8
turret sound files with no speech, plus turret_active and other_hubactivated_cardinal; many
core and defective-turret lines call the player "lady" or "angel" - check them against the
unnamed test subject before using them; docs/sound-library.md says the cake recipe has no
captions, but the catalogue marks sphere_cakemix-17, -22 and -24 as caption - one of
the two is wrong.
- Lines not found (2026-10-06): check the rip and the installed games for "Exile Vilify",
Wheatley's post-credits apology ("I wish I could take it all back..."), a phone-ring sound (the
red phone), and Portal 1's own portal enter/exit sounds (only in the installed game).
E5. Dev tooling:
- The music mode misses a service-mode exit (found by the 2026-11-04 review): modes/music stops on game_ended only, but leaving service mode ends a game without it, so the next game_started finds it
running. speaker_bar and small_ending also stop on service_mode_entered, game_start; the music mode's
config is generated (tools/sounds/music_mode.py), so fix it there.
- Same-day screen renders sort by name (found 2026-11-04): chain_review.latest_render takes the last
folder by name, so 2026-11-04-art-list lost to that morning's -p3w-backdrop (renamed to 2026-11-04-round-v9-art-list). screens.json's generated holds only the date: add the time and sort by it.
- hw_console can't edit summary: / area: / category: / idea_only: (2026-10-04): the registry
fields behind the generated design/playfield.md and design/overview.md are hand-edited in components.yaml for now. Add them to the detail pane and the "+ Add element" dialog (area as
a dropdown of registry.AREAS).
- Trim the feature files' Rules sections (2026-10-04): converting them to Markdown kept all
prose, including implementation notes ("IMPLEMENTED 2026-08-27… corrected…") that repeat
the mode configs' comments. Per design/README.md, implementation detail belongs in the mode
config; move anything not already there, then cut it from design/features/*.md.
- hw_console has no committed tests (2026-10-04): the parallel-status-flags change was
verified with throwaway scripts (Flask test-client API checks, a concurrent-PATCH check, and
a Playwright click-through driving the installed Edge via channel="msedge", no browser
download). Worth turning those into a tests/test_hw_console.py. Playwright isn't a project
dependency yet.
- in_code auto flag misses MPF-internal uses (2026-10-04): it's a text search of this
repo's config, so the Service-Enter/Esc/Up/Down parts read no even though MPF 0.80's
built-in service mode hardcodes those sw_service_* switch names in its own source. It also
counts a name used in a mode that isn't listed under config.yaml's modes:. Acceptable per
the plan; revisit if it misleads (e.g. a per-component override, or skipping unlisted modes).
- tools/atmega328p-trough-bridge/'s .ino firmware has no dedicated conventions doc,
unlike the rest of the project's documented subsystems (surfaced during the KM-overhaul
planning pass, 2026-09-13).
- True graceful Ctrl+C shutdown for tools/mpf-session.ps1: current -Action Stop is a
tracked Stop-Process (hard-stop), not a real SIGINT to MPF's own signal handler —
deliberately deferred in favor of simplicity, since a hard-stop was verified safe on this
hardware (OPP boards de-energize drivers on serial disconnect, COM ports release cleanly).
A true graceful stop would need a small Win32 helper (AttachConsole/ GenerateConsoleCtrlEvent) to deliver a real CTRL_C to the child process. Revisit only if
MPF's own clean-shutdown logic (e.g. flushing something mid-write) ever actually matters.
- Windows USB selective suspend fix isn't repo-level: idle OPP COM ports crashed a live mpf session twice during real-hardware bring-up (2026-09-06), fixed via a powercfg
change on this laptop's power plan (see CHANGES.md entries 11-12) — not something version
control preserves, so it would need reapplying if this laptop is reimaged or the power plan
gets reset.
- Spike mpf-ls (official MPF language server — lint/autocomplete/diagnostics for MPF YAML)
against machinefolder/config/*.yaml and machinefolder/modes/*/config/*.yaml to see what
it flags — a candidate answer to the "no mpf format/lint tool exists" gap noted in CHANGES.md entry 7.
- Consider adding a single Mermaid flowchart to design/README.md showing how the 8 Phase 3
features and super_wizard connect — deathsave/grand-prix keeps one in docs/logic/ index.md; that relationship currently only lives in scattered mode configs and CHANGES.md
prose.
- Consider MpfFakeGameTestCase (overrides start_game()/drain_ball(), no ball devices
needed) for fast, hardware-independent tests of pure rules logic — e.g. the sling combo
window or dropbank escalation — as an alternative to routing through the real trough-fill
machinery docs/testing-strategy.md had to work around.