Tiny demo scene

A tiny-gate demo in Verilog: a testbench, a gate-count cap, and golden framebuffer dumps, with no FPGA or tapeout required.

This is a HDL 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/tiny-demo-scene
Version
0.2.1
Published by
onyx
Updated
14 Nov 2026

Build this spec

Build the spec at https://spekkr.com/onyx/tiny-demo-scene/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?

Tiny demo scene: heroTiny demo scene: loop

What can I customize?

Simulator Either must pass the same testbench and goldens, within a documented pixel tolerance if timing differs by a cycle at reset.

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.

    Tiny demo scene

    What this builds

    A small, original demo that fits in a tight gate budget (around 4k gates, as counted by a documented tool), written in Verilog. A testbench clocks the design and dumps a framebuffer. Golden frames are compared. No FPGA, no board, and no tapeout are required. The art and the music (if any) are original.

    Read spekkr.inputs.json first. title may appear on a frame. width and height size the buffer. audio and scanline change what is dumped. sim is the simulator.

    Out of scope

    • A real FPGA, a tapeout, or a board in the checks.
    • A copyrighted demo or a commercial game's art.
    • A gate-array vendor's licence server.

    Requirements

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

    R1. Testbench and goldens
    • The testbench runs a documented number of frames (for example 4) and writes framebuffer dumps. Frames 0 and N (the last, or a mid frame in the file) match goldens within the tolerance in design.md.
    • If title is drawn, the pixels of the title region match a mask or a glyph dump in the file.
    • Reset is deterministic: two runs hash the same dumps.

    Accept when: the golden frames match, the title mask matches if used, and two runs hash equal.

    R2. Gate cap and files
    • A documented count (Yosys or an equivalent, with the script in the repo) reports a gate or cell count at or under 4096, or the bound in the file, for the default size.
    • Renders: frame 0, frame N, a title-card still, and a small diff view (empty when goldens match).
    • One command simulates, counts, and writes the dumps and renders. No FPGA.

    Accept when: the count is under the cap, the command passes for both simulators, and a deliberately large fixture exceeds the cap.

    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 Verilog testbench dumps a framebuffer that matches golden frames. A documented gate-count script stays at or under the cap. Two runs are deterministic. No FPGA, no handheld, and no tapeout are 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 simulate, how the count is taken, and that a tapeout is optional.
    # Tiny demo scene
    
    ## What this builds
    
    A small, original demo that fits in a tight gate budget (around 4k gates,
    as counted by a documented tool), written in Verilog. A testbench clocks
    the design and dumps a framebuffer. Golden frames are compared. No FPGA,
    no board, and no tapeout are required. The art and the music (if any) are
    original.
    
    Read `spekkr.inputs.json` first. `title` may appear on a frame. `width`
    and `height` size the buffer. `audio` and `scanline` change what is
    dumped. `sim` is the simulator.
    
    ## Out of scope
    
    - A real FPGA, a tapeout, or a board in the checks.
    - A copyrighted demo or a commercial game's art.
    - A gate-array vendor's licence server.
    
    ## Requirements
    
    Each requirement has an id. Checks name the id they cover.
    
    ### R1. Testbench and goldens
    
    - The testbench runs a documented number of frames (for example 4) and
      writes framebuffer dumps. Frames 0 and N (the last, or a mid frame in
      the file) match goldens within the tolerance in `design.md`.
    - If `title` is drawn, the pixels of the title region match a mask or a
      glyph dump in the file.
    - Reset is deterministic: two runs hash the same dumps.
    
    Accept when: the golden frames match, the title mask matches if used, and
    two runs hash equal.
    
    ### R2. Gate cap and files
    
    - A documented count (Yosys or an equivalent, with the script in the repo)
      reports a gate or cell count at or under 4096, or the bound in the file,
      for the default size.
    - Renders: frame 0, frame N, a title-card still, and a small diff view
      (empty when goldens match).
    - One command simulates, counts, and writes the dumps and renders. No
      FPGA.
    
    Accept when: the count is under the cap, the command passes for both
    simulators, and a deliberately large fixture exceeds the cap.
    
    ### 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 Verilog testbench dumps a framebuffer that matches golden frames. A
    documented gate-count script stays at or under the cap. Two runs are
    deterministic. No FPGA, no handheld, and no tapeout are 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 simulate, how the count is taken, and that a
      tapeout is optional.
    

    Open spec.md as plain text

  • design.md The gate-count cap, the testbench timing, and framebuffer goldens.

    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.

    Budget

    4096 gates or cells, as counted by the shipped script (the file states the exact Yosys command or the cell library). The default 320 by 240 design must fit. Larger buffers may exceed it and are then out of the cap check, as the file says.

    Goldens

    fixtures/demo-frames/ holds frame 0 and frame N. Pixel tolerance: 0 (exact) for a digital dump, or 2 levels if a dither is documented.

    Frames

    N is 3 (the fourth frame, 0-based), or as in fixtures/demo-timing.json. Clock rate and reset cycles are in that file.

    Inputs

    KeyLabelDefaultNotes
    titleDemo titleA tiny sceneShown in the first frames, if the design has a font, or only in the README if not.
    widthFramebuffer width320160, 320 or 640.
    heightFramebuffer height240120, 240 or 480.
    audioA tiny audio registeroffA documented register dumped by the testbench; no speaker is required.
    scanlineA visible scanline effectonA documented effect in the framebuffer.
    simSimulatorverilatorEither must pass the same testbench and goldens, within a documented pixel tolerance if timing differs by a cycle at reset.

    Acceptance at the defaults

    A small HDL demo: a 320 × 240 (or documented 160 × 120) framebuffer, a bouncing mark, and a scanline option. The testbench dumps frames.

    QuantityValueToleranceSource
    Frame size320 × 240exactDefault; 160 × 120 is accepted if documented
    Frame count in the loop600A full cycle of the bounce
    Background colour#10141c—As 24-bit RGB in the dump
    Mark size16 × 160The bouncing rectangle
    Scanline darkening12%2%When scanline is on, odd rows

    A Verilog (or VHDL) testbench clocks the design and writes PPM or raw frames. Frame 0, the mid bounce, and frame 59 are compared to goldens. No FPGA board is required. Icarus or Verilator is enough.

    Screenshots

    These pictures are dumps of a working reference model of the core, in reference/preview.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/frame-0.pngFrame 0 320 × 240, mark in the corner, scanlines on
    shots/mid-bounce.pngMid-bounce the 16 × 16 mark, scanlines on

    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 Verilog testbench dumps a framebuffer that matches golden frames. A documented gate-count script stays at or under the cap. Two runs are deterministic. No FPGA, no handheld, and no tapeout are 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.
    
    ## Budget
    
    4096 gates or cells, as counted by the shipped script (the file states the
    exact Yosys command or the cell library). The default 320 by 240 design
    must fit. Larger buffers may exceed it and are then out of the cap check,
    as the file says.
    
    ## Goldens
    
    `fixtures/demo-frames/` holds frame 0 and frame N. Pixel tolerance: 0
    (exact) for a digital dump, or 2 levels if a dither is documented.
    
    ## Frames
    
    N is 3 (the fourth frame, 0-based), or as in `fixtures/demo-timing.json`.
    Clock rate and reset cycles are in that file.
    
    ## Inputs
    
    | Key | Label | Default | Notes |
    | --- | --- | --- | --- |
    | `title` | Demo title | A tiny scene | Shown in the first frames, if the design has a font, or only in the README if not. |
    | `width` | Framebuffer width | 320 | 160, 320 or 640. |
    | `height` | Framebuffer height | 240 | 120, 240 or 480. |
    | `audio` | A tiny audio register | off | A documented register dumped by the testbench; no speaker is required. |
    | `scanline` | A visible scanline effect | on | A documented effect in the framebuffer. |
    | `sim` | Simulator | verilator | Either must pass the same testbench and goldens, within a documented pixel tolerance if timing differs by a cycle at reset. |
    
    ## Acceptance at the defaults
    
    A small HDL demo: a 320 × 240 (or documented 160 × 120) framebuffer, a
    bouncing mark, and a scanline option. The testbench dumps frames.
    
    | Quantity | Value | Tolerance | Source |
    | --- | --- | --- | --- |
    | Frame size | 320 × 240 | exact | Default; 160 × 120 is accepted if documented |
    | Frame count in the loop | 60 | 0 | A full cycle of the bounce |
    | Background colour | #10141c | — | As 24-bit RGB in the dump |
    | Mark size | 16 × 16 | 0 | The bouncing rectangle |
    | Scanline darkening | 12% | 2% | When `scanline` is on, odd rows |
    
    A Verilog (or VHDL) testbench clocks the design and writes PPM or raw
    frames. Frame 0, the mid bounce, and frame 59 are compared to goldens. No
    FPGA board is required. Icarus or Verilator is enough.
    
    ## Screenshots
    
    These pictures are dumps of a working reference model of the core, in `reference/preview.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/frame-0.png` | Frame 0  320 × 240, mark in the corner, scanlines on |
    | `shots/mid-bounce.png` | Mid-bounce  the 16 × 16 mark, scanlines on |
    
    
    ## 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 Verilog testbench dumps a framebuffer that matches golden frames. A
    documented gate-count script stays at or under the cap. Two runs are
    deterministic. No FPGA, no handheld, and no tapeout are 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. Testbench and goldens (R1). Build what R1. Testbench and goldens asks for, to the numbers in design.md. In particular: The testbench runs a documented number of frames (for example 4) and writes framebuffer dumps. Frames 0 and N (the last, or a mid frame in the file) match goldens within the tolerance in design.md. Check: the R1. Testbench and goldens acceptance checks pass.
    3. Gate cap and files (R2). Build what R2. Gate cap and files asks for, to the numbers in design.md. In particular: A documented count (Yosys or an equivalent, with the script in the repo) reports a gate or cell count at or under 4096, or the bound in the file, for the default size. Check: the R2. Gate cap 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. **Testbench and goldens (R1).** Build what `R1. Testbench and goldens`
    asks for, to the numbers in `design.md`. In particular: The testbench runs
    a documented number of frames (for example 4) and writes framebuffer
    dumps. Frames 0 and N (the last, or a mid frame in the file) match goldens
    within the tolerance in `design.md`.
       Check: the `R1. Testbench and goldens` acceptance checks pass.
    
    3. **Gate cap and files (R2).** Build what `R2. Gate cap and files` asks
    for, to the numbers in `design.md`. In particular: A documented count
    (Yosys or an equivalent, with the script in the repo) reports a gate or
    cell count at or under 4096, or the bound in the file, for the default
    size.
       Check: the `R2. Gate cap 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/preview.py A CPU reference of the default framebuffer. A build should dump the same frames from an HDL testbench.
  • 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/Unbounded.ttf Unbounded variable typeface for the reference preview.

Is it for me?

Kind
HDL
Tools
Verilog, Icarus, Verilator

What does it need?

Agent permissions
shell
Commands it runs
install a Verilog simulator, such as Icarus or Verilator install a tool that can write a PNG from a framebuffer dump

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.