gaming-bricks
Fixes Puck GB/GBC/GBA and NES/Famicom (HGD) emulators: CPU, PPU/STAT timing, APU, links, snapshots and Post batteries (--cosim, --filter). Cartridges: rom-forge.
SKILL.md.claude/skills/gaming-bricks/SKILL.md
GitHubGaming Bricks
Treat the GamingBricks as one deterministic machine family: a shared SM83
compatibility core covering every DMG/MGB/SGB/CGB/AGB hardware revision
(src/Puck.HumbleGamingBrick), plus the separate ARM7TDMI-based GBA-native core
(src/Puck.AdvancedGamingBrick). src/Puck.Machines holds what both share:
snapshots, the instance/fork/pool lifecycle, queued hosts, link groups. The Humble
Gaming Deck adds the NTSC NES/Famicom console on the same substrate; its master
tick is distinct from either handheld clock. Read its
manual and run
Puck.HumbleGamingDeck.Post for changes to that core. The current implementation
and its Post stages are authoritative; update stale skill guidance in the same
change.
Core invariants
- Advance emulated state only from integer clocks and explicit inputs.
- Keep configuration in constructor parameters or CLI options, never environment
variables. AGB diagnostic hardware/trace overrides live in
AgbMachineOptions; preserve them across forks and include behavioral options in typed snapshot identity. - Preserve direct embedding through the public synchronous
AdvancedGamingBrickCoreandHumbleGamingBrickCoreAPIs and default factory composition. The shared Machine hosting runtime owns the host contract; both Postembeddingstages exercise it without a worker, renderer or audio device. - Keep firmware identity separate from startup mode.
MachineBootMode.Fastskips startup without discarding the selected image; AGB still executes runtime BIOS services from that image. Explicit low-level diagnostic inputs remain supported. Bundled images are generated ahead of packaging, never by a runtime-to-Forge dependency. - Keep floating point and host timing beyond a one-way presentation seam.
- Express console differences through capability gates (a named question on
ConsoleModelExtensions), not forked SM83 cores and not a revision switch insideSm83,PpuorApu. A fix that needs no model question needs no gate. - Preserve snapshot, replay, fork, and cross-machine link determinism.
- Keep every idle fast path exact: an absorbed quiet stretch, a display ticked
alone, or a halted span leaves the state the reference stepping would.
ComponentClock'sabsorbsQuietStretches: falseand singleStepcalls are the references;ColourIdleEquivalenceLawTestsandAdvancedIdleEquivalenceLawTestscompare them over the shipped cartridges. A ticked cycle withdraws both cached clock agreements, including the others-only bound: rejoining the display to a stale bound can skip a timer edge. - External suites, co-simulators, Post stages and golden replays are evidence about the hardware model. A stage or replay that a better-sourced correction moves is updated with the correction.
Contracts that bite
- Lockstep presentation completes machine steps. The World selects
IMachineRuntime.AdvancethroughWorldMachineHost.SynchronousStepswhileworld.lockstepis on. Ordinary presentation keeps asynchronousSubmit. A source upload's publication number identifies the upload, not the native frame its worker finished: compareWriteFrame's version and bytes when diagnosing screen or screen-light repeatability. Adding a GPU fence wait can hide a late worker frame without fixing its completion boundary.
Each is detailed in references/hardware-and-oracles.md.
- STOP and EI are oracle conflicts, not bugs.
ExecuteStop(Sm83.Decode.cs) consumes STOP's pad byte (PC+2) only when no interrupt is pending (IE & IF, independent of IME) and leaves it when one is latched. The SingleStepTests/sm83 corpus models STOP as one byte and re-arms EI when IME is already set, so families10andfbare documented oracle-conflict skips in thesst-sm83stage, never silent exclusions. The Tier-Asm83-stop-pending-interruptstage covers the pending edge; the acceptanceei_sequenceROM pins EI. - The GB PPU schedule is one coupled contract. Mode transition, polled STAT,
VRAM and OAM locks, the mode-0 interrupt, the LY-comparison pulse and the
fetcher order move together. Never tune one lag constant alone, and never move
the PPU onto SameBoy's dots: the decompositions are measured and refuted
(Refuted PPU schedule decompositions),
and the screenshot corpus is the gate. Acceptance cases that pin it by name:
hblank_ly_scx_timing, theintr_2_*family,intr_1_2,stat_irq_blocking,lcdon_timing,lcdon_write_timing. - Timer before serial at equal timestamps, and serial edges follow the free-running
DIV counter, never the moment SC is written (
link-churnandboot_sclk_align). - A
--cosimrun under about 60 frames proves nothing (the boot logo scroll dominates it). Give a CPU-stream comparison at least 120 frames and check that the record count differs per ROM before believing a clean result. - Know which AGB BIOS ran before blaming firmware. Advanced Post
diagnostics (
--render,--trace-crashand the rest) boot the bundled Puck firmware unless--biosnames another image, as a World does; only the battery runs the zeroed stub, where any SWI or IRQ runs off into zeroed BIOS memory. A hosted core orAgbLinkSessionconsole that stops being able to run (Undefined or Abort mode, a fetch from a region with no code) throwsAgbExecutionFaultException, whichmachine.stateshows asfault=. - Every core's framebuffer is packed
0x00RRGGBB(ITimeTravelMachineCore.Framebuffer, red in bits 16-23; the advanced brick sets the alpha byte), because the queued worker repacks it for the World's screens in that order. A PNG or a hash of the image goes throughFramebufferRgba.Pack(Puck.Machines.Post), neverMemoryMarshal.AsBytesof the words, which spells blue first. - Snapshot layout is one list per component. Every component lists its fields
once in a
TransferState(a Humble mapper'sTransferRegisters). No file records the layout; a deliberate layout change raisesCurrentVersionofMachineIdentity(Humble) orAgbMachineIdentity(Advanced). - Deck boards own offsets, not memory, and time from bus edges. NROM,
MMC1 (
HgdMmc1) and MMC3 (HgdMmc3) keep every RAM byte, the battery save's layout and its snapshot order in oneHgdBoardMemory; a new board does the same. Board timing comes only fromIHgdMapper.ObserveM2andObservePpuAddress: MMC1's consecutive-cycle write rule counts M2 falls, and MMC3's counter clocks on a PPU A12 rise after three whole low M2 cycles. A board's laws live inBoardLawTests, and its fixture joinsPostMachine.Fixtures, which the determinism, fork and mid-instruction replay stages all run. A Deck cycle's transaction runs at the read point mid-M2 and its write lands as M2 falls, with the interrupt sample; theblargg-suitesandaccuracy-coinstages are the judge of Deck timing (owner ruling in the Deck manual), never another emulator or a game's look. A Deck program that clears the CPU's I flag inhibits the APU frame IRQ ($4017 = $40) first, or the shared IRQ line never drops. - GBA multiplayer SIOCNT has an unmodeled ready line.
AgbSerialController.PackSioControldoes not derive the SD/SI bits from cable-partner presence, so a program that polls the ready lines to find a partner never sees one. No committed stage covers a partner-polling program; the Tier Clink-replayandlink-churnmicro-ROMs poll IF with IME off. Implementing the bits adds a stage for it: derive them from the modeledAgbLinkCablepartner, never from ambient state, update the reference, and close the gap in open items. - Tests never depend on a commercial ROM or a retail BIOS (owner ruling). A
stage, test or CI step runs on committed sources and the fetched homebrew and
test-cartridge corpora, and a stage whose only input is a licensed image is
deleted, not kept (a retail-BIOS control inside a stage runs only when
--biosnames one by hand). A commercial ROM or retail BIOS is a local, by-hand input to a diagnostic (--render,--bios) and stays out of the repository, its builds, packages, logs and commit messages. A world device boots one only as the owner's local default: the git-ignored folder's ownfolder.json, written bymachine.default(puck-world, engagement), so nothing committed names it.
Workflow
- Identify the affected machine and capability: shared SM83 compatibility in
Puck.HumbleGamingBrick, or native ARM7TDMI GBA inPuck.AdvancedGamingBrick. - Read the relevant hardware contract and inspect the current implementation,
stage registry (
PostStages.csin each Post project), and Post README. Do not infer timing from names or old stage counts. - Make the smallest hardware-model change that explains the evidence. Keep clock conversions exact, event ordering explicit, and snapshots complete.
- Show the change working by running the Post stages it reaches in Release
(below), or by booting a cartridge that exercises it. Diagnostic flags
(
--stat-trace,--render,--cosim) explain a run; they are not a verdict. Add a self-checking stage only where running cannot show the behavior. No file records an expected outcome: a corpus ROM that fails today fails its stage on every run until the emulator is corrected, and the machines plan tracks them. - Report the exact commands, selected stages and asset-gated skips.
Test a hosted machine with the debugger
Start a headless worktree World with devices none and use the debug world's machine debugger. Set its screen, body and hardware RAM range while run is zero, pose the driver beside the screen from the host, then set run=1. It uses ordinary engagement and player input folding, checks native progress, compares neutral/held RAM, restores a checkpoint, compares two program traces, and swaps/ejects through provider operations. Read each machine's summary and per-check ticks, host.log and machineDebuggerViolations; use world.addons for last/peak/total fuel. Run=2 plays runtime segments; run=3 fuzzes a seeded window. No game addresses or title knowledge belongs in this guest.
The debug world runs 30 world ticks per second, holding inputs across about two native
frames. Hash/probe reads drain workers; checkpoints preserve their rational cycle phase,
so these generic checks need no extra frame-stamped input seam. Every queued core
implements pure PeekByte/PeekBytes (AGB's reads bus inspection, including byte
lanes of 16-bit IO registers); the inherited default peeks zero and hides live RAM.
The focused hardware-access law checks nonzero bytes and native progress after restore.
The authored machine-debugger-tests.puck runs bundled diagnostic cartridges, with a withheld-input responsive failure as a negative control. All default cartridges also need a live headless pass: a diagnostic passing does not prove an arbitrary game handles a particular button. Record from boot before any addon steps when investigating a failure with replay.drive; the addon receipt and machine inputs reproduce the check.
Run it
The batteries are CPU-only executables; none opens the GPU.
dotnet run --project src/Puck.HumbleGamingBrick.Post -c Release -- --fetch-corpora
dotnet run --project src/Puck.HumbleGamingBrick.Post -c Release -- --filter <stage-text>
dotnet run --project src/Puck.AdvancedGamingBrick.Post -c Release -- --tier A
--fetch-corpora fills the pinned corpus cache once. Iterate with --filter or
--tier; Tier A needs no assets, Tier B runs over the fetched corpora, Tier C
covers serial, link and infrared exchange. A stage whose asset is absent skips
(--require-assets turns that into an infrastructure failure), and the report
lists every skip. Report stage and skip counts from stdout; exit 0 alone does
not prove a stage ran. Exit 0 is pass or skip, 1 a failed check (a corpus ROM that does
not pass included), 2 infrastructure. tests/Puck.HumbleGamingBrick.Tests and
tests/Puck.AdvancedGamingBrick.Tests run their battery with an empty corpus cache,
so CPU suites cover the self-contained stages (and the cores they check). The
Puck.*.Post harnesses are outside the 100% coverage denominator.
Load references selectively
- Read references/hardware-and-oracles.md for clock and event ordering, serial and timer edges, snapshots, GB PPU timing, oracle conflicts, and the documented GBA ready-line gap.
- Read the
Puck.Machines.PostREADME first when a change touches stage or verdict semantics rather than one brick's own context — the shared battery scaffold all three Post projects close over:PostBattery<TContext>,IPostStage<TContext>,PostVerdict,PostTier,MachineStageTable,HashDivergenceReport,MachineBenchmark,CpuTestMemory,SstComparison,PostCommandLine,CorpusManifest,CoreEmbeddingProbe. Bind shared stages and benchmarks there; keep CPU registers, stepping, embedding checks and report wording in the owning battery. - Read the
Humble Post README for
tiers, the corpus suites and their per-case result rules, BESS,
--dump-snapshot,--hash-divergenceand the co-simulation workflow. - Read the Advanced Post README for current tiers, assets, ARM/GBA diagnostics, co-simulation normalization, and the accuracy workflow.
- For a rendered accuracy check rather than a Post stage, write a framebuffer with
Humble Post
--render <rom> <out.png> [frames] [dmg|cgb|agb]and compare it by eye or against a reference capture. The authored comparison worlds (hgb-compare.puck,hgb-mirror.puck) are quarantined underexperimental/and are not run. No test, tool, or asset names a licensed image, not even as a default path.
Route adjacent work
| Skill | Use when |
|---|---|
maths-usage |
Selecting or changing deterministic numeric primitives shared with emulator state. |
maths-laws |
Authoring law-suite coverage for a changed public Puck.Maths member. |
content-search |
Finding stage names, registers, opcodes, ROM identifiers, or timing constants textually. |
symbol-analysis |
Resolving semantic C# references, implementations, or rename and deletion safety. |
puck-world |
Integrating an emulator into world/session behavior beyond the emulator-host seam. |
rendering |
The renderer, SDF and shaders that present a machine's framebuffer; the emulator itself has no GPU path. |
rom-forge |
Authoring or compiling the cartridge under test — puck.cartridge.v1, the .puck DSL, or the native CGB/AGB compilers, rather than the emulator core executing it. |
verification |
The landing bar, building before testing, and reading a flaky versus failing leg. |