Skip to main content

Modular Simulation Kernel

Why this shape​

The product supports deterministic fixed-step runs, placed and scheduled stimuli, saved experiments, replay, headless execution and a Python step/action interface. Putting those rules inside UI scenes would make testing, replay and external control fragile. The kernel is independent of the renderer and coordinates small feature modules.

This is a partial microkernel, also described as a microkernel-inspired modular kernel. The kernel owns only shared simulation concerns, while arena, stimuli, agent and recording behaviour live in plugins. It is partial because Sprint 1 plugins are compiled source modules registered at startup. The system does not install untrusted plugins at runtime, resolve plugin dependencies or isolate plugins in separate processes. This provides useful separation without adding complexity that Sprint 1 does not need.

Boundary​

Web portal / Godot UI / Python TCP client
                 |
            commands + state
                 |
         SimulationKernel
    - fixed-step clock
    - seeded RNG
    - lifecycle
    - ordered plugins
    - event stream
            |
    +-------+---------+------------+----------+
    |                 |            |          |
 ArenaPlugin   StimulusPlugin  AgentPlugin  RecorderPlugin

The kernel is the only owner of simulated time and seeded randomness. Plugins must never create their own unseeded random generator or advance time.

UI panels never retain a kernel reference. They emit intent signals to the app shell; the shell calls the stable kernel API and routes stepped and run_state_changed updates back to interested panels. This lets different team members work in src/app/panels/ without repeatedly editing main.gd.

Simulation speed changes how many fixed steps are executed per display tick. It never changes fixed_delta, the experiment seed, or simulation rules. Max speed uses a small per-frame time budget so the UI remains responsive.

Plugin lifecycle​

Every module implements SimulationPlugin:

  1. plugin_id() returns a stable unique identifier.
  2. priority() controls deterministic execution order.
  3. initialize(context, experiment) receives shared state and configuration.
  4. before_step(context) handles inputs and scheduled changes.
  5. step(context) advances the feature by exactly one fixed step.
  6. after_step(context) observes the completed step.
  7. shutdown(context) releases run-specific state.

The current ordering is arena, stimuli, statistical agent and recorder. IDs and priorities are part of the compatibility contract.

Experiment model​

An experiment is one versioned JSON document:

metadata + simulation + arena + stimuli + protocol + treatment + controller + rodent + ui
  • Geometry defines boundaries and physical regions.
  • A region can have a semantic zone and a surface material.
  • Stimulus sources have a type, position, radius, and properties.
  • Protocol entries switch sources at integer steps.
  • Treatment identifies no-treatment, medicine, or placebo conditions and an administration step.
  • The rodent section stores physical and behavioural controls.
  • The UI section stores camera preferences without affecting simulation rules.
  • Schema version 1 experiments are migrated to schema version 2 before validation.
  • The Python client can reset, step, observe, act, load and close a headless run.

Materials and stimuli are separate. A bridge can use wire mesh while also being brightly illuminated; wood-chip bedding can affect movement while an odour source independently affects sensing.

Determinism rules​

  • Advance only in integer steps with a fixed delta.
  • Initialize the one shared RNG from the experiment seed.
  • Keep plugin order stable.
  • Record interventions at their effective step.
  • Do not use wall-clock time in simulation decisions.
  • Do not mutate a saved experiment during a run.
  • Save the seed, experiment snapshot and recorded steps with each replay.

Implemented integration boundaries​

  • The local web service uses Python and SQLite for zero-configuration development.
  • The hosted portal uses Supabase Auth and Postgres with Row Level Security.
  • The website and embedded Godot client communicate with same-origin postMessage events.
  • Headless Python control uses a localhost TCP protocol.
  • The simulator website is deployed on Vercel.
  • This documentation is built with Docusaurus and deployed on Cloudflare Pages.

AI Attribution: This document was drafted and edited with AI assistance, including ChatGPT and OpenAI Codex. The team reviewed it against the implemented project.