sim/particles/snapshots/index.js
Exports
Notes & Examples
Physics Engine Integration

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: snapshots/index.js — Re exports for snapshot, playback, and async management. Exports No ES module exports detected in this file. <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


packSandboxCell(speciesCode, temperatureK = SANDBOXREFERENCETEMPERATUREK, life = 255, variant = 0)

packSandboxObject(objectId, sourceSpeciesCode = 0, strength = 255, direction = 0)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Engine owned material facade for dense cellular sandboxes. Atomic numbers, particle material IDs, and sandbox cell codes are separate identities. A sandbox code is only a compact runtime index. The catalog keeps the canonical references beside it so the Editor, demos, and future authoring tools can share labels and properties without conflating those identity spaces. The generated behaviour is qualitative and mesoscale. It does not claim that a grid cell is an atom or that periodic table properties alone predict chemistry. Only explicitly flagged reaction classes react in a solver. Functions Build an immutable shared element/substance/object view for dense sandboxes. Compile the shared catalog into one vec4<u32 record per cell code. Constants — Pairwise interaction traits compiled into the high byte of LUT word 3. <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SubstanceMixer.js — Multi substance blending for mixed emitters. When an emitter uses multiple elements (e.g. fire 0.8 + smoke 0.3), this module blends their substance properties into a single effective definition. Replaces scattered mixing logic in ParticleEmitterSystem.js (deriveTemperatureFromElements, deriveMaterialIndexFromElements, elementMixToEmitterConfig). Functions Mix multiple substances into a blended definition. Returns: — blended substance like object with interpolated properties Derive a substance approximation from element layers (used by emitter system). Maps element IDs to substance IDs and mixes them. <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SubstanceRegistry.js — Central registry for all substance definitions. Provides a unified API to: Register/unregister substance definitions Look up substances by id, materialId, category, or tag Derive physics profiles, phase state, thermal presets, SSFR tint, etc. Each substance is a plain object assembled from per substance sub files: { id, materialId, label, icon, category, tags, chemistry, thermal, physics, sph, visual, emitter, audio, decals, reactions, spell } Replaces scattered lookups across ParticleEmitterSystem, ParticleConstraints, ParticleReactionTable, EditorParticles, and ParticleElementRegistry. Functions Register a substance definition. Overwrites if id already exists. Parameters: (Object) — — substance definition (must have and ) Unregister a substance by id. Parameters: (string) — No description in source JSDoc. Get substance by id (e.g. 'water', 'lava', 'fire'). Parameters: (string) — No description in source JSDoc. Get substance by material ID number. Parameters: (number) — No description in source JSDoc. Get all registered substances. Get substances filtered by category. Parameters: (string) — No description in source JSDoc. Get substances filtered by tag. Parameters: (string) — No description in source JSDoc. Get substance IDs as an array. Resolve a substance key (preset name, element symbol, compound) to a substance definition. Falls back to partial matching. Parameters: (string) — No description in source JSDoc. Derive the phase of matter for a substance at a given temperature. Parameters: (string) — No description in source JSDoc. (number) — — Kelvin Returns: } Derive which physics systems to enable for a substance at a given temperature. Parameters:


— No description in source JSDoc. (number) — — Kelvin Returns: } Derive which physics systems to enable for a substance at a given temperature. Parameters: (string) — No description in source JSDoc. (number) — No description in source JSDoc. Returns: — { enableLJ, enableSPH, enableEM, enableNBody, enableChemistry, enableBlackbody } Get SSFR tint for a substance. Parameters: (string) — No description in source JSDoc. Returns: — [r, g, b] or null Get thermal preset for a substance. Parameters: (string) — No description in source JSDoc. Get SPH fluid parameters for a substance. Parameters: (string) — No description in source JSDoc. Get emitter defaults for a substance. Parameters: (string) — No description in source JSDoc. Get audio cues for a substance. Parameters: (string) — No description in source JSDoc. Get reactions for a substance. Parameters: (string) — No description in source JSDoc. Get material ID for a substance key (replaces SUBSTANCE TO MATERIAL lookup). Parameters: (string) — No description in source JSDoc. Build THERMAL MATERIAL PRESETS compatible object from all registered substances. For backward compatibility with ParticleConstraints.js consumers. Build SUBSTANCE TO MATERIAL compatible object from all registered substances. For backward compatibility with ParticleReactionTable.js consumers. Total number of registered substances. <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced:


detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SubstanceSchema.js — Shared constants and type definitions for the substance system. Single source of truth for: Phase constants (PHASE SOLID, PHASE LIQUID, PHASE GAS, PHASE PLASMA) Material ID enum (MATERIAL) Reverse lookup helpers Replaces scattered definitions in ParticleConstraints.js and ParticleReactionTable.js. Those files re export from here for backward compatibility. Functions Get phase name string from phase constant. Parameters: (number) — No description in source JSDoc. Get phase constant from name string. Parameters: (string) — No description in source JSDoc. Get material name from material ID. Parameters: (number) — No description in source JSDoc. Get material ID from name string. Parameters: (string) — No description in source JSDoc. Constants <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: MoleculePresets.js — Common molecule/compound definitions. Re export of MOLECULE PRESETS from ParticleElementTable.js. Lives in substances/elements/ for organizational clarity. Re exports <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PeriodicTable.js — Full periodic table data for 118 elements. Re export of the core element data from ParticleElementTable.js. This file lives in the new substances/elements/ folder for organizational clarity. The original ParticleElementTable.js remains functional and re exports from here for backward compatibility. Provides: ELEMENT DATA raw array ELEMENTS BY Z / ELEMENTS BY SYMBOL parsed lookups getElement, getElementBySymbol, getAllElements ELEMENTS shorthand constants ljMixingRule for LJ cross interactions GPU buffer creation (createElementTable, etc.) Re exports , , , , , , , , , <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


sim/particles/substances/index.js
Re-exports
Notes & Examples
Physics Engine Integration

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: substances/index.js — Barrel export for the substance system. Single import point: import { getSubstance, MATERIAL, PHASE LIQUID, ... } from './substances/index.js'; Re exports , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Exports No ES module exports detected in this file. <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: materials/index.js — Auto registers all substance definitions with SubstanceRegistry. Import this file to ensure all built in substances are registered. Each substance folder exports a default object assembled from its sub files. Re exports <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


sim/particles/thermal/index.js
Exports
Notes & Examples
Physics Engine Integration

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: thermal/index.js — Re exports for heat, phase transitions, and chemistry. Exports No ES module exports detected in this file. <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


sim/physics/ConnectivityCompute.js
Classes
class ConnectivityCompute
Functions
indexTo3D(idx, size)
positionToIndex(x, y, z, size)
Constants
Notes & Examples
Physics Engine Integration

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ConnectivityCompute.js GPU Accelerated Voxel Connectivity Analysis Problem: When voxels are destroyed, we need to detect which parts are still connected to anchors (ground) vs floating (should fall). CPU flood fill is O(n) and too slow for real time destruction. Solution: GPU wave propagation using ping pong buffers. Each iteration, voxels adopt the minimum component ID of their neighbors. After log(n) iterations, all connected voxels share the same ID. Algorithm: 1. Initialize: Each solid voxel gets unique ID, anchors get ID=1 2. Propagate: Each voxel takes min(self, neighbors) if solid 3. Repeat until no changes (typically 10 20 iterations for 32³) 4. Result: All voxels connected to anchors have ID=1, others form islands Performance Target: <1ms for 32³ chunk (10 20 iterations) Classes Method Signature Summary Initialize GPU resources and pipelines Initialize component IDs from voxel data Run connectivity propagation until convergence Read back component IDs to CPU Get connected components as separate groups Get indices of floating (unanchored) voxels Destroy GPU resources Functions Convert 1D index to 3D position Parameters: (number) — Linear index (number) — Grid size Convert 3D position to 1D index Parameters: (number) — No description in source JSDoc. (number) — No description in source JSDoc. (number) — No description in source JSDoc. (number) — Grid size Constants — Maximum iterations before forcing stop (prevents infinite loops) — Workgroup size for compute shaders — Component ID for anchored voxels (ground, supports) — Component ID for empty/air voxels <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision


— Component ID for empty/air voxels <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


voxelizeMesh(vertices, indices, resolution = 64)

decomposeMesh(vertices, indices, options = {})

createDecomposedCollider(vertices, indices, options = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ConvexDecomposition.js V HACD Style Convex Decomposition Implements Volumetric Hierarchical Approximate Convex Decomposition (V HACD) for breaking concave meshes into convex pieces suitable for physics collision. This is essential for: Complex mesh colliders (characters, vehicles, props) Hollow objects (cups, bowls, tubes) Concave terrain features The algorithm: 1. Voxelize the mesh at a given resolution 2. Recursively split voxel regions using optimal cutting planes 3. Compute convex hulls for each region 4. Simplify hulls to reduce vertex count Functions Voxelize a mesh into a 3D grid Parameters: (Float32Array) — Vertex positions (x, y, z, x, y, z, ...) (Uint32Array Uint16Array) — Triangle indices (number) — Grid resolution Returns: Voxel grid data Decompose a mesh into convex hulls Parameters: (Float32Array) — Vertex positions (Uint32Array Uint16Array) — Triangle indices (Object) — Decomposition options Returns: Array of convex hulls Convert decomposition result to PhysX compound collider format Parameters: (Array) — Array of convex hulls from decomposeMesh Returns: Collider config with compoundColliders array High level function: Decompose mesh and create PhysX collider Parameters: (Float32Array) — Vertex positions (Uint32Array Uint16Array) — Triangle indices (Object) — Decomposition options Returns: Collider config ready for PhysX Constants — Default decomposition parameters <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle


Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


getColliderConfigForMesh(meshId, halfExtents = [0.5, 0.5, 0.5])

createUniversalCollider(world, meshType, geometryFn, halfExtents = [0.5, 0.5, 0.5], material = null, density = 1.0)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Functions <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


meshFragmentToIndexedMesh(meshFragment, options = null)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: FragmentPhysics.js Physics Integration for Mesh Fragments Handles physics simulation for fracture fragments using PhysX. Features: Convex hull generation for rigid body collision Mass distribution based on volume/material Structural connection graph for progressive collapse Fragment → particle conversion for small pieces Classes Represents a connection between two fragments Method Signature Summary Apply stress to connection Reset stress (for iterative solvers) A mesh fragment with physics properties Method Signature Summary Compute mass and inertia from mesh Check if fragment is too small (should become particles) Get convex hull points for PhysX Apply impulse at point Check if fragment is at rest Manages all physics fragments in the world Method Signature Summary Initialize the fragment manager Fracture a mesh at impact point Update all fragments Apply damage to structural connections Create cell lookup function from seeds Convert small fragment to particles Create GPU buffers for fragment rendering Add fragment to PhysX world Sync fragment state from PhysX Build connection graph between fragments Check if two bounding boxes overlap Estimate contact area between fragments Remove a fragment Load configuration from engine.cfg section Destroy all resources Functions <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints


phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


sim/physics/GPUArticulationSolver.js
Classes
class GPUArticulationSolver
Functions
async getGPUArticulationSolver(device)
Notes & Examples
Physics Engine Integration

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: GPUArticulationSolver.js WebGPU Articulation Physics GPU based articulation solver using vGPU compute shaders. Replaces PhysX WASM articulation with pure WebGPU implementation. Based on: Stable Cosserat Rods (SIGGRAPH 2025) Split position/rotation optimization Direct PBD Solver for Stiff Rods (Bender et al. 2018) XPBD compliance for stable stiffness Key Features: Parallel Jacobi solver for position constraints Quaternion orientation updates for twist Graph coloring for dependency free parallel solving Warm starting for faster convergence Classes Method Signature Summary Create a rope articulation Step simulation on GPU Read particle positions back to CPU Get particles synchronously (uses last known positions) Functions <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


sim/physics/GPUClothSolver.js
Classes
class GPUClothSolver
Constants
Notes & Examples
Physics Engine Integration

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: GPU Cloth Physics Solver Position based dynamics (PBD) solver running entirely on GPU Handles cloth, ropes, soft bodies with collision detection Small Substeps Approach (Miles Macklin, NVIDIA 2019): Uses 8 substeps with 1 iteration each for better stability than 1 substep with 8 iterations. This is especially important for stiff constraints like ropes and tightly woven cloth. OGC Contact Model (Chen et al., SIGGRAPH 2025): Uses Offset Geometric Contact for penetration free simulation. Barrier energy prevents penetration before it occurs, with orthogonal contact forces along face normals. Classes Method Signature Summary Step cloth simulation using small substeps approach Per Miles Macklin (NVIDIA 2019): n small timesteps with 1 iteration each is more stable than 1 large timestep with n iterations. Add a sphere collider Add a plane collider (infinite half space) Add a capsule collider (OGC enabled) Clear all colliders Set OGC contact parameters at runtime Create cloth mesh from grid Constants — Default substeps (small substeps approach) — Default iterations per substep <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt


Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


async createSpatialHashFromVGPU(vgpu, options = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes CPU based spatial hash grid for physics broad phase Method Signature Summary Clear all objects from the grid Get cell coordinates from world position Insert an object with AABB into the grid Remove an object from the grid Update an object's position in the grid Query potential collision candidates for an AABB Get all potential collision pairs Uses the "home cell" optimization from GPU Gems to avoid duplicate pairs AABB overlap test Get statistics about the grid GPU accelerated spatial hash grid using WebGPU compute shaders Method Signature Summary Update object AABBs from CPU data Run broad phase collision detection Functions Calculate Morton code for 3D position Parameters: (number) — X coordinate (0 1023) (number) — Y coordinate (0 1023) (number) — Z coordinate (0 1023) Returns: Morton code Simple hash function for cell coordinates Factory function to create GPUSpatialHashGrid from VirtualGPU Parameters: (Object) — VirtualGPU instance (Object) — Grid options Returns: Initialized grid <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable


collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


computeWeight(px, py, pz, gx, gy, gz, cellSize = 1.0)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: MLSMPMSolver.js Moving Least Squares Material Point Method Hybrid Lagrangian Eulerian simulation for: Soft body deformation (jelly, flesh) Fracturing materials (snow, sand) Fluid solid interaction Large deformation scenarios Algorithm Overview: 1. P2G (Particle to Grid): Transfer mass/momentum using quadratic B splines 2. Grid Update: Apply forces, boundaries, compute velocities 3. G2P (Grid to Particle): Gather velocity, update deformation gradient 4. Advection: Move particles Key Features: Fixed point atomics for P2G scatter (WebGPU has no f32 atomics) SoA (Structure of Arrays) for GPU coalescing Multiple constitutive models (Neo Hookean, Fixed Corotated, Snow) Performance Target: 100k particles < 10ms Classes Method Signature Summary Compute Lamé parameters from Young's modulus and Poisson's ratio Method Signature Summary Method Signature Summary Initialize GPU resources Add a particle Add a box of particles Upload particles to GPU Update uniform buffer Step simulation (CPU fallback for debugging) Destroy GPU resources Functions Quadratic B spline weight Parameters: (number) — Distance in grid cells Returns: Weight Quadratic B spline derivative Parameters: (number) — No description in source JSDoc. Compute 3D weight and gradient for a particle grid pair Constants — Grid cell size (1 unit typical) — Default grid dimensions — Quadratic B spline support radius (3 cells) — Constitutive model types — Material presets <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase


collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


sim/physics/MeshCutter.js
Classes
class Plane
class Vertex
class Triangle
class MeshFragment
class MeshCutter
Notes & Examples
Physics Engine Integration

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: MeshCutter.js Mesh Cutting and Fragment Generation System Cuts meshes along Voronoi cell boundaries to create realistic fragments. Uses plane triangle intersection to split geometry. Features: Triangle classification (front/back/spanning) Edge plane intersection computation Cap geometry generation for cut faces UV coordinate preservation Convex hull generation for PhysX Classes Method Signature Summary Create plane from point and normal Create plane from three points Signed distance from point to plane Classify point relative to plane Get intersection point of line segment with plane Method Signature Summary Interpolate between two vertices Method Signature Summary Get triangle normal Get triangle centroid Classify triangle vs plane Split triangle by plane, returns { front: [], back: [] } Triangulate a convex polygon Method Signature Summary Add triangle to fragment Add cap triangle (cut surface) Compute bounding box Compute centroid Estimate volume using bounding box Generate convex hull points for PhysX Convert to GPU ready vertex/index arrays Method Signature Summary Cut a mesh by a single plane Cut mesh by multiple planes (from Voronoi boundaries) Cut mesh using Voronoi cell assignments (centroid based, fast but imprecise). Only assigns whole triangles — does NOT split triangles across cell boundaries. Use cutByVoronoiExact for low poly meshes that need proper clipping. Cut mesh into exact Voronoi cells using bisecting plane clipping. For each seed, clips the full mesh against bisecting planes with every other seed, keeping only the region closest to that seed. Properly splits triangles that span cell boundaries and generates cap geometry at cuts. Collect edges that lie on


keeping only the region closest to that seed. Properly splits triangles that span cell boundaries and generates cap geometry at cuts. Collect edges that lie on the cutting plane Generate cap triangles for cut surface Get a tangent vector perpendicular to normal <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


decimateGrid(vertices, indices, gridSize = DEFAULTGRIDSIZE)

decimateQEM(vertices, indices, targetRatio = DEFAULTTARGETRATIO, maxIterations = Infinity, options = null)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: MeshDecimation.js Mesh Simplification for Debris Reduces triangle count for debris meshes to maintain performance. Two algorithms available: 1. Grid Based (Fast): O(n) Good for realtime debris Snap vertices to grid Merge coincident vertices Remove degenerate triangles 2. QEM (Quality): O(n log n) Better for LOD generation Quadric Error Metrics Edge collapse with priority queue Preserves shape better Performance Targets: Grid: 10k verts → 500 verts in <1ms QEM: 10k verts → 500 verts in <50ms Classes Method Signature Summary Method Signature Summary Method Signature Summary Create from plane equation ax + by + cz + d = 0 Create from triangle Add another quadric Evaluate error at point Find optimal point that minimizes error Returns null if matrix is singular Method Signature Summary Method Signature Summary Decimate a mesh Decimate with automatic method selection based on size Functions Fast grid based mesh decimation Parameters: (number[]) — Flat array [x,y,z, x,y,z, ...] (number[]) — Triangle indices (number) — Cell size for vertex snapping Returns: } QEM based mesh decimation Parameters: (number[]) — Flat array [x,y,z, ...] (number[]) — Triangle indices (number) — Target vertex count ratio (0.1 = 10% of original) (number) — Max edge collapses (for realtime) Returns: } Constants — Default grid cell size for grid based decimation — Default target reduction ratio — Maximum QEM iterations per frame (for realtime) <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase


sim/physics/MeshParticles.js
Classes
class DebrisParticle
class MeshParticleSystem
Constants
Re-exports
Notes & Examples
Physics Engine Integration

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Single debris chunk with mesh, physics, and rendering state Method Signature Summary Reset for pool reuse Initialize from cluster data Generate LOD meshes Update LOD based on camera distance Get current mesh for rendering Method Signature Summary Initialize GPU resources Spawn debris from a cluster Spawn multiple debris from connectivity result Update all particles Get instance data for GPU rendering Upload instance data to GPU Get active particles for rendering Clear all particles Destroy GPU resources Get stats Constants — Maximum active debris particles — LOD distance thresholds — LOD decimation ratios — Minimum voxels to create debris (smaller clusters become particles) — Maximum voxels per debris chunk — Debris lifetime in seconds — Debris states Re exports <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See


collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


distanceToOffsetSphere(p, center, radius, r)

distanceToOffsetPlane(p, planePoint, planeNormal, r)

distanceToOffsetCapsule(p, a, b, radius, r)

distanceToOffsetBox(p, center, halfExtents, rotation, r)

evaluateAnalyticSDF(shape, params, lx, ly, lz)

distanceToOffsetTriangle(p, v0, v1, v2, r)

applyOGCForce(particle, distance, normal, contactRadius, stiffness, dt)

applyOGCPositionCorrection(particle, distance, normal, contactRadius, compliance, dt)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: OGCContact.js Offset Geometric Contact Model Implementation of the SIGGRAPH 2025 paper: "Offset Geometric Contact for Real Time Simulation" Chen et al., 2025 Key features: Guaranteed penetration free simulation Orthogonal contact forces (along face normals, not radial) Large contact radius support (2 5mm without artifacts) No CCD required uses conservative displacement bounds GPU efficient parallel local operations The offset geometry approach inflates primitives by a contact radius, computes distance to the offset surface, and applies smooth barrier energy that activates before penetration occurs. Classes Manages OGC contacts for a simulation Method Signature Summary Clear all colliders Add a sphere collider Add a plane collider Add a capsule collider Add a ground plane at y=0 Find closest contact for a point Solve contacts for an array of particles (PBD style) Functions OGC Barrier energy function g(d) = d²(2r d)² Smooth C1 continuous, zero at d=0 and d=2r Maximum at d=r Parameters: (number) — Distance to offset surface (number) — Contact radius Returns: Barrier energy Derivative of barrier energy: g'(d) = 2d(2r d)(2r 2d) Used for force computation Parameters: (number) — Distance to offset surface (number) — Contact radius Returns: Barrier force magnitude (negative = repulsive) Normalized barrier energy for stability Scales to [0, 1] range with maximum at d=r Parameters: (number) — Distance (number) — Contact radius Returns: Normalized energy [0, 1] Compute conservative displacement bound for a vertex This is the maximum safe movement before barrier check is needed Parameters: (number) — Current distance to nearest obstacle (number) — Contact radius r Returns: Maximum safe


safe movement before barrier check is needed Parameters: (number) — Current distance to nearest obstacle (number) — Contact radius r Returns: Maximum safe displacement Distance from point to offset sphere (sphere with radius inflated by r) Parameters: (Array) — Point [x, y, z] (Array) — Sphere center [x, y, z] (number) — Original sphere radius (number) — Contact offset radius Returns: } Distance and contact normal Distance from point to offset plane (plane pushed by r along normal) Parameters: (Array) — Point [x, y, z] (Array) — Point on plane (Array) — Plane normal (unit vector) (number) — Contact offset radius Returns: } Distance from point to offset capsule Parameters: (Array) — Point [x, y, z] (Array) — Capsule start [x, y, z] (Array) — Capsule end [x, y, z] (number) — Capsule radius (number) — Contact offset radius Returns: } Distance from point to offset box (OBB with offset shell) Handles rotated boxes by transforming into local space. Parameters: (Array) — Point [x, y, z] (Array) — Box center [x, y, z] (Array) — Half extents [hx, hy, hz] (Array) — Quaternion [x, y, z, w] (identity = [0,0,0,1]) (number) — Contact offset radius (particle radius added by caller) Returns: } Evaluate an analytic SDF in local space (no transform — caller handles that). Parameters: (string) — SDF shape type ('box','sphere','capsule','cylinder','torus') (Array) — Shape parameters [p0, p1, p2, p3] (number) — Local space X (number) — Local space Y (number) — Local space Z Returns: } Signed distance and outward normal Distance from point to offset edge (line segment with offset radius) Parameters: (Array) — Point [x, y, z] (Array) — Edge start [x, y, z] (Array) — Edge end [x, y, z] (number) — Contact offset radius Returns: } Distance from point to offset triangle (triangle with offset


— Edge start [x, y, z] (Array) — Edge end [x, y, z] (number) — Contact offset radius Returns: } Distance from point to offset triangle (triangle with offset shell) Uses the face normal for orthogonal contact Parameters: (Array) — Point [x, y, z] (Array) — Triangle vertex 0 (Array) — Triangle vertex 1 (Array) — Triangle vertex 2 (number) — Contact offset radius Returns: } Apply OGC barrier force to a particle Parameters: (Object) — Particle with position, velocity, invMass (number) — Distance to offset surface (Array) — Contact normal (number) — Contact radius r (number) — Barrier stiffness (number) — Time step Apply OGC position correction (for PBD style solvers) Parameters: (Object) — Particle with position, i


sim/physics/PBDRagdoll.js
Classes
class CapsuleCollider
class RagdollBoneData
class PBDRagdoll
Constants
Notes & Examples
Physics Engine Integration

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Method Signature Summary Update world position from bone transform Check collision with point Check collision with another capsule Method Signature Summary Method Signature Summary Build the skeleton structure Assign each bone's jointType + jointLimits from the canonical RagdollBuilder/JointLimits anatomical profile (CANONICAL JOINT LIMITS, keyed by canonical slot via RAGDOLL BONE TO SLOT) instead of a hand duplicated local table — the single source of truth every other humanoid ragdoll consumer already reads from. Initialize from animation pose Activate ragdoll physics Deactivate ragdoll, return to animation Apply impulse to a bone Apply explosion force Update ragdoll physics Get bone world position Get all bone transforms for rendering Check if currently ragdolling Set gravity direction Initialize earthquake response system Apply earthquake shaking to ragdoll Get earthquake response state Set earthquake sensitivity Integrate with SeismicSystem Constants — Bone identifiers — Joint types — Ragdoll states — Default humanoid measurements (meters) — Joint angle limits (radians) <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters,


Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


class DistanceConstraint extends PBDConstraint

class AngleConstraint extends PBDConstraint

class AttachmentConstraint extends PBDConstraint

class BendingConstraint extends PBDConstraint

class SpringConstraint extends PBDConstraint

class CohesionConstraint extends PBDConstraint

class LongRangeAttachmentConstraint extends PBDConstraint

class VolumeConstraint extends PBDConstraint

class ShapeMatchingConstraint extends PBDConstraint

class PressureConstraint extends PBDConstraint

class DensityConstraint extends PBDConstraint

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PBDSolver.js Position Based Dynamics Solver Implements XPBD (Extended Position Based Dynamics) for: Rope/cable physics (line segments) Soft body deformation Ragdoll skeletons Cloth simulation Key Algorithms: Verlet integration (position based) Gauss Seidel constraint projection Graph coloring for GPU parallelization XPBD compliance for stable stiffness Small Substeps Approach (Miles Macklin, NVIDIA 2019): "n small timesteps with 1 iteration each 1 large timestep with n iterations" This provides better stability for stiff systems (ropes, cloth). We use 8 substeps with 1 iteration each by default (equivalent to but more stable than 1 substep with 8 iterations). OGC Contact Model (Chen et al., SIGGRAPH 2025): Uses Offset Geometric Contact for penetration free collision. Barrier energy prevents penetration before it occurs. Performance Targets: 1000 particles + 3000 constraints: <5ms 8 substeps, 1 iteration per substep (small substeps approach) Classes PBD Particle with position, velocity, and inverse mass Method Signature Summary Set position and sync previous Set velocity (adjusts previous position) Check if particle is fixed Base constraint class Method Signature Summary Set stiffness via compliance (XPBD) Lower compliance = stiffer Distance constraint maintains rest length between two particles Method Signature Summary Project constraint (Gauss Seidel) Angle constraint limits angle between three particles Method Signature Summary Attachment constraint pins particle to world position Simple and stable: directly moves particle toward target Method Signature Summary Bending constraint maintains angle between 3 particles UNTESTED Used for hair, grass, stiff ropes Method Signature


toward target Method Signature Summary Bending constraint maintains angle between 3 particles UNTESTED Used for hair, grass, stiff ropes Method Signature Summary Spring constraint UNTESTED Unlike distance constraint, springs can compress AND extend (Hooke's law) Method Signature Summary Cohesion constraint UNTESTED Particles attract each other within a radius (like water droplets) Method Signature Summary Long Range Attachment (LRA) Constraint Creates distance constraints from fixed/anchor particles to all particles in a rope. This dramatically improves convergence for long ropes (100+ segments). Reference: Kim et al. 2012 "Long Range Attachments A Method to Simulate Inextensible Clothing in Computer Games" Reference: Müller 2017 "Long Range Constraints for Rigid Body Simulations" Key idea: Instead of only having adjacent distance constraints, we create constraints from the anchor to every Nth particle along the rope. This allows the solver to propagate length corrections globally in fewer iterations. Method Signature Summary Volume constraint preserves volume of a tetrahedron (4 particles) C = V V0 = 0, where V = (1/6) (p1 p0) · ((p2 p0) × (p3 p0)) Method Signature Summary Shape Matching constraint restores N particles to their original shape Based on "Meshless Deformations Based on Shape Matching" (Müller 2005) Method Signature Summary Pressure constraint internal pressure for closed meshes (balloons) Works with N particles forming a closed surface Method Signature Summary SPH Density constraint maintains constant density (fluids) Based on "Position Based Fluids" (Macklin & Müller 2013) Method Signature Summary Method Signature Summary Add a particle Add a distance constraint Add an angle constraint Add attachment constraint Add Long Range Attachment (LRA) constraints


Method Signature Summary Add a particle Add a distance constraint Add an angle constraint Add attachment constraint Add Long Range Attachment (LRA) constraints for a rope/chain This dramatically improves convergence for long ropes (100+ particles) Add a bending constraint between 3 particles UNTESTED Maintains angle at center particle (particleB) Add a spring constraint UNTESTED Unlike distance, springs can compress AND extend (Hooke's law) Add a cohesion constraint Particles attract each other within a radius Add volume constraint (4 particles forming tetrahedron) Used for soft body simulation Add shape matching constraint (N particles) Restores particles to original shape works with ANY number of particle


createRootLink(articulation, options = {})

createChildLink(articulation, parentLink, options = {})

createRope(world, startPos, endPos, segments = 10, options = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PhysXArticulations.js PhysX Articulation Support Articulations are optimized for chains of connected bodies like: Ropes and cables Ragdolls Robotic arms Vehicles (suspensions) Per NVIDIA PhysX Best Practices: "Articulations are much better at simulating articulated objects. They can be used to model better ropes, bridges, vehicles, or ragdolls out of the box, without the need for workarounds." Articulations provide: Better stability than joint chains Reduced jitter More accurate constraint solving Built in tendon support for muscle simulation Functions Create a reduced coordinate articulation (PhysX 5.x) Parameters: (Object) — Physics world (Object) — Articulation options Returns: Articulation handle Create the root link of an articulation Parameters: (Object) — Articulation handle (Object) — Link options (position, geometry, etc.) Returns: Link handle Create a child link attached to a parent link Parameters: (Object) — Articulation handle (Object) — Parent link handle (Object) — Link and joint options Returns: Link handle Add articulation to scene (must be called after all links are created) Parameters: (Object) — Articulation handle Create a rope using articulations Per NVIDIA: "Use spheres instead of capsules. A rope made of spheres will be more stable." Parameters: (Object) — Physics world (Array) — Start position [x, y, z] (Array) — End position [x, y, z] (number) — Number of rope segments (Object) — Rope options Returns: Articulation handle Update articulation link positions from simulation Parameters: (Object) — Articulation handle Returns: Array of {position, rotation} for each link Destroy an articulation and clean up resources Parameters: (Object) — Articulation handle


handle Returns: Array of {position, rotation} for each link Destroy an articulation and clean up resources Parameters: (Object) — Articulation handle <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


createD6Joint(world, bodyA, bodyB, options = {})

createRevoluteJoint(world, bodyA, bodyB, options = {})

createSphericalJoint(world, bodyA, bodyB, options = {})

createDistanceJoint(world, bodyA, bodyB, options = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PhysX Joint Creation API Exposes D6, revolute, distance, and spherical joints for articulated bodies Functions PhysX Joint Creation API Exposes D6, revolute, distance, and spherical joints for articulated bodies Create a D6 joint (6 degrees of freedom most flexible joint type) Parameters: (Object) — PhysX world (Object) — First body (or null for world anchor) (Object) — Second body (Object) — Joint configuration Returns: Joint handle with control methods Create a revolute joint (hinge joint 1 rotational DOF) Parameters: (Object) — PhysX world (Object) — First body (Object) — Second body (Object) — Joint configuration Returns: Joint handle Create a spherical joint (ball and socket 3 rotational DOF) Parameters: (Object) — PhysX world (Object) — First body (Object) — Second body (Object) — Joint configuration Returns: Joint handle Create a distance joint (maintains distance between two points) Parameters: (Object) — PhysX world (Object) — First body (Object) — Second body (Object) — Joint configuration Returns: Joint handle <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use


kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


cookAndRegisterTriangleMeshForWorld(world, meshId, positions, indices)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Local register helpers (avoid circular import with PhysXPhysicsWorld) Functions Re exports <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


sim/physics/PhysXModule.js
Functions
ensurePhysXModule()
Re-exports
Notes & Examples
Physics Engine Integration

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Functions Re exports <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


setKinematicPose(world, handle, position, rotation = [0, 0, 0, 1])

raycastWorld(world, origin, direction, maxDistance)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Functions Move a kinematic body to a new pose (PhysX setKinematicTarget — the solver sweeps it there over the next step, pushing dynamic bodies out of the way instead of teleporting through them). Used for script driven obstacles (e.g. AI traffic cars that dynamic bodies must collide with). Parameters: (object) — No description in source JSDoc. (number) — body handle from createBody (simMode 'kinematic') (number[]) — [x,y,z] (number[]) — [x,y,z,w] Update a body's collision filter data based on EntityFlags Call this when EntityFlags.collisionLayer, collisionMask, or collisionMode changes Parameters: (object) — Physics world (number object) — Body handle or body object (object) — Updated EntityFlags component data Returns: True if update succeeded Re exports <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics ·


to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


sim/physics/PhysXVehicle.js
Re-exports
Notes & Examples
Physics Engine Integration

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Compatibility entry point. Implementation is split by vehicle subsystem in ./vehicle so existing engine and playground import paths remain stable. Re exports , <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


createPhysicalMaterial(presetKey, overrides = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PhysicalMaterialPresets.js — Real world material property presets Each preset defines how a shape behaves physically: density for mass, elasticity for springback, hardness for deformation resistance, brittleness for shatter vs bend, and fracture configuration. Used by the PhysicalMaterial ECS component and EditorPhysicalMaterial bridge. Functions Get a full material preset by key (returns a shallow copy). Parameters: (string) — — e.g. 'steel', 'wood' Create a PhysicalMaterial component value from a preset key, with optional property overrides. Parameters: (string) — No description in source JSDoc. (Object) — No description in source JSDoc. Compute mass from material density and collider volume. Parameters: (Object) — — PhysicalMaterial component (number[]) — — [hx, hy, hz] from collider (string) — — 'box', 'sphere', 'capsule', etc. Returns: mass in kg Constants — All preset keys. <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying


: Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


sim/physics/PhysicsSchema.js
Functions
getSimModeId(modeName)
getSimModeName(modeId)
getColliderShapeId(shapeName)
getColliderShapeName(shapeId)
getCollisionMask(...layerNames)
layersCollide(maskA, maskB)
validatePhysicsBody(config)
validateCollider(config)
validatePhysicsMaterial(config)
createDefaultPhysicsBody()
createDefaultCollider(shape = "box")
createDefaultJoint(type = "fixed")
createDefaultPhysicsWorld()
getPhysicsMaterial(name)
Constants
Notes & Examples
Physics Engine Integration

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PhysicsSchema.js Unified JSON Schema for Physics System Defines consistent data structures for: Body types (dynamic, kinematic, static) Collider shapes (box, sphere, capsule, mesh) Joint types (D6, revolute, spherical, distance) Collision layers and masks Material properties (friction, restitution) All physics code should use these schemas for consistency. Functions Get simulation mode ID from name Get simulation mode name from ID Get collider shape ID from name Get collider shape name from ID Get collision layer mask from layer names Check if two layer masks collide Validate physics body configuration Validate collider configuration Validate physics material Create default physics body config Create default collider config Create default joint config Create default physics world config Get physics material by name Constants — Physics simulation modes — Collider shape types — Joint types for articulated bodies — D6 joint axis motion types — D6 joint axes — Collision layer definitions (bitmask) — Physics material schema Compliant Contacts (PhysX 5.1+): Set restitution to a NEGATIVE value to enable spring damper contact model. This provides more stable collision behavior for complex contact configurations. restitution = springStiffness (negative enables compliant mode) damping = damping ratio for the spring compliantAcceleration = true to use acceleration spring (mass independent) — Preset physics materials Note: Negative restitution enables compliant (spring damper) contacts — Physics body schema — Collider schema — Joint schema — Physics world configuration — Standard convex collider mesh IDs <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides


schema — Physics world configuration — Standard convex collider mesh IDs <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


createSDFFromMesh(vertices, indices, options = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SDFCollision.js Signed Distance Field Collision Detection Based on GPU Gems 3, Chapter 34: "Signed Distance Fields Using Single Pass GPU Scan" and PhysX 5.x SDF collision geometry. SDFs provide: Accurate collision for concave shapes without decomposition Efficient distance queries for soft body interactions Smooth contact normals for stable simulation Fast ray/sphere casting The SDF stores the signed distance to the nearest surface at each point: Negative inside the object Positive outside the object Zero on the surface Classes 3D SDF Grid for collision detection Method Signature Summary Sample an SDF function into the grid Get the signed distance at a world position using trilinear interpolation Get gradient (surface normal) at a point using central differences Get voxel value at grid coordinates Sphere cast against SDF Check collision between a point/sphere and the SDF Functions Create SDF collider from mesh using jump flooding algorithm This is a simplified CPU version GPU version would be faster Parameters: (Float32Array) — Mesh vertices (Uint32Array) — Mesh triangle indices (Object) — Options Returns: SDF grid Constants — SDF primitive functions — SDF combination operations <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters,


Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


sim/physics/SeismicSystem.js
Classes
class FaultLine
class SeismicWave
class Earthquake
class SeismicSystem
Constants
Notes & Examples
Physics Engine Integration

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SeismicSystem.js Tectonic Simulation and Earthquake Events Simulates geological activity on the planet: Tectonic fault lines with stress accumulation Earthquake event triggering when stress exceeds threshold Seismic wave propagation (P waves, S waves, surface waves) Distance based attenuation Character/entity response integration Wave Types: P waves (Primary): Compressional, fastest, travels through solids/liquids S waves (Secondary): Shear, slower, solids only Surface waves: Slowest, most destructive, along surface Classes Represents a tectonic fault line Method Signature Summary Accumulate stress over time Release stress (earthquake) Get closest point on fault to a position Propagating seismic wave Method Signature Summary Update wave propagation Get wave amplitude at distance from epicenter Get wave intensity at a position Get shaking vector at position Complete earthquake event with multiple wave types Method Signature Summary Update earthquake Get combined shaking at position Get magnitude category Method Signature Summary Add a fault line Manually trigger an earthquake Update seismic simulation Get total shaking at a position Check if destruction should occur at position Add event listener Remove event listener Get nearest fault to position Generate random fault network Get stats Constants — Wave types — Wave speeds (m/s, scaled for game) — Earthquake magnitude scales — Default seismic parameters <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision


detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ShockPropagation.js Shock Propagation for Stable Stacking Based on "Nonconvex Rigid Bodies with Stacking" (Guendelman et al., SIGGRAPH 2003) and NVIDIA PhysX best practices. Problem: Standard iterative solvers struggle with deep stacks of objects. Objects at the bottom don't "know" about the weight above them, causing jitter and instability. Solution: Process contacts in a specific order, propagating forces from the ground upward through the contact graph. This ensures each layer is stable before processing the next. Key Techniques: Contact graph construction Topological sorting by "height" from ground Bottom up constraint solving Velocity level shock propagation Classes Shock propagation solver for stable stacking Method Signature Summary Clear all contacts for a new frame Add a body to the contact graph Add a contact between two bodies Build level structure from contact graph Uses BFS from static (ground) bodies Solve all contacts using shock propagation Solve a single contact constraint Solve friction constraint Get debug info about the contact graph Functions Integrate shock propagation with existing physics world Call this after broad/narrow phase but before velocity integration Parameters: (Object) — Physics world (Array) — Contact pairs from narrow phase (number) — Time step <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced:


accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


sim/physics/SpatialIntegritySystem.js
Classes
class SpatialIntegritySystem
class ChunkIntegrityTracker
Constants
Notes & Examples
Physics Engine Integration

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SpatialIntegritySystem.js Coordinate Validation & Correction Ensures spatial integrity for planetary scale worlds: O(1) position lookup via composite keys Fast checksum validation for corruption detection World tick based temporal tracking Authority snapshots for rollback/sync Drift correction for network sync Designed for minimal overhead while providing strong guarantees. Classes Method Signature Summary Initialize with external systems Get current tick from world time Register an entity's position Unregister an entity Update an entity's position Generate position key from coordinates Add entity to position index Remove entity from position index Validate a single entity's position Validate and auto correct an entity Batch validate entities (call each frame) Validates a subset of entities per frame for minimal overhead Take a snapshot of all positions at current tick Get snapshot at or before a specific tick Rollback an entity to a previous snapshot Call each frame to perform maintenance Update memory usage statistics Get all entities at a position Get entity's registered position Get all entities in a category Check if position is occupied Get record for entity Get system statistics Print stats to console Verify integrity of all records Clear all data Specialized integrity tracking for chunk positions Uses integer coordinates for exact matching Method Signature Summary Register a chunk Unregister a chunk Validate chunk position Check if chunk is registered Get all registered chunk keys Compute checksum for chunk coordinates Get stats Constants <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and


Get stats Constants <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


expandAABBByVelocity(aabb, velocity, dt, margin = 0.01)

timeOfClosestApproach(posA, velA, radiusA, posB, velB, radiusB)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SpeculativeContacts.js Speculative Continuous Collision Detection Based on "Speculative Contacts" (Bullet Physics) and PhysX eSPECULATIVE CCD. Traditional CCD is expensive as it requires time of impact (TOI) calculations. Speculative contacts provide a cheaper alternative: 1. Expand AABBs by velocity dt to predict where objects will be 2. Generate contacts for all potentially overlapping pairs 3. Add velocity constraints to prevent future penetration Benefits: Cheaper than sweep based CCD Prevents tunneling for most cases Works well with iterative solvers Limitations: Can cause "ghost collisions" with thin objects Not as accurate as full CCD for very fast objects Classes Speculative contacts solver Method Signature Summary Clear all contacts Generate speculative contacts for potentially colliding pairs Solve all speculative contacts Solve a single speculative contact Solve friction for a contact Get debug info Functions Expand AABB by velocity to get speculative bounds Parameters: (Object) — Original AABB {minX, minY, minZ, maxX, maxY, maxZ} (Array) — Linear velocity [vx, vy, vz] (number) — Time step (number) — Extra margin for numerical safety Returns: Expanded AABB Calculate time of closest approach between two moving spheres Used for speculative contact timing Parameters: (Array) — Position of sphere A (Array) — Velocity of sphere A (number) — Radius of sphere A (Array) — Position of sphere B (Array) — Velocity of sphere B (number) — Radius of sphere B Returns: Time of closest approach (0 to Infinity) Enable speculative CCD on a PhysX rigid body This configures the PhysX specific flags for speculative contacts Parameters: (Object) — PhysX rigid dynamic actor (Object) — PhysX


CCD on a PhysX rigid body This configures the PhysX specific flags for speculative contacts Parameters: (Object) — PhysX rigid dynamic actor (Object) — PhysX module <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Functions Constants Re exports <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


sim/physics/StructuralIntegrity.js
Classes
class StructuralNode
class StructuralEdge
class StructuralIntegritySolver
Constants
Notes & Examples
Physics Engine Integration

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: StructuralIntegrity.js Structural Integrity and Collapse System Implements realistic structural mechanics for destructible buildings: Iterative relaxation solver for force propagation Stress accumulation and breaking thresholds Connectivity analysis with flood fill from anchors Chain reaction cascading collapse Based on constraint relaxation similar to Verlet physics but for structural connections rather than particle positions. Classes A node in the structural graph (corresponds to a fragment or chunk) Method Signature Summary Get total weight (mass gravity) Check if this node is an anchor Apply damage to this node Reset per frame state An edge connecting two structural nodes Method Signature Summary Get the other node in this edge Apply load to this edge Reset per frame state Check if edge can transmit force Main structural integrity system Method Signature Summary Add a node to the structure Remove a node and its connections Connect two nodes Set a node as an anchor (connected to ground) Auto detect anchors based on Y position (nodes touching ground) Main update run one frame of structural simulation Propagate anchor distances using BFS Calculate loads from top down (weight accumulation) One iteration of stress relaxation Check for and handle breaks Find regions disconnected from anchors Apply slow natural stress relief Apply damage at a point (explosion, impact, etc.) Apply impulse (directional force) at a point Build structure from fragments Build structure from voxel chunks Clear all structure data Get all falling nodes Get stress visualization data Load configuration from engine.cfg section Constants <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics


nodes Get stress visualization data Load configuration from engine.cfg section Constants <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


sim/physics/TreePhysics.js
Classes
class TreeVoxelBody
class TreePhysicsSystem
Notes & Examples
Physics Engine Integration

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: TreePhysics.js Teardown style Tree Physics System Features: Trees must spawn on solid ground (validated placement) Root connection tracking (trees anchored at base) Structural integrity cut trees fall realistically Physics body conversion when disconnected Based on Teardown's structural integrity system where objects fall when disconnected from anchors (ground). Classes Represents a tree's voxel structure for physics Method Signature Summary Calculate mass, center of mass, bounding box Check if tree has valid root connection to ground Start falling (called when disconnected from ground) Update physics simulation Find ground Y level at current position Called when tree settles on ground after falling Get world positions of all voxels (accounting for physics transform) Manages all tree physics in the world Method Signature Summary Set chunk manager reference for world queries Check if a world position has solid ground Validate tree placement location Check if position is underwater Register a tree for physics tracking Remove a tree from tracking Called when voxels are modified check affected trees Update physics simulation Check all trees for root connection Update statistics Get all falling trees for rendering Force a tree to fall (for testing or player actions) Get debug info <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and


broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


sim/physics/UnifiedDamageSystem.js
Classes
class DamageEvent
class UnifiedDamageSystem
Constants
Notes & Examples
Physics Engine Integration

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: UnifiedDamageSystem.js Cross System Damage Integration Connects all destruction systems so everything affects everything: Particles damage voxels (erosion, accumulation) Particles damage meshes (impact fracture) Mesh debris creates voxel craters Voxel explosions affect mesh structures Acts as the central hub for damage propagation between systems. Classes Represents a damage event that propagates through systems Method Signature Summary Central damage system that coordinates between all subsystems Method Signature Summary Initialize with system references Initialize GPU connectivity (requires device) Queue a damage event for processing Create explosion damage Process all pending damage events Check particle collisions and create damage events Process a single damage event Handle particle impacting voxels/meshes Handle mesh debris creating craters Handle explosion damage to all systems Handle generic damage Damage voxels in a radius Remove voxels in sphere (guaranteed removal) Create debris particles from removed voxels Check for chain reaction explosions Get material name from ID Get damage history for replay Clear damage history Load configuration from engine.cfg section Constants — Damage types <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics


bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


sim/physics/VoronoiFracture.js
Classes
class VoronoiFracture
Constants
Notes & Examples
Physics Engine Integration

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: VoronoiFracture.js GPU accelerated Voronoi Fracture System Uses Jump Flooding Algorithm (JFA) to compute 3D Voronoi diagrams for realistic mesh fracturing. Seeds are placed based on impact location and fracture patterns. Algorithm: 1. Place seed points (impact based or pattern based) 2. Run JFA to compute nearest seed for each voxel 3. Extract cell boundaries as fracture planes 4. Cut mesh along planes to create fragments Classes Method Signature Summary Initialize the fracture system Compute Voronoi diagram for fracturing Destroy GPU resources Constants — Predefined fracture patterns for different impact types <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine


createVoxelMeshCollider(device, options = {})

createCascadedVoxelCollider(device, options = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: VoxelMeshCollision.js Voxel based Mesh Collision for Particles and Ropes Voxelizes meshes into an occupancy grid with compressed normals for efficient GPU collision detection. This allows particles and ropes to collide with arbitrary mesh geometry beyond simple AABBs. Representation (per voxel, 32 bits total): Bit 31: Occupancy flag (1 = solid) Bits 30 21: Normal X (10 bits, signed normalized) Bits 20 11: Normal Y (10 bits, signed normalized) Bits 10 1: Normal Z (10 bits, signed normalized) Bit 0: Reserved Features: GPU mesh voxelization via compute shader Compressed normal storage (10 10 10 2 format) Cascaded/multi resolution support GPU collision queries for particles Cache and reuse voxelized meshes Classes Method Signature Summary Upload mesh triangles and voxelize Create collision bind group for particle buffers Run particle voxel collision Clear the mesh cache CascadedVoxelCollider Multi resolution voxel collision with LOD levels Uses multiple grid resolutions for efficient collision: LOD 0: Fine (128³) Near particles, high accuracy LOD 1: Medium (64³) Mid range particles LOD 2: Coarse (32³) Far particles, fast queries Method Signature Summary Voxelize mesh at all LOD levels Get appropriate LOD collider based on distance VoxelCacheManager Persistent cache for voxelized meshes Saves/loads voxelized mesh data to avoid re voxelization. Uses IndexedDB for persistence. Method Signature Summary Save voxel data to persistent cache Load voxel data from cache Check if key exists in cache Clear all cached data Functions Helper: Convert mesh vertices/indices to triangle buffer format Parameters: (Float32Array) — Vertex positions (x,y,z,x,y,z,...) (Uint32Array Uint16Array) — Triangle


Convert mesh vertices/indices to triangle buffer format Parameters: (Float32Array) — Vertex positions (x,y,z,x,y,z,...) (Uint32Array Uint16Array) — Triangle indices Returns: Triangle data for voxelization Helper: Compute mesh AABB Parameters: (Float32Array) — No description in source JSDoc. Returns: } <! HUMAN NOTES Notes & Examples Physics Engine Integration The physics system provides rigid body dynamics, collision detection, and raycasting. Bodies have shapes (box, sphere, mesh), mass properties, and constraints. The GPU physics engine accelerates broad phase collision detection and particle systems. Example: Creating physics bodies Advanced: Collision detection and raycasting Advanced: Constraints and joints Advanced: Continuous collision detection (CCD) Gotchas: Units : Physics uses meters, kilograms, seconds. A 1 unit cube is 1 meter. Time step : Fixed time step (1/60) gives stable simulation; variable dt causes explosions. Collision layers : Use collision masks to filter what collides (player vs enemy, bullet vs world). Sleeping : At rest bodies sleep to save CPU — wake them before applying forces. See also: Physics · GPU Physics Engine