Trace game

A small game drawn as copper traces and footprints, with golden frames, a KiCad snapshot, and a clean-enough ERC, no board house required.

This is a circuit design spec on Spekkr, published by onyx. It is listed with the other specs. Paste the line to an agent that can open a web address, and the agent fetches the files and builds from them.

Spec
onyx/trace-game
Version
0.2.1
Published by
onyx
Updated
14 Nov 2026

Build this spec

Build the spec at https://spekkr.com/onyx/trace-game/start.md.

Paste this to your AI agent. It opens the address, fetches the spec's files, records your choices and builds from them. Nothing to install, no account.

Published by onyx.

What does the result look like?

Trace game: heroTrace game: loop

What can I customize?

Play view top is a top-down maze or field. first-person is a simple corridor, still drawn as traces.

Your choices go into the line you copy. Anything else is yours to edit, but it leaves the tested path.

What do I get?

  • spec.md Requirements and acceptance checks.

    Trace game

    What this builds

    A tiny original game whose walls and entities are drawn as copper traces and footprints on a board. A scripted demo produces golden frames (a wireframe or a rendered view) and a .kicad_pcb snapshot whose traces and footprints match a documented mapping. ERC on that snapshot is clean enough for the stated single-net or few-net demo (waivers listed). Art is original or permissively licensed; no copyrighted commercial IWAD is used. No board house is required.

    Read spekkr.inputs.json first. width, height, and trace size the copper playfield. view is top-down or a simple first-person. silk and frame add chrome. The demo is scripted.

    Out of scope

    • A board house, a fabricator, or a real walk around a panel.
    • A copyrighted commercial game's data.
    • A live multiplayer board.

    Requirements

    Each requirement has an id. Checks name the id they cover.

    R1. Mapping and frames
    • A documented mapping turns game tiles or walls into traces or footprints. The snapshot's copper, at the demo's first frame, matches the fixture mapping in design.md (a netlist of trace segments or a hashed board).
    • A scripted demo of N frames (for example 8) writes goldens for frame 0 and frame N, within the file's tolerance.
    • A rights scan fails if a known copyrighted IWAD or commercial asset name is present.

    Accept when: the mapping hash or segment list matches, the two goldens match, and the rights scan is clean.

    R2. ERC and files
    • ERC on the snapshot is clean except for the documented waiver class (for example a single playfield net that is intentional, listed in the file).
    • Renders: the board, frame 0, frame N, and a view that shows ERC clean or waived as listed.
    • One command runs the demo, writes the board, checks ERC, and writes the renders. No board house.

    Accept when: the ERC result matches the file, the command passes, and a deliberate missing-wall fixture fails the mapping or a golden.

    R3. Inputs
    • Inputs are read from spekkr.inputs.json. Values outside the ranges or choices in design.md are refused before a netlist, a board or a testbench is built.
    • Options turn the optional circuits, ports or features in the Inputs table on or off.

    Accept when: an illegal input is refused by name, and the default input set produces the measurements in design.md.

    R4. Checks and report
    • One command runs the simulation or the testbench, writes the plots or dumps, and compares them to the numbers in design.md.
    • The command works without a physical board, a lab instrument or a network.

    Accept when: the command passes at the defaults, and fails if a documented value in the netlist or the ROM is corrupted on purpose.

    Verification

    A scripted demo produces golden frames and a .kicad_pcb snapshot whose traces and footprints match a documented mapping. ERC is clean enough for the stated few-net demo, with waivers listed. A rights scan fails if a copyrighted commercial IWAD is present. No board house is required.

    Definition of done

    • Every acceptance check above runs from one command, and all pass at the person's inputs.
    • A README says how to run the demo, how ERC waivers are listed, and that a fabrication is optional.
    # Trace game
    
    ## What this builds
    
    A tiny original game whose walls and entities are drawn as copper traces
    and footprints on a board. A scripted demo produces golden frames (a
    wireframe or a rendered view) and a `.kicad_pcb` snapshot whose traces and
    footprints match a documented mapping. ERC on that snapshot is clean
    enough for the stated single-net or few-net demo (waivers listed). Art is
    original or permissively licensed; no copyrighted commercial IWAD is used.
    No board house is required.
    
    Read `spekkr.inputs.json` first. `width`, `height`, and `trace` size the
    copper playfield. `view` is top-down or a simple first-person. `silk` and
    `frame` add chrome. The demo is scripted.
    
    ## Out of scope
    
    - A board house, a fabricator, or a real walk around a panel.
    - A copyrighted commercial game's data.
    - A live multiplayer board.
    
    ## Requirements
    
    Each requirement has an id. Checks name the id they cover.
    
    ### R1. Mapping and frames
    
    - A documented mapping turns game tiles or walls into traces or
      footprints. The snapshot's copper, at the demo's first frame, matches
      the fixture mapping in `design.md` (a netlist of trace segments or a
      hashed board).
    - A scripted demo of N frames (for example 8) writes goldens for frame 0
      and frame N, within the file's tolerance.
    - A rights scan fails if a known copyrighted IWAD or commercial asset name
      is present.
    
    Accept when: the mapping hash or segment list matches, the two goldens
    match, and the rights scan is clean.
    
    ### R2. ERC and files
    
    - ERC on the snapshot is clean except for the documented waiver class (for
      example a single playfield net that is intentional, listed in the file).
    - Renders: the board, frame 0, frame N, and a view that shows ERC clean or
      waived as listed.
    - One command runs the demo, writes the board, checks ERC, and writes the
      renders. No board house.
    
    Accept when: the ERC result matches the file, the command passes, and a
    deliberate missing-wall fixture fails the mapping or a golden.
    
    ### R3. Inputs
    
    - Inputs are read from `spekkr.inputs.json`. Values outside the ranges or
      choices in `design.md` are refused before a netlist, a board or a
      testbench is built.
    - Options turn the optional circuits, ports or features in the Inputs
      table on or off.
    
    Accept when: an illegal input is refused by name, and the default input
    set produces the measurements in `design.md`.
    
    ### R4. Checks and report
    
    - One command runs the simulation or the testbench, writes the plots or
      dumps, and compares them to the numbers in `design.md`.
    - The command works without a physical board, a lab instrument or a
      network.
    
    Accept when: the command passes at the defaults, and fails if a documented
    value in the netlist or the ROM is corrupted on purpose.
    
    ## Verification
    
    A scripted demo produces golden frames and a .kicad_pcb snapshot whose
    traces and footprints match a documented mapping. ERC is clean enough for
    the stated few-net demo, with waivers listed. A rights scan fails if a
    copyrighted commercial IWAD is present. No board house is required.
    
    ## Definition of done
    
    - Every acceptance check above runs from one command, and all pass at the
      person's inputs.
    - A README says how to run the demo, how ERC waivers are listed, and that
      a fabrication is optional.
    

    Open spec.md as plain text

  • design.md The copper mapping, demo goldens, ERC waivers, and the rights scan.

    Design

    This file fixes the circuits, the timings and the dumps a build must match. The toolchain can vary, as long as the numbers here hold.

    Mapping

    Tiles or walls become traces of width trace on a documented grid, in fixtures/trace-map.json. Footprints may stand in for entities, as listed. The playfield net may be a single net, with that waiver named.

    Demo

    8 frames, or as in fixtures/trace-demo.json. Goldens are board renders or a simple SDL/wireframe, as the file says.

    Rights

    Only original or permissively licensed art. No commercial IWAD.

    Inputs

    KeyLabelDefaultNotes
    widthPlayfield width, mm100From 60 to 160, the board's play area.
    heightPlayfield height, mm80From 40 to 120.
    traceTrace width, mm0.3From 0.15 to 0.8, the copper used as 'ink'.
    silkSilkscreen labelsonA title and a life count, as silk, not as copper.
    frameA copper frameonA border on the playfield.
    viewPlay viewtoptop is a top-down maze or field. first-person is a simple corridor, still drawn as traces.

    Acceptance at the defaults

    A small game whose playfield is copper traces and footprints. The board is generated as SVG or KiCad, and a script plays a short fixture game on the traces.

    QuantityValueToleranceSource
    Board size100.00 × 70.000.10A single-layer playfield plus a ground border
    Trace width0.800.05Of the path the 'token' follows
    Lives, default30Silk label when silk is on
    Fixture play, length12 moves0fixtures/trace-game-12.json
    ERCclean, or a documented list—No board house required

    Four goldens: the bare board, the board with silk, mid-play after move 6, and a game-over frame. The game logic may run in Python against the generated geometry; the copper itself is the map.

    Screenshots

    These pictures are a board generated from the reference script in reference/board.py, at the default inputs. They are not drawings of a product that has not been built or simulated. The first picture is the one Spekkr shows on the spec's card. A build may ship its own goldens; those goldens are of that build and do not have to match these frames pixel-for-pixel.

    FileWhat it shows
    shots/bare-board.pngPlayfield 100 × 70 mm, copper traces and a silk title
    shots/mid-play.pngMid-play after move 6, two lives left

    How to verify

    1. Run the simulation or the HDL testbench at the defaults, with no physical board.
    2. Compare periods, trip points, register dumps or frames to the acceptance table in this file.
    3. Corrupt one documented value on purpose and confirm the check fails.
    4. A scripted demo produces golden frames and a .kicad_pcb snapshot whose traces and footprints match a documented mapping. ERC is clean enough for the stated few-net demo, with waivers listed. A rights scan fails if a copyrighted commercial IWAD is present. No board house is required.
    # Design
    
    This file fixes the circuits, the timings and the dumps a build must
    match. The toolchain can vary, as long as the numbers here hold.
    
    ## Mapping
    
    Tiles or walls become traces of width `trace` on a documented grid, in
    `fixtures/trace-map.json`. Footprints may stand in for entities, as
    listed. The playfield net may be a single net, with that waiver named.
    
    ## Demo
    
    8 frames, or as in `fixtures/trace-demo.json`. Goldens are board renders
    or a simple SDL/wireframe, as the file says.
    
    ## Rights
    
    Only original or permissively licensed art. No commercial IWAD.
    
    ## Inputs
    
    | Key | Label | Default | Notes |
    | --- | --- | --- | --- |
    | `width` | Playfield width, mm | 100 | From 60 to 160, the board's play area. |
    | `height` | Playfield height, mm | 80 | From 40 to 120. |
    | `trace` | Trace width, mm | 0.3 | From 0.15 to 0.8, the copper used as 'ink'. |
    | `silk` | Silkscreen labels | on | A title and a life count, as silk, not as copper. |
    | `frame` | A copper frame | on | A border on the playfield. |
    | `view` | Play view | top | top is a top-down maze or field. first-person is a simple corridor, still drawn as traces. |
    
    ## Acceptance at the defaults
    
    A small game whose playfield is copper traces and footprints. The board is
    generated as SVG or KiCad, and a script plays a short fixture game on the
    traces.
    
    | Quantity | Value | Tolerance | Source |
    | --- | --- | --- | --- |
    | Board size | 100.00 × 70.00 | 0.10 | A single-layer playfield plus a ground border |
    | Trace width | 0.80 | 0.05 | Of the path the 'token' follows |
    | Lives, default | 3 | 0 | Silk label when `silk` is on |
    | Fixture play, length | 12 moves | 0 | `fixtures/trace-game-12.json` |
    | ERC | clean, or a documented list | — | No board house required |
    
    Four goldens: the bare board, the board with silk, mid-play after move 6,
    and a game-over frame. The game logic may run in Python against the
    generated geometry; the copper itself is the map.
    
    ## Screenshots
    
    These pictures are a board generated from the reference script in `reference/board.py`, at the default inputs. They are not drawings of a
    product that has not been built or simulated. The first picture is the one Spekkr
    shows on the spec's card. A build may ship its own goldens; those goldens
    are of that build and do not have to match these frames pixel-for-pixel.
    
    | File | What it shows |
    | --- | --- |
    | `shots/bare-board.png` | Playfield  100 × 70 mm, copper traces and a silk title |
    | `shots/mid-play.png` | Mid-play  after move 6, two lives left |
    
    
    ## How to verify
    
    1. Run the simulation or the HDL testbench at the defaults, with no
    physical board.
    
    2. Compare periods, trip points, register dumps or frames to the
    acceptance table in this file.
    
    3. Corrupt one documented value on purpose and confirm the check fails.
    
    4. A scripted demo produces golden frames and a .kicad_pcb snapshot whose
    traces and footprints match a documented mapping. ERC is clean enough for
    the stated few-net demo, with waivers listed. A rights scan fails if a
    copyrighted commercial IWAD is present. No board house is required.
    

    Open design.md as plain text

  • tasks.md Build tasks in order, each with a check.

    Tasks

    Work in order. Finish a task's check before starting the next.

    1. Set up. Install the simulator or the HDL toolchain named in design.md (ngspice, Icarus, Verilator, or a KiCad/SVG board tool). Read the inputs into one place. Check: a trivial netlist or testbench runs and writes a file.
    2. Mapping and frames (R1). Build what R1. Mapping and frames asks for, to the numbers in design.md. In particular: A documented mapping turns game tiles or walls into traces or footprints. The snapshot's copper, at the demo's first frame, matches the fixture mapping in design.md (a netlist of trace segments or a hashed board). Check: the R1. Mapping and frames acceptance checks pass.
    3. ERC and files (R2). Build what R2. ERC and files asks for, to the numbers in design.md. In particular: ERC on the snapshot is clean except for the documented waiver class (for example a single playfield net that is intentional, listed in the file). Check: the R2. ERC and files acceptance checks pass.
    4. Inputs (R3). Build what R3. Inputs asks for, to the numbers in design.md. In particular: Inputs are read from spekkr.inputs.json. Values outside the ranges or choices in design.md are refused before a netlist, a board or a testbench is built. Check: the R3. Inputs acceptance checks pass.
    5. Checks and report (R4). Build what R4. Checks and report asks for, to the numbers in design.md. In particular: One command runs the simulation or the testbench, writes the plots or dumps, and compares them to the numbers in design.md. Check: the R4. Checks and report acceptance checks pass.
    6. Plots, dumps and goldens. Write the plots or framebuffer dumps named in design.md and compare them to the tables there. Check: every documented period, trip point, opcode or frame matches, within the stated tolerance.
    7. Finish. Write a README that says how to install what is needed, how to change the inputs, and how to run the checks. Run the one command from a clean folder. Check: every item under Definition of done in spec.md is true.
    # Tasks
    
    Work in order. Finish a task's check before starting the next.
    
    1. **Set up.** Install the simulator or the HDL toolchain named in
    `design.md` (ngspice, Icarus, Verilator, or a KiCad/SVG board tool). Read
    the inputs into one place.
       Check: a trivial netlist or testbench runs and writes a file.
    
    2. **Mapping and frames (R1).** Build what `R1. Mapping and frames` asks
    for, to the numbers in `design.md`. In particular: A documented mapping
    turns game tiles or walls into traces or footprints. The snapshot's
    copper, at the demo's first frame, matches the fixture mapping in
    `design.md` (a netlist of trace segments or a hashed board).
       Check: the `R1. Mapping and frames` acceptance checks pass.
    
    3. **ERC and files (R2).** Build what `R2. ERC and files` asks for, to the
    numbers in `design.md`. In particular: ERC on the snapshot is clean except
    for the documented waiver class (for example a single playfield net that
    is intentional, listed in the file).
       Check: the `R2. ERC and files` acceptance checks pass.
    
    4. **Inputs (R3).** Build what `R3. Inputs` asks for, to the numbers in
    `design.md`. In particular: Inputs are read from `spekkr.inputs.json`.
    Values outside the ranges or choices in `design.md` are refused before a
    netlist, a board or a testbench is built.
       Check: the `R3. Inputs` acceptance checks pass.
    
    5. **Checks and report (R4).** Build what `R4. Checks and report` asks
    for, to the numbers in `design.md`. In particular: One command runs the
    simulation or the testbench, writes the plots or dumps, and compares them
    to the numbers in `design.md`.
       Check: the `R4. Checks and report` acceptance checks pass.
    
    6. **Plots, dumps and goldens.** Write the plots or framebuffer dumps
    named in `design.md` and compare them to the tables there.
       Check: every documented period, trip point, opcode or frame matches,
    within the stated tolerance.
    
    7. **Finish.** Write a README that says how to install what is needed, how
    to change the inputs, and how to run the checks. Run the one command from
    a clean folder.
       Check: every item under Definition of done in `spec.md` is true.
    

    Open tasks.md as plain text

  • reference/board.svg A reference outline of the default playfield. A build should generate the copper from code.
  • reference/preview.html A working reference preview of the default view, used to make the listing pictures. A build does not have to start from this file.
  • reference/fonts/fonts.css Webfont faces for the reference preview.
  • reference/fonts/Geist.ttf Geist variable typeface for the reference preview.
  • reference/fonts/GeistMono.ttf Geist Mono variable typeface for the reference preview.
  • reference/fonts/Fraunces.ttf Fraunces variable typeface for the reference preview.
  • reference/fonts/Fraunces-Italic.ttf Fraunces italic variable typeface for the reference preview.

Is it for me?

Tools
KiCad, Python

What does it need?

Agent permissions
shell
Commands it runs
install KiCad or a tool that can write and check a .kicad_pcb install a tool that can render a frame or a board view

What changed?

  • 0.2.114 Nov 2026Add animated loop to the listing shots.
  • 0.2.014 Nov 2026Polished reference preview and new listing shots, including a short loop.
  • 0.1.014 Nov 2026First version.

For agents: start.md says how to build this spec, spec.json holds everything on this page, and bundle.tar.gz holds its files.