Under the hood
Architecture
How the game, the engine, NEST and the Python package fit together, and what happens in each millisecond of a run.
This page is a tour of how Spike is built, for people who want to read or change the code. You do not need it to play.
The big pictureLink to this section
NEST (pinned commit, linked statically) the simulator: neuron and synapse models
+ NESTML cells compiled in custom cells (heart, breathing, gut, crab)
|
engine/ C++20 -> libspike
circuit.cpp circuit JSON -> NEST nodes and connections
engine.cpp the closed loop: set inputs, step NEST, read spikes
tasks/ one file per level: world, score, hints, notebook
body/ muscle, joint, heart, lungs, eye, gut (plain C++, no NEST)
analysis/ motifs, bursts, HRV, PRC, phase plane, spike-triggered average
catalog/ the parts-bin cards and their measured thumbnails
spike_run.cpp the command line (headless runner and scorer)
|
gdext/ GDExtension (godot-cpp) -> SpikeSim, SpikeTask
|
godot/ the game (Godot 4.7): code-built UI, levels in godot/circuits,
parts catalogue data in godot/catalog
python/ the spike package: the same circuit JSON in PyNEST, plus analysis
Each box has a job and little else. The engine knows nothing about Godot. The game knows nothing about NEST except through the engine. The Python package shares only the circuit file and the analysis maths.
NEST, built inLink to this section
NEST is the neural simulator behind most published spiking-network research. Spike pins one commit of it (NEST_REF in scripts/build-nest.sh) and builds it as static libraries, so the game is one self-contained program with no Python at run time. The game uses NEST's own models, names and units. That is the point of the project: when you wire two iaf_psc_alpha cells, a researcher gets the same behaviour from the same file in PyNEST. See what is real.
Custom cells that NEST does not ship are written in NESTML and compiled in. See make it yours.
GSL (the GNU Scientific Library, which NEST uses to integrate some models) is linked statically. NEST is built without OpenMP by default, so it runs on one thread.
The engineLink to this section
libspike is the C++ library. The header engine/include/spike/engine.h is the contract shared by the game, the tasks and the tests. It is kept stable, and new features are only added.
What it does:
- Loads a circuit.
circuit.cppreads the JSON, validates every field (unknown keys, weight limits, synapse rules) and creates NEST nodes. See a circuit is data. - Steps in a closed loop. The engine advances NEST in slices and exchanges data with the world between slices.
- Reports structure.
Engine::structure()lists populations and projections with their connection counts, mean weights and signs, read from the live NEST connections.has_path,has_loopandhas_loop_viaanswer "is there a path from A to B?" and "is there a feedback loop through this group?". Tasks use these to check that a circuit uses the mechanism a level teaches. Seedocs/ENGINE-STRUCTURE.md. - Reads and sets. Spikes (
drain_spikes), output rates and counts, input levels, neuromodulator levels, single weights (this is what a lesion does) and cell state.
The closed loop, millisecond by millisecondLink to this section
A level is a conversation between the world and the circuit. Every 1 ms of model time the task does this:
- Read the world. Where is the limb? How high is the blood pressure? What is the salt concentration at the worm's head? The task turns that into sensor levels.
- Set the inputs. The task sets the level of each sensor channel in the engine (a current in pA or a rate in Hz).
- Step NEST. The engine runs the simulator for that 1 ms. NEST itself uses a finer step, 0.1 ms in the game's circuits, so spike times are accurate to 0.1 ms.
- Read the spikes. The engine counts spikes of each output channel in that slice.
- Move the world. The task converts output rates into muscle drive, vagal tone, breathing effort or similar. The body model advances one step.
- Score. The task updates its running score.
The loop is deterministic for a given NEST build, thread count and seed. The tests check it with golden spike checksums (a hash over every spike), per build rather than across compilers. The overhead of one engine step is measured at about 3 microseconds in the first release's notes.
The bodies are not NEST. The muscle, joint, heart and circulation, lungs, eye and gut are small deterministic C++ models in engine/src/body/, documented in docs/body/. See bodies. The same state also feeds the picture the game draws.
TasksLink to this section
Each level is one C++ file in engine/src/tasks/ that registers itself with SPIKE_REGISTER_TASK(id, order, circuit, factory). It defines the world, the scoring, the verdicts and the three-tier hints, the notebook entry, the challenge variants and the difficulty modes. The registry order is the campaign play order. See make it yours for the contract and the tests every level must pass. There are 78 registered levels in this build.
The GDExtensionLink to this section
gdext/ is a Godot extension built with godot-cpp. It exposes two classes:
SpikeSim: a circuit loaded into the engine, with run, step, spikes, inputs, modulators, analysis calls (bursts, HRV, PRC, motifs, spike-triggered average) and so on.SpikeTask: a level, as the game sees it: its brief, channels, timeline, bands, hints, notebook entry and scoring, plus headless scoring (it starts aspike-runchild process in a worker thread).
The engine can host only one NEST instance per process. That is why the Check button runs spike-run as a separate process, and why seeds can run in parallel child processes.
The gameLink to this section
godot/ is a Godot 4.7 project. Almost all of the user interface is built in code, not in scenes.
| Folder | What is in it |
|---|---|
godot/main.gd | The app shell: screens, back stack, layout, input. |
godot/game/ | Game logic with no drawing: the campaign (chapters, concepts, unlock rules), progress and stars, settings, circuits (load, save, edit, the reference fingerprint), the lesion helper, audio, the play log. |
godot/ui/ | The screens (title, campaign map, lab, parts bin, notebook, settings, analysis, what is real, credits), the lab's pieces (editor, raster, traces, gauges, body views, inspector, hint panel, lesion lab) and a small widget kit. |
godot/circuits/ | The reference circuits, one per level. |
godot/catalog/ | The citation registry, the card thumbnails and the generated histograms. |
godot/tests/ | The interaction graph and its test. |
Layouts adapt: desktop, handheld and phone. The look is the "Cajal Plate" identity (docs/IDENTITY.md): India ink and Golgi stain on paper, sienna for excitation and Prussian blue for inhibition, and a second cue (an arrowhead for excitatory and a bar for inhibitory) so colour is never the only signal. See settings and performance.
The Python packageLink to this section
python/spike/ builds the same circuit in PyNEST and analyses spikes. It does not run tasks. Parity tests check that its spikes equal the engine's for the same circuit. See Use your circuit in Python.
Data flow of a CheckLink to this section
- You press Check in the lab.
- The game writes your circuit to a private temporary file and calls
SpikeTask.score_headless_quick_async. - A worker thread starts
spike-run --task <id> --quickwith your circuit, mode and variant, pinned to the circuit seed you are watching. spike-runloads the circuit into a fresh engine, runs the task's quick episode, and prints a score as JSON.- The game polls the job and shows the verdict. If the verdict asks for more strength while a weight is already at the end of its slider, the game swaps it for a note that more strength is not the answer.
The headless score and a live run agree because they use the same task code and the same seed rules. See the core loop and spike-run.
Tests that guard the structureLink to this section
The engine tests include golden spike traces, the closed loop, body physics, the cheap-circuit tables, every task's reference circuit, and parity with PyNEST. The UI has a graph test that walks every screen and control. See building from source.
Note: The interaction-graph rule: any UI change updates
godot/tests/interaction_graph.jsonin the same commit. A test starts the real game headless and presses every control, and fails if a visible control is not listed. This is why the game's controls are documented in one place. See controls.
Related pagesLink to this section
A circuit is data, make it yours, building from source, contributing.
Something wrong or missing? Edit this page on GitHub (source) or open an issue.