The World

The simulation lives entirely in Rust, in rust/brain_sim/src/lib.rs, exported to JavaScript as a #[wasm_bindgen] struct called World. The TypeScript Brain wrapper holds one World instance and drives it.

rust/brain_sim/src/lib.rs

#[wasm_bindgen]
pub struct World { /* neurons, axons, pool, telemetry, settings, ... */ }

Construction

rust/brain_sim/src/lib.rs

#[wasm_bindgen(constructor)]
pub fn new(vertices_buf: &js_sys::Float32Array, settings_js: JsValue)
    -> Result<World, JsError>

new takes a flat Float32Array of brain-mesh vertices (length must be a multiple of 3) and a settings object. It copies the vertices in, computes the bounding box, then:

1. Builds neurons: walks the vertex list with a stride of vertices_skip_step, classifying each into a cortical region and pushing a Neuron.
2. Builds axons: connects nearby neurons (see Neurons & Axons).
3. Bakes render buffers: sampled axon positions, line indices, and per-vertex opacities.
4. Creates the signal pool: sized to limit_signals.
5. Initializes telemetry: region counts and per-region neuron buckets.

A construction error (e.g. a vertex buffer whose length is not a multiple of 3) is returned as a JsError, which surfaces in JavaScript as a thrown exception caught by the boot() handler.

Default settings

The settings come from the JS side, falling back to these Rust defaults:

Setting	Default	Meaning
vertices_skip_step	2	Use every Nth mesh vertex as a neuron.
max_axon_dist	8.0	Maximum distance for an axon connection.
max_connections_per_neuron	6	Connection cap per neuron.
current_max_signals	16_000	Active signal ceiling (live cap).
limit_signals	65_536	Hard pool capacity.

The Brain wrapper mirrors these defaults on the JS side and reads the live caps from the World getters (current_max_signals, limit_signals).

Stepping the simulation

The World exposes three step entry points:

rust/brain_sim/src/lib.rs

pub fn step_cpu(&mut self, delta_time: f32) { self.step_inner(delta_time, true); }
pub fn step_t_only(&mut self, delta_time: f32) { self.step_inner(delta_time, false); }
pub fn step(&mut self, delta_time: f32) { self.step_cpu(delta_time); }

Method	Position writes	Used by
step_cpu(dt)	Yes	The current front end (Brain.update).
step_t_only(dt)	No	Reserved for a future GPU travel pass.
step(dt)	Yes (alias)	Backwards compatibility.

The front end only calls step_cpu. step_t_only advances signal lifecycle and the t parameter without writing positions, leaving the Bezier sampling to a hypothetical GPU compute pass: not wired up in the current build.

Public API surface

The World exposes, via wasm-bindgen:

• Stepping: step_cpu, step_t_only, step.
• Stimulus: inject_stimulus(stim): see Regions & Stimulus.
• Telemetry: telemetry_snapshot(): see Telemetry.
• Counts: num_neurons(), num_axons(), num_signals().
• Settings/colors: set_setting(key, value), set_color(key, hex), plus getters for the style fields (neuron_size_multiplier, neuron_opacity, neuron_color_hex, axon_opacity_multiplier, axon_color_hex, current_max_signals, limit_signals).
• Raw pointers (for zero-copy views): neuron positions, axon positions/indices/opacities/control points, and the signal-pool struct-of-arrays fields. The Brain wraps these in typed arrays.

See the next pages for how each subsystem works.