Under the hood

Contributing and the honesty contract

How to report a bug, what a good contribution looks like, and the rules every level and every claim in Spike must follow.


Spike is a game that teaches by being right. That only works if the puzzles cannot be passed by tricks and the biology it quotes is real. This page says how to help, and which rules a contribution has to meet.

Report a bug or a confusing levelLink to this section

Open an issue at github.com/ixaxaar/spikes/issues. The project asks for two kinds of report: what broke, and what confused you. Confusion is a bug. If a brief left you guessing or a verdict misled you, say so.

A useful report has:

  1. The level id or name, and the mode (Guided, Standard or Researcher). See modes.
  2. The circuit file. Save it from the lab (More, then Save, once that opens) and attach it. See a circuit is data.
  3. What you expected, and what you got.
  4. The verdict text, if it was a Check or a Test x5.
  5. Your platform and the game version shown on the title screen.

If you want to help the maintainers learn where players get stuck, Settings has an opt-in play log (Game tab, "Record my play"). It is off by default and keeps data on your own device only: time per level, runs, hint tiers, quits, and edits before your first pass. You can export it as JSON and attach it to a report. Nothing is ever sent for you.

Before you send codeLink to this section

  1. Build and run the tests (see building from source).
  2. Read architecture and, for a level, make it yours.
  3. If your change touches the UI, update the interaction graph (below).
  4. Keep your change small, and say in the description what it changes for a player.

Pushes that only touch Markdown, docs/ or research/ do not run CI.

The honesty contractLink to this section

These five rules came out of a harsh review of version 0.3 (docs/REVIEW-HARSH.md) and are recorded in docs/REQ-0.4.md. Every level must follow them, and tests enforce most of them.

1. Mechanism, not just outputLink to this section

A level checks that the circuit uses the mechanism the level teaches, through the circuit's structure, and the verdict says which part is missing. For example, the reflex level needs at least two sensory cells converging onto the motor pool, and a circuit without that fails whatever its weights. A cheap trick that happens to hit the numbers does not pass.

2. No numbers in verdicts or hintsLink to this section

Verdicts describe what the circuit did and which way to change it ("too weak to reach threshold"), never the answer ("375 pA"). In the current code this applies to verdicts and to all three hint tiers of every level, pass or fail. A test scans every task for digits. Only the recipe, which Guided mode shows in the brief and Standard shows behind a Show recipe button, carries numbers. See stars, par and the hint ladder.

Note: The original requirements text says "tier-1/2 hints". The 0.5 playtest fixes extended the rule to tier 3 as well, and the changelog says so. The code is what counts.

3. A table of circuits that must failLink to this section

Every level has rows in engine/tests/cheap_rows_*.inc: an empty bench, a single cell, a tonic cell with all weights 0, the reference with every weight 0 or extreme, the reference with the taught mechanism cut out, and any cheap circuit a reviewer found. Each must fail on two seeds, and say something. A broken harness is caught because the reference circuit must pass the same harness. Diagnosis cases test that every wrong and unknown answer fails. See make it yours.

4. Honest novice testsLink to this section

A scripted novice may use only the brief, the verdicts and the lab's own defaults. It may not use recipes, tier-3 hints or the reference. Levels it cannot solve are reported, not hidden. The playtest report for 0.5 is research/PLAYTEST-0.5.md; it lists bugs the project then fixed, such as round-number circuits being wrongly flagged as copies of the reference.

5. Real data, honest labelsLink to this section

  • Every citation is checked against PubMed or Crossref, with a DOI stored next to it.
  • Wrong citations are fixed or removed. docs/CITATIONS.md lists the corrections that were made.
  • Facts that do not fit their level are rewritten.
  • Generated histograms are labelled "generated variants of the reference, not players".
  • There is a What is real page in the game and in the docs: what is real.

What the labels meanLink to this section

docs/WHAT-IS-REAL.md sorts every part of the game under five labels. A contribution must say which one applies.

LabelMeaning
NESTThe equations are NEST's own.
NESTML re-fitA custom cell with structure from a paper and hand-adjusted numbers. Not validated.
Tuned in silicoA number picked by sweeping until the level passed. A property of the game, not a measurement.
IllustrativeA coefficient picked so a body looks plausible.
GeneratedProduced by a script (the histograms).

Do not call a tuned number a measurement. Do not call a body model clinical.

CitationsLink to this section

The registry is catalog/citations.json. Every reference the game shows (notebook notes, concept cards, lesion hints, diagnosis explanations) or the docs make must be in it.

python3 tools/citations/check.py               # offline: registry sanity, missing references, known wrong strings
python3 tools/citations/check.py --online      # ask Crossref about every DOI
python3 tools/citations/check.py --online --fill   # look up DOIs for entries that lack one
python3 tools/citations/check.py --write-md    # regenerate docs/CITATIONS.md

Each entry has a status. Verified means the record was read from PubMed. Verified-locus means PubMed has a record at exactly that journal, year, volume, first page and first author. Unverified means it could not be checked (books and older papers); they are kept because the work is real and classic, but are marked. The registry at the last count held 161 entries, of which 34 are unverified. The citation file is generated; do not edit it by hand.

The interaction-graph ruleLink to this section

godot/tests/interaction_graph.json lists every screen, tab, panel, modal and toast, and every control, with the actions that move between them. A test starts the real game headless, presses each control with a real mouse click, and fails if a control is covered, dead, or not listed. So:

  • Any UI change updates the JSON in the same commit.
  • Run tools/graph/render.py to regenerate the diagram in docs/INTERACTION-GRAPH.md, and commit it.
  • Run scripts/ui_graph_test.sh.
  • Name new controls (Kit.btn names them from their label; Kit.ident names anything else).

This is also the source for controls.

The lookLink to this section

The visual identity is "Cajal Plate" (docs/IDENTITY.md): India ink and Golgi stain on aged paper, sienna for excitation and Prussian blue for inhibition, with a second cue so colour is never the only signal. Type: Fraunces for display, Atkinson Hyperlegible for text and IBM Plex Mono for readouts, all open licences and vendored. Keep text at 14 px or larger on screen; the smoke test fails below that. Respect the Reduced motion setting.

Licences and creditsLink to this section

The Credits screen (title screen, or Settings) lists the engine, fonts and sources, including the connectome data behind the worm touch level (OpenWorm's ConnectomeToolbox, with the terms of the original paper). Read it before you add a data source.

Make it yours, building from source, what is real, tips and common mistakes, the changelog.

Something wrong or missing? Edit this page on GitHub (source) or open an issue.