Complete feature reference

This page is the implementation inventory for the 11 October 2026 release. It describes what a researcher can use now and links to the detailed design and task guides. Features marked as limitations are intentionally not presented as finished scientific capabilities.

Accounts, security, and research teams

Feature	Current behaviour
Account lifecycle	Email sign-up, email confirmation, sign-in, sign-out, password recovery, optional authenticator 2FA, and guarded account deletion.
Hosted session	Supabase restores the browser session across refreshes and newly opened experiment tabs.
Projects	Any active account may create a project and becomes its lead. Projects are isolated by Supabase Row Level Security.
Team roles	Project lead, researcher, and observer. A lead can add or remove existing accounts.
Research scopes	A researcher can be limited to arena, simulation, rodent settings, light, odour, sound, or treatment. Leads have all project controls.
Enforcement	Website controls explain permissions, while database policies, RPCs, and configuration checks provide the actual security boundary.

See Accounts and projects and Database.

Project and experiment preparation

• Create a project in a dialog and choose its baseline arena before opening the workspace.
• Add experiments from a supplied template or draw a custom arena.
• Rename experiments, choose a seed and fixed-step duration, and set the rat's starting position and direction.
• Save versioned experiment drafts in the project.
• Validate geometry, source positions, doors, bridges, IDs, references, and reachability with researcher-readable errors.
• Apply optional Open-Meteo environment suggestions after reviewing their source place, date, and time.

Supplied templates

The release includes six validated presets:

1. MCSF-inspired layout
2. Complex habitat
3. Four-room arena
4. Light/dark box
5. Open field
6. T-maze

Template identity is saved with the experiment. The workspace also supports region colour and material changes without rebuilding the scene.

Custom arena builder

The 2D builder supports regions, walls, and doors; grid size and snapping; selection, movement, resizing, rotation, duplication, and deletion; JSON preview; undo and redo; validation; and creation of a normal project experiment. The resulting experiment opens in the same 3D workspace as a supplied template.

See Custom arenas, Template builder, and Arena validation.

Arena and 3D workspace

• X and Z are the arena floor; Y is elevation. Experiment dimensions and positions use centimetres.
• Floors, outer walls, inner walls, corridors, regions, shelters, bridges, barriers, doors, and a treatment chamber are data-driven.
• Regions and objects have stable IDs so recordings and model observations do not depend on display labels.
• Materials include solid floor, rubber, wire mesh, wood chip, painted steel, and clear acrylic. They affect appearance and stimulus propagation.
• Collision rules stop the rat at arena bounds, solid walls, closed doors, and invalid bridge movement. The built-in and model-driven rats use the same RatBody collision code.
• Doors can start open or closed and can be changed during a live run. Each change is recorded as an intervention.
• Orbit, free-fly, follow-agent, and rat-eye cameras are available. The website also provides labels, reset, sensitivity, follow distance, axis inversion, focus mode, and keyboard controls.

See Arena renderer and Collision system.

Stimuli and environmental fields

Researchers can add, move, remove, enable, disable, and schedule light, odour, and sound sources. Each source has a stable ID, position, radius, configured intensity, enabled state, active state, and optional protocol events.

The field calculation is independent of the controller. The built-in baseline, researcher models, recorder, and visual overlays therefore read the same local stimulus values.

Light

• Floor lights fade with path distance to zero at their radius.
• Direct light is reduced by each crossed material's transmission value.
• Floor lights can contribute one material-weighted reflection from a visible wall, allowing weaker indirect exposure around some corners.
• Overhead lights have a height and beam angle. They are strongest below the lamp, fade toward the cone edge, and account for eye height, wall height, shadows, and covered rooms. They do not use the floor-light reflection path.
• Lux is normalized against response_reference, 1000 lux by default. This is an engineered response scale, not a calibrated photometry instrument.

Sound

• Sound gain fades with distance.
• Every crossed wall multiplies the result by that material's sound transmission.
• Open doorway gaps do not attenuate the direct path.
• The model is repeatable attenuation, not full acoustics. It does not simulate frequencies, interference, or a measured room impulse response.

Odour diffusion

• Every odour source owns a concentration grid sized to about 40 cells along the arena's longer dimension.
• While active, a source releases gas into its grid cell. The default release rate is derived from intensity; a researcher can provide an explicit rate.
• An explicit diffusion step moves concentration between neighbouring cells. Longer fixed steps are split into stable substeps.
• Exponential decay removes a configured share over simulated time.
• Heavy gas spreads faster along the floor and decays more slowly. Light gas uses the base diffusion and gains an extra loss term because it rises away from the sensing plane.
• Walls reduce transfer to 0.08 × material odour transmission; open doors allow free transfer. Closed or opened doors affect subsequent diffusion, not gas that has already moved.
• The rat receives local normalized exposure 1 - exp(-concentration / detection_reference) and the uphill concentration direction. At the reference concentration, exposure is about 0.63.

Material propagation defaults

Material	Light reflection	Light transmission	Sound transmission	Odour transmission
Solid floor	0.35	0.00	0.30	0.40
Rubber	0.05	0.00	0.15	0.35
Wire mesh	0.15	0.60	0.90	0.95
Wood chip	0.25	0.00	0.40	0.50
Painted steel	0.60	0.00	0.20	0.30
Clear acrylic	0.08	0.85	0.35	0.30

Experiments may override these values in material propagation data.

See Stimulus propagation for the calculation and scientific boundary.

How stimuli affect the rat

The built-in baseline responds to local exposure every fixed step. Its default rules are deliberately visible and configurable:

Type	Default preference	Steering gain	Speed change
Light	-0.45, avoidance	0.55	+0.10
Odour	+0.55, attraction	0.55	+0.05
Sound	-0.35, avoidance	0.45	+0.15

For each source, the signed steering contribution is exposure × preference × steering gain. Contributions combine into a response direction. The controller caps steering weight, adjusts speed, and records the dominant source and every source contribution. Researchers may override these values or disable the baseline response in controller.stimulus_response.

These defaults prove that a configured stimulus can produce a measurable software effect. They are not a biological claim. A researcher model may use the same observation and learn or implement a different response.

Treatment

• No-treatment, placebo, and medicine groups are distinct in configuration and run metadata.
• Dose, unit, administration step, treatment ID, and chamber are versioned with the experiment.
• Administration is a scheduled event and is recorded in the event stream and exported result.
• The platform records the treatment condition but does not contain a universal biological medicine-response model. A researcher must supply or validate the model used to interpret treatment.

Running the simulation

• Start, pause, resume, single-step, reset, and selectable presentation speed.
• Fixed simulation steps and a seeded random generator make software runs repeatable. Display speed does not alter step results.
• Explorer, Balanced, and Shelter Seeker provide visibly different baseline patterns.
• Live door controls remain available during a run.
• Focus mode enlarges the arena while retaining essential run and door controls.
• The browser and native Godot interface use the same experiment and command contract.

See Running an experiment.

Recorded data and metrics

Full recording includes, at each step:

• step and simulation time;
• position, heading, region, and distance moved;
• active stimulus state;
• per-source local exposure, distance, direction, falloff, direct and reflected shares, walls crossed, and line of sight;
• built-in stimulus response, magnitude, speed multiplier, dominant source, and contributions;
• treatment events, door changes, and researcher interventions; and
• controller and immutable model-version provenance.

The summary reports total distance, mean speed, region dwell steps and seconds, first exposure step, steps exposed, mean exposure, maximum exposure, exposure area under the time curve, affected steps, mean and maximum response magnitude, cumulative response magnitude, and dominant-source counts.

Results can be read in the website, downloaded as JSON or CSV, saved to the project, converted to a DataFrame, plotted, or compared from Python.

See Results.

Replay

• Save a completed or partial run to the project.
• Load runs made in the browser or saved from Python.
• Seek to a step, play, pause, step backward or forward, restart, change replay speed, and use replay camera modes.
• Minimize or hide replay controls to inspect the arena.
• Continue live from a selected step by rebuilding prior deterministic state and leaving replay mode.
• Open an SDK-generated review link at a specific recorded step.

Headless Python, Colab, and training

• rodent-sdk runs the same Godot simulation without rendering.
• Experiments expose reset, step, run, observations, actions, results, and validation.
• The observation schema contains 31 ordered values for body state, eight wall rays, wall contact, light, sound, odour, and episode progress.
• Continuous actions provide turn and speed. Discrete mode provides stay, forward, turn left, turn right, and run.
• Researchers define the reward, end condition, start policy, episode length, seed, and optional extra observations.
• Vector environments run multiple copies; episode logs support interruption recovery, exact action replay, plots, comparisons, and selected-episode reconstruction.
• summary_only mode keeps metrics while avoiding the memory cost of full replay frames during large batches.

See Python and Colab and Training your rat.

Researcher models

• Models belong to a project and have immutable numbered versions.
• Metadata records checksum, size, framework, action mode, observation contract, SDK and pack version, episode length, source, notes, and training summary.
• Private Supabase Storage holds weights and ONNX files with project-scoped access.
• Compatible PyTorch networks can be saved with an ONNX copy.
• The website checks an uploaded or saved ONNX model before use, then passes 31 observations to ONNX Runtime Web and returns constrained actions to Godot.
• The model-driven rat uses the same speed, wall, door, edge, and bridge rules as the built-in rat.
• The browser does not execute arbitrary uploaded Python.

See Model execution.

APIs and integrations

Interface	Purpose
Python SDK	Public researcher API for headless runs, training, analysis, hosted projects, replays, and models.
Local REST API	Development server for accounts, projects, experiments, templates, replays, commands, and weather suggestions.
Internal Godot protocol	Versioned JSON command and observation boundary used by Python and the web bridge.
Supabase REST and RPCs	Hosted authentication, project access, experiment persistence, replay persistence, model metadata, and protected membership operations.
Open-Meteo	Optional weather-derived setup suggestions. Manual configuration remains available when it is unavailable.
ONNX Runtime Web	Constrained live execution of compatible researcher controllers in the browser.

See Python SDK, Internal API, and External API.

Quality, deployment, and known limits

• Gitea Actions runs Ruff, gdlint, JavaScript syntax, preset checks, backend and SDK tests, Godot behavioural tests, deterministic checks, an API load smoke test, and an 85% Python coverage gate.
• The verified local release passed 148 Python tests at 85.13% measured line coverage, six preset validations, determinism checks, and a 100-request API smoke test with no failures.
• Vercel hosts the portal, Supabase hosts data and authentication, and Cloudflare Pages hosts this documentation.
• Temperature is imported context, not a simulated heat field.
• Stimulus propagation and the supplied baseline are engineered models, not calibrated biological or physical instruments.
• JavaScript and GDScript have automated checks and behavioural tests but do not currently produce line-coverage percentages.

See Current release, Automated testing, and Final submission guide.

AI Attribution: This inventory was prepared with OpenAI Codex assistance by tracing the merged application, tests, schema, and user guides. The team remains responsible for verifying the submitted commit and scientific wording.