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

GitHub

Gaming 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 AdvancedGamingBrickCore and HumbleGamingBrickCore APIs and default factory composition. The shared Machine hosting runtime owns the host contract; both Post embedding stages exercise it without a worker, renderer or audio device.
  • Keep firmware identity separate from startup mode. MachineBootMode.Fast skips 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 inside Sm83, Ppu or Apu. 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's absorbsQuietStretches: false and single Step calls are the references; ColourIdleEquivalenceLawTests and AdvancedIdleEquivalenceLawTests compare 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.Advance through WorldMachineHost.SynchronousSteps while world.lockstep is on. Ordinary presentation keeps asynchronous Submit. A source upload's publication number identifies the upload, not the native frame its worker finished: compare WriteFrame'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 families 10 and fb are documented oracle-conflict skips in the sst-sm83 stage, never silent exclusions. The Tier-A sm83-stop-pending-interrupt stage covers the pending edge; the acceptance ei_sequence ROM 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, the intr_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-churn and boot_sclk_align).
  • A --cosim run 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-crash and the rest) boot the bundled Puck firmware unless --bios names 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 or AgbLinkSession console that stops being able to run (Undefined or Abort mode, a fetch from a region with no code) throws AgbExecutionFaultException, which machine.state shows as fault=.
  • 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 through FramebufferRgba.Pack (Puck.Machines.Post), never MemoryMarshal.AsBytes of 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's TransferRegisters). No file records the layout; a deliberate layout change raises CurrentVersion of MachineIdentity (Humble) or AgbMachineIdentity (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 one HgdBoardMemory; a new board does the same. Board timing comes only from IHgdMapper.ObserveM2 and ObservePpuAddress: 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 in BoardLawTests, and its fixture joins PostMachine.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; the blargg-suites and accuracy-coin stages 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.PackSioControl does 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 C link-replay and link-churn micro-ROMs poll IF with IME off. Implementing the bits adds a stage for it: derive them from the modeled AgbLinkCable partner, 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 --bios names 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 own folder.json, written by machine.default (puck-world, engagement), so nothing committed names it.

Workflow

  1. Identify the affected machine and capability: shared SM83 compatibility in Puck.HumbleGamingBrick, or native ARM7TDMI GBA in Puck.AdvancedGamingBrick.
  2. Read the relevant hardware contract and inspect the current implementation, stage registry (PostStages.cs in each Post project), and Post README. Do not infer timing from names or old stage counts.
  3. Make the smallest hardware-model change that explains the evidence. Keep clock conversions exact, event ordering explicit, and snapshots complete.
  4. 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.
  5. 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.Post README 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-divergence and 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 under experimental/ 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.