Expand description
QualiaDB Deterministic Simulation Engine (qualia-sim).
Consolidated into etalon-sim and etalon-render (see
docs/plans/etalon-sim-render-consolidation-uplift-2026-11-06.md).
Preserves 100% backwards-compatible module and symbol paths while exposing
the uplifted multi-domain simulation, physics, skeletal, camera, hydrological,
and botanical capabilities.
Modules§
- acoustics_
continuum - 3D Continuum Acoustic & Elastic Solvers, Helmholtz, Room Acoustics & Kramers-Kronig Dispersion.
- animation
- camera
- character
- Kinematic Character Controller Engine (
character). - continuum_
3d - Sector 3D Physics, Stress-Cleavage Fracture & Continuum Bridge (
continuum_3d.rs). - differential_
codec - ecs
- Zero-Heap Fixed-Capacity SOA Archetype ECS (
ecs). - environment
- Environmental, Space Weather, Atmosphere, Fire Ecology & Geotechnical Mechanics
- flora_
archetype - ground_
cover - hydro
- input
- Zero-Heap Bitset Input Engine & Mobile Touch Gestures (
input). - kinematics
- Rover & Vehicle Kinematics (
kinematics.rs). - leaf_
biophysics - maxwell_
emf etalon_sim::maxwell_emf— 3D Continuum Maxwell Vector Calculus, Cartesian Yee FDTD, Dispersive ADE Media, Poynting Energy Balance, and C02 Electromagnetic Oracles.- metamer_
fspm - navigation
- Unified 2D Grid & 2.5D Polygon Navigation Engine (
navigation). - optics
- physics3d
- Unified Analytical SDF + B-Rep 3D Physics & ODE Response Engine (
physics3d). - ripple
- skeletal
- Zero-Heap Skeletal Animation, ABSM, Blend Spaces, Motor IK & Dual-Quaternion Skinning (
skeletal). - time
- Unified Multi-Rate Time & Fixed-Tick Engine (
time). - vegetation
- Vegetation simulation, physical bending, leaf biophysics, FSPM metamers, and ground cover.
- water_
surface - Caller-buffered shoreline attributes, Gerstner spectra, buoyancy, optics, and ripples for open water.
Structs§
- Aabb3D
- 3D Axis-Aligned Bounding Box (
[min_x, min_y, min_z]..[max_x, max_y, max_z]). - Added
- Zero-heap iterator yielding
(entity_id, &T)for rows whoseadded_tickis newer thanlast_run. - Aeroelastic
Branch - Aeroelastic branch oscillator with Vogel crown streamlining reconfiguration.
- Agent
State - Compact entity state in fixed-point space (millimeter coordinates).
- Animation
State Machine - Zero-heap animation state machine controller.
- Archimedes
Proxy - Multi-sphere proxy hull for volumetric character buoyancy.
- Articulated
Ragdoll - Zero-heap articulated ragdoll controller for up to
MAX_LIMBSbones. - Atmospheric
Electric Circuit - Global Electric Circuit and atmospheric electrical state.
- Ball
Motor Joint - Spherical ball-and-socket joint locking two local anchor points in world space.
- Barometric
State - Synoptic thermodynamic and barometric state of the air column.
- BioGeo
Optical Constituents - Ecological and Geomorphic Bio-Geo-Optical constituents (CASE-2 Waters).
- Boundary
Layer Profile - Atmospheric Boundary Layer (ABL) logarithmic wind profile.
- Broadphase
Bvh - Zero-heap dynamic broadphase BVH with fat-AABB hysteresis.
- Buoyancy
Result - Instantaneous buoyancy evaluation result.
- Buoyancy
Sphere - Sphere element of an Archimedes buoyancy hull.
- Changed
- Zero-heap iterator yielding
(entity_id, &T)for rows whosechanged_tickis newer thanlast_run. - Character
Config - Character controller movement configuration.
- Character
Controller - Zero-heap kinematic character controller.
- Character
State - Dynamic runtime state of the character.
- Contact
Manifold3D - Persistent 4-point 3D contact manifold between
body_aandbody_b. - Contact
Point3D - A single contact point inside a
ContactManifold3D. - Continuum
Bridge3D - Two-way continuum coupling bridge coordinating Geomechanics, Hydrodynamics, and Botanical Biomechanics.
- Deterministic
Prng - Deterministic 64-bit pseudo-random number generator (xorshift64*).
- Dielectric
Volume Iop - Inherent Optical Properties (IOP) of a dielectric medium or fluid volume.
- Disocclusion
Forecaster - Predicts disocclusions k frames in advance using velocity vectors and frustum planes.
- Driven
Spring - Stiffness and damping per unit mass:
stiffness * (target - position) - damping * velocity. - Ecotope
Patch - A compact semantic ground-cover ecotope patch.
- Entity
Spatial Bounds - A bounding box for a spatial entity in world space.
- Excavation
Verdict - The physical outcome of a tool contact attempt on a soil stratum.
- Fireline
Verdict - Result of Byram fireline intensity evaluation.
- Fixed
Motor Joint - Rigid weld joint preserving a fixed relative PGA [
Motor] offset frombody_atobody_b. - Fixed
Tick World - Fixed-capacity multi-agent simulation world kernel (Zero Heap hot path).
- Fixed
Timestep Accumulator - 64 Hz Fixed Timestep Accumulator.
- Fixed
Vec2 - 2D vector in fixed-point millimeter space.
- Flora
Archetype Config - Continuous biophysical trait parameters defining any flora archetype.
- Flora
Biomechanics Evaluator - Evaluator for stem mechanics and seasonal dieback across flora archetypes.
- FlyCamera
- 6-DOF Free-flight camera with velocity damping for editor, debug, and free inspection.
- Forest
Fuel Stratum - Fuel stratum structural breakdown for an ecological vegetation community.
- Fracture
Material Props - Physical material cleavage properties for principled
.10dPROC1stress-cleavage fracture. - Fracture
Outcome3D - Result of splitting a
RigidBody3Dalong a principal tensile stress cleavage plane. - Fuel
Moisture State - Atmospheric and edaphic fuel dryness state.
- Geomagnetic
Storm State - Planetary geomagnetic storm state and auroral energy dissipation.
- Gerstner
Wave - Individual Gerstner wave harmonic component.
- Hale
Magnetic Cycle - 22-year Hale magnetic polarity cycle (two Schwabe cycles average).
- Heliophysical
Fire Weather Report - Integrated multi-domain earth-system state report.
- Hydrological
Hysteresis Gate - Hysteresis gate to filter high-frequency fluid noise before committing discrete transitions.
- Interactive
Ripple Buffer - A zero-heap 2D discrete wave heightfield solver.
- Kinematic
Extrapolator - Evaluates analytical 6-DoF trajectory extrapolation forward in time.
- Leaf
Economics Profile - Continuous Leaf Economics Spectrum (LES) profile.
- Leaf
Flutter State - Aeroelastic leaf oscillator with Strouhal vortex-shedding flutter and petiole abscission.
- Leaf
Vascular Skeleton - Zero-heap planar leaf vascular skeleton with coupled biophysics.
- Metamer
- The atomic structural and hydraulic unit of a plant graph.
- Metamer
Plant Graph - Zero-heap whole-plant FSPM solver.
- Multi
Rate SimClock - Multi-rate simulation clock coordinating 64 Hz continuous physics substeps with deterministic lockstep world-state ticks.
- Multi
Touch Tracker - Fixed 10-slot multi-touch tracker without heap allocation.
- Narrowphase
Contact - Result of a narrowphase contact query between two 3D colliders.
- NavPolygon
- A single convex polygon in the navigation mesh.
- Navigation
Grid - Bounded deterministic 2D navigation grid.
- Orbit
Camera - Orbit inspection camera around a central pivot point.
- Progressive
Monte Carlo Governor - Phase 4: Manages static scene dwell, progressive Monte Carlo convergence, and power throttling.
- Ray3D
- A 3D ray with origin and normalized direction vector.
- RayHit3D
- Hit result returned by
cast_ray. - Revolute
Motor Joint - 1-DOF revolute hinge joint with angular limits and optional motor drive.
- Rigid
Body3D - 3D rigid body with PGA [
Motor] pose and physical properties (HotZeroHeap). - Rover
Kinematics - Zero-heap rover vehicle simulator.
- Rover
State - Dynamic vehicle suspension state and kinematics wrapper for 4-wheel rover exploration.
- Salience
Perceptual Governor - Computes Quantization Parameter (QP) and ray budgets from D_9 semantic salience.
- Schwabe
Solar Cycle - 11-year Schwabe solar sunspot cycle and radiative output state.
- SdfCollider
- Analytical Signed Distance Field collision primitive for sector terrain landforms.
- Sector
Physics Receipt - Structured receipt verifying 3D physics, spatial queries, and continuum coupling in a sector.
- Sector
Physics World3D - Unified sector physics simulation world coordinating 3D XPBD rigid bodies, analytical SDF terrain, character controller, rover kinematics, ragdolls, dynamic fracture, and two-way continuum coupling.
- Shape
Cast Hit3D - Hit result returned by
cast_sphereandcast_capsule. - SimTable
- Fixed-capacity SOA component table with dense storage and per-row change-detection ticks.
- Simd
Gerstner Spectrum - 8-harmonic Gerstner wave spectrum for zero-allocation CPU water queries.
- Simulation
Command - Simulation command intent submitted by an agent or user.
- Soil
Mechanics Profile - Canonical geotechnical soil failure and physical mechanics profile.
- Solar
Wind State - Solar wind in-situ plasma parameters at L1 / Earth orbit.
- Spring
Chase Camera - 2nd-order spring-damper critically damped pursuit camera.
- Spring
State - 1D spring position and velocity state.
- Spring
Suspension Joint - Compliant linear suspension strut connecting
body_a(chassis) andbody_b(wheel/bogie). - Thermal
Phenology - Thermal time phenology tracker.
- Thermal
Targets - Two-channel driven thermal reservoir targets and relaxation rates ($s^{-1}$).
- Tick
- Monotonically advancing 32-bit change-detection tick.
- Tool
Effector - Kinematic tool effector parameters.
- Toroidal
Ground Cover Clipmap - Zero-allocation toroidal clipmap buffer centered on the moving camera.
- Touch
Contact - Touch contact point record for multi-touch finger gesture tracking.
- Transform3D
- 3D affine transform representation (
rotationstored as[x, y, z, w]). - Vehicle
Chassis Config - Vehicle chassis physical specifications.
- Vehicle
State - Dynamic runtime state of a 4-wheel vehicle.
- Vein
Edge - A single vascular vein segment within the leaf dual-graph skeleton.
- Virtual
Touch Stick - Virtual touch joystick for mobile phones and touchscreen devices.
- Wheel
Config - Wheel configuration parameters.
- Xpbd
World3D - 64 Hz deterministic Extended Position-Based Dynamics (XPBD) rigid-body physics world.
- Zero
Heap Button Input - Zero-heap bitset representing 256 discrete button states with single-frame transition events.
- Zero
Heap NavMesh - Zero-heap navigation mesh container.
- Zero
Heap Skeleton - Fixed-capacity skeletal rig (
MAX_BONES = 64).
Enums§
- Collider
Shape3D - Unified 3D collider shape supporting analytical primitives, convex hulls, and analytical SDFs.
- Command
Payload - Strongly typed command payload.
- Command
Receipt - Deterministic receipt issued for every executed command.
- Fireline
Regime - Dynamic fireline behavior classification.
- Ground
Cover Lod - 4-tier continuous representation level.
- Metamer
Organ - Botanical organ type borne by a metamer node.
- Motor
Joint3D - Unified 6-DOF PGA [
Motor] joint enum. - Path
Result - Detailed outcome of an A* pathfinding query.
- Ragdoll
Mode - Operational mode of an
ArticulatedRagdoll. - Raunkiaer
Life Form - Raunkiær life form based on the vertical height $z$ of surviving buds during the harsh season.
- Rejection
Reason - Reason for rejecting a proposed command.
- Rigid
Body Type3D - Kinematic / dynamic simulation class of a 3D rigid body.
- SdfPrimitive
- Analytical SDF primitive shapes evaluated in $O(1)$ local coordinates.
- SimTable
Error - Errors returned by
SimTableoperations. - Stem
Support Regime - Mechanical stem support regime.
- Submersion
State - Locomotion and submersion mode of an entity.
- Tool
Kind - Tool physical class distinguishing human implements, machinery, and abstract clicks.
- Transition
Mode - Animation state machine transition blend mode.
Constants§
- BASELINE_
TSI_ W_ M2 - Baseline solar constant / Total Solar Irradiance at 1 AU in W/m².
- BUTTON_
MIDDLE - BUTTON_
PRIMARY - BUTTON_
SECONDARY - DEAD_
FUEL_ EXTINCTION_ MOISTURE - Extinction fuel moisture fraction (fuels above this moisture content will not sustain flaming).
- DEFAULT_
MAX_ SUBSTEPS - EUCALYPT_
HEAT_ YIELD_ KJ_ KG - Heat of combustion for Australian dry sclerophyll eucalypt fuels in kJ/kg (~18,600 kJ/kg).
- FIXED_
DELTA_ NANOS - FIXED_
DELTA_ SECONDS - FIXED_
HZ - FIXED_
TIMESTEP_ 64HZ - Standard deterministic simulation timestep at 64 Hz ($1/64\text{ s} = 0.015625\text{ s}$).
- GAS_
CONSTANT_ DRY_ AIR - Gas constant for dry air in J/(kg·K).
- GAS_
CONSTANT_ WATER_ VAPOR - Gas constant for water vapor in J/(kg·K).
- GRAVITY_
M_ S2 - Gravity constant in m/s².
- HALE_
CYCLE_ YEARS - Hale double magnetic cycle duration in Earth years (~22.10 years).
- INPUT_
WORDS_ 4 - INVALID_
ROW - Sentinel value indicating that an entity ID is not present in a
SimTable. - KEY_A
- KEY_
ARROW_ DOWN - KEY_
ARROW_ LEFT - KEY_
ARROW_ RIGHT - KEY_
ARROW_ UP - KEY_D
- KEY_E
- KEY_
ESCAPE - KEY_Q
- KEY_S
- KEY_
SHIFT - KEY_
SPACE - KEY_TAB
- KEY_W
- MAX_
BONES - Maximum bones supported per skeleton instance (fits in GPU uniform blocks).
- MAX_
BUOYANCY_ SPHERES - Maximum number of buoyancy proxy spheres per character/rigid-body hull.
- MAX_
COMMANDS_ PER_ TICK - MAX_
ENTITIES - Default capacity constants.
- MAX_
GERSTNER_ HARMONICS - Maximum number of analytical wave components evaluated simultaneously.
- MAX_
METAMERS - MAX_
NAVMESH_ NODES - Maximum navigation polygons supported per local sector.
- MAX_
PATH_ LENGTH - Maximum path length returned in a single query.
- MAX_
PATH_ WAYPOINTS - Maximum waypoints returned in a single route.
- MAX_
PREDICTED_ DISOCCLUSIONS - MAX_
SECTOR_ COLLIDERS - Maximum number of active colliders in a sector physics simulation world.
- MAX_
SECTOR_ JOINTS - Maximum number of joint constraints in a single sector world.
- MAX_
SECTOR_ MANIFOLDS - Maximum number of persistent contact manifolds allocated per sector.
- MAX_
TOUCH_ POINTS - MAX_
VEIN_ EDGES - NAV_
GRID_ MAX_ CELLS - NAV_
GRID_ MAX_ DIM - Maximum dimensions for navigation grid.
- NO_
PARENT_ METAMER - NO_
PARENT_ VEIN - PURE_
WATER_ ABSORPTION_ RGB - Pure H2O molecular absorption coefficients in m⁻¹ at 20°C (Smith & Baker, 1981).
- PURE_
WATER_ RAYLEIGH_ RGB - Pure H2O molecular Rayleigh scattering coefficients in m⁻¹.
- RIPPLE_
GRID_ DIM - RIPPLE_
TOTAL_ CELLS - SCHWABE_
CYCLE_ YEARS - Nominal solar cycle duration in Earth tropical years (~11.05 years).
- SIMULATION_
TICK_ MS - SIMULATION_
TICK_ RATE_ HZ - Simulation frequency (20 Hz = 50ms per tick).
- STANDARD_
MSLP_ HPA - Standard atmospheric pressure at sea level in hPa.
- TOROIDAL_
GRID_ DIM - TOROIDAL_
TOTAL_ CELLS - VON_
KARMAN_ KAPPA - von Kármán constant for boundary-layer turbulence.
- WATER_
DENSITY_ KG_ M3 - Standard water density in kg/m³ (freshwater = 1000.0, ocean = 1025.0).
- WAVELENGTH_
BLUE_ NM - WAVELENGTH_
GREEN_ NM - WAVELENGTH_
RED_ NM - Wavelength standards in nanometers: Red (650 nm), Green (532 nm), Blue (450 nm).
Functions§
- cast_
capsule - Casts a vertical 3D capsule (
radius,half_height) alongdirup tomax_distby sweeping 3 axial proxy spheres (bottom hemisphere, center, top hemisphere). - cast_
ray - Casts a 3D ray through a
BroadphaseBvhand collider slice, returning the closestRayHit3D. - cast_
sphere - Casts a sphere of
radiusalongdirup tomax_distby inflating target primitives byradius. - compute_
boids_ separation - Computes a continuous 2D boids / crowd separation steering vector for an agent given neighboring agent positions.
- compute_
narrowphase_ contact - Evaluates narrowphase contact between two 3D colliders (
HotZeroHeap). - couple_
rigid_ body_ with_ botanical_ stem - Couples a 3D rigid-body impact against
metamer_idxin aMetamerPlantGraph. - couple_
rigid_ body_ with_ hydro - Applies two-way 3D Archimedes buoyancy, wave-normal righting torque, and quadratic fluid drag
between a
RigidBody3Dand aSimdGerstnerSpectrumwavefield. - couple_
rigid_ body_ with_ soil - Applies two-way geotechnical force coupling between a
RigidBody3D(wheel, foot, boulder, or chassis) and aSoilMechanicsProfile. - critical_
trench_ depth_ m - Critical maximum unsupported vertical trench wall depth before geotechnical collapse (Rankine slip).
- evaluate_
and_ fracture_ body - Evaluates whether an impact impulse
impact_impulse_nsovercontact_area_m2fracturesbody, and if $\sigma = J / A \ge \text{tensile_strength}$, partitions the collider along the cleavage plane usingevaluate_stress_cleavage_partition. - evaluate_
dead_ fine_ fuel_ moisture - Computes Dead Fine Fuel Moisture ($DFMC$) from ambient weather and solar exposure.
- evaluate_
excavation_ pass - Evaluates Mckyes-Ali earthmoving cutting resistance and geotechnical failure.
- evaluate_
fireline_ intensity - Evaluates Byram’s Fireline Intensity, distinguishing fuel load from weather-driven intensity.
- evaluate_
heliophysical_ fire_ weather - Evaluates integrated multi-domain heliophysical space weather, atmospheric thermodynamics, and fire weather coupling.
- evaluate_
soil_ compaction - Evaluates topsoil compaction under vehicular tracks or footsteps.
- evaluate_
solar_ cycle_ phase - Computes the astronomical Schwabe and Hale solar cycle states for an absolute calendar year.
- evaluate_
space_ weather_ coupling - Evaluates real-time space weather coupling into Earth’s magnetosphere and Global Electric Circuit.
- gjk_
intersect - Zero-heap GJK intersection test on a fixed 4-vertex stack simplex.
- overlap_
aabb - Convenience wrapper returning all collider IDs overlapping
query_aabb. - project_
grid_ path_ to_ waypoints - Projects a 2D integer grid path into continuous world-space waypoints (
Point2Don XZ plane), centering each cell coordinate and scaling bycell_size_m. - run_
sector_ physics_ verification_ step - Executes a complete deterministic verification pass on the designated
sector_idworld: - spatial_
hash_ 2d - Deterministic spatial hash generating consistent pseudo-random offsets from world position $(x, z)$.
- step_
character_ 3d - Convenience wrapper for
CharacterController::step_character_3d. - step_
spring - Steps a
DrivenSpringoverdt(0.0..=0.05s), substepped at $\le 1/240$ s viaRk4Integrator4D. - step_
thermal - Steps two thermal channels toward
targetsoverdt(0.0..=0.05s) viaRk4Integrator4D. - step_
xpbd_ world - Steps a slice of
RigidBody3Dbodies, contact manifolds, andMotorJoint3Dconstraints by one fixed timestepdt(typically $1/64 = 0.015625\text{ s}$) usingsubstepsXPBD iterations. - unproject_
screen_ to_ ray - Unprojects 2D screen coordinates into a 3D world ray using a $4 \times 4$ inverse view-projection matrix.
Type Aliases§
- Command
Receipt Status - Alias for
RejectionReason. - Ecopunk
Sector Physics World - Type alias preserving 100% compatibility with downstream sector physics consumers.
- Entity
State - Ergonomic alias for
AgentState. - Point2D
- A 2D point [x, z] on the ground plane.
- SimCommand
- Ergonomic alias for
SimulationCommand. - World
State - Ergonomic alias for
FixedTickWorld.