Under the hood
Make it yours
Add your own cell model with NESTML, or write a new level, from the task contract to the tests every level must pass.
Spike is open source and built to be extended. There are two common ways to add to it: a new neuron model, and a new level. Both need a build from source (see building from source), because cells and levels are compiled into the engine. You cannot drop a new cell into a downloaded game.
If all you want is a different circuit, you do not need any of this. Build it in the lab or write a circuit file.
Part 1: a custom cell with NESTMLLink to this section
NESTML is a domain language for writing neuron models. A .nestml file holds the equations in a few readable lines; a tool turns it into C++ that NEST can run. Spike uses NESTML 9.0.1 for its custom cells.
The four cells that exist today are in models/nestml/:
| Cell | What it stands for |
|---|---|
sa_node_pacemaker | A sinoatrial (heart pacemaker) cell. One spike is one heartbeat. |
butera_burster | A breathing-rhythm bursting neuron from the brainstem. |
icc_slow_wave | A gut pacemaker cell. A simplified oscillator in slow-wave units. |
stg_cell | A crab stomatogastric neuron with several ion currents. |
Each has a page in docs/models/ that says where the equations come from and how far they can be trusted. See what is real.
The stepsLink to this section
- Write the model. Add
models/nestml/my_cell.nestml. Follow an existing file. The repository's cells share conventions: anexcitatoryand aninhibitoryspike input port (so a positive circuit weight excites and a negative one inhibits), a continuous current port fordcinputs, and a parameterI_efor a constant current. Neuromodulator levelsachandneare plain parameters; the modulation table drives them. NESTML 9 syntax has quirks: a spike port takes no unit (declare an internalunit_psg nSinstead), and variable namesaandhcollide with unit names. - Generate the C++. Run
scripts/build-nestml.sh. It makes a virtual environment with the pinned NESTML, then runsscripts/nestml_generate.pyover every.nestmlfile inmodels/nestml, and writes C++ intothird_party/nestml-gen/. The script patches around some incompatibilities between NESTML 9 and the pinned NEST (it fixes the NEST version label, replaces NESTML's own build step, and removes alibltdlguard the neuron code does not need). - Rebuild the engine.
cmake -S . -B build && cmake --build build -j. CMake globs the generated sources and compiles them into the engine. It warns if a.nestmlfile is newer than the generated code. The models register themselves after every NEST reset, inengine/src/modules/nestml_models.cpp. - Add a parts-bin card. The cards are defined in C++ in
engine/src/catalog/catalog.cpp. A card gives the model's title, a family ("Custom (NESTML)"), a plain summary, real-world examples, a source line, the key parameters with units and ranges, the default input weight and its unit, whether it suits excitatory or inhibitory use, and the drive levels for its thumbnail. Copy thestg_cellcard and edit it. Slow oscillators setrun_msandmax_msso the probe sees at least 10 cycles. - Measure the thumbnails.
build/engine/spike-catalogruns every card in its own process and writescatalog/thumbs.json(the f-I curve and a voltage trace). The game reads that file for the card pictures. - Python parity.
scripts/build-nestml.sh --pynestbuilds the loader library for PyNEST.models/nestml/test_parity.pycompares the engine with PyNEST spike for spike; add your model to it. See Use your circuit in Python. - Write a test next to the existing ones:
engine/tests/test_nestml_*.cpp(for exampletest_nestml_sa_node.cpp). These tests skip, with exit code 77, when the NESTML code was not generated. - Label it honestly. Add it to
docs/WHAT-IS-REAL.mdas a NEST model, a NESTML re-fit or phenomenological, and say what was tuned. The project's rule is that nothing is called real unless it is. See contributing.
Note: A new cell appears in the sandbox parts bin once its card exists. Which levels offer it is controlled by the campaign: the lab unlocks the parts bin and cell types as the player reaches levels whose reference circuit uses them.
Part 2: a new levelLink to this section
A level has a world, a score, a reference circuit and a lesson. In the code it is a task: one C++ file in engine/src/tasks/.
The contractLink to this section
The base class is spike::Task in engine/include/spike/task.h. The important pieces:
| Method | What it provides |
|---|---|
id(), title(), brief() | The level name and the plain-language brief. The brief says what to build and how it is scored, but gives no numbers that give the answer away. |
sensor_channels(), motor_channels() | The names of the inputs the task drives and outputs it reads. A circuit must declare them. |
channel_kinds() | How each channel is declared (dc, poisson, rate, ...) and a default sensor weight, so the lab can build a correct empty bench. |
duration_ms(), quick_duration_ms() | The full episode, and a shorter one that Check uses by the same rules. |
reset(seed), step(engine, dt_ms) | The world. reset builds a deterministic world from the seed. step reads the world into engine inputs, steps the engine 1 ms, reads outputs, and advances the world. |
score() | A value from 0 to 100, a pass flag, a verdict sentence and named parts. |
body() and view() | What the game draws: a limb, heart, lungs, eye, gut, a dashboard or the generic polyline. See bodies. |
chapter(), level_kind(), on_spine() | Where it sits: a chapter id, micro, task, boss or diagnosis, and whether it gates progress. Branches never gate. |
concepts_new(), concepts_used() | The ideas it teaches and relies on. These feed the glossary and the "know first" chips. |
par_neurons() | The neuron count for the third star. |
timeline(), bands(), modulators() | Scripted events, target bands for the timeline plot and the neuromodulators the task reads. |
set_mode(), variants(), set_variant() | Difficulty modes and challenge variants. A mode changes tolerance and noise, never structure. |
hints() | Three tiers: the idea, the place (a population or channel id to outline), a partial recipe. |
recipe() | The concrete numbers, kept apart from the brief so the lab can show them by mode. |
metrics() | A quality number for the post-solve histograms. |
notebook() | The cited fact unlocked on first pass. |
diagnosis() | For diagnosis cases only: the circuit, symptoms, candidates and the answer. |
RegisteringLink to this section
End the file with the macro, with the id equal to the file name:
SPIKE_REGISTER_TASK( my_level, 301, "my_level.json", make_my_level )
The number sorts the campaign (10s are Invertebrates, 100s Spinal cord, 200s Heart, 300s Breathing, 400s Autonomic, 500s the Bestiary, 600s Theory). CMake finds the file by globbing and generates the code that keeps its registration. The file stem must equal the id.
The stepsLink to this section
Write the task in
engine/src/tasks/my_level.cpp. Many levels use scaffolds:micro_a.handmicro_b.hfor micro-puzzles,spinal_limb.hfor the limb levels,bestiary_*.h,theory.h, anddx_common.hfor diagnosis cases.Check the mechanism, not only the output. The task asks the engine for the circuit's structure (
Engine::structure(),has_path,has_loop,has_loop_via; seedocs/ENGINE-STRUCTURE.md) and the verdict names the missing part. A circuit that hits the numbers by a cheap trick must fail.Build a reference circuit that passes, and save it as
godot/circuits/my_level.json. The repository'scircuitsfolder is a link to it. Several circuits are generated by scripts incircuits/tools/.Write the cheap rows. This is the most important test. In
engine/tests/cheap_rows_*.inc, add rows that list circuits that must fail:CHEAP_ROW( "my_level", "empty bench", cheap::empty( "my_level" ) ); CHEAP_ROW( "my_level", "one cell, tonic 450 pA", cheap::tonic( "my_level", 450 ) ); CHEAP_ROW( "my_level", "reference without the loop", cheap::from_ref( "my_level", cheap::cut( "MN", "RC" ) ) ); CHEAP_ROW_V( "my_level", "no inhibition", "inhibitory", /* circuit */ );Every level has at least these: the empty bench, a single cell, a tonic cell with all weights 0, the reference with every weight 0, with every weight extreme, and the reference minus its mechanism.
CHEAP_ROW_Valso requires the verdict to contain a word, which pins that the verdict names the missing mechanism. A row passes when the task does not pass on seeds 1 and 2 and says something. The test also checks that the reference passes the same harness, so a broken harness cannot "fail" everything. A scan checks that verdicts and hint tiers contain no digits.Write the notebook entry and the glossary concept. Cite real papers. The concept text lives in
godot/game/campaign.gd(theCONCEPTStable). Run the citation checker (below).Put it on the map. Engine order sets play order.
campaign.gdhas aPLANNEDtable of map positions per chapter (levels not listed are placed automatically) andDX_PARENTfor diagnosis cases. Add an energy budget ingodot/game/progress.gdif the reference circuit's spike rate matters; the default is 40 spikes per second per cell.Document it in
docs/circuits/my_level.mdanddocs/WHAT-IS-REAL.md.Run the tests: the cheap rows,
tasks_circuits_test, the smoke test, and the interaction-graph test if the UI changed.
Making the rowsLink to this section
The cheap-row builders (empty, skeleton, single_cell, tonic, from_ref, zero_weights, max_weights) and the mutators (cut, silence, scale_input, set_params, set_model, set_delay, and so on) are documented at the top of engine/tests/tasks_cheap_test.cpp. A hand-built circuit can be made with the fluent Bench class. For tuning, tasks_cheap_test run <task> <circuit.json> [seed] and tasks_circuits_test run <task> <circuit.json> score one circuit and print the parts.
The citation ruleLink to this section
Every reference shown in the game must be in catalog/citations.json, with a DOI where one exists. python3 tools/citations/check.py checks offline: registry sanity, references in the source that are missing from the registry, and known wrong strings. --online asks Crossref to confirm each DOI against the title, first author, year, volume and page. --write-md regenerates docs/CITATIONS.md. See contributing.
The interaction-graph ruleLink to this section
If your level changes the UI (a new screen, button or control), you must update godot/tests/interaction_graph.json in the same commit, run tools/graph/render.py to regenerate the diagram, and run scripts/ui_graph_test.sh. The test fails if a visible control is not listed. Details are in architecture.
HistogramsLink to this section
After a pass, the game shows "where you stand" against generated variants of the reference circuit, not other players. tools/histograms/gen_histograms.py makes the files for your level: it varies the reference, scores each variant on two seeds and keeps those that pass.
Related pagesLink to this section
Architecture, contributing, stars, par and the hint ladder, what is real.
Something wrong or missing? Edit this page on GitHub (source) or open an issue.