ALICE-Physics

Deterministic 128-bit Fixed-Point Physics Engine - v1.0.0 stable

English | 日本語

Part of ALICE-Eco-System — 260+ crate Edge-to-Cloud data pipeline (SDF / Physics / LLM / Motion / Font / TTS)

A high-precision physics engine designed for deterministic simulation across different platforms and hardware. The rigid-body core uses 128-bit fixed-point arithmetic (Fix128); the surrounding engineering / field modules use IEEE f32 / f64 with every transcendental routed through the crate's own det_math. Either way the result is bit-exact regardless of CPU, compiler, or operating system — see Determinism scope.

Published on crates.io (1.0.0 semver-locked stable released 2026-09-14; 1.1.0 makes every module cross-platform bit-exact via det_math; 1.2.0 fixes the default-config physics found by the 2026-09-15 external review and adds analytic-solution oracles — see CHANGELOG.md).

Determinism scope

Every module in the crate is bit-exact across platforms, for two different reasons:

Tier	Modules	Why the bits agree everywhere
Fix128 core	rigid-body solver, joints, distance / contact constraints, BVH broad-phase, GJK / EPA, CCD, sleeping, scene I/O, netcode snapshot / rollback, neural controller, and every module whose public API is expressed in Fix128 / Vec3Fix / QuatFix	Pure i64 / u64 integer arithmetic. Pinned by tests/determinism_golden.rs
f32 / f64 field modules (27: acoustic_wave, aeroelasticity, anomaly, convex_decompose, erosion, fracture, gpu_sdf, phase_change, piezoelectric, pressure, privacy, rolling_contact, sdf_adaptive, sdf_ccd, sdf_character, sdf_collider, sdf_destruction, sdf_fem_mesh, sdf_manifold, sdf_sph, sdf_wind_field, sim_field, sim_modifier, sketch, thermal, thin_wall, transient_thermal; list generated by scripts/f32_modules.py --check, which CI-gates this row — 8 more modules carry floats only across an I/O boundary: ffi, pipeline, analytics_bridge, db_bridge, replay, fluid_netcode, character_state, solver_tgs)	IEEE 754 + - * / sqrt and fused multiply-add are specified to the bit on every target Rust supports (SSE2+, aarch64, wasm32). Every transcendental (sin, exp, ln, powf, cbrt, hypot, …) goes through det_math — integer range reduction + fixed-order polynomials — never the platform libm. clippy.toml disallowed-methods makes a stray libm call a CI error. Pinned by tests/determinism_golden_f32.rs (13 scenarios, 29 modules)

Both golden suites run on macOS ARM / x86, Linux ARM / x86, Windows and wasm32-wasip1 in CI.

Boundary — code you pass in. ClosureSdf takes a user closure Fn(f32, f32, f32) -> f32. The solver stays deterministic, but the closure is your code: call alice_physics::det_math::{sin, exp, …} instead of f32::sin etc. inside it, or hand in an SDF whose evaluator has the same discipline. (ALICE-SDF's CPU evaluator is being aligned with det_math; until then treat it as same-binary deterministic.)

Out of scope. Targets that do not honour IEEE 754 for the basic operations: 32-bit x86 built for x87 (i586, no SSE2) and any build with fast-math style flags.

Correctness scope — what "deterministic" does and does not tell you

Bit-exactness says every peer computes the same numbers; it says nothing about whether those numbers are right. The 2026-09-15 external review found four physics bugs in the default configuration with 1456 tests and 44 golden hashes green (see CHANGELOG.md 1.2.0), so the crate now separates the two properties explicitly. Validation below means "compared against a closed-form solution or an independent reference in tests/"; the golden hashes only detect change.

Layer	Modules	Validation
Core — what the determinism guarantee is for	math (Fix128, Vec3Fix, QuatFix, CORDIC), solver (XPBD rigid bodies, distance / contact constraints, sleeping), joint, bvh, collider (GJK / EPA), ccd, contact_cache, sdf_collider, netcode / snapshot	tests/analytic_physics.rs — free fall, projectile, terminal velocity, mg/k extension, spring and pendulum periods, collision momentum + energy bound, kinematic targets, torque-free rotation, resting contact; sqrt / transcendental oracles in math::tests; det_math sweeps vs correctly-rounded references
Engineering / field modules — textbook formulas made deterministic	transient_thermal, fatigue	tests/engineering_oracles.rs — cosine eigenmode decay (Carslaw & Jaeger) for explicit and Crank–Nicolson steps, Basquin / Miner closed forms
	solid / structural: beam_stress, buckling, thin_wall, fillet_stress, modal, vibration_wall, damping_rayleigh, hyperelastic, plastic, creep_longterm, structural_solver, laminate, laminate_failure (Tsai-Wu / Hashin / Puck), anisotropic, bimaterial, prestressed, bridging, thermal_stress, mass_properties, print_orientation, filament_db	tests/engineering_oracles_solid.rs (34) — Roark beam deflection / stress and section properties, Euler–Johnson buckling (Shigley), Rayleigh damping (Chopra), CLT laminate ABD and ply transformation (Jones), Tsai-Wu / Hashin envelopes at the uniaxial strengths, Shigley bolt joint and Irvine cable, Kirsch / Inglis exact concentration and Peterson fit invariants, Norton creep, Findley / WLF, hyperelastic uniaxial stress as derivative of the strain energy, first modes (Blevins beam, Leissa plate, Rao SDOF), closed-form inertia tensors and Steiner parallel axis, rule of mixtures / thermal mismatch, thermal-stress magnitude and sign
	fluid / thermal / field: cfd_solver, eulerian_grid, sdf_sph, multiphase, interface_capture, surface_tension_csf, compressible, non_newtonian, turbulence, buoyancy_zone, wind_zone, sdf_wind_field, cloth_fluid, fsi_advanced, smoke_fire, wave_ship, aeroelasticity (Facchinetti 2004), acoustic_wave, electromagnetic, piezoelectric, thermal, phase_change, pressure, erosion	tests/engineering_oracles_fluid.rs (39) — viscous shear-mode decay, pressure projection removes divergence and is identity on solenoidal fields, SPH kernel normalisation and lattice rest density, Young–Laplace through the CSF band, ISA density / speed of sound, normal-shock and isentropic tables (Anderson), Bingham / Herschel–Bulkley / power-law / Carreau flow curves (integer and fractional index), Smagorinsky simple shear, Archimedes, quadratic drag, d'Alembert at Courant 1, Coulomb / Lorentz / dipole, d33 piezo relations, Arrhenius / Boussinesq, deep-water dispersion / Froude–Krylov / JONSWAP, van der Pol amplitude and Strouhal frequency, Newton cooling and conduction eigenmode, enthalpy-method plateau and conservation, level-set curvature and fast-sweeping distance, erosion rate-law invariants
	cloth, rope, deformable, fluid (PBF), character, vehicle (WheelConfig / EngineConfig), sleeping, netcode, audio_physics, support (print supports), neural	tests/default_configs.rs — every Config::default() on its most ordinary scenario: hanging curtain / rope geometry, free-fall closed form for a deformable cube and a fluid block's centre of mass, wheel compression mg/k, engine first-frame Δv = T·gear/(r·m)·dt, sleep at exactly frames_to_sleep, lockstep checksums + rollback bit-exact, support volumes to 1e-6
	mechanisms / fields / netcode: rolling_contact, fracture, kinematic_loop, sdf_force, anisotropic_friction, physics2d, sdf_destruction, soft_body_cut, layer_adhesion, fluid_netcode	tests/engineering_oracles_misc.rs (27) — Hertz sphere contact and Basquin life (Johnson §4.2), crack growth L = min(vt, L_max) and Quilez capsule subtraction, PBD loop closure (mass-weighted projection, geometric residual contraction, four-bar link lengths), F = −kφ∇φ and the contain / repel / vortex closed forms, orthotropic friction ellipse (Zmitrowicz) with the Coulomb isotropic limit, 2-D free fall / θ = ωt / momentum / Newton restitution v_sep = e·v_app / Coulomb sliding μ g / inertia tensors (Meriam & Kraige), hemisphere crater and capped-cylinder bore volumes, plane-cut partition invariants, bit-exact snapshot round trip and lossless τ = 0 delta
	warp_risk (empirical fit: two ALICE-Bamboo data points), sim_field, layer_adhesion (empirical FDM factors, invariants only) and the remaining utility / bridge modules	none yet — the formulas are implemented as published and the code is bit-exact, but no test compares them with a reference solver, a textbook worked example or experimental data. Treat their numbers as implementations of the cited equation, not as validated predictions, until the module gains an oracle (the 1.2.0 batches above show the pattern: closed form at Config::default(), precision parameter varied)

Where the crate fits. The core is built for use cases where bit-exact replay is the requirement, not a nicety: rollback netcode (fighting / RTS / .io games, tens to hundreds of bodies), server-side replay verification and anti-cheat, and reproducible research or audit batches. Measured on the 1000-overlapping-sphere scene (cargo bench --bench physics_bench, thousand_overlapping_spheres_1_step) it runs at a few ms per frame with the default configuration. It is not a drop-in replacement for a float engine in a general game: destruction, crowds of thousands, VFX-grade contact counts at 60 fps are outside its design point, and a float engine pays none of the fixed-point cost for a determinism it does not need. v0.10-0.14 highlights — a five-wave completeness push adds 54 modules + 3 integrated solver loops + a Session 4 19-module tier-classified push covering the full spectrum from 3D-printing safety (warp / thin-wall / stress / bridging) through composite / plastic / fatigue mechanics, up to turbulence, VOF / level-set multi-phase flow, a runnable CFD time-step loop, humanoid ragdoll, SDF-boundary SPH, transient thermal, composite failure, VIV / piezoelectric / acoustic / electromagnetic, IK / anisotropic friction / netcode prediction / character FSM / kinematic loop / buoyancy zone / wind zone / SDF FEM / SDF wind. All bit-exact across platforms — Fix128 modules by integer arithmetic, f32 modules via det_math (Determinism scope); see Session 1-3 Additions and v0.13.0 Session 4 Additions.

v1.0.0 release highlights (2026-09-14)

• API surface freeze — 32 module × 512 pub items audit (Iterations 1-6 + Final), 133+ items pub → pub(crate) downgraded, snapshot 20,201 → 19,406 (−795 items). solver_tgs* extension mechanism moved to pub(crate) (Option C). 7 prelude-exported structs marked #[non_exhaustive] for forward-compat.
• 6-platform bit-exact determinism — golden hash (9 tests) + semantic invariant (22 tests) suite verified on macOS ARM/x86 + Linux ARM/x86 + Windows + WASM (wasm32-wasip1 via wasmtime).
• Hard-gated semver enforcement — cargo semver-checks blocks breaking-API PRs.
• Ecosystem contracts frozen — [docs/ECOSYSTEM_CONTRACTS.md] catalogues API for ALICE-TRT (GpuSolverBridge), ALICE-SDF (SdfField), ALICE-Bamboo, ALICE-Anima, ALICE-Kinematics.
• 8/8 fuzz targets — fuzz_step / fuzz_collision / fuzz_deterministic_roundtrip / fuzz_joint / fuzz_cfd / fuzz_ccd / fuzz_trimesh / fuzz_structural.
• 1695 lib tests + 44 determinism tests — all passing on all 6 platforms.

v0.12.0 addition — GpuSolverBridge gains a joint-solve pipeline (send_joints / send_body_rotations / dispatch_joint_solve_iteration) and PhysicsWorld auto-routes both contact AND joint solve through the installed bridge, coordinated with ALICE-TRT v3.1.0's FIX128_BALL_SOCKET_JOINT_SOLVE_WGSL kernel (byte-exact vs CPU solve_ball_joint). See CHANGELOG.md.

v0.13.0 Session 4 Additions (19 modules across 3 tiers)

Extends the v0.10-0.12 engineering-solver foundation with a 19-module push covering game-physics polish (ragdoll / character state / netcode prediction / IK), soft-body simulation (SDF SPH / SDF character / SDF FEM / SDF wind), engineering research (composite failure / transient thermal / rolling contact fatigue / VIV / piezoelectric / acoustic / electromagnetic), and multi-material coupling (buoyancy zone / anisotropic friction / kinematic loop). All bit-exact across platforms (Determinism scope); formula sources cited in module docs.

Tier ★★★ — 5 modules (real-world critical, downstream-load-bearing)

Module	Purpose
ragdoll	Humanoid ragdoll builder with pose targets, joint limits, breakable constraints (G1)
buoyancy_zone	Bounded 3-D fluid volume with buoyancy + drag, fluid-surface CSF coupling (G2)
laminate_failure	Tsai-Wu / Tsai-Hill / Hashin / Puck composite failure indices (R1)
transient_thermal	Temperature-dependent material properties + 1-D unsteady heat solver + phase-boundary tracking (R2)
ALICE-SDF morphology	Signed offset + tolerance fit check for print clearance (S1, ships in ALICE-SDF v1.7.7)

Tier ★★ — 7 modules (broad utility, cross-domain glue)

Module	Purpose
wind_zone	Bounded 3-D wind volume with drag + lift on rigid / soft bodies (G3)
sdf_character	SDF-terrain-aware character controller with slope / step / air-time state (S4)
rolling_contact	Rolling contact fatigue (Hertz + subsurface shear + Basquin S-N cycle counting) (R3)
netcode_prediction	Client-side prediction + reconciliation + input replay (G5)
character_state	Character FSM (idle / walk / run / jump / fall / crouch) with transition validation (G6)
sdf_sph	SDF-boundary SPH fluid with density / viscosity / surface tension (S3)
kinematic_loop	Kinematic body loop constraint solver for closed-chain mechanisms (R4)

Tier ★ — 8 modules (specialized engineering / research)

Module	Purpose
ik_physics_bridge	Physics-aware IK solver with joint-limit respecting FABRIK / CCD backend (G4)
anisotropic_friction	Direction-dependent friction coefficient (rolling vs sliding, wood grain, fabric) (G7)
aeroelasticity	Vortex-induced vibration (VIV) + flutter + galloping for slender structures (R5)
piezoelectric	Piezoelectric coupling for sensors / actuators (voltage ↔ strain) (R6)
acoustic_wave	1-D / 2-D / 3-D acoustic wave propagation with material impedance boundary (R7)
electromagnetic	Electromagnetic force field (Lorentz / induction / eddy current) for conductor bodies (R8)
sdf_fem_mesh	SDF-to-tetrahedral FEM mesh generator for large-deformation simulation (S2)
sdf_wind_field	SDF-boundary-aware wind field with turbulence intensity + gust modeling (S5)

Features

Feature	Description
128-bit Fixed-Point	I64F64 format (64-bit integer + 64-bit fraction) for extreme precision
CORDIC Trigonometry	Deterministic sin/cos/atan without FPU instructions
XPBD Solver	Extended Position Based Dynamics for stable constraint solving
GJK/EPA Collision	Robust collision detection for convex shapes
Stackless BVH	Morton code-based spatial acceleration with escape pointers
Constraint Batching	Graph-colored parallel constraint solving
Rollback Support	Complete state serialization for netcode
Neural Controller	Deterministic AI via ALICE-ML ternary weights + Fix128 inference
12 Joint Types	Ball, Hinge, Fixed, Slider, Spring, D6, Cone-Twist, Pulley, Gear, Weld (breakable), Rack-and-Pinion, Mouse
Raycasting	Ray and shape casting against spheres, AABBs, capsules, planes
Shape Cast / Overlap	Sphere cast, capsule cast, overlap sphere, overlap AABB queries
CCD	Continuous collision detection (TOI, conservative advancement)
Sleep/Islands	Automatic sleep with Union-Find island management
Triangle Mesh	BVH-accelerated triangle mesh collision (Moller-Trumbore)
Height Field	Grid terrain with bilinear interpolation
Articulated Bodies	Multi-joint chains, ragdolls, robotic arms with FK propagation
Force Fields	Wind, gravity wells, drag, buoyancy, vortex, explosion, magnetic dipole
PD Controllers	1D/3D proportional-derivative joint motors
Collision Filtering	Layer/mask bitmask system with collision groups
Trigger/Sensor	Sensor bodies that detect overlap without physics response
Character Controller	Kinematic capsule-based move-and-slide with stair stepping and SDF terrain
Rope	XPBD distance chain rope and cable simulation
Cloth	XPBD triangle mesh cloth with self-collision (spatial hash grid)
Fluid	Position-Based Fluids (PBF) with spatial hash grid
Deformable	FEM-XPBD deformable body (tetrahedral mesh)
Vehicle	Wheel, suspension, engine, steering, gear shifting
Animation Blend	Ragdoll-to-animation blending with SLERP
Audio Physics	Physics-based audio parameter generation (impact, friction, rolling)
SDF Manifold	Multi-point contact manifold from SDF surfaces
SDF CCD	Sphere tracing continuous collision detection for SDF
SDF Force Fields	SDF-driven force fields (attract, repel, contain, flow)
SDF Destruction	Real-time CSG boolean destruction
SDF Adaptive	Adaptive SDF evaluation with distance-based LOD
Convex Decompose	Convex decomposition from SDF voxel grid
GPU SDF	GPU compute shader interface for batch SDF evaluation
Fluid Netcode	Deterministic fluid netcode with delta compression
Simulation Fields	3D scalar/vector fields with trilinear interpolation and diffusion
Thermal	Heat diffusion, melt, thermal expansion, freeze
Pressure	Contact force accumulation, crush, bulge, dent deformation
Erosion	Wind, water, chemical corrosion, ablation
Fracture	Stress-driven crack propagation with CSG subtraction
Phase Change	Solid/liquid/gas transitions driven by temperature
Deterministic RNG	PCG-XSH-RR pseudo-random number generator
Contact Events	Begin/Persist/End contact and trigger event tracking
Box/OBB Collider	Oriented Bounding Box with GJK support and fast AABB
Compound Shape	Multi-shape compound collider with local transforms
Contact Cache	Persistent manifold cache with HashMap O(1) lookup and warm starting
Dynamic AABB Tree	Incremental BVH with O(log n) insert/remove/update, AVL balancing
D6 Joint	6-DOF configurable joint with per-axis lock/free/limit
Cone-Twist Joint	Ball joint with cone swing limit and twist limit
Material Table	Per-pair friction/restitution with combine rules (Avg, Min, Max, Mul)
Scaled Shape	Uniform scale wrapper for any Support-implementing shape
Speculative CCD	Speculative contacts for fast-moving bodies without time rewinding
Featherstone	O(n) forward dynamics for articulated bodies
Debug Render	Wireframe visualization API (bodies, contacts, joints, BVH, forces)
Profiling	Per-stage timer and per-frame statistics API
Substep Interpolation	WorldSnapshot with NLERP quaternion blending for smooth rendering
Probabilistic Sketches	HyperLogLog, DDSketch, Count-Min Sketch, Heavy Hitters
Streaming Anomaly Detection	MAD, EWMA, Z-score composite detector
Local Differential Privacy	Laplace noise, RAPPOR, randomized response
Metric Pipeline	Lock-free ring buffer metric aggregation with registry
Cone Collider	Cone shape with GJK support (apex +Y, base -Y)
Ellipsoid Collider	Three independent semi-axes with anisotropic support
Torus Collider	Major/minor radii with Minkowski sum decomposition
Plane Collider	Infinite plane (Hessian normal form) with sphere/AABB intersection
Wedge Collider	Triangular prism with 6-vertex GJK support
Convex Hull Builder	Incremental convex hull from arbitrary point sets
2D Physics	Complete 2D subsystem: SAT collision, XPBD solver, Circle/Polygon/Capsule/Edge shapes
Mass Properties	Inertia tensor computation for sphere, box, cylinder, capsule, convex hull
Collision Mesh Gen	Marching cubes SDF-to-mesh with edge-collapse simplification
Scene I/O	Binary (.aphys) and JSON scene serialization with bit-exact Fix128 roundtrip
Cloth-Fluid Coupling	Bidirectional cloth-fluid interaction (drag, buoyancy, boundary repulsion)
Rope Attachment	Rigid body rope attachment with compliance and break force
Soft Body Cutting	Plane-based cutting of deformable bodies and cloth
Stress Heatmap	Stress/temperature/pressure 2D slice visualization with viridis colormap
Flow Visualization	Fluid velocity field arrows and streamline generation
Contact Visualization	Contact force arrows and friction cone rendering
Multi-World	Multiple independent physics worlds with body transfer
Particle System	General-purpose emitters, lifetime, force field integration
no_std Compatible	Works on embedded systems and WebAssembly

Session 1-3 Additions (v0.10-0.12)

Three completeness sessions added 35 modules + 3 integrated solver loops + 3 runnable examples to close the gap between "physics primitives" and "usable engineering solvers." Every addition is bit-exact across platforms (see Determinism scope) and cites the source formula (Roark / Timoshenko / Simo & Hughes / Jones / Tsai-Wu / Hill / Norton / Findley / WLF / Brackbill / Smagorinsky / Launder-Spalding / Wilcox / Hasselmann / Turns / Anderson / etc.).

Session 1 — 3D Print Safety + Structural Tier 1 (v0.10)

Module	Purpose	Formula source
filament_db	10-material property DB (Young's / yield / tensile / density / Tg / anisotropy)	MatWeb / ASM Metals Handbook
thin_wall	SDF sphere-marching wall thickness detection	Bambu/Prusa min-wall guidance
beam_stress	Cross-section + load case + Euler buckling + FoS	Roark's Formulas for Stress and Strain
support_volume	Overhang → filament mm³ + print time estimate	Bambu Studio support manual
anisotropic	9-constant orthotropic + Hill + Tsai-Wu failure	Jones, Mechanics of Composite Materials
plastic	von Mises + isotropic/kinematic/combined hardening + Norton creep	Simo & Hughes; Norton (1929)
buckling	Johnson / Euler / plate / snap-through	Timoshenko & Gere; Bažant & Cedolin
hyperelastic	Neo-Hookean / Mooney-Rivlin / Yeoh	Ogden (1984); Yeoh (1990)
bimaterial	Timoshenko bimetal residual + Voigt/Reuss bounds	Timoshenko (1925)
layer_adhesion	XY vs Z 6-component effective strength envelope	Empirical FDM data
print_orientation	Load-direction optimization + Euler grid search	Anisotropy transformation
bridging	Material-specific max bridge distance check	Bambu/Prusa knowledge base
warp_risk	Cooling shrinkage × footprint → Low/Medium/High/Critical	ALICE-Bamboo docs incident-tuned

Session 2 — Structural Tier 2 + Fluid Tier 1-2 (v0.11-0.12)

Module	Purpose	Formula source
fatigue	Basquin S-N + Miner cumulative damage	Basquin (1910); Miner (1945)
modal	1-DOF / beam / Warburton plate / torsional natural frequency	Blevins; Warburton (1954)
damping_rayleigh	C = αM + βK + fit_two_modes	Clough & Penzien
laminate	Classical Laminate Theory ABD matrix	Jones eq. 2.84
prestressed	Motosh bolt preload + parabolic cable pretension	Shigley; VDI 2230
fillet_stress	Kirsch / Inglis / Peterson K_t	Peterson; Pilkey; Norton
vibration_wall	Thin-wall resonance vs 6 printer excitation presets	Blevins; Bambu X1C spec
thermal_stress	Constrained σ = c·E·α·ΔT + Tg proximity warning	Timoshenko & Goodier
creep_longterm	Findley 3-parameter + WLF time-temperature superposition	Findley (1989); Williams et al. (1955)
non_newtonian	Power-law / Carreau / Bingham / Herschel-Bulkley	Bird, Stewart, Lightfoot
multiphase	VOF advection + level set reinit + curvature	Hirt & Nichols (1981); Osher & Sethian (1988)
compressible	Ideal gas + Rankine-Hugoniot shock + Riemann invariants	Anderson, Modern Compressible Flow
eulerian_grid	Staggered MAC + Jacobi/red-black GS pressure projection	Harlow & Welch (1965)
turbulence	Smagorinsky LES + k-ε + k-ω + wall function	Pope; Wilcox; Launder & Spalding
surface_tension_csf	Continuum Surface Force	Brackbill, Kothe & Zemach (1992)
fsi_advanced	Solid ↔ fluid drag / buoyancy / reaction	Peskin immersed boundary
smoke_fire	Arrhenius reaction + soot + Boussinesq buoyancy	Turns; Kuo
wave_ship	JONSWAP spectrum + Froude-Krylov + 2-DOF	Hasselmann (1973); Faltinsen
interface_capture	Fast Sweeping FSM + PLIC (Rider-Kothe analytical)	Zhao (2005); Youngs (1982)

Session 3 — Solver Loops + 12 Improvements + 3 Demos (v0.12)

Integrated solver loops — single step(dt) entry points that compose the Session 1-2 modules into a driven simulation:

Solver	Composes
cfd_solver::CfdSolver	MAC + turbulence + non-Newtonian + level_set + CSF + Boussinesq + gravity
structural_solver::StructuralSolver	beam + plastic + creep + fatigue + buckling with history tracking
print_pipeline_solver	10 print-safety checks (warp + layer + orientation + thermal + beam + bridging + support + fillet + bimaterial) in one shot

12 improvements — accuracy / performance / robustness:

• I1 math_util shared exp_fix / cbrt_fix / pow_int / clamp_fix
• I2 eulerian_grid trilinear P2G / G2P (was nearest-cell)
• I3 multiphase semi-Lagrangian advection (was first-order upwind)
• I4 PLIC Rider-Kothe analytical + cbrt (bisection collapse)
• I5 FSM Godunov 3-neighbour quadratic Eikonal (was min + dx)
• I6 safety::sdf_aabb NaN/degenerate/min-dim guards
• I7 safety_validate integrates thin_wall + layer_adhesion + thermal_stress
• I8 turbulence log-law wall function + ln_fix
• I9 pressure projection red-black Gauss-Seidel (~2× convergence)
• I10 dynamic Smagorinsky Germano estimator
• I11 laminate::compute_abd rayon parallel (feature-gated)
• I12 fatigue::stress_at_cycles Newton early exit

3 runnable examples demonstrating the solvers end-to-end:

cargo run --example cfd_smoke_plume --release          # gravity settling in a 12³ MAC grid
cargo run --example structural_pla_shelf_creep --release  # 20 h PLA shelf under 20 N centre load
cargo run --example print_full_safety --release        # SKADIS-style plate full safety report

cfd_smoke_plume demonstrates bit-exact v_y = -g·t recovery, with the pressure projection maintaining zero divergence at the grid centre throughout the run. print_full_safety exercises all 10 safety checks and returns a realistic UNSAFE verdict for a 300 × 300 × 5 mm PLA plate (Warp Critical / Beam FoS 1.16 / Fillet K_t 3.30) — exactly matching the failure mode documented in the ALICE-Bamboo warp incident.

Mutation score (cargo-mutants, quality-deep.yml)

"Tests pass" says nothing about whether they check values. The core modules are measured with cargo-mutants (-- --lib, test helpers excluded via .cargo/mutants.toml); a mutant is caught when some test fails after the mutation. Score = caught / (caught + missed), unviable mutants excluded. The campaign started at 32.0 % (2026-09-15, 16-shard weekly run) and found six real defects on the way (remove_body constraint remap, Fix128::atan CORDIC shift, cloth bending sign, LinearBvh::find_pairs n², joint angular split / unsigned twist, EPA normal sign).

module	score	measured
ccd	95.4 % (208 / 218)	local run after batch 8
collider	93.5 % (145 / 155)	local run after batch 8
math	92.2 % (295 / 320)	weekly run at b187144, partial shards; scoped run pending
contact_cache	88.0 % (66 / 75)	scoped run at 3c12ee6, before batch 7 tests
solver_tgs	81.7 % (89 / 109)	weekly run at b187144, before batch 7 tests
bvh	79.9 % (135 / 169)	weekly run at b187144, before batch 8 (9 tests added)
solver	76.2 % compiled code (433 / 568)	weekly run at b187144, before batch 8 (24 tests added); 163 further mutants sit in cfg(feature = "parallel" / "gpu-solver-bridge") code and are measured on that feature axis
joint	72.0 % (206 / 286)	weekly run at b187144, before batch 8 (15 tests + 8 re-derived after the angular-split fix)

Rows marked "before batch N" are the last measured figure; the tests written since target the listed misses (equivalent mutants documented in each test module) and are re-measured by the scoped quality-deep dispatch. The next measured numbers replace this table; estimates are not written here.

Test count

Session 1 baseline (v0.9): 719 → Session 1 end (v0.10): 904 → Session 2 end (v0.11): 1170 → Session 3 end (v0.12): 1175 alice-physics tests + 53 alice-bamboo integration tests, all passing.

Sub-stepping TGS Solver — v1.0 status: pub(crate) internal

The trait-abstracted temporal Gauss-Seidel solver primitives (TgsHooks, ImpulseCache, build_islands, 6-DOF hooks, per-island scoped solve, rayon parallelisation, quaternion orientation integration) exist in-crate as solver_tgs* modules but are pub(crate) since 1.0.0 — the extension mechanism had zero downstream adoption during the v1.0 API audit (Option C, see docs/PUB_AUDIT_FINAL.md). The primary PhysicsWorld::step API uses its own internal TGS solver in crate::solver and remains fully public. If your project needs a generic hooks-based TGS integrator, open an issue — re-exposing pub(crate) items via a semver-minor bump is non-breaking.

Advanced solver primitives (Turn D / Phase E / Phase F)

Additional building blocks stacked on top of the sub-stepping TGS core:

• Adaptive sub-stepping — AdaptiveSubStepConfig + HasVelocity + adaptive_substeps_for compute a deterministic sub-step count from the fastest body's L∞ velocity (Fix128 pure, closed-form, division-free — safe under lockstep and rollback)

• CCD-optimised adaptive sub-stepping — adaptive_substeps_for_ccd tightens the per-step translation cap to smallest_collider_radius × safety_factor, guaranteeing fast bodies never tunnel through thin walls

• Adaptive sub-TOI — adaptive_toi_substeps bridges Adaptive sub-stepping with the existing speculative_contact TOI so a pair on a collision course over dt immediately requests max_substeps (Phase F 11.1, body complete)

• ImpulseCache observability — hits/misses/stats/hit_rate/reset_stats expose warm-starting effectiveness so callers can gauge whether contact IDs stay stable across frames (high hit rate) or the scene is churning (low hit rate)

• Per-island scoped oriented solve — solver_tgs_hooks_6dof_oriented_scoped extracts an isolated body / contact subset per island for the full 6-DOF oriented hook, prevents gravity double-counting, and preserves bit-perfect parallel-vs-serial equality

• LinearBvh::refit_leaves (bottom-up) — retains the flat tree structure while requantising leaf AABBs and propagating unions to internal nodes in the i32 domain (no CORDIC / rounding dependency), enabling O(N) refit as an alternative to full rebuild

• BroadphaseHybrid — layers a SpatialGrid hash grid over a static LinearBvh (Turn D 5' plan), reducing per-frame broad-phase work from O(N_total log N_total) to O(N_dynamic + log N_static). Recommended per-frame flow: clear_dynamic → insert_dynamic × N → build_dynamic → query_pairs

• FeatherstoneSolver::solve_with_mass_splitting — extends the O(n) forward-dynamics solver with a mass-ratio split threshold (heavy / light > threshold → dt / 2 × 2 recursion), relieving stiffness-induced ill-conditioning for extreme mass-ratio stacks. Determinism preserved via lookup-free multiplicative comparison and Fix128::half (Phase F 11.2, body + 3 tests complete)

• FFI byte-for-byte determinism — AliceVec3Fix128Raw + alice_physics_body_get_position_fix128_raw expose Fix128 hi/lo pairs across the C ABI. ffi_contract_gravity_fall_deterministic asserts a bracket bound plus a full second-world replay that must produce the exact same hi/lo pair, so Unity / UE5 hosts can assert bit-pattern equality (Phase F 11.3, runtime determinism gate complete)

• GpuSolverBridge trait (--features gpu-solver-bridge) — opt-in extension surface for external GPU offload backends (e.g. ALICE-TRT TrtSolverAdapter). Ships with DiffFixture / GpuDivergence types so implementations must certify byte-for-byte equivalence with the CPU-side solver before the runtime accepts them. Default builds keep the CPU-native TGS pipeline as the only code path

Companion crate — ALICE-TRT (GPU solver offload)

Pair with ALICE-TRT v1.0.0+ --features physics-solver for the reference GpuSolverBridge implementation (TrtSolverAdapter). Enabling physics-solver on ALICE-TRT automatically activates gpu-solver-bridge on this crate, so a single feature line covers both sides. ALICE-TRT v1.x is semver-stable — public adapter surface (send_island / dispatch_iterations / set_gravity / set_floor / push_distance_constraint / recv_island / assert_bit_exact_vs_cpu) is byte-stable across the v1.x line.

[dependencies]
alice-physics = { version = "1", features = ["gpu-solver-bridge"] }
alice-trt     = { version = "3.1", features = ["physics-solver"] }

use alice_physics::gpu_bridge::{DiffFixture, GpuSolverBridge};
use alice_physics::math::Fix128;
use alice_trt::{GpuDevice, TrtSolverAdapter};

// Live PGS dispatch (integrate + gravity + floor + multi-distance constraints)
let device = GpuDevice::new()?;
let mut adapter = TrtSolverAdapter::new(&device);

adapter.send_island(&positions, &velocities);
adapter.set_gravity(Some([Fix128::ZERO, Fix128::from_ratio(-98, 10), Fix128::ZERO]));
adapter.set_floor(Some(Fix128::ZERO));
adapter.push_distance_constraint(0, 1, Fix128::from_int(2));   // Gauss-Seidel ordered
adapter.push_distance_constraint(1, 2, Fix128::from_int(2));

adapter.dispatch_iterations(10, Fix128::from_ratio(1, 60));    // real GPU dispatch, not a stub
adapter.recv_island(&mut positions, &mut velocities);

// Production gate: certify byte-for-byte equivalence with the CPU solver.
adapter.assert_bit_exact_vs_cpu(&DiffFixture {
    description: "3body_triangle_10iter",
    tolerance: Fix128::ZERO,
})?;

Companion releases: ALICE-TRT v3.1.0 (coordinated with alice-physics v0.12.0 for joint-solve GPU offload). Every ALICE-TRT release is validated on macOS (Metal) / Ubuntu (Vulkan lavapipe) / Windows (DX12 WARP) with 37 Fix128 unit tests + 170 physics-solver tests, all byte-exact against the CPU golden.

Determinism guardrails for every primitive above are documented in the deterministic-physics-lockstep-discipline skill (private reference).

Optimizations ("黒焦げ" Edition) — 100/100

ALICE-Physics achieves a perfect 100/100 optimization score across 6 layers:

Optimization Scorecard

Layer	Score	Key Techniques
L1: Memory Layout	15/15	#[repr(C, align(64))] on RigidBody/Cloth/Fluid, hot/cold field reorder
L2: Execution	20/20	#[inline(always)] on GJK/BVH/constraints, branchless select, precomputed grid_half
L3: Compute	20/20	Warm-start cached_lambda, reciprocal precomputation (inv_rest_length, inv_rest_density)
L4: GPU & Throughput	15/15	SIMD_WIDTH const + simd_width(), GpuSdfInstancedBatch/GpuSdfMultiDispatch, batch_size()
L5: Build Profile	10/10	opt-level=3, lto="fat", codegen-units=1, panic="abort", strip=true
L6: Code Quality	20/20	1695 lib tests + 13 analytic-solution oracles + 105 engineering oracles (5 thermal/fatigue + 34 solid + 39 fluid + 27 misc) + 13 default-config oracles + 53 alice-bamboo integration tests + 8 fuzz targets + 44 determinism tests (6-platform bit-exact, Fix128 + f32 golden), clippy -D warnings (default + full native feature set, all targets), MSRV 1.85 CI job (default / no_std / native), #![deny(missing_docs)], cargo-semver-checks hard-gated
Total	100/100

L1: Memory Layout (15/15)

All hot data structures use 64-byte cache-line alignment with hot/cold field separation:

#[repr(C, align(64))]
pub struct RigidBody {
    // HOT fields (accessed every substep) — first cache line
    pub position: Vec3Fix,
    pub velocity: Vec3Fix,
    pub inv_mass: Fix128,
    pub inv_inertia: Vec3Fix,
    pub prev_position: Vec3Fix,
    // COLD fields (accessed occasionally)
    pub rotation: QuatFix,
    pub angular_velocity: Vec3Fix,
    pub restitution: Fix128,
    pub friction: Fix128,
    // ...
}

• RigidBody (solver.rs): #[repr(C, align(64))] + hot/cold field reorder
• Cloth (cloth.rs): #[repr(C, align(64))] + precomputed inv_rest_length per edge constraint
• Fluid (fluid.rs): #[repr(C, align(64))] + precomputed inv_rest_density and grid_half

L2: Execution Model (20/20)

Aggressive inlining and branchless execution across all hot paths:

• GJK/BVH: All support functions and traversal marked #[inline(always)] (35 annotations total)
• Constraint solving: #[inline(always)] on distance/contact constraint kernels
• Fluid spatial grid: grid_half precomputed at construction, eliminates repeated division in hash() hot path
• Branchless primitives (math.rs): select_fix128(), select_vec3() — CMOV-equivalent using bitwise masks, zero pipeline flushes

L3: Compute Strategy (20/20)

Division elimination and warm-starting for faster convergence:

• Distance constraint warm-start: cached_lambda field stores the Lagrange multiplier from the previous substep, biasing the initial guess for dramatically faster convergence
• Cloth reciprocal precomputation: inv_rest_length computed once at construction, constraint solving uses multiplication instead of division
• Fluid reciprocal precomputation: inv_rest_density eliminates 2+ divisions per particle per iteration in incompressibility constraint
• Contact manifold warm-start: Per-contact lambda_n, lambda_t1, lambda_t2 accumulated across frames via apply_warm_start()
• Contact modifier parallel pre-pass: pre_process_contacts() runs sequentially before Rayon parallel dispatch, applying pre-solve hooks and contact modifiers safely without data races

L4: GPU & Throughput (15/15)

SIMD-width-aware batching for optimal GPU and CPU utilization:

// Compile-time CPU feature detection
pub const SIMD_WIDTH: usize = simd_width();
// AVX2=8, SSE=4, NEON=4, scalar=1

#[inline(always)]
pub fn batch_size() -> usize { crate::math::SIMD_WIDTH }

• SIMD_WIDTH constant (math.rs): Compile-time CPU feature detection (AVX2=8, SSE=4, NEON=4, scalar=1)
• GpuSdfInstancedBatch (gpu_sdf.rs): Groups SDF queries by ID to minimize GPU kernel launches
• GpuSdfMultiDispatch (gpu_sdf.rs): Manages multiple GPU batches with total_queries() and total_dispatches() statistics
• batch_size() (gpu_sdf.rs): Returns SIMD_WIDTH for register-width-aligned data streams

L5: Build Profile (10/10)

[profile.release]
opt-level = 3          # Maximum optimization
lto = "fat"            # Link-time optimization (all crates unified)
codegen-units = 1      # Single code generation unit (maximum optimization)
panic = "abort"        # No unwinding tables
strip = true           # Strip symbols

L6: Code Quality (20/20)

• 1695 lib tests + 44 determinism tests across the alice-physics crate (Iter 2-6 audit + v1.0 stable release additions + v1.0.1 coloring / island / Fix128 tests + 1.2.0 mutation-score batches 1-8 and analytic oracles)
• 53 alice-bamboo integration tests (end-to-end 3D-print safety scenarios)
• 9 fuzz targets (fuzz_step, fuzz_collision, fuzz_deterministic_roundtrip, fuzz_joint, fuzz_cfd, fuzz_ccd, fuzz_trimesh, fuzz_structural, fuzz_step_parity)
• Total: 2001 passing tests in cargo test (default features: 1695 lib + 44 determinism (9 Fix128 golden + 13 f32 golden + 22 semantic) + 220 integration / oracle (72 + 13 analytic + 105 engineering + 13 default-config + 3 parallel + 14 other) + 21 doctests + 3 ignored; 1728 lib tests with the full native feature set), clippy: 0 warnings under -D warnings (default + std,simd,parallel,ffi,gpu-solver-bridge,neural,replay,analytics, --all-targets), #![deny(missing_docs)] (0 warnings)

---

Additional Optimizations

Stackless BVH Traversal

Traditional BVH traversal uses a stack to track nodes to visit. Our implementation uses escape pointers embedded in each node:

┌──────────────────────────────────────────────────────┐
│  BvhNode Layout (32 bytes, cache-aligned)            │
├──────────────────────────────────────────────────────┤
│  aabb_min[3]        (12 bytes)  - Bounding box min   │
│  first_child/prim   (4 bytes)   - Child or prim idx  │
│  aabb_max[3]        (12 bytes)  - Bounding box max   │
│  prim_count_escape  (4 bytes)   - [count:8|escape:24]│
└──────────────────────────────────────────────────────┘

Traversal: single index variable, no stack allocation
  if (hit)  → descend to first_child
  if (miss) → jump to escape_idx (skip entire subtree)

Benefits:

• Zero heap allocation during queries
• Single register for traversal state
• Better branch prediction
• i32 AABB comparison (no Fix128 reconstruction)

SIMD Acceleration (optional)

Enable with --features simd:

// x86_64 with SSE2
impl Fix128 {
    pub unsafe fn add_simd(self, rhs: Self) -> Self;
    pub unsafe fn sub_simd(self, rhs: Self) -> Self;
}

impl Vec3Fix {
    pub fn dot_simd(self, rhs: Self) -> Fix128;
    pub fn cross_simd(self, rhs: Self) -> Self;
    pub fn dot_batch_4(a: [Self; 4], b: [Self; 4]) -> [Fix128; 4];
}

Constraint Batching (optional)

Enable with --features parallel:

Constraints are grouped by graph coloring - constraints with no shared bodies are placed in the same "color" and can be solved independently:

// Rebuild constraint batches (greedy graph coloring)
world.rebuild_batches();

// Step with batched constraint solving
world.step_parallel(dt);

// Check number of color batches
println!("Batches: {}", world.num_batches());

Benefits:

• Zero heap allocation in constraint loop (index-based iteration)
• Rayon-ready parallel solving
• Reduced lock contention
• Better cache utilization

HashMap Contact Cache

Contact manifold lookup via BodyPairKey → usize HashMap for O(1) access:

// O(1) manifold lookup (was O(n) linear scan)
pub fn find(&self, a: usize, b: usize) -> Option<&ContactManifold> {
    let key = BodyPairKey::new(a, b);
    self.pair_index.get(&key).map(|&i| &self.manifolds[i])
}

Falls back to linear scan for no_std environments.

Rayon Parallel Integration

Enable with --features parallel:

Position integration and velocity updates run in parallel via par_iter_mut():

// Parallel position integration (gravity + damping + Euler)
bodies.par_iter_mut().for_each(|body| {
    body.velocity = body.velocity + gravity * dt;
    body.velocity = body.velocity * damping;
    body.position = body.position + body.velocity * dt;
});

Python Batch APIs

Zero-copy NumPy batch operations with GIL release:

# Batch body creation from (N,4) array [x, y, z, mass]
world.add_bodies_batch(np.array([[0,10,0,1.0], [5,10,0,2.0]]))

# Batch velocity update with GIL release
world.set_velocities_batch(velocities_array)  # (N,3)

# Combined state output as (N,10) array [px,py,pz,vx,vy,vz,qx,qy,qz,qw]
states = world.states()

Why Deterministic Physics?

Traditional physics engines using IEEE 754 floating-point can produce different results across:

• Different CPU architectures (x86 vs ARM)
• Different compilers (GCC vs Clang vs MSVC)
• Different optimization levels (-O0 vs -O3)
• Different instruction sets (SSE vs AVX)

ALICE-Physics guarantees bit-exact results across platforms for every module (see Determinism scope), enabling:

• Lockstep Multiplayer: All clients compute identical simulation
• Rollback Netcode: Replay inputs deterministically
• Replay Systems: Perfect reproduction of game sessions
• Distributed Simulation: Parallel computation with consistent results

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                          ALICE-Physics v1.0.0 stable                         │
│    1695 lib tests + 44 determinism tests (9 golden + 22 semantic), 6 CI     │
├─────────────────────────────────────────────────────────────────────────────┤
│  Core Layer                                                                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │  math    │ │ collider │ │  solver  │ │   bvh    │ │sdf_colldr│          │
│  │ Fix128   │ │ AABB     │ │ RigidBody│ │ Morton   │ │ SdfField │          │
│  │ Vec3Fix  │ │ Sphere   │ │ XPBD     │ │ Stackless│ │ Gradient │          │
│  │ QuatFix  │ │ Capsule  │ │ Sensor   │ │ Zero-    │ │ Early-out│          │
│  │ CORDIC   │ │ GJK/EPA  │ │ Rollback │ │  alloc   │ │          │          │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘          │
│                                                                              │
│  AAA Engine Layer                                                            │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │box_colldr│ │ compound │ │cont_cache│ │dynamic_bv│ │ material │          │
│  │ OBB      │ │ Multi-   │ │ HashMap  │ │ Incr BVH │ │ Pair Tbl │          │
│  │ GJK Supp │ │ Shape    │ │ O(1) Get │ │ AVL Bal  │ │ Combine  │          │
│  │ Inertia  │ │ Local Tx │ │ Warm Str │ │ O(log n) │ │ Friction │          │
│  │ Corners  │ │ AABB Mrg │ │ 4-point  │ │ Fat AABB │ │ Restit   │          │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘          │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐                                    │
│  │dbg_rendr │ │profiling │ │ interp   │                                    │
│  │ Wireframe│ │ Timers   │ │ Snapshot │                                    │
│  │ Contacts │ │ Per-Stage│ │ NLERP    │                                    │
│  │ Joints   │ │ Stats    │ │ Blend    │                                    │
│  │ BVH/AABB │ │ History  │ │ Alpha    │                                    │
│  └──────────┘ └──────────┘ └──────────┘                                    │
│                                                                              │
│  Collision Shapes (v0.5.0)                                                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │  cone    │ │ellipsoid │ │  torus   │ │plane_col │ │  wedge   │          │
│  │ Apex/Base│ │ 3-Axis   │ │ Maj/Min  │ │ Hessian  │ │ TriPrism │          │
│  │ GJK Supp│ │ Aniso    │ │ Minkowsk │ │ Sph/AABB │ │ 6-Vertex │          │
│  │ Inertia  │ │ Support  │ │ Support  │ │ Intersct │ │ GJK Supp│          │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘          │
│  ┌──────────┐                                                               │
│  │cvx_mesh  │                                                               │
│  │ Incr Hull│                                                               │
│  │ Tetra    │                                                               │
│  │ Horizon  │                                                               │
│  └──────────┘                                                               │
│                                                                              │
│  Constraint & Dynamics Layer                                                 │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │  joint   │ │joint_extr│ │  motor   │ │articulatn│ │  force   │          │
│  │ Ball     │ │ Pulley   │ │ PD 1D/3D │ │ Ragdoll  │ │ Wind     │          │
│  │ Hinge    │ │ Gear     │ │ Position │ │ FK Chain │ │ Gravity  │          │
│  │ Fixed    │ │ Weld     │ │ Velocity │ │ Robotic  │ │ Buoyancy │          │
│  │ Slider   │ │ Rack&Pin │ │ Max Torq │ │ Feather- │ │ Drag     │          │
│  │ Spring   │ │ Mouse    │ │          │ │  stone   │ │ Vortex   │          │
│  │ D6       │ │ Breakabl │ │          │ │ 12-body  │ │ Explosion│          │
│  │ ConeTwst │ │          │ │          │ │          │ │ Magnetic │          │
│  │ Breakable│ │          │ │          │ │          │ │          │          │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘          │
│  ┌──────────┐                                                               │
│  │ sleeping │                                                               │
│  │ Islands  │                                                               │
│  │ Union-   │                                                               │
│  │  Find    │                                                               │
│  └──────────┘                                                               │
│                                                                              │
│  Query & Collision Layer                                                     │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │ raycast  │ │   ccd    │ │ trimesh  │ │heightfld │ │  filter  │          │
│  │ Sphere   │ │ TOI      │ │ Triangle │ │ Bilinear │ │ Layer    │          │
│  │ AABB     │ │ Conserv. │ │ BVH-accel│ │ Normal   │ │ Mask     │          │
│  │ Capsule  │ │ Advance  │ │ Moller-  │ │ Sphere   │ │ Group    │          │
│  │ Plane    │ │ Swept    │ │ Trumbore │ │ Collide  │ │ Bidirect │          │
│  │ Sweep    │ │ Specultv │ │ Closest  │ │ Signed   │ │          │          │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘          │
│  ┌──────────┐ ┌──────────┐                                                  │
│  │  query   │ │character │                                                  │
│  │ SphCast  │ │ Move&Sld │                                                  │
│  │ CapCast  │ │ Stair    │                                                  │
│  │ Overlap  │ │ Ground   │                                                  │
│  │ AABB Ovr │ │ SDF Terr │                                                  │
│  └──────────┘ └──────────┘                                                  │
│                                                                              │
│  Soft Body & Simulation Layer                                                │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │  rope    │ │  cloth   │ │  fluid   │ │deformable│ │ vehicle  │          │
│  │ XPBD     │ │ XPBD     │ │ PBF      │ │ FEM-XPBD │ │ Wheel    │          │
│  │ Distance │ │ Triangle │ │ SPH Hash │ │ Tetrahedr│ │ Suspensn │          │
│  │ Chain    │ │ Self-Col │ │ Density  │ │ Volume   │ │ Engine   │          │
│  │ Cable    │ │ SpatHash │ │ Viscosty │ │ Neo-Hook │ │ Steering │          │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘          │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐                       │
│  │clth_flud │ │rope_atth │ │soft_cut  │ │ particle │                       │
│  │ Drag     │ │ RigidBdy │ │ Plane    │ │ Emitters │                       │
│  │ Buoyancy │ │ Complnce │ │ Deform   │ │ Lifetime │                       │
│  │ Boundary │ │ Break    │ │ Cloth    │ │ ForceInt │                       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘                       │
│                                                                              │
│  SDF Advanced Layer                                                          │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │sdf_mnfld │ │ sdf_ccd  │ │sdf_force │ │sdf_destr │ │sdf_adapt │          │
│  │ Manifold │ │ SphTrace │ │ Attract  │ │ CSG Bool │ │ LOD      │          │
│  │ N-point  │ │ March    │ │ Repel    │ │ Subtract │ │ Distance │          │
│  │ Contact  │ │ TOI      │ │ Contain  │ │ Real-time│ │ Adaptive │          │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘          │
│  ┌──────────┐ ┌──────────┐                                                  │
│  │cvx_decomp│ │ gpu_sdf  │                                                  │
│  │ Voxel    │ │ Compute  │                                                  │
│  │ Flood    │ │ Batch    │                                                  │
│  │ Convex   │ │ Shader   │                                                  │
│  └──────────┘ └──────────┘                                                  │
│                                                                              │
│  SDF Simulation Modifiers Layer                                              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
│  │sim_field │ │sim_modif │ │ thermal  │ │ pressure │ │ erosion  │          │
│  │ Scalar3D │ │ Modifier │ │ Heat Eq  │ │ Crush    │ │ Wind     │          │
│  │ Vector3D │ │ Chain    │ │ Melt     │ │ Bulge    │ │ Water    │          │
│  │ Trilin   │ │ Modified │ │ Freeze   │ │ Dent     │ │ Chemical │          │
│  │ Diffuse  │ │ SDF      │ │ Expand   │ │ Yield    │ │ Ablation │          │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘          │
│  ┌──────────┐ ┌──────────┐                                                  │
│  │ fracture │ │phase_chg │                                                  │
│  │ Stress   │ │ Solid    │                                                  │
│  │ Crack    │ │ Liquid   │                                                  │
│  │ CSG Sub  │ │ Gas      │                                                  │
│  │ Voronoi  │ │ Latent H │                                                  │
│  └──────────┘ └──────────┘                                                  │
│                                                                              │
│  2D Physics Subsystem (v0.5.0)                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ physics2d                                                           │    │
│  │ Vec2Fix, Shape2D (Circle/Polygon/Capsule/Edge), RigidBody2D         │    │
│  │ SAT + Voronoi collision, XPBD 2D solver, Joint2D (Rev/Dist/Weld/M) │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                                                              │
│  Mesh & I/O Utilities (v0.5.0)                                              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐                       │
│  │mass_prop │ │col_mesh  │ │ scene_io │ │multi_wrld│                       │
│  │ Sphere   │ │ Marching │ │ Binary   │ │ N worlds │                       │
│  │ Box      │ │ Cubes    │ │ APHYS    │ │ Transfer │                       │
│  │ Cylinder │ │ EdgeClps │ │ JSON     │ │ Isolate  │                       │
│  │ PAxis    │ │ Simplify │ │ Fix128   │ │ Step All │                       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘                       │
│                                                                              │
│  Visualization (v0.5.0)                                                     │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐                                    │
│  │ heatmap  │ │ flow_viz │ │contct_viz│                                    │
│  │ Stress   │ │ Arrows   │ │ Force    │                                    │
│  │ Temp     │ │ Streamln │ │ Friction │                                    │
│  │ Viridis  │ │ Velocity │ │ Cone     │                                    │
│  └──────────┘ └──────────┘ └──────────┘                                    │
│                                                                              │
│  Game Systems Layer                                                          │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐                                    │
│  │anim_blnd │ │audio_phys│ │ netcode  │                                    │
│  │ SLERP    │ │ Impact   │ │ FrameInp │                                    │
│  │ Ragdoll  │ │ Friction │ │ Checksum │                                    │
│  │ Blend    │ │ Rolling  │ │ Snapshot │                                    │
│  │ IK Mix   │ │ Material │ │ Rollback │                                    │
│  └──────────┘ └──────────┘ └──────────┘                                    │
│                                                                              │
│  Analytics & Privacy Layer                                                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐                       │
│  │  sketch  │ │ anomaly  │ │ privacy  │ │ pipeline │                       │
│  │ HyperLog │ │ MAD      │ │ Laplace  │ │ MetricPi │                       │
│  │ DDSketch │ │ EWMA     │ │ RAPPOR   │ │ RingBuf  │                       │
│  │ CountMin │ │ Z-score  │ │ RandResp │ │ Registry │                       │
│  │ HeavyHit │ │ Composit │ │ XorShift │ │ Snapshot │                       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘                       │
│                                                                              │
│  Utility Layer                                                               │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────────────────────────┐│
│  │   rng    │ │  event   │ │fluid_net │ │      neural (ALICE-ML × Phys)   ││
│  │ PCG-XSH  │ │ Begin    │ │ Delta    │ │ Ternary {-1,0,+1} → Fix128     ││
│  │ Fix128   │ │ Persist  │ │ Compress │ │ Deterministic AI                ││
│  │ Direction│ │ End      │ │ Snapshot │ │ Ragdoll Controller              ││
│  └──────────┘ └──────────┘ └──────────┘ └─────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────┘

Usage

Choose Your Path

Pick the entry point that matches your role. All paths share the same deterministic PhysicsWorld, so you can start simple and layer in advanced features (rollback / GPU offload / joints) later without rewriting.

You are…	Path	Best for	Section
First time here	Hello, first physics ↓	Sanity-check the install with a falling sphere	↓
Simulation dev, want the basics	Basic Simulation	Rigid bodies, gravity, ground, per-frame stepping	↓
Netcode / lockstep game dev	Rollback Netcode	Snapshot save/load, deterministic replay, Fix128 bit-exact	↓
Rope / cloth / constraint dev	Distance Constraint + joint module	Chains, ropes, ragdolls, breakable constraints	↓
Perf-sensitive (many bodies)	BVH Broad-Phase	Spatial acceleration, zero-alloc queries, Morton codes	↓
GPU offload (advanced)	GPU Solver Bridge	PGS iteration on GPU via ALICE-TRT, byte-exact vs CPU	↑
Unity / UE5 / Godot integrator	C-ABI FFI	Fix128 hi/lo pairs across the C ABI, bit-pattern equality	see alice_physics_ffi::*
CCD / raycast / trimesh user	Module-specific	ccd / raycast / trimesh modules with dedicated APIs	see Modules

Hello, First Physics (30 seconds)

The smallest working sample — one falling sphere onto static ground, step it, print the y-coord:

use alice_physics::prelude::*;

let mut world = PhysicsWorld::new(PhysicsConfig::default());

let sphere = RigidBody::new_dynamic(Vec3Fix::from_int(0, 10, 0), Fix128::ONE);
let _sphere_id = world.add_body(sphere);
world.add_body(RigidBody::new_static(Vec3Fix::ZERO));   // ground plane at y=0

let dt = Fix128::from_ratio(1, 60);
for frame in 0..60 {
    world.step(dt);
    println!("frame {frame}: y = {}", world.bodies[0].position.y.hi);
}

Once this runs, jump to the path that matches your role.

Basic Simulation

use alice_physics::prelude::*;

fn main() {
    // Create physics world with default config
    let config = PhysicsConfig::default();
    let mut world = PhysicsWorld::new(config);

    // Add a dynamic body (falling sphere)
    let sphere = RigidBody::new_dynamic(
        Vec3Fix::from_int(0, 100, 0),  // position: (0, 100, 0)
        Fix128::ONE,                    // mass: 1.0
    );
    let sphere_id = world.add_body(sphere);

    // Add static ground
    let ground = RigidBody::new_static(Vec3Fix::ZERO);
    world.add_body(ground);

    // Simulate at 60 FPS
    let dt = Fix128::from_ratio(1, 60);  // 1/60 second

    for frame in 0..300 {  // 5 seconds
        world.step(dt);

        let pos = world.bodies[sphere_id].position;
        println!("Frame {}: y = {}", frame, pos.y.hi);
    }
}

Distance Constraint (Rope/Chain)

use alice_physics::prelude::*;

fn create_rope(world: &mut PhysicsWorld, segments: usize) {
    let mut prev_id = None;

    for i in 0..segments {
        let body = RigidBody::new_dynamic(
            Vec3Fix::from_int(i as i64 * 2, 50, 0),
            Fix128::ONE,
        );
        let id = world.add_body(body);

        if let Some(prev) = prev_id {
            let constraint = DistanceConstraint {
                body_a: prev,
                body_b: id,
                local_anchor_a: Vec3Fix::ZERO,
                local_anchor_b: Vec3Fix::ZERO,
                target_distance: Fix128::from_int(2),
                compliance: Fix128::from_ratio(1, 1000),  // Soft constraint
            };
            world.add_distance_constraint(constraint);
        }

        prev_id = Some(id);
    }

    // Fix first segment in place
    world.bodies[0].inv_mass = Fix128::ZERO;
}

Rollback Netcode

use alice_physics::prelude::*;

struct GameState {
    physics: PhysicsWorld,
    frame: u64,
    input_buffer: Vec<PlayerInput>,
}

impl GameState {
    fn save_snapshot(&self) -> Vec<u8> {
        self.physics.serialize_state()
    }

    fn load_snapshot(&mut self, data: &[u8]) {
        self.physics.deserialize_state(data);
    }

    fn rollback_and_resimulate(&mut self, to_frame: u64, new_input: PlayerInput) {
        // Load snapshot from frame
        let snapshot = self.get_snapshot(to_frame);
        self.load_snapshot(&snapshot);

        // Replay with corrected input
        self.input_buffer[to_frame as usize] = new_input;

        for frame in to_frame..self.frame {
            let input = &self.input_buffer[frame as usize];
            self.apply_input(input);
            self.physics.step(Fix128::from_ratio(1, 60));
        }
    }
}

BVH Broad-Phase Collision

use alice_physics::bvh::{LinearBvh, BvhPrimitive};

// Build BVH from primitives
let primitives: Vec<BvhPrimitive> = bodies.iter().enumerate()
    .map(|(i, body)| BvhPrimitive {
        aabb: body.compute_aabb(),
        index: i as u32,
        morton: 0,  // Computed during build
    })
    .collect();

let bvh = LinearBvh::build(primitives);

// Query with zero heap allocation (callback version)
bvh.query_callback(&query_aabb, |prim_idx| {
    // Handle potential collision with primitive
});

// Or collect results
let hits = bvh.query(&query_aabb);

// Get BVH statistics
let stats = bvh.stats();
println!("Nodes: {}, Leaves: {}", stats.node_count, stats.leaf_count);

Common Recipes

Additional patterns that come up frequently — copy-paste starting points.

1. Raycast against the world

use alice_physics::prelude::*;

let ray = Ray {
    origin:    Vec3Fix::from_int(0, 5, 0),
    direction: Vec3Fix::from_int(0, -1, 0),   // straight down
    max_distance: Fix128::from_int(100),
};
if let Some(hit) = world.raycast(&ray) {
    println!("hit body {} at distance {}", hit.body_id, hit.distance.hi);
}

2. Put idle bodies to sleep (perf win)

// PhysicsConfig has sleeping enabled by default; tune the thresholds when needed.
let mut config = PhysicsConfig::default();
config.sleeping.linear_threshold  = Fix128::from_ratio(1, 100);   // 0.01 m/s
config.sleeping.angular_threshold = Fix128::from_ratio(1, 100);
config.sleeping.time_to_sleep     = Fix128::from_ratio(1, 2);     // 0.5 s
let mut world = PhysicsWorld::new(config);

3. Breakable constraint (rope snap under load)

let constraint = DistanceConstraint {
    body_a: a,
    body_b: b,
    local_anchor_a: Vec3Fix::ZERO,
    local_anchor_b: Vec3Fix::ZERO,
    target_distance: Fix128::from_int(2),
    compliance:      Fix128::from_ratio(1, 1000),
};
let id = world.add_distance_constraint(constraint);
world.set_constraint_break_force(id, Fix128::from_int(500));   // snaps > 500 N

4. Static-ground quick setup

let ground = RigidBody::new_static(Vec3Fix::ZERO);
let ground_id = world.add_body(ground);
world.set_collider(ground_id, Collider::plane(Vec3Fix::from_int(0, 1, 0), Fix128::ZERO));

5. Save + reload a snapshot (rollback primitive)

let snapshot: Vec<u8> = world.serialize_state();     // byte-exact across arch
// ... later, or on another machine:
world.deserialize_state(&snapshot);                  // resumes at frame boundary

6. Continuous collision (fast-moving projectile)

use alice_physics::ccd;

let bullet = RigidBody::new_dynamic(Vec3Fix::from_int(0, 0, 0), Fix128::ONE);
let bullet_id = world.add_body(bullet);
world.enable_ccd(bullet_id);   // subswept collision, avoids tunneling

Session 3 Solver Loops (v0.12)

CFD gravity settling — solve incompressible Navier-Stokes for one time step with pressure projection:

use alice_physics::cfd_solver::CfdSolver;
use alice_physics::math::Fix128;

let mut solver = CfdSolver::new(12, 12, 12, Fix128::from_ratio(1, 10));
solver.jacobi_iterations = 100;

// Water in gravity, closed box → settles, divergence ≈ 0
for _ in 0..30 {
    solver.step(Fix128::from_ratio(1, 1000));  // 0.001 s per step
}
// solver.grid.v[…] centre column will read −0.294 m/s at t = 0.03 s
// matching −g·t exactly (bit-exact recovery of the free-fall analytical solution)

Structural creep + fatigue history — advance a PLA shelf through 20 h of sustained load at 55 °C and print the diagnostic table:

use alice_physics::beam_stress::{CrossSection, LoadCase};
use alice_physics::filament_db::MaterialProperties;
use alice_physics::math::Fix128;
use alice_physics::structural_solver::StructuralSolver;

let section = CrossSection::Rectangular {
    width_mm: Fix128::from_int(150),
    height_mm: Fix128::from_int(10),
};
let load = LoadCase::SimplySupportedCenter {
    load_n: Fix128::from_int(20),
    length_mm: Fix128::from_int(300),
};
let mut solver = StructuralSolver::new(section, load, MaterialProperties::pla());
solver.operating_temp_c = Fix128::from_int(55);
solver.dt_s = Fix128::from_int(3600);   // 1-hour steps

let history = solver.run(20);
println!(
    "creep {:.5}, fatigue D = {:.4}, failure step = {:?}",
    history.plastic_state.creep_strain.to_f32(),
    history.fatigue_damage.to_f32(),
    history.failure_step,
);

Print pipeline safety — run 10 print-safety checks in one call:

use alice_physics::beam_stress::{CrossSection, LoadCase};
use alice_physics::math::Fix128;
use alice_physics::print_orientation::LoadDirection;
use alice_physics::print_pipeline_solver::{analyze_print_pipeline, PrintPipelineInputs};
use alice_physics::support_volume::OverhangRegion;
use alice_physics::warp_risk::Footprint;

let footprint = Footprint {
    area_mm2: Fix128::from_int(300 * 300),
    max_dimension_mm: Fix128::from_int(300),
};
let inputs = PrintPipelineInputs {
    beam_load: Some((
        CrossSection::Rectangular {
            width_mm: Fix128::from_int(50),
            height_mm: Fix128::from_int(5),
        },
        LoadCase::CantileverEndPoint {
            load_n: Fix128::from_int(30),
            length_mm: Fix128::from_int(300),
        },
    )),
    load_direction: Some(LoadDirection::axis_z()),
    overhangs: vec![OverhangRegion {
        projected_area_mm2: Fix128::from_int(50 * 50),
        support_height_mm: Fix128::from_int(15),
    }],
    fillet: Some((Fix128::from_ratio(3, 10), Fix128::from_int(20), Fix128::from_int(40))),
    ..Default::default()
};

let report = analyze_print_pipeline(footprint, "PLA", &inputs);
report.print();
// Prints warp / strength envelope / thermal / beam FoS / bridging /
// support volume / K_t / bimaterial and an overall SAFE / UNSAFE verdict.

Where to go next

I want to…	See
Understand the full type surface	Modules section below
Deep dive into determinism guarantees	Why Deterministic Physics?
Offload PGS iterations to the GPU	Companion crate — ALICE-TRT
Wire into Unity / UE5 native plugin	alice_physics_ffi::* (module in this crate)
See the joint catalog (12 base + 5 advanced)	joint / joint_extra sections
Prove byte-exact CI on 3 platforms	See ALICE-TRT's Fix128 + physics-solver test matrix (companion release)
Compare to Rapier / PhysX / Box2D	Why Deterministic Physics? benchmark table

Companion crates that plug directly into PhysicsWorld:

• ALICE-TRT (gpu-solver-bridge feature) — GPU PGS solver offload with byte-exact CPU parity
• ALICE-Cloth — XPBD cloth on top of the same Fix128 primitives
• ALICE-Vehicle — Deterministic vehicle rig
• ALICE-Netcode — Rollback netcode plumbing built for serialize_state / deserialize_state

Modules

math - Fixed-Point Primitives

Type	Description
Fix128	128-bit fixed-point number (I64F64)
Vec3Fix	3D vector with Fix128 components
QuatFix	Quaternion for rotations
Mat3Fix	3x3 matrix for inertia tensors

Constants:

• Fix128::ZERO, Fix128::ONE, Fix128::NEG_ONE
• Fix128::PI, Fix128::HALF_PI, Fix128::TWO_PI

CORDIC functions (deterministic, no FPU):

• Fix128::sin(), Fix128::cos(), Fix128::sin_cos()
• Fix128::atan(), Fix128::atan2()
• Fix128::sqrt() (Newton-Raphson, 64 iterations)

Utility:

• Fix128::from_ratio(num, denom) - Create from fraction
• Fix128::half(), Fix128::double() - Exact bit shifts
• Fix128::abs(), Fix128::floor(), Fix128::ceil()

collider - Collision Detection

Shape	Description
AABB	Axis-Aligned Bounding Box
Sphere	Sphere collider
Capsule	Capsule (cylinder + hemispheres)
ConvexHull	Arbitrary convex polyhedron
CollisionResult	Contact information

Algorithms:

• GJK: Gilbert-Johnson-Keerthi for intersection test (64 iterations max)
• EPA: Expanding Polytope Algorithm for penetration depth (64 iterations max)

solver - XPBD Physics

RigidBody fields:

Field	Type	Description
position	Vec3Fix	Center of mass position
rotation	QuatFix	Orientation quaternion
velocity	Vec3Fix	Linear velocity
angular_velocity	Vec3Fix	Angular velocity
inv_mass	Fix128	Inverse mass (0 = static)
inv_inertia	Vec3Fix	Inverse inertia tensor (diagonal)
restitution	Fix128	Bounciness (0-1)
friction	Fix128	Friction coefficient
is_sensor	bool	Sensor mode: detects overlap but no physics response

Constraints:

• DistanceConstraint: Fixed distance between anchor points
• ContactConstraint: Collision response with friction/restitution

Methods:

• RigidBody::new(position, mass) - Create dynamic body
• RigidBody::new_dynamic(position, mass) - Alias for new
• RigidBody::new_static(position) - Create immovable body
• RigidBody::new_sensor(position) - Create sensor/trigger body (no physics response)

bvh - Spatial Acceleration

Type	Description
LinearBvh	Flat array BVH with stackless traversal
BvhNode	32-byte cache-aligned node with escape pointer
BvhPrimitive	Primitive entry for construction
BvhStats	Tree statistics

Features:

• Morton Codes: Z-order curve for spatial locality
• Escape Pointers: Stackless traversal (zero allocation)
• i32 AABB: Fast integer comparison without Fix128 reconstruction

joint - 12 Joint Types + Breakable Constraints

Type	Description
BallJoint	Spherical joint (3 rotational DOF)
HingeJoint	Revolute joint (1 rotational DOF) with angle limits
FixedJoint	Weld joint (0 DOF)
SliderJoint	Prismatic joint (1 translational DOF) with limits
SpringJoint	Damped spring constraint
D6Joint	6-DOF configurable joint with per-axis lock/free/limit
ConeTwistJoint	Ball joint with cone swing limit and twist limit

joint_extra - 5 Advanced Joints (v0.5.0)

Type	Description
PulleyJoint	Pulley with 2 anchors and rope ratio (total distance constraint)
GearJoint	Gear coupling (angular velocity ratio between two bodies)
WeldJoint	Rigid weld with break_force / break_torque threshold
RackAndPinionJoint	Rotation-to-translation conversion with pitch radius
MouseJoint	Target-following joint for mouse/touch drag interaction

All joint types support breakable constraints via with_break_force(max_force). When the constraint force exceeds the threshold, the joint breaks and is removed from simulation.

use alice_physics::joint::*;
// Hinge with angle limits
let hinge = HingeJoint::new(body_a, body_b, anchor_a, anchor_b, axis_a, axis_b)
    .with_limits(-Fix128::HALF_PI, Fix128::HALF_PI);

// D6 joint (lock X translation, free Y rotation, limit Z rotation)
let d6 = D6Joint::new(body_a, body_b, anchor_a, anchor_b)
    .with_axis(Axis::LinearX, D6Mode::Locked)
    .with_axis(Axis::AngularY, D6Mode::Free)
    .with_axis(Axis::AngularZ, D6Mode::Limited(-Fix128::HALF_PI, Fix128::HALF_PI));

// Cone-twist joint (shoulder-like with cone + twist limits)
let cone = ConeTwistJoint::new(body_a, body_b, anchor_a, anchor_b, twist_axis)
    .with_cone_limit(Fix128::from_ratio(45, 1))  // 45° cone
    .with_twist_limit(Fix128::from_ratio(30, 1)); // 30° twist

// Breakable ball joint (breaks at force > 100)
let ball = BallJoint::new(body_a, body_b, anchor_a, anchor_b)
    .with_break_force(Fix128::from_int(100));

// Solve with breakable support — returns indices of broken joints
let broken = solve_joints_breakable(&joints, &mut bodies, dt);

raycast - Ray & Shape Casting

Function	Description
ray_sphere	Ray vs sphere intersection
ray_aabb	Ray vs AABB (slab method)
ray_capsule	Ray vs capsule
ray_plane	Ray vs infinite plane
sweep_sphere	Moving sphere vs sphere (Minkowski expansion)

ccd - Continuous Collision Detection

Function	Description
sphere_sphere_toi	Sphere-sphere TOI via quadratic
sphere_plane_toi	Sphere-plane TOI
conservative_advancement	TOI via iterative safe stepping
swept_aabb	Swept AABB bounding volume
speculative_contact	Speculative contact for CCD integration with solver
needs_ccd	Velocity threshold check for CCD activation

sleeping - Sleep & Island System

Type	Description
IslandManager	Union-Find island management
SleepData	Per-body sleep tracking
SleepConfig	Velocity thresholds, idle frame count

trimesh - Triangle Mesh Collision

Type	Description
Triangle	Single triangle with Moller-Trumbore intersection
TriMesh	BVH-accelerated triangle mesh

Features:

• Ray-triangle intersection (Moller-Trumbore)
• Closest point on triangle
• Sphere-mesh collision detection

heightfield - Height Field Terrain

Type	Description
HeightField	Grid-based terrain with bilinear interpolation

Features:

• sample_height(world_x, world_z) with bilinear interpolation
• sample_normal(world_x, world_z) from central differences
• collide_sphere() for sphere-terrain collision
• signed_distance(point) for point-terrain distance

filter - Collision Filtering

Type	Description
CollisionFilter	Layer/mask bitmask with collision groups
layers module	Predefined layers (DEFAULT, STATIC, PLAYER, ENEMY, etc.)

force - 7 Force Fields

Variant	Description
Directional	Uniform wind/gravity (direction + strength)
Point	Radial gravity well with inverse-square falloff
Drag	Velocity-proportional drag
Buoyancy	Plane-based buoyancy with density
Vortex	Spinning vortex field (center + axis + strength)
Explosion	Radial impulse with configurable falloff_power attenuation
Magnetic	Simplified dipole model with 1/r^3 inverse cube law

motor - PD Controllers

Type	Description
PdController	1D proportional-derivative controller
PdController3D	3D PD controller
JointMotor	Joint motor with position/velocity/torque modes

articulation - Articulated Bodies

Type	Description
ArticulatedBody	Multi-joint chain with FK propagation
Link	Joint + body pair in a chain

Presets:

• build_ragdoll() — 12-body humanoid (head, torso, arms, legs)

rng - Deterministic Random

Type	Description
DeterministicRng	PCG-XSH-RR 32-bit generator

Methods:

• next_fix128() — Random Fix128 in [0, 1)
• range_fix128(min, max) — Random in [min, max)
• next_direction() — Random unit Vec3Fix

event - Contact Events

Type	Description
EventCollector	Tracks contact begin/persist/end per pair
ContactEvent	Body pair + event type + contact point
ContactEventType	Begin, Persist, End

query - Shape Cast & Overlap Queries

Function	Description
sphere_cast	Sweep a sphere along a direction (Minkowski sum approach)
capsule_cast	Sweep a capsule along a direction (3-point sphere cast)
overlap_sphere	Find all bodies overlapping a sphere
overlap_aabb	Find all bodies within an AABB (point test)
overlap_aabb_expanded	Find all bodies within an AABB expanded by body radius

character - Character Controller

Type	Description
CharacterController	Kinematic capsule-based character with move-and-slide
CharacterConfig	Radius, height, max slope, step height, skin width
MoveResult	Movement result with ground state

Features:

• Collide-and-slide algorithm with configurable max slides
• Ground detection via downward raycast + SDF
• Stair stepping (automatic step-up for small obstacles)
• SDF terrain integration (push out of SDF surfaces)

rope - XPBD Rope & Cable

Type	Description
Rope	XPBD distance-chain rope simulation
RopeConfig	Segment count, length, stiffness, damping

cloth - XPBD Cloth Simulation

Type	Description
Cloth	XPBD triangle mesh cloth with stretch/shear/bend constraints
ClothConfig	Stiffness, damping, self-collision, gravity

Features:

• Distance constraints (stretch resistance)
• Bending constraints
• Self-collision via spatial hash grid

fluid - Position-Based Fluids

Type	Description
Fluid	Position-Based Fluids (PBF) simulation
FluidConfig	Particle count, rest density, viscosity, kernel radius

Features:

• SPH density estimation with spatial hash grid
• Incompressibility constraint solving
• Viscosity (XSPH)
• Surface tension

deformable - FEM-XPBD Deformable Bodies

Type	Description
DeformableBody	FEM tetrahedral mesh deformable body
DeformableConfig	Young's modulus, Poisson's ratio, damping

vehicle - Vehicle Physics

Type	Description
Vehicle	Complete vehicle simulation
VehicleConfig	Wheel count, suspension, engine, steering parameters

Features:

• Wheel contact with ground/terrain
• Spring-damper suspension
• Engine torque with gear shifting
• Ackermann steering geometry

cone - Cone Collider (v0.5.0)

Type	Description
Cone	Cone collider with apex at +Y and base at -Y

Features:

• GJK Support trait implementation (apex/base center switching)
• AABB computation, volume, surface area, inertia diagonal
• Configurable radius and half-height with rotation

ellipsoid - Ellipsoid Collider (v0.5.0)

Type	Description
Ellipsoid	Ellipsoid with three independent semi-axes (rx, ry, rz)

Features:

• Anisotropic GJK support (scale direction by radii, normalize, scale back)
• Volume, AABB, and inertia diagonal computation

torus - Torus Collider (v0.5.0)

Type	Description
Torus	Torus with major radius (ring) and minor radius (tube)

Features:

• GJK support via Minkowski sum decomposition
• Volume and AABB computation

plane_collider - Infinite Plane Collider (v0.5.0)

Type	Description
PlaneCollider	Infinite plane in Hessian normal form (normal + offset)

Features:

• intersect_sphere() — sphere-plane intersection with contact point
• intersect_aabb() — AABB-plane overlap test
• signed_distance() — point-plane signed distance

wedge - Wedge Collider (v0.5.0)

Type	Description
Wedge	Triangular prism (wedge) with 6 vertices

Features:

• GJK support (iterates 6 vertices for max dot product)
• Volume, AABB, and centroid computation

convex_mesh_builder - Convex Hull Builder (v0.5.0)

Function	Description
build_convex_hull(points)	Build convex hull from arbitrary point set
compute_centroid(faces, vertices)	Compute centroid of convex hull

Algorithm: Incremental convex hull — find initial tetrahedron, incrementally insert points, remove visible faces, patch with horizon edges.

physics2d - 2D Physics Engine (v0.5.0)

Type	Description
Vec2Fix	2D vector with Fix128 components
Shape2D	Circle, Polygon (max 16 vertices), Capsule, Edge
RigidBody2D	2D rigid body with position, angle, velocity, angular velocity
PhysicsWorld2D	Complete 2D physics world with XPBD solver
PhysicsConfig2D	Gravity, substeps, iterations, sleep threshold
Contact2D	Contact point with normal, depth, body indices
Joint2D	Revolute, Distance, Weld, Mouse joint variants
BodyType2D	Dynamic, Static, Kinematic

Algorithms:

• SAT (Separating Axis Theorem) with Voronoi region classification
• XPBD position-based solver with configurable substeps
• Broad-phase AABB overlap, narrow-phase polygon projection

mass_properties - Mass & Inertia (v0.5.0)

Function	Description
sphere_mass_properties(radius, density)	Sphere mass + inertia tensor
box_mass_properties(half_extents, density)	Box mass + inertia tensor
cylinder_mass_properties(radius, half_h, density)	Cylinder mass + inertia
capsule_mass_properties(radius, half_h, density)	Capsule mass + inertia
convex_hull_mass_properties(vertices, faces, density)	Convex hull mass + inertia
translate_inertia(inertia, mass, offset)	Parallel axis theorem

collision_mesh_gen - SDF to Mesh (v0.5.0)

Type / Function	Description
CollisionMeshConfig	Grid resolution, bounding box, simplification target
CollisionMesh	Vertices + triangle indices output
generate_collision_mesh(sdf, config)	Marching cubes mesh generation
simplify_mesh(mesh, target)	Edge-collapse mesh simplification

scene_io - Scene Serialization (v0.5.0, std)

Function	Description
save_binary(path, scene)	Save to .aphys binary format (bit-exact Fix128)
load_binary(path)	Load from .aphys binary format
save_json(path, scene)	Save to .aphys.json human-readable format
load_json(path)	Load from .aphys.json format

Binary format: Magic APHYS\0, little-endian, raw Fix128 {hi: i64, lo: u64} for bit-exact deterministic roundtrip.

cloth_fluid - Cloth-Fluid Coupling (v0.5.0)

Type	Description
ClothFluidCoupling	Bidirectional cloth-fluid interaction

Effects: Fluid drag force on cloth vertices, buoyancy based on submersion, boundary repulsion to prevent penetration.

rope_attach - Rope Attachment (v0.5.0)

Type	Description
RopeAttachment	Attach rope endpoints to rigid bodies

Features: Configurable compliance, break force threshold, automatic detachment.

soft_body_cut - Soft Body Cutting (v0.5.0)

Function	Description
cut_deformable(body, plane)	Cut deformable body along a plane
cut_cloth(cloth, plane)	Cut cloth mesh along a plane

Algorithm: Plane-based topology splitting — classifies vertices, creates new vertices at intersection points, rebuilds connectivity.

heatmap - Stress/Temperature Heatmap (v0.5.0)

Type	Description
Heatmap	2D scalar field visualization with colormap
HeatmapConfig	Resolution, value range, colormap selection

Features: Viridis colormap, RGBA pixel output, configurable min/max range.

flow_viz - Flow Visualization (v0.5.0)

Type	Description
FlowArrow	Velocity arrow with position, direction, magnitude
Streamline	Ordered list of points tracing a flow path

Functions: generate_flow_arrows(), generate_streamlines() from velocity fields.

contact_viz - Contact Visualization (v0.5.0)

Type	Description
ContactArrow	Force arrow at contact point
FrictionCone	Cone geometry representing friction limit

Functions: visualize_contacts(), visualize_friction_cones() from contact manifolds.

multi_world - Multiple Physics Worlds (v0.5.0)

Type	Description
MultiWorld	Container for N independent physics worlds

Features:

• add_world() / remove_world() — manage independent worlds
• step_all(dt) — advance all worlds simultaneously
• transfer_body(from, to, body_id) — move body between worlds

particle - Particle System (v0.5.0)

Type	Description
ParticleSystem	General-purpose particle simulation
ParticleEmitter	Directional emitter with cone spread
Particle	Position, velocity, age, lifetime, mass

Features:

• Configurable emission rate, spread angle, speed range
• Lifetime management with automatic recycling
• Full ForceField integration (including Explosion and Magnetic)
• Deterministic via DeterministicRng

animation_blend - Animation Blending

Type	Description
AnimationBlender	Ragdoll-to-animation pose blending
BlendMode	Lerp, Slerp, Additive
SkeletonPose	Joint transforms for a skeleton
AnimationClip	Keyframed animation data

audio_physics - Physics-Based Audio

Type	Description
AudioGenerator	Generates audio parameters from physics contacts
AudioConfig	Material properties for audio synthesis
AudioEvent	Impact, friction, rolling audio events
AudioMaterial	Surface material with audio properties

sdf_manifold - SDF Contact Manifold

Multi-point contact generation from SDF surfaces for more stable collision response.

sdf_ccd - SDF Continuous Collision Detection

Sphere tracing-based CCD for bodies moving against SDF surfaces.

sdf_force - SDF Force Fields

Variant	Description
Attract	Pull bodies toward SDF surface
Repel	Push bodies away from SDF surface
Contain	Keep bodies inside SDF boundary
Flow	Flow field following SDF gradient

sdf_destruction - SDF Boolean Destruction

Real-time CSG boolean operations for destructible environments.

Type	Description
DestructibleSdf	SDF that accumulates destruction shapes
DestructionShape	Sphere, box, or custom SDF subtraction

sdf_adaptive - Adaptive SDF Evaluation

Distance-based LOD for SDF evaluation — faraway queries use coarser sampling.

convex_decompose - Convex Decomposition

Generate convex hull decomposition from an SDF voxel grid for use with GJK/EPA.

gpu_sdf - GPU Compute Shader

Batch SDF evaluation on GPU via compute shaders. Requires --features std.

fluid_netcode - Fluid Netcode

Deterministic fluid simulation with delta-compressed snapshots for network sync. Requires --features std.

sim_field - 3D Simulation Fields

Type	Description
ScalarField3D	Uniform grid scalar field with trilinear interpolation
VectorField3D	Uniform grid vector field with trilinear interpolation

Features:

• Trilinear interpolation for smooth sampling
• Diffusion (heat equation solver)
• Decay over time
• Point splatting for localized effects

sim_modifier - SDF Simulation Modifiers

Type	Description
PhysicsModifier	Trait for physics-driven SDF modification
ModifiedSdf	Chain of modifiers that alter SDF distance
SingleModifiedSdf	Single-modifier convenience wrapper

thermal - Thermal Simulation

Type	Description
ThermalModifier	Heat diffusion SDF modifier
ThermalConfig	Conductivity, melt/freeze thresholds
HeatSource	Point/area heat source

Effects: Melt (surface recedes), thermal expansion, freeze (crystalline growth)

pressure - Pressure Simulation

Type	Description
PressureModifier	Contact-force-driven deformation
PressureConfig	Yield threshold, elastic spring-back

Effects: Crush (high pressure), bulge (internal pressure), permanent dents

erosion - Erosion Simulation

Type	Description
ErosionModifier	Surface material removal from forces
ErosionConfig	Hardness, erosion rate
ErosionType	Wind, Water, Chemical, Ablation

fracture - Fracture Simulation

Type	Description
FractureModifier	Stress-driven crack propagation
FractureConfig	Fracture toughness, crack speed
Crack	Individual crack with position and direction

Effects: Stress accumulation, crack seeds, Voronoi-like fragmentation via CSG subtraction

phase_change - Phase Change Simulation

Type	Description
PhaseChangeModifier	Temperature-driven state transitions
PhaseChangeConfig	Melt/boil temperatures, latent heat
Phase	Solid, Liquid, Gas

Effects: Melting (solid→liquid, flows downward), vaporization (liquid→gas, expands), solidification, condensation

box_collider - Oriented Bounding Box

Type	Description
OrientedBox	OBB with center, half-extents, and rotation quaternion

Features:

• GJK Support trait implementation for collision detection
• Fast world-space AABB computation from OBB
• Corner vertices, volume, surface area, inertia tensor

compound - Compound Shape

Type	Description
CompoundShape	Multi-shape collider with local transforms
ChildShape	Individual shape + local offset/rotation

Features:

• Merges child AABBs for broadphase
• Per-child GJK support (transforms direction to child local space)
• Mass properties from children

contact_cache - Persistent Contact Cache

Type	Description
ContactCache	Frame-persistent contact manifold storage
ContactManifold	Up to 4 contact points with warm-started lambdas

Features:

• HashMap O(1) manifold lookup by body pair
• Warm starting (carry lambda across frames for stable stacking)
• Automatic manifold pruning at end of frame

dynamic_bvh - Dynamic AABB Tree

Type	Description
DynamicBvh	Incremental BVH with insert/remove/update

Features:

• O(log n) insert, remove, and update operations
• AVL-style tree balancing (rotation on height imbalance)
• Fat AABBs with margin to reduce update frequency
• AABB query and ray query

material - Material Pair Table

Type	Description
MaterialTable	Per-pair friction/restitution override table
MaterialProperties	Friction, restitution, combine rule
CombineRule	Average, Min, Max, Multiply

debug_render - Debug Visualization

Type	Description
DebugRenderer	Wireframe rendering of physics state
DebugLine	Line segment with color
DebugDrawFlags	Bitmask for bodies, contacts, joints, BVH, forces

profiling - Performance Profiling

Type	Description
PhysicsProfiler	Per-stage timing and statistics
StageTimer	Individual stage measurement
FrameStats	Broadphase/narrowphase/solver/total times

interpolation - Substep Interpolation

Type	Description
WorldSnapshot	Captured physics state for interpolation
interpolate_snapshots	NLERP blending between two snapshots

Features:

• Capture position + rotation snapshots
• NLERP quaternion interpolation (faster than SLERP, visually smooth)
• Alpha-based blending for fixed-timestep rendering

pipeline - Metric Aggregation Pipeline

Type	Description
MetricPipeline	Lock-free ring buffer metric aggregation engine
MetricRegistry	Named metric registration and lookup
MetricSnapshot	Point-in-time metric state capture
MetricEvent	Timestamped metric event with type and value
MetricType	Counter, Gauge, Histogram metric kinds
RingBuffer	Fixed-capacity circular buffer for time-series data

Features:

• Lock-free ring buffer for high-throughput metric collection
• Named metric registry with typed metric support
• Snapshot capture for periodic reporting
• Integrates with sketch module for probabilistic aggregation

sketch - Probabilistic Sketches

Type	Description
HyperLogLog	Cardinality estimation with configurable precision
DDSketch	Distribution-aware quantile sketch (P50/P99/P99.9)
CountMinSketch	Frequency estimation with configurable width/depth
HeavyHitters	Top-k frequent item tracking via Count-Min Sketch
FnvHasher	FNV-1a hash for deterministic, allocation-free hashing
Mergeable	Trait for sketch merging across distributed workers

Size variants:

• HyperLogLog10 (1 KB), HyperLogLog12 (4 KB), HyperLogLog14 (16 KB), HyperLogLog16 (64 KB)
• DDSketch128, DDSketch256, DDSketch512
• CountMinSketch256x4, CountMinSketch512x4, CountMinSketch1024x8

anomaly - Streaming Anomaly Detection

Type	Description
MadDetector	Median Absolute Deviation detector
EwmaDetector	Exponentially Weighted Moving Average detector
ZScoreDetector	Standard Z-score detector with running statistics
CompositeDetector	Combines multiple detectors with voting
StreamingMedian	O(log n) streaming median via sorted-insert buffer
AnomalyEvent	Timestamped anomaly report with severity
AnomalyCallback	Callback trait for anomaly notifications

Features:

• Streaming operation with constant memory per detector
• Composite detector with configurable voting threshold
• Callback-driven anomaly notification

privacy - Local Differential Privacy

Type	Description
LaplaceNoise	Calibrated Laplace mechanism for numeric queries
Rappor	RAPPOR protocol for categorical data collection
RandomizedResponse	Binary randomized response with tunable epsilon
PrivacyBudget	Epsilon budget tracker with composition accounting
PrivateAggregator	Privacy-preserving aggregation over multiple queries
XorShift64	Deterministic PRNG for reproducible noise generation

Features:

• Laplace noise calibrated to sensitivity/epsilon
• RAPPOR with Bloom filter encoding for categorical data
• Composable privacy budget tracking

SDF Collider (ALICE-SDF Integration)

ALICE-Physics can use ALICE-SDF distance fields as collision shapes. Instead of approximating complex shapes with convex hulls (GJK/EPA), the solver samples the SDF directly — giving mathematically exact surfaces at O(1) cost per query.

How It Works

Body (sphere)                    SdfCollider
  ┌───┐                         ┌──────────────────────┐
  │ ● │──world_to_local(pos)──▶│ SdfField::distance() │─── >0 → no hit (early-out)
  └───┘                         │ SdfField::normal()   │─── ≤0 → contact + resolve
                                │ cached inv_rotation   │
                                │ cached scale_f32      │
                                └──────────────────────┘

Key Optimizations

Optimization	Description	Benefit
Early-out	Call distance() (1 eval) first, only compute normal() (4 evals) on collision	80% fewer evals for non-colliding bodies
Cached invariants	Pre-computed inv_rotation, scale_f32, inv_scale_f32	No per-query recomputation
Rayon parallel	par_iter_mut over bodies with --features parallel	Linear speedup with cores
4-eval combined	Tetrahedral gradient gives distance + normal from 4 evals	1 eval saved vs naive 1+4

Usage

use alice_physics::prelude::*;
use alice_physics::sdf_collider::SdfCollider;
use alice_sdf::physics_bridge::CompiledSdfField;
use alice_sdf::prelude::*;

// 1. Create SDF shape in ALICE-SDF
let terrain = SdfNode::plane(0.0, 1.0, 0.0, 0.0)  // ground plane
    .union(SdfNode::sphere(2.0).translate(0.0, -1.5, 0.0));  // hill

let field = CompiledSdfField::new(terrain);

// 2. Create physics world
let mut world = PhysicsWorld::new(PhysicsConfig::default());

// 3. Register SDF as static collider
let collider = SdfCollider::new_static(
    Box::new(field),
    Vec3Fix::ZERO,                    // position
    QuatFix::IDENTITY,                // rotation
);
world.add_sdf_collider(collider);

// 4. Add dynamic bodies — they will collide with the SDF surface
let ball = RigidBody::new_dynamic(
    Vec3Fix::from_int(0, 10, 0),     // start above terrain
    Fix128::ONE,                      // mass
);
world.add_body(ball);

// 5. Simulate — SDF collisions resolved automatically in step()
let dt = Fix128::from_ratio(1, 60);
for _ in 0..300 {
    world.step(dt);
}

SdfCollider API

Method	Description
SdfCollider::new_static(field, position, rotation)	Static SDF collider
SdfCollider::new_dynamic(field, position, rotation, body_index)	Attached to a body
.with_scale(scale)	Set uniform scale (updates cached invariants)
.update_cache()	Recompute cached inv_rotation, scale_f32 after manual changes
collide_point_sdf(point, sdf)	Point vs SDF contact test
collide_sphere_sdf(center, radius, sdf)	Sphere vs SDF contact test

Requirements

Enable the physics feature in ALICE-SDF:

[dependencies]
alice-sdf = { path = "../ALICE-SDF", features = ["physics"] }

See the ALICE-SDF README for CompiledSdfField details.

Rendering Pipeline Integration (ALICE-SDF v1.4.0+)

ALICE-Physics provides physics state data that drives ALICE-SDF's rendering pipeline destruction uniforms. The physics engine simulates thermal, fracture, erosion, and pressure fields — the application layer samples these fields and uploads them as shader uniforms for real-time visual feedback.

Architecture

ALICE-Physics (CPU)                    ALICE-SDF Shader (GPU)
┌─────────────────────┐                ┌──────────────────────┐
│ ThermalModifier      │──→ sample ──→│ uniform float uShatter│
│ FractureModifier     │──→ sample ──→│ uniform float uEntropy│
│ PressureModifier     │──→ sample ──→│ uniform float uImpact │
│ ErosionModifier      │──→ sample ──→│ uniform vec2 uShake   │
│ ForceField::Explosion│──→ sample ──→│ uniform float uMeteorY│
└─────────────────────┘                └──────────────────────┘
         ↓ Application layer bridges the gap (each frame)

Uniform Mapping

Physics Source	Field / Method	Rendering Uniform	Description
ThermalModifier	temperature.sample(pos)	uShatter	Temperature above melt threshold → destruction intensity
ThermalModifier	melt_accumulator.sample(pos)	uEntropy	Cumulative material loss (0-1)
FractureModifier	stress_field.sample(pos)	uShatter	Stress-driven crack propagation
PressureModifier	pressure_field.sample(pos)	uImpact	Contact force deformation depth
ForceField::Explosion	center, radius	uMeteorImpact, uImpactRing	Explosion center and blast radius
Impact event	collision velocity	uShake	Camera shake from impact force
Projectile body	body.position.y	uMeteorY	Falling object altitude

Example: Physics-Driven Destruction

use alice_physics::{PhysicsWorld, ThermalModifier, ThermalConfig, HeatSource};
use alice_sdf::compiled::glsl::RenderConfig;

// Physics side: thermal simulation
let mut thermal = ThermalModifier::new(ThermalConfig {
    melt_temperature: 800.0,
    melt_rate: 0.01,
    droop_strength: 0.5,
    ..Default::default()
});
thermal.add_heat_source(HeatSource::point(impact_pos, 2000.0));

// Each frame:
thermal.step(&mut world, dt);

// Application bridge: sample physics → upload to shader
let shatter = thermal.melt_accumulator.sample(surface_pos).min(1.0);
let entropy = thermal.temperature.sample(surface_pos) / 1000.0;
gl.uniform1f(u_shatter_loc, shatter);
gl.uniform1f(u_entropy_loc, entropy.min(1.0));

Relevant Modules

Module	Description	Drives Uniform
thermal.rs	Heat diffusion, melt, thermal expansion, freeze	uShatter, uEntropy
fracture.rs	Stress-driven crack propagation (CSG subtraction)	uShatter
pressure.rs	Contact force → crush/bulge/dent deformation	uImpact
erosion.rs	Wind, water, chemical, ablation erosion	uEntropy
sdf_destruction.rs	Real-time CSG boolean destruction	uImpactRing
force.rs	Explosion force field (center, radius, falloff)	uMeteorImpact, uImpactRing
sim_field.rs	3D scalar/vector field with trilinear interpolation	All (infrastructure)

RenderConfig Compatibility

Enable destruction: true in ALICE-SDF's RenderConfig to activate the shader-side destruction features:

let config = RenderConfig {
    destruction: true,       // Voronoi cracking, debris, shockwave visuals
    spectral_rendering: true, // Blackbody radiation for heated surfaces
    vfx_effects: true,       // Domain warp for melting surfaces
    ..Default::default()
};

Deterministic Neural Controller (ALICE-ML Integration)

ALICE-Physics integrates with ALICE-ML to provide bit-exact deterministic AI for game characters. By combining 1.58-bit ternary weights {-1, 0, +1} with 128-bit fixed-point arithmetic, neural inference reduces to pure addition/subtraction — the inference path is integer-only (Fix128 mat-vec, no IEEE 754 rounding, no platform-dependent behavior).

This is the "holy grail" for networked fighting games and action games: all clients compute identical AI behavior without synchronization.

How It Works

Ternary Weight {-1, 0, +1}:
  +1 → Fix128 addition
  -1 → Fix128 subtraction
   0 → skip (free sparsity)

Result: Zero floating-point multiplication in the entire inference pipeline.

Ragdoll Controller Example

use alice_physics::prelude::*;
use alice_ml::{TernaryWeight, quantize_to_ternary};

// 1. Quantize pre-trained weights to ternary
let (w1, _) = quantize_to_ternary(&trained_weights_l1, hidden_size, input_size);
let (w2, _) = quantize_to_ternary(&trained_weights_l2, output_size, hidden_size);

// 2. Convert to fixed-point (one-time)
let ftw1 = FixedTernaryWeight::from_ternary_weight(w1);
let ftw2 = FixedTernaryWeight::from_ternary_weight(w2);

// 3. Build deterministic network
let network = DeterministicNetwork::new(
    vec![ftw1, ftw2],
    vec![Activation::ReLU, Activation::HardTanh],
);

// 4. Create ragdoll controller
let config = ControllerConfig {
    max_torque: Fix128::from_int(100),
    num_joints: 8,    // 8 joints × 3 axes = 24 outputs
    num_bodies: 9,    // 9 body parts × 13 features = 117 inputs
    features_per_body: 13,  // pos(3) + vel(3) + rot(4) + angvel(3)
};
let mut controller = RagdollController::new(network, config);

// 5. In physics loop — deterministic across ALL clients
for frame in 0..3600 {
    let output = controller.compute(&world.bodies);
    for (joint_idx, torque) in output.torques.iter().enumerate() {
        world.bodies[joint_idx].apply_impulse(*torque);
    }
    world.step(dt);
}

Neural Controller API

Type	Description
FixedTernaryWeight	TernaryWeight wrapper with Fix128 scale
DeterministicNetwork	Multi-layer network (zero-allocation forward pass)
RagdollController	Body states → joint torques
ControllerConfig	max_torque, num_joints, num_bodies
ControllerOutput	Vec3Fix torque per joint
Activation	ReLU, HardTanh, TanhApprox, None

Function	Description
fix128_ternary_matvec()	Core kernel — pure add/sub, zero multiplication
fix128_relu()	max(0, x) via sign-bit comparison
fix128_hard_tanh()	clamp(x, -1, 1) for bounded output
fix128_tanh_approx()	Padé rational x(27+x²)/(27+9x²)
fix128_leaky_relu()	Leaky ReLU with Fix128 alpha

Requirements

[dependencies]
alice-physics = { path = "../ALICE-Physics", features = ["neural"] }

Configuration

// SolverConfig / PhysicsConfig
let config = PhysicsConfig {
    substeps: 8,       // XPBD substeps per frame (more = stable but slower)
    iterations: 1,     // Solver passes per substep (default 1: Small Steps — raise substeps, not iterations)
    gravity: Vec3Fix::new(
        Fix128::ZERO,
        Fix128::from_int(-10),  // -10 m/s²
        Fix128::ZERO,
    ),
    damping: Fix128::from_ratio(99, 100),  // 0.99 velocity retention
};

// Or use defaults
let config = PhysicsConfig::default();

Performance Characteristics

Measured, not estimated: cargo bench --bench physics_bench (criterion, release profile) on Apple M-series, 2026-09-15, alice-physics 1.2.0. Absolute numbers are machine-dependent; the algorithmic column is what the implementation actually does.

Operation	Algorithm	Measured
Fix128 add/sub	128-bit add with carry	< 1 ns
Fix128 mul	3 × 64×64→128 partial products	1.1 ns
Fix128 div	u128 integer quotient + 64-step long division for the fraction	141 ns
Fix128 sqrt	96-step restoring digit recurrence (exact floor)	193–354 ns across runs (1.1.0: 9,676 ns, Newton × 64 divisions)
Vec3Fix normalize	length via sqrt + 3 div	618 ns (1.1.0: 10,390 ns)
CORDIC sin/cos / atan	48 fixed iterations	~1 µs
GJK intersection	max 64 iterations	—
EPA penetration	max 64 iterations	—
BVH build	Morton code sort, O(n log n)	—
BVH query / find_pairs	stackless traversal per leaf AABB, O(n log n) expected	1.1.0 queried the root AABB → O(n²)
World step, 10 bodies × 60 steps (default config)		398 µs (1.1.0: 5.11 ms)
World step, 1000 overlapping spheres (10³ grid, default config: detection in each of 8 substeps)	thousand_overlapping_spheres_1_step	first frame 65 ms (2 700 contacts, 57 k broad-phase candidates × 8); frames 2–10 as the bodies separate: 7.7 ms/frame

External review of 1.1.0 (Linux x86_64) measured 1000 overlapping bodies at 432 ms/frame with frame-level detection; 1.2.0 detects in every substep (a correctness requirement, see CHANGELOG), so the dense first frame costs more and the steady state less. Re-run the bench on your target before quoting numbers.

MSRV Policy

Minimum Supported Rust Version: 1.85

ALICE-Physics follows a Serde-style MSRV policy:

• MSRV bumps within the 0.x line are treated as minor version bumps (0.13.x → 0.14.0), never patch bumps
• MSRV bumps within a stable 1.x line will also be treated as minor version bumps (1.x → 1.(x+1)), never patch
• The MSRV commitment covers the latest 3 stable Rust channels (N-2 policy) — at the time of a release, we support the current stable + previous 2
• alice-physics does not require a nightly toolchain
• CI enforces the declared MSRV via a dedicated msrv job: cargo +1.85 check on the default feature set, the no_std build (rlib) and the core native feature set, resolved by resolver = "3" (MSRV-aware). 1.0.x–1.1.0 declared 1.70.0; that toolchain could not even parse the lockfile and the no_std build needed core::f32::abs (1.85), so the claim was corrected in 1.2.0 (minor bump per the policy above)

Scope of the MSRV guarantee — the library with the default feature set, no_std (--no-default-features, as rlib) and the core native features (std, simd, parallel, ffi, gpu-solver-bridge) builds on 1.85. Outside that scope:

Component	Effective MSRV	Why
neural / replay / analytics bridge features	follows the sibling crate (alice-ml / alice-db / alice-analytics); 1.87 as of alice-db 0.2.0-beta.2 → alice-zip 0.3.0	sibling crates set their own MSRV
Tests / benches (dev-dependencies)	1.85+	criterion, serde_derive
wasm feature	stable channel recommended	wasm-bindgen moves fast

Downstream crates can rely on alice-physics not raising its MSRV within a patch release, preserving their own MSRV window.

Building

Note on --all-features: alice-physics uses wasm and ffi as mutually exclusive features (they link wasm-bindgen and C ABI FFI respectively, which cannot coexist in a single binary). cargo build --all-features will fail with a compile_error! by design. Build with one or the other.

Recommended feature combinations:

Target	Command
Native app / game engine host (Unity, UE5, Godot)	cargo build --features "std,simd,parallel,ffi,gpu-solver-bridge"
Browser (WebGL / WebGPU via wasm-bindgen)	cargo build --features "std,simd,parallel,wasm,gpu-solver-bridge"
Embedded / no_std	as a dependency: default-features = false; standalone: cargo rustc --lib --no-default-features --crate-type rlib (the package also declares cdylib/staticlib for the C ABI, which need std)
Python bindings	cargo build --features "std,simd,parallel,python"

docs.rs builds with the native feature set (see [package.metadata.docs.rs] in Cargo.toml).

# Standard build
cargo build --release

# no_std library build (for embedded/WASM); downstream crates just set default-features = false
cargo rustc --release --lib --no-default-features --crate-type rlib

# C ABI artifacts for Unity / UE5 (target/release/libalice_physics.{so,dylib,a}, alice_physics.dll)
cargo build --release --features ffi

# Run tests
cargo test

# Run all feature combinations
cargo test --features simd
cargo test --features parallel
cargo test --features neural
cargo test --features "simd,parallel"

# Run benchmarks (requires nightly or criterion)
cargo bench

Cargo Features

Feature	Default	Description
std	Yes	Standard library support
simd	No	*_simd / dot_batch_4 API surface + SIMD_WIDTH. Scalar-equivalent as of 1.2.0: SSE2/AVX2 have no 128-bit multiply and cannot carry lo→hi, so no intrinsic path is faster than the scalar ADC chain; kept for a future AVX-512 / NEON batch path
parallel	No	Constraint batching with Rayon (graph-colored parallel solving)
neural	No	Deterministic neural controller via ALICE-ML ternary inference
python	No	Python bindings (PyO3 + NumPy zero-copy)
replay	No	Replay recording/playback via ALICE-DB
ffi	No	C FFI for Unity, Unreal Engine, and other game engines
wasm	No	WebAssembly bindings via wasm-bindgen
analytics	No	Simulation profiling via ALICE-Analytics

Note: wasm and ffi are mutually exclusive — enabling both causes a compile error.

# Enable SIMD optimizations
cargo build --release --features simd

# Enable parallel constraint solving
cargo build --release --features parallel

# Enable both
cargo build --release --features "simd,parallel"

# Enable neural controller (requires ALICE-ML)
cargo build --release --features neural

# Build C shared library for game engines
cargo build --release --features ffi

Tested Feature Combinations

All feature combinations are tested in CI across macOS, Ubuntu, and Windows:

Combination	Status	Tests
--no-default-features (no_std)	✅	9
--features std (default)	✅	1695 unit + 72 integration + 13 analytic + 105 engineering + 13 default-config oracles + 44 determinism + 21 doc
--features simd	✅	20
--features parallel	✅	20
--features "simd,parallel"	✅	20
--features ffi	✅	build + cdylib/staticlib artifact check
--features python	✅	1
--features replay	✅	build only
--features analytics	✅	build only
--features neural	✅	build only
--features wasm	✅	build only

Feature compatibility matrix:

	std	simd	parallel	neural	python	ffi	wasm	replay	analytics
std	-	✅	✅	✅	✅	✅	✅	✅	✅
simd	✅	-	✅	✅	✅	✅	❌	✅	✅
parallel	✅	✅	-	✅	✅	✅	❌	✅	✅
wasm	✅	❌	❌	❌	❌	❌	-	❌	❌

Game Engine Integration (C FFI / Unity / UE5)

ALICE-Physics provides a C FFI layer for integration with Unity, Unreal Engine, and any language that can call C functions.

Building the Shared Library

# macOS (.dylib)
cargo build --release --features ffi

# Linux (.so)
cargo build --release --features ffi

# Windows (.dll)
cargo build --release --features ffi

The output library is in target/release/ (libalice_physics.dylib, libalice_physics.so, or alice_physics.dll).

C API

The C header is at include/alice_physics.h. All types use f64 at the FFI boundary and convert to Fix128 internally.

#include "alice_physics.h"

// Create world
AlicePhysicsWorld* world = alice_physics_world_create();

// Add bodies
AliceVec3 pos = {0.0, 10.0, 0.0};
uint32_t body = alice_physics_body_add_dynamic(world, pos, 1.0);

// Step simulation
alice_physics_world_step(world, 1.0 / 60.0);

// Read back position
AliceVec3 out_pos;
alice_physics_body_get_position(world, body, &out_pos);

// State serialization (rollback netcode)
uint32_t len;
uint8_t* state = alice_physics_state_serialize(world, &len);
alice_physics_state_deserialize(world, state, len);
alice_physics_state_free(state, len);

// Cleanup
alice_physics_world_destroy(world);

Unity C# Bindings

Copy bindings/AlicePhysics.cs and the native library to your Unity project:

Assets/
  Plugins/
    macOS/    libalice_physics.dylib
    Win64/    alice_physics.dll
    Linux/    libalice_physics.so
  Scripts/
    AlicePhysics.cs

using AlicePhysics;

var world = new AlicePhysicsWorld();
uint body = world.AddDynamicBody(new Vector3(0, 10, 0), 1.0);
world.Step(1.0 / 60.0);
Vector3 pos = world.GetBodyPosition(body);

// Rollback netcode
byte[] state = world.SerializeState();
world.DeserializeState(state);

world.Dispose();

Unreal Engine 5 Plugin

Copy the unreal-plugin/ contents to Plugins/AlicePhysics/ in your UE5 project and place the native library in ThirdParty/AlicePhysics/lib/<Platform>/.

The plugin provides UAlicePhysicsWorldComponent with full Blueprint support:

• AddDynamicBody, AddStaticBody — body creation
• GetBodyPosition, GetBodyRotation, GetBodyVelocity — state queries
• ApplyImpulse, ApplyImpulseAt — force application
• SerializeState, DeserializeState — rollback netcode
• Automatic coordinate system conversion (UE5 Z-up cm → ALICE Y-up m)

Release Workflow

Tag a version to trigger automatic cross-platform builds:

git tag v0.5.0
git push origin v0.5.0

GitHub Actions builds for macOS (ARM + Intel), Windows, and Linux, then packages:

• UE5 Plugin ZIP — includes native library + plugin source + header
• Unity Package ZIP — includes native library + C# bindings + header

Comparison with Floating-Point Engines

Aspect	ALICE-Physics	Float Engines
Determinism	Guaranteed	Platform-dependent
Precision	64-bit fraction	23-bit (f32) / 52-bit (f64)
Speed	Slower (2-5x)	Faster
Rollback	Trivial	Requires care
Embedded	no_std	Requires FPU
Range	±9.2×10^18	±3.4×10^38 (f32)

Deterministic Netcode

ALICE-Physics includes a frame-based deterministic netcode foundation. Because the engine guarantees bit-exact results, only player inputs need to be synchronized — state sync is unnecessary.

Bandwidth Savings

Approach	Per-Frame (10 bodies, 2 players)
State sync (traditional)	~1,600 bytes
Input sync (ALICE)	~40 bytes
Savings	97.5%

Core Types

Type	Description
FrameInput	20-byte serializable player input (movement, actions, aim)
SimulationChecksum	XOR rolling hash of physics state (WyHash-style avalanche)
SimulationSnapshot	Full state capture for rollback
DeterministicSimulation	PhysicsWorld wrapper with frame counter, checksum history, snapshot ring buffer
InputApplicator	Trait for game-specific input → physics force mapping

Usage

use alice_physics::prelude::*;

// Both clients create identical simulation
let mut sim = DeterministicSimulation::new(NetcodeConfig::default());

// Add bodies and assign to players
let body0 = sim.add_body(RigidBody::new_dynamic(
    Vec3Fix::from_int(0, 10, 0), Fix128::ONE,
));
sim.assign_player_body(0, body0);

// Each frame: collect inputs, advance, compare checksums
let inputs = vec![
    FrameInput::new(0).with_movement(Vec3Fix::from_int(1, 0, 0)),
    FrameInput::new(1).with_movement(Vec3Fix::from_int(0, 0, -1)),
];
let checksum = sim.advance_frame(&inputs);

// Save snapshot for rollback
sim.save_snapshot();

// Verify remote client's checksum
assert_eq!(sim.verify_checksum(1, checksum), Some(true));

ALICE-Sync Integration (Game Engine Pipeline)

ALICE-Physics integrates with ALICE-Sync for complete multiplayer game networking. Enable physics feature in ALICE-Sync:

[dependencies]
alice-sync = { path = "../ALICE-Sync", features = ["physics"] }

How It Works

Player Input ──► InputFrame (i16, 24B) ──► FrameInput (Fix128) ──► PhysicsWorld
                     ALICE-Sync                 bridge                 step()
                                                  │
PhysicsWorld ──► SimulationChecksum ──► WorldHash ──► Desync Verify
                   from_world()           bridge        ALICE-Sync

ALICE-Sync's PhysicsRollbackSession wraps both RollbackSession (input sync) and DeterministicSimulation (physics) into a single game loop driver:

1. Submit local input → predict remote inputs
2. Convert InputFrame (i16) → FrameInput (Fix128)
3. Save snapshot → step physics → record checksum
4. On mismatch: auto rollback + re-simulate

Bandwidth

Approach	Per-Frame (4 players, 60fps)
State sync	~960 KB/s
Input sync (ALICE)	5.6 KB/s
Savings	99.4%

See ALICE-Sync README for full API.

Python Bindings (PyO3 + NumPy Zero-Copy)

Install with:

pip install maturin
maturin develop --release --features python

Optimization Layers

Layer	Technique	Effect
L1	GIL Release (py.allow_threads)	Parallel physics stepping
L2	Zero-Copy NumPy (into_pyarray_bound)	No memcpy for bulk positions/velocities
L3	Batch API (step_n, positions, states)	FFI amortization
L4	Batch Mutation (add_bodies_batch, set_velocities_batch, apply_impulses_batch)	Bulk operations with GIL release
L5	Rust backend (Fix128, XPBD, BVH)	Hardware-speed simulation

Python API

import alice_physics

# Basic physics world
world = alice_physics.PhysicsWorld()
body0 = world.add_dynamic_body(0.0, 10.0, 0.0, mass=1.0)
ground = world.add_static_body(0.0, 0.0, 0.0)

# Step with GIL release (other Python threads can run)
world.step(1.0 / 60.0)

# Batch step for training loops
world.step_n(1.0 / 60.0, steps=300)

# Get all positions as NumPy (N, 3) float64 array (zero-copy)
positions = world.positions()  # shape: (N, 3)
velocities = world.velocities()  # shape: (N, 3)

# Deterministic netcode simulation
sim = alice_physics.DeterministicSimulation(player_count=2, fps=60)
body = sim.add_body(0.0, 10.0, 0.0, mass=1.0)
sim.assign_player(0, body)

# Advance with player inputs: (player_id, move_x, move_y, move_z, actions)
checksum = sim.advance_frame([(0, 1.0, 0.0, 0.0, 0), (1, 0.0, 0.0, -1.0, 0)])

# Snapshot for rollback
frame = sim.save_snapshot()
sim.load_snapshot(frame)

# Serialization
state = world.serialize_state()  # NumPy uint8 array
world.deserialize_state(state.tolist())

# Frame input encoding (20 bytes, network-ready)
data = alice_physics.encode_frame_input(player_id=0, move_x=1.0, actions=0x3)
player_id, mx, my, mz, actions, ax, ay, az = alice_physics.decode_frame_input(data)

# === Batch APIs (v0.4.0) ===

import numpy as np

# Batch body creation from (N,4) array [x, y, z, mass]
ids = world.add_bodies_batch(np.array([
    [0.0, 10.0, 0.0, 1.0],
    [5.0, 10.0, 0.0, 2.0],
    [10.0, 10.0, 0.0, 0.5],
]))

# Batch velocity update (N,3) with GIL release
world.set_velocities_batch(np.array([
    [1.0, 0.0, 0.0],
    [0.0, 0.0, -1.0],
    [0.0, 5.0, 0.0],
]))

# Batch impulse (M,4) [body_id, ix, iy, iz] with GIL release
world.apply_impulses_batch(np.array([
    [0.0, 100.0, 0.0, 0.0],
    [2.0, 0.0, 50.0, 0.0],
]))

# Combined state output (N,10) [px,py,pz, vx,vy,vz, qx,qy,qz,qw]
states = world.states()  # shape: (N, 10), zero-copy NumPy

Replay Recording (ALICE-DB Integration)

ALICE-Physics can record and replay simulation trajectories via ALICE-DB. Enable with --features replay.

[dependencies]
alice-physics = { path = "../ALICE-Physics", features = ["replay"] }

Recording

use alice_physics::replay::ReplayRecorder;

// Create recorder (path, body_count)
let mut recorder = ReplayRecorder::new("./replay_data", 3)?;

// In game loop: record every frame
for _ in 0..300 {
    world.step(dt);
    recorder.record_frame(&world)?;
}

recorder.flush()?;
recorder.close()?;

Playback

use alice_physics::replay::ReplayPlayer;

let player = ReplayPlayer::open("./replay_data", 3)?;

// Random access: get position at any frame
let pos = player.get_position(frame, body_id)?;
// Returns Option<(f32, f32, f32)>

// Range query: scan positions over frame range
let trajectory = player.scan_positions(0, 299, body_id)?;
// Returns Vec<(u64, f32, f32, f32)>

player.close()?;

Storage Format

Each body stores 6 channels (pos_x/y/z, vel_x/y/z) in ALICE-DB. ALICE-DB's model-based compression automatically fits trajectories:

• Constant velocity → linear model (2 coefficients)
• Projectile motion → quadratic model (3 coefficients)
• Complex motion → Fourier model

Test Results

v0.4.0 Test Summary:
  - 358 unit tests across 63 modules
  - 62 integration tests (end-to-end physics scenarios)
  - 12 doc tests (runnable examples)
  - Total: 432 passing tests (435 with --features parallel)
  - Clippy: 0 warnings
  - CI: Format + Clippy + Test (macOS/Ubuntu/Windows)
  - All feature combinations pass (default, parallel, simd, no_std)

Cross-Crate Bridges

ALICE-Physics connects to other ALICE ecosystem crates via feature-gated bridge modules:

Bridge	Feature	Target Crate	Description
Physics Visualization	view	ALICE-View	Real-time physics debug overlay rendering
GPU Physics Controller	trt	ALICE-TRT	GPU ternary inference for physics control policies
Physics State Streaming	asp	ALICE-Streaming-Protocol	Physics body state delta encoding as ASP D-packets
db_bridge	replay	ALICE-DB	Physics state snapshot persistence (energy, bodies, contacts)
analytics_bridge	analytics	ALICE-Analytics	Simulation profiling (step time, collision pairs, energy drift)

Recent Performance Improvements

Module	Change	Impact
fluid.rs	Buffer reuse in neighbor queries	~99% allocation reduction in SPH simulation
animation_blend.rs	clone_from() replaces clone()	Eliminates 60 allocs/sec during blend

Cargo Profile

Standardized [profile.bench] added for consistent benchmarking across ALICE crates.

Complete API Reference

Core Types

Module	Type / Function	Description
math	Fix128	128-bit fixed-point number (I64F64)
math	Vec3Fix	3D vector with Fix128 components
math	QuatFix	Quaternion for rotations
math	Mat3Fix	3x3 matrix for inertia tensors
math	SIMD_WIDTH	Compile-time SIMD lane count (AVX2=8, NEON=4, scalar=1)
math	simd_width()	Returns SIMD width at compile time
math	select_fix128()	Branchless conditional select
math	select_vec3()	Branchless Vec3 conditional select

Collision Detection

Module	Type / Function	Description
collider	AABB	Axis-Aligned Bounding Box
collider	Sphere	Sphere collider
collider	Capsule	Capsule (cylinder + hemispheres)
collider	ConvexHull	Arbitrary convex polyhedron
collider	ScaledShape	Uniform scale wrapper for any Support shape
collider	CollisionResult	Contact point, normal, depth
collider	Support trait	GJK support function interface
box_collider	OrientedBox	OBB with center, half-extents, rotation
compound	CompoundShape	Multi-shape compound collider
compound	ShapeRef	Shape reference within compound
cylinder	Cylinder	Cylinder collider with GJK support
filter	CollisionFilter	Layer/mask bitmask collision groups

Solver & Dynamics

Module	Type / Function	Description
solver	PhysicsWorld	Main simulation world
solver	PhysicsConfig	Substeps, iterations, gravity, damping
solver	RigidBody	Dynamic/static/sensor rigid body
solver	BodyType	Dynamic, Static, Kinematic
solver	DistanceConstraint	Fixed distance between anchor points
solver	ContactConstraint	Collision response with friction/restitution
solver	ContactModifier	Trait for custom contact modification (std)
joint	BallJoint	Spherical joint (3 rotational DOF)
joint	HingeJoint	Revolute joint with angle limits
joint	FixedJoint	Weld joint (0 DOF)
joint	SliderJoint	Prismatic joint with limits
joint	SpringJoint	Damped spring constraint
joint	D6Joint	6-DOF configurable joint
joint	ConeTwistJoint	Cone swing + twist limit joint
joint	solve_joints_breakable()	Solve with break-force support
motor	PdController	1D proportional-derivative controller
motor	JointMotor	Joint motor (position/velocity/torque modes)
force	ForceField	Wind, gravity well, drag, buoyancy, vortex
force	ForceFieldInstance	Active force field in simulation
material	MaterialTable	Per-pair friction/restitution override
material	PhysicsMaterial	Material properties
material	CombineRule	Average, Min, Max, Multiply

Spatial Acceleration

Module	Type / Function	Description
bvh	LinearBvh	Flat array BVH with stackless traversal
bvh	BvhNode	32-byte cache-aligned node
bvh	BvhPrimitive	Primitive entry for BVH construction
dynamic_bvh	DynamicAabbTree	Incremental BVH with O(log n) insert/remove
spatial	SpatialGrid	Hash grid for neighbor queries

Queries

Module	Type / Function	Description
raycast	Ray	Ray origin + direction
raycast	RayHit	Hit result (t, normal, index)
raycast	ray_sphere(), ray_aabb(), ray_capsule(), ray_plane()	Shape-specific ray tests
raycast	raycast_all_spheres(), raycast_all_aabbs()	Batch raycasts
query	sphere_cast()	Sweep sphere along direction
query	capsule_cast()	Sweep capsule along direction
query	overlap_sphere()	Find bodies in sphere
query	overlap_aabb()	Find bodies in AABB
query	batch_raycast(), batch_sphere_cast()	Batch queries
ccd	sphere_sphere_toi()	Time of impact (sphere-sphere)
ccd	conservative_advancement()	Iterative safe stepping TOI
ccd	speculative_contact()	Speculative CCD contacts

Soft Body & Simulation

Module	Type / Function	Description
rope	Rope	XPBD distance-chain rope
rope	RopeConfig	Segment count, stiffness, damping
cloth	Cloth	XPBD triangle mesh cloth
cloth	ClothConfig	Stiffness, self-collision, gravity
fluid	Fluid	Position-Based Fluids (PBF)
fluid	FluidConfig	Rest density, viscosity, kernel radius
deformable	DeformableBody	FEM tetrahedral mesh
deformable	DeformableConfig	Young's modulus, Poisson's ratio
vehicle	Vehicle	Vehicle simulation
vehicle	VehicleConfig	Wheels, suspension, engine, steering
character	CharacterController	Kinematic capsule move-and-slide
character	CharacterConfig	Radius, height, max slope, step height

SDF Integration

Module	Type / Function	Description
sdf_collider	SdfCollider	SDF as collision shape
sdf_collider	SdfField trait	Distance + normal evaluation interface
sdf_collider	ClosureSdf	Closure-based SDF implementation
sdf_manifold	SdfManifold	Multi-point contact from SDF surface
sdf_manifold	ManifoldConfig	Contact point count, spread
sdf_ccd	SdfCcdConfig	Sphere tracing CCD for SDF
sdf_force	SdfForceField	SDF-driven force field
sdf_force	SdfForceType	Attract, Repel, Contain, Flow
sdf_destruction	DestructibleSdf	CSG boolean destruction (std)
sdf_destruction	DestructionShape	Sphere/box subtraction shape
sdf_adaptive	AdaptiveSdfEvaluator	Distance-based LOD evaluation (std)
convex_decompose	DecomposeConfig	Voxel grid decomposition settings (std)
gpu_sdf	GpuSdfBatch	GPU compute SDF batch (std)
gpu_sdf	GpuSdfInstancedBatch	Instanced GPU SDF batch
gpu_sdf	GpuSdfMultiDispatch	Multi-batch GPU dispatch

SDF Simulation Modifiers

Module	Type / Function	Description
sim_field	ScalarField3D	3D scalar field with trilinear interpolation (std)
sim_field	VectorField3D	3D vector field with trilinear interpolation (std)
sim_modifier	PhysicsModifier trait	SDF modifier interface (std)
sim_modifier	ModifiedSdf	Modifier chain (std)
thermal	ThermalModifier	Heat diffusion, melt, freeze (std)
thermal	ThermalConfig	Conductivity, melt/freeze thresholds
pressure	PressureModifier	Contact-force deformation (std)
pressure	PressureConfig	Yield threshold, spring-back
erosion	ErosionModifier	Wind/water/chemical erosion (std)
erosion	ErosionType	Wind, Water, Chemical, Ablation
fracture	FractureModifier	Stress-driven crack propagation (std)
fracture	FractureConfig	Toughness, crack speed
phase_change	PhaseChangeModifier	Solid/liquid/gas transitions (std)
phase_change	Phase	Solid, Liquid, Gas

Game Systems

Module	Type / Function	Description
animation_blend	AnimationBlender	Ragdoll-to-animation blending
animation_blend	BlendMode	Lerp, Slerp, Additive
animation_blend	SkeletonPose	Joint transforms for skeleton
audio_physics	AudioGenerator	Physics-based audio parameters
audio_physics	AudioEvent	Impact, friction, rolling events
audio_physics	AudioMaterial	Surface material with audio properties
netcode	DeterministicSimulation	PhysicsWorld + frame counter + checksum
netcode	FrameInput	20-byte serializable player input
netcode	SimulationChecksum	XOR rolling hash of physics state
netcode	SimulationSnapshot	Full state capture for rollback
netcode	InputApplicator trait	Game-specific input → force mapping
fluid_netcode	FluidSnapshot	Deterministic fluid state (std)
fluid_netcode	FluidDelta	Delta-compressed fluid update (std)

Analytics & Privacy

Module	Type / Function	Description
sketch	HyperLogLog	Cardinality estimation (std)
sketch	DDSketch	Quantile sketch (P50/P99/P99.9) (std)
sketch	CountMinSketch	Frequency estimation (std)
sketch	HeavyHitters	Top-k frequent items (std)
sketch	FnvHasher	FNV-1a deterministic hasher (std)
sketch	Mergeable trait	Distributed sketch merging (std)
anomaly	MadDetector	Median Absolute Deviation (std)
anomaly	EwmaDetector	Exponentially Weighted Moving Average (std)
anomaly	ZScoreDetector	Standard Z-score detector (std)
anomaly	CompositeDetector	Multi-detector voting (std)
anomaly	StreamingMedian	O(log n) streaming median (std)
privacy	LaplaceNoise	Calibrated Laplace mechanism (std)
privacy	Rappor	RAPPOR protocol for categorical data (std)
privacy	RandomizedResponse	Binary randomized response (std)
privacy	PrivacyBudget	Epsilon budget tracker (std)
privacy	PrivateAggregator	Privacy-preserving aggregation (std)
privacy	XorShift64	Deterministic PRNG (std)
pipeline	MetricPipeline	Lock-free ring buffer aggregation (std)
pipeline	MetricRegistry	Named metric registration (std)
pipeline	MetricEvent	Timestamped metric event (std)
pipeline	MetricType	Counter, Gauge, Histogram (std)
pipeline	RingBuffer	Fixed-capacity circular buffer (std)

Utility

Module	Type / Function	Description
rng	DeterministicRng	PCG-XSH-RR 32-bit generator
event	EventCollector	Contact begin/persist/end tracking
event	ContactEvent	Body pair + event type + contact point
sleeping	IslandManager	Union-Find island management
sleeping	SleepConfig	Velocity thresholds, idle frame count
trimesh	TriMesh	BVH-accelerated triangle mesh
trimesh	Triangle	Single triangle (Moller-Trumbore)
heightfield	HeightField	Grid terrain with bilinear interpolation
articulation	ArticulatedBody	Multi-joint chain with FK propagation
articulation	FeatherstoneSolver	O(n) forward dynamics
contact_cache	ContactCache	HashMap O(1) manifold lookup
contact_cache	ContactManifold	Up to 4 contact points
interpolation	WorldSnapshot	Physics state for interpolation
debug_render	DebugDrawData	Wireframe visualization
debug_render	DebugDrawFlags	Bitmask for what to draw
profiling	PhysicsProfiler	Per-stage timing
profiling	StepStats	Broadphase/narrowphase/solver times
error	PhysicsError	Typed physics error enum

Feature-Gated Modules

Module	Feature	Description
neural	neural	Deterministic ternary neural controller (ALICE-ML)
python	python	PyO3 + NumPy zero-copy Python bindings
ffi	ffi	C FFI for Unity/UE5 game engines
wasm	wasm	WebAssembly bindings (wasm-bindgen)
replay	replay	Replay recording/playback via ALICE-DB
db_bridge	replay	Physics state persistence bridge
analytics_bridge	analytics	Simulation profiling bridge (ALICE-Analytics)

Python API (PyO3)

Class / Function	Description
PhysicsWorld	Python wrapper for physics simulation
PhysicsWorld.add_dynamic_body(x, y, z, mass)	Add dynamic body
PhysicsWorld.add_static_body(x, y, z)	Add static body
PhysicsWorld.step(dt)	Step with GIL release
PhysicsWorld.step_n(dt, steps)	Batch step for training
PhysicsWorld.positions()	NumPy (N,3) zero-copy
PhysicsWorld.velocities()	NumPy (N,3) zero-copy
PhysicsWorld.states()	NumPy (N,10) combined state
PhysicsWorld.add_bodies_batch(array)	Batch body creation from (N,4)
PhysicsWorld.set_velocities_batch(array)	Batch velocity update (N,3)
PhysicsWorld.apply_impulses_batch(array)	Batch impulse (M,4)
PhysicsWorld.serialize_state()	State to NumPy uint8
PhysicsWorld.deserialize_state(data)	Restore from bytes
DeterministicSimulation	Netcode simulation wrapper
DeterministicSimulation.advance_frame(inputs)	Advance with player inputs
DeterministicSimulation.save_snapshot()	Save for rollback
DeterministicSimulation.load_snapshot(frame)	Restore snapshot
encode_frame_input(...)	Encode 20-byte input
decode_frame_input(data)	Decode 20-byte input

C FFI API

Function	Description
alice_physics_world_create()	Create physics world
alice_physics_world_destroy(world)	Destroy physics world
alice_physics_world_step(world, dt)	Step simulation
alice_physics_body_add_dynamic(world, pos, mass)	Add dynamic body
alice_physics_body_add_static(world, pos)	Add static body
alice_physics_body_get_position(world, id, out)	Get body position
alice_physics_body_apply_impulse(world, id, impulse)	Apply impulse
alice_physics_state_serialize(world, len)	Serialize state
alice_physics_state_deserialize(world, data, len)	Deserialize state
alice_physics_state_free(data, len)	Free serialized buffer

License

AGPL-3.0-or-later - See LICENSE for details.

AGPL is a strong copyleft: a game or application that links alice-physics (including through the Unity / UE5 bindings) and is distributed or served to users must be released under the AGPL as well. That is intentional for the open ecosystem. For commercial use without the AGPL obligations, contact sakamoro@alicelaw.net for a separate license.

Copyright (C) 2024-2026 Moroya Sakamoto

Acknowledgments

• XPBD: Müller et al., "XPBD: Position-Based Simulation of Compliant Constrained Dynamics"
• GJK/EPA: Ericson, "Real-Time Collision Detection"
• Morton Codes: Morton, "A Computer Oriented Geodetic Data Base"
• CORDIC: Volder, "The CORDIC Trigonometric Computing Technique"