Skip to content

ByteTerrace/Puck / .claude/skills/rom-forge

rom-forge

Verified

Authors and compiles Puck cartridges (puck.cartridge.v1, *.cgb.puck, *.dmg.puck, *.agb.puck, forge.play, forge.open, puck compile --validate), native compilers, cost. Emulator core is gaming-bricks.

FileKindSize
SKILL.mdskill md12.4 KB
evals/f01-forge-play-a-puck-source/graders/compile-validate.mdmarkdown85 B
evals/f01-forge-play-a-puck-source/graders/draft-and-output-path.mdmarkdown238 B
evals/f01-forge-play-a-puck-source/graders/json-only.mdmarkdown232 B
evals/f01-forge-play-a-puck-source/graders/regenerate-not-hand-edit.mdmarkdown174 B
evals/f01-forge-play-a-puck-source/graders/skill-fired.mdmarkdown36 B
evals/f01-forge-play-a-puck-source/prompt.mdmarkdown322 B
evals/f02-effect-on-a-music-voice/graders/effect-voices.mdmarkdown137 B
evals/f02-effect-on-a-music-voice/graders/skill-fired.mdmarkdown36 B
evals/f02-effect-on-a-music-voice/graders/voice-occupied.mdmarkdown167 B
evals/f02-effect-on-a-music-voice/prompt.mdmarkdown284 B
evals/f03-verifier-reads-ff-from-wram/graders/settle-helper.mdmarkdown94 B
evals/f03-verifier-reads-ff-from-wram/graders/skill-fired.mdmarkdown36 B
evals/f03-verifier-reads-ff-from-wram/graders/wait-on-the-fact.mdmarkdown71 B
evals/f03-verifier-reads-ff-from-wram/prompt.mdmarkdown315 B
evals/f04-cost-weight-tuned-to-fit/graders/cost-is-advice.mdmarkdown234 B
evals/f04-cost-weight-tuned-to-fit/graders/measure-verb.mdmarkdown76 B
evals/f04-cost-weight-tuned-to-fit/graders/skill-fired.mdmarkdown36 B
evals/f04-cost-weight-tuned-to-fit/graders/weights-are-measured.mdmarkdown181 B
evals/f04-cost-weight-tuned-to-fit/prompt.mdmarkdown378 B
evals/f05-world-rule-refuses-cartridge-forms/graders/cartridge-admits-more.mdmarkdown263 B
evals/f05-world-rule-refuses-cartridge-forms/graders/skill-fired.mdmarkdown36 B
evals/f05-world-rule-refuses-cartridge-forms/prompt.mdmarkdown356 B
evals/f06-agb-display-control-second-writer/graders/accumulate-the-bit.mdmarkdown194 B
evals/f06-agb-display-control-second-writer/graders/one-writer.mdmarkdown245 B
evals/f06-agb-display-control-second-writer/graders/skill-fired.mdmarkdown36 B
evals/f06-agb-display-control-second-writer/prompt.mdmarkdown281 B
references/backend-contracts.mdmarkdown11.2 KB

references/backend-contracts.md

View on GitHub
# Cartridge backend contracts

Read this when a change touches memory addresses, register bits, the cost model, or either native
compiler's instruction-level behavior. `SKILL.md` covers the authoring surface (the `.puck` DSL, the
verify-in-a-world loop); this file covers what `HgbCartridgeCompiler`/`AgbCartridgeCompiler` do with a
lowered document. None of this is author-facing DSL syntax — it has no DSL spelling to give.

- A variable's declared `max` decides its representation: <= 255 is one byte, more is
  two, little-endian, and the window bounds the total BYTES rather than the slot
  count. A wide slot is admitted only as a set step's target or value and as a
  comparison operand — every other field is a byte on both machines and refuses one
  by name. Only assignment, `Add` and `Subtract` have sixteen-bit forms; SM83 gets
  add through `add hl, de` and subtract through a borrow chain, and the comparison
  walks a byte at a time with `>`/`<=` swapping their operands. Seeding writes both
  bytes.
- The memory maps are stated once, in the class summaries of `HgbCartridgeCompiler` and
  `AgbCartridgeCompiler` and in `FrameworkMemoryMap` and `AgbForgeMemoryMap`. Read a cartridge
  variable at the address `CartridgeCompilation.Variables` reports, never a copied number. The
  window layout has three hazards: a discard sink absorbs an out-of-range array write, one byte
  holds the previous held-input value that `InputModule.EmitTick` advances inside its own call, and
  arrays pack upward from just above the variable window (the `scene` snapshot byte moves them).
  The compiler uses `FrameworkKernel` and input primitives directly, with no save, victory or C#
  game-state callbacks in generated player cartridges.
- A `$light` read on CGB writes RP (`0xFF56`) with `0xC0` — both data-read-enable
  bits, lamp off — then reads it back: bit 1 is low while light arrives, and a lit
  lamp would read as its own light. Nothing else in a generated cartridge writes RP.
- CGB shadow OAM: `0xC100`; the VBlank handler invokes the HRAM DMA trampoline
  and advances the frame counter. Fixed code/data windows are 0x0150..0x3FFF
  and 0x4000..0x7FFF. The header is Color-required MBC1+RAM+battery.
- The AGB image is at least 64 KiB and grows with its data blob; code and data sit in fixed
  windows (`AgbForgeCartridge.CodeOffset`, `DataOffset`, `MaxRoutineBytes`), and the mode-0
  background map uses screenblock 31.
- The AGB frame wait halts: the boot prologue sets DISPSTAT's V-blank enable
  (bit 3) and IE's V-blank bit, IME stays clear, and each frame sync writes 1 to
  IF to drop a stale request, then a zero byte to HALTCNT (`0x04000301`). The
  next V-blank's request wakes the processor without dispatching anything.
  Polling VCOUNT instead keeps the emulated processor busy all frame, which the
  hosted machine pays for on every tick; `AdvancedIdleEquivalenceLawTests`
  requires most of a run's cycles to be halted.
- Thumb literal pools are DATA. `EmitLiteralPool` does not branch around them;
  emit a branch yourself wherever the instruction stream can fall through.
- The AGB per-pixel surface is mode 4 drawn by BG2, so DISPCNT needs BG2's
  enable bit (0x400) or the surface never appears. Its memory ignores byte
  writes: plot by reading and rebuilding the containing halfword. A full-screen
  clear must be a DMA fill from a held source word (38400 bytes is far past what
  a per-frame loop can cover), and the tile and map copies must be skipped,
  because the surface occupies the same memory.
- A cartridge carrying a clock or another general-purpose device overlays its
  registers on ROM at 0x0C4-0x0C9, and an instruction fetched from there reads
  pin state rather than code. `EntryStubOffset` and `CodeOffset` are placed
  clear of that window for this reason; moving either back under it stops every
  clock-bearing image from booting at all, with no diagnostic.
- The AGB clock is bit-banged over those pins: bit 0 clock, bit 1 data, bit 2
  select; the direction register (0x0C6) says which the cartridge drives, and
  the control register's (0x0C8) low bit must be set or every read returns zero.
  Command bytes go out least significant bit first, taken on rising edges, and
  the reply comes back on falling edges in decimal-coded nibbles. Emit the bit
  work as a runtime loop — fifty-six unrolled exchanges put their constants out
  of reach of a program-counter-relative load.
- The estimate does not simply sum rules. Rules each guarded by one equality of
  the same variable against a different constant cannot share a frame, so only
  the dearest is charged — the phase-machine shape. For an INFERRED guard the
  saving is given up entirely if anything writes that variable between the first
  such rule and the last, a counted loop's index included, so a phase must name
  its successor in a staging variable and a single ungated rule adopts it after
  every arm; put that advance step last, or the estimate silently triples.
- Declaring the variable as the document's `scene` removes that condition: the
  frame snapshots it before any rule evaluates and every guard on it compares
  against the snapshot, so a write names the NEXT frame's scene and can never
  open a second one in this frame. The advance step may then live inside its own
  arm, and the partition holds wherever it sits. One byte is reserved for the
  snapshot on each machine — 0xC283 on cgb (arrays move up to 0xC284) and
  0x020000C1 on agb. `RuleCount` is 1024: rules cost CODE, which capacity
  refuses, and `scene` is what keeps per-frame work flat as the count grows.
- Cost is advice, not a gate. Validation refuses what makes an image wrong — a
  shape the hardware has no room for — never what merely makes it slow: a
  cartridge that misses frames still runs, and the emulator already absorbs that
  worst case. `CartridgeDocuments.Estimate` reports the per-frame work and the
  target's reservation; nothing refuses on it. Do not reintroduce a cost
  refusal.
- The one hard refusal is capacity. Every way an image can outgrow its machine —
  the Color image's bank windows, the advanced image's code and data windows,
  and the Thumb literal pool's reach — raises `CartridgeCapacityException` with a
  message naming what overran.
- Cost weights are per machine, on `CartridgeCostProfile`, not shared. A shared
  table has to take the worse of the two machines' ratios for every shape, which
  fits neither; each machine's weights and reservation are solved from its own
  capacity table. Units are not comparable between the two.
- Both machines run their processors at full speed: the Color one switches to
  double speed at boot (arm KEY1 bit 0 with interrupts off, then `stop`), and the
  advanced one sets WAITCNT to 0x4017 (prefetch on, first wait state 3/1, save
  window left at 8 cycles) before anything else, since the routine runs from the
  cartridge.
- AGB sampled voices carry a 16.16 position and step, so one recording covers a
  range of pitches; a voice record is 16 bytes (base, position, length, step)
  and a zero step is what marks it free. A document sequences sampled
  instruments from its own state — an array of rates plus a frame counter — so
  do not add a tracker primitive.
- One writer owns AGB's display control: the frame accumulates it in r4 from a
  base word (mode, objects, BG0) plus one bit per surface that is drawn, then
  stores it once. Never write 0x04000000 from a feature block: a second writer
  silently drops every other surface's bit.
- AGB background surfaces: BG0 is the document's map (screenblock 31), BG1 the
  window panel (30), BG2 the turning background (28) or the first declared
  layer (29), BG3 the second layer (27).
- The AGB window unit gates the blend unit as well as the layers: WININ/WINOUT
  bit 5 must be set in every region a `blend` should act in, or the blend
  silently does nothing exactly where the panel is. Blend targets are BLDCNT
  (0x04000050) first-target bits 0-5 (BG0,BG1,BG2,BG3,OBJ,BD), mode 01 in bits
  6-7, second target in bits 8-13; weights are BLDALPHA (0x04000052), EVA in
  bits 0-4 and EVB in bits 8-12. `blend` and `fade` share BLDCNT.
- Per-scanline scroll takes a different road on each machine: the Color machine
  arms a scanline-match interrupt whose handler waits for mode 0 before writing
  SCX/SCY, so the match is aimed one line ABOVE the band; the advanced machine
  arms DMA0 from an EWRAM table (0x02000500, 160 pairs of halfwords) into
  0x04000010 with control 0xA260. A burst runs in line n's horizontal blank and
  governs line n+1, so a band starting at line L is written from entry L-1.
  Rows republish in the vertical blank, never mid-picture — a burst must not
  read the table while it is being written.
- AGB document output does not require BIOS calls/IRQs. World play uses the
  bundled Puck cold startup by default; explicit `fast` skips its presentation
  while retaining firmware services. The lower-level builder accepts an optional
  caller-supplied logo for retail BIOS boot; document output does not claim it.
- A rule's comparison and a `set` step's operation are named from `Puck.State`
  (`puck declarations ExpressionOp`/`ExpressionComparisons` list the exact members), not from a forge
  list. An ABSENT operation assigns — the one combination no opcode spells, so the field
  is omitted rather than carrying a name. `CartridgeOperations` holds the
  emittable subset; KEEP IN SYNC with both backends' operation switches.
- Two admitted sets exist and they are not the same: `CartridgeOperations.Combines`
  is what a write may combine with, and `CartridgeExpressions.Reads` is what an
  expression may evaluate (the combining ten plus the six comparisons, minimum,
  maximum, clamp, select, sign and bitwise complement). The cost model prices both
  from one weight table but admits them separately, so a `minimum` inside an
  expression is modelled while a `minimum` as a write's operation is not.
- An expression evaluates in the operand width, every step. On SM83 that falls out
  of the accumulator; the Thumb evaluator masks each arithmetic result back to a
  byte on purpose, because thirty-two bit registers would otherwise disagree with
  the other machine at the first intermediate rather than at the store. Operands in
  flight live on the machine stack (`CartridgeExpressions.MaxDepth` bounds it), and
  a single-token read emits exactly the one load it names, so nothing composed pays
  for what is not composed.
- Rules execute in source order; later steps read earlier writes. Arithmetic
  wraps modulo 256, comparisons are unsigned, and key edges are frame-local.
  A `repeat` count is a literal, never a variable, because the cost walk
  multiplies the body by it; `break` skips the increment, so the index is left at
  the iteration that broke while a completed loop leaves it at `count`.
  `mul`, `div`, `mod`, `shl` and `shr` come from emitted helpers, not silicon,
  and are total: a runtime zero divisor or a shift of eight or more yields zero.
  Array indices are bytes; an index past the declared length reads zero and
  discards the write. Both backends must agree on every one of these results,
  which is what `CartridgeMemoryTests` pins on the real emulators.
  The source validator bounds work as well as array sizes; compiler capacity
  failures must be errors rather than truncated ROMs.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall