workers/CompressionWorker.js

workers/CompressionWorker.js
Exports
Notes & Examples
Editor Extension System

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: CompressionWorker Offloads timeline/history compression to background thread Uses delta+entropy residual encoding for lossless reconstruction Exports No ES module exports detected in this file. <! HUMAN NOTES Notes & Examples Editor Extension System The editor supports extensions via the same Plauna component system as apps. Extensions can add panels, tools, menu items, and hooks into the engine. They run with elevated 'editor' capability granting access to the scene graph, asset database, and build pipeline. Example: Editor extension adding a custom panel See also: Editor Overview


workers/ProfilerCanvasWorker.js

workers/ProfilerCanvasWorker.js
Exports
Notes & Examples
Editor Extension System

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ProfilerCanvasWorker.js OffscreenCanvas worker for profiler rendering Moves ALL canvas rendering off the main thread: Timeline graph Thread lanes Flame graph bars Main thread only sends frame data, worker handles all drawing. Exports No ES module exports detected in this file. <! HUMAN NOTES Notes & Examples Editor Extension System The editor supports extensions via the same Plauna component system as apps. Extensions can add panels, tools, menu items, and hooks into the engine. They run with elevated 'editor' capability granting access to the scene graph, asset database, and build pipeline. Example: Editor extension adding a custom panel See also: Editor Overview


Engine Architecture

Net & Collab (engine/net/, engine/collab/)

How the engine's subsystems compose through the ECS and an event bus, all running on a single shared WebGPU device. Engine Architecture How the engine's modules compose. The engine is organized as independent subsystems that communicate through the ECS and an event bus, all running on a single shared WebGPU device. High level structure Core ( ) The lowest layer. Notable sub areas: — the WebGPU device and the VGPU abstraction ( ), multi queue, bind groups, streaming, memory tracking, recovery, canvas bootstrap. This is what the OS's GPU device broker builds on. + — declarative render/compute pass graph and the per frame pipeline. — task scheduling ("processes"), including async compute. — GPU and host memory managers, object pools, mapped buffer rings, vertex pools. , , , , , , , , , — supporting services. — asset/resource loading and lifetime. ECS ( ) State model for the whole engine. — entity lifecycle. — component schema definitions (large; the canonical component catalog). — schema migration / repair of component data. , , , , , — the moving parts. Systems read and mutate components; rendering and simulation are driven from ECS state. Render ( ) Turns ECS state into frames. Renderers: , , world/preview/minimap renderers. , culling ( ), , . Sub areas: , , , , , , , , , , , , , . Sim ( ) GPU first simulation, driven each tick by : , , , , , . Net & Collab ( , ) — , , , . — the multi user mesh: identity, crypto, integrity, presence, signaling, host migration, fast channel, scene/transform sync. The OS uses this for cross tab/peer IPC and multi user scenarios. Gameplay ( ) (including , the Tier 1 capability gate stand in), ( ), , , . How the OS reuses the engine The OS does not reimplement these — see Architecture Overview for the mapping of OS concerns onto engine


Engine Architecture

stand in), ( ), , , . How the OS reuses the engine The OS does not reimplement these — see Architecture Overview for the mapping of OS concerns onto engine modules (GPU, scheduler, memory, events, resources). See also GPU Device Sharing. Engine API Reference — generated per file from source.


Audio System

Audio System
Architecture
Patch system
Node types
Material-to-sound mapping
Spatial audio
Synthesis modules
Key files

A fully procedural audio engine — node-graph patch synthesis, 30+ node types, material-to-sound mapping from particle state, spatial audio, and physical-modeling synths. Audio System A fully procedural audio engine with node graph synthesis, material to sound mapping, spatial audio, and real time particle driven sound generation — no pre recorded samples required. Architecture Three execution paths converge on the same patch format: Patch system A patch is a JSON descriptor defining a node graph of audio generators and processors — the universal currency of the audio system. Node types 30+ node types organized by category: Category Node types Generators Oscillator, Noise, GrainCloud Processors Filter, Delay, Reverb, Compressor, Waveshaper Modulators LFO, ADSR, Envelope, RandomWalk Physics models KarplusStrong, CombFilter, FMOperator, Waveguide, ModalBank Atoms CrackleAtom, HissAtom, RumbleAtom, ImpactAtom Output Output, SoundBlender Material to sound mapping maps particle substance properties to audio parameters in real time, so burning, flowing, or colliding particles generate sound procedurally: Temperature → pitch, brightness, crackle intensity. Density → body/weight of the sound. Velocity → whoosh intensity, impact force. Phase → which procedural patch to use (fire, water, wind). Spatial audio provides 3D positional audio with distance attenuation, reverb zones, and environmental effects. Sources are positioned in world space and attenuated by listener distance. Synthesis modules Waveguide — bidirectional delay line physical model for string/tube sounds (damping, reflection, excitation). Modal bank — resonant filter bank with material presets (metal, glass, wood) using Bessel zeros for accurate modal frequencies. Noise generator — 8 noise colors via Voss McCartney:


Audio System

filter bank with material presets (metal, glass, wood) using Bessel zeros for accurate modal frequencies. Noise generator — 8 noise colors via Voss McCartney: white, pink, brown, blue, violet, velvet, grey, crackle. Key files File Purpose Main thread node creation (30+ types) Node type registry and categories Physical modeling waveguide Resonant modal bank Material→audio parameter mapping Particle→audio bridge 3D spatial audio


Curl Noise Flow Atlas

Curl Noise Flow Atlas
Pipeline
Scaling model
Selection and rendering semantics
Studies
Controls
Research basis
See also

Architecture, controls, performance policy, and scientific scope of the adaptive WebGPU Curl Noise playground demo. Curl Noise Flow Atlas Curl Noise Flow Atlas is an adaptive GPU tracer demo in the Playground. It combines a shared periodic curl field with Particle Storm's high count compute density architecture and five authored flow studies. The demo visualizes procedural incompressible style flow. It is not a Navier Stokes solver, fluid pressure simulation, or claim of physically exact continuous incompressibility after texture filtering. Pipeline bakes three decorrelated potential channels into an 3D texture. A second compute pass reads periodic neighbors and writes the centered difference curl into a separate volume. The shared stencil makes discrete divergence cancel on the bake lattice before half float quantization. Trilinear interpolation can introduce residual divergence between texels, so the demo describes the result as procedural curl flow rather than exact computational fluid dynamics. (Source: .) The bake limits unfiltered octaves to the volume's sample density and rejects configurations with fewer than two lattice samples per base noise cell. At the default period of 16, a 64³ field uses two octaves, 128³ uses three, and 256³ uses four. Runtime work then becomes one filtered field lookup per tracer instead of repeated scalar noise evaluations. The direct fallback in uses the same three component potential construction. (Sources: , .) Scaling model Each tracer stores three bounded positions and normalized lifetime in two packed values. gives uniform precision across the fixed domain. Velocity remains derived from the flow field, which keeps live state at 8 bytes without counting a retained or non simulated tier as full dynamics. (Source: .) One compute


Curl Noise Flow Atlas

derived from the flow field, which keeps live state at 8 bytes without counting a retained or non simulated tier as full dynamics. (Source: .) One compute invocation unpacks a tracer, samples and applies the field, advances lifetime, repacks state, projects the result, and optionally adds one integer contribution to one of eight density planes. Two dimensional dispatch avoids the one dimensional workgroup count ceiling. State grows in adapter probed chunks, shaders compile before large state allocation, and size dependent targets commit only after asynchronous WebGPU validation and out of memory scopes succeed. A failed resize retains the last valid image. (Sources: , .) The governor has no configured particle count ceiling. It grows until measured frame pressure, WebGPU's 32 bit identity space, or allocation failure stops it. Per pass GPU timestamps separate fused simulation from resolve and presentation cost. Two timestamped empty markers distinguish the recurring density clear from transient state resets before the compute pass without replacing optimized commands with a slower compute clear. Reset and reactivation samples remain visible in telemetry but are excluded from governor learning. The governor also requires two fresh timestamp intervals before acting, so one cold sample cannot force a quality step. A frame cadence fallback still calibrates on adapters without timestamp queries. The HUD reports estimated GPU memory because it includes state, density, HDR history, and both field volumes. (Source: .) Under the State First rasterizer policy, four authored emitter cohorts act as bounded semantic proxies for the packed GPU population. The demo submits one aggregate bucket plan per sampled frame; it never reads individual tracer state back to JavaScript or creates


Curl Noise Flow Atlas

the packed GPU population. The demo submits one aggregate bucket plan per sampled frame; it never reads individual tracer state back to JavaScript or creates one CPU object per tracer. The selected , , , , or representation is packed into the existing uniform block and changes the density deposition footprint and weight. It does not delete, freeze, or change the 8 byte simulation state. Native policy retains the original field style deposition. (Sources: , , .) Selection and rendering semantics The demo always keeps at least , or 62.5%, of active tracers eligible for density rasterization. It changes the quota by at most one cohort per adjustment. A low discrepancy permutation distributes changes within ea


ECS v2

ECS v2
Quick example
Core concepts
Worlds
Entities
Components
Systems
Execution phases
Archetype storage
Component healing
Entity lifecycle
Prefabs
World snapshots
Key files

The Entity-Component-System core — worlds, generational entity IDs, data components, phased systems, archetype storage, component healing, prefabs, and snapshots. ECS v2 Entity Component System architecture: entities are IDs, components are data, systems are functions. No inheritance and no scene graph — just fast, flat, data oriented design. Quick example Core concepts Worlds A world is a container for entities, components, and systems. Most apps use a single world, but you can create multiple for isolation (e.g. a UI world separate from gameplay). The world tracks: — current tick count, elapsed time, fixed delta. — registered system list. — per system timing for profiling. — ordered execution phases. Entities An entity is a generational ID — a 32 bit integer encoding an index and a generation counter. This prevents dangling references: if entity slot 5 is destroyed and reused, the old ID (generation 1) won't match the new occupant (generation 2). ID encoding: the lower 20 bits are the entity index (max 1M entities); the upper bits are the generation counter. Decode via → . Components Components are plain data objects attached to entities by name. The engine defines a standard schema in with normalization and validation: Component Key fields Purpose position, rotation, scale Spatial placement velocity, mass, type Rigid body dynamics shape, size, offset Collision shapes meshId, materialId, visible Visual representation type, color, intensity, range Light sources fov, near, far, projection View configuration preset, rate, lifetime Particle spawning speed, radius, destination AI pathfinding ownerId, priority Network sync Systems Systems are registered functions that execute each frame in a defined phase order. They process entities by querying for required components.


ECS v2

sync Systems Systems are registered functions that execute each frame in a defined phase order. They process entities by querying for required components. Execution phases Systems are grouped into phases that execute in order. The default phases are: Phase Purpose Typical systems Input processing, AI decisions InputSystem, AISystem Physics simulation, movement PhysicsSystem, MovementSystem Collision response, constraints CollisionSystem, ConstraintSystem Prepare render data CameraSystem, LightSystem Cleanup, UI sync AnimationSystem, UISync Two step functions exist: — runs all kind systems (fixed timestep). — runs all kind systems (variable timestep). Archetype storage Components are stored in archetype based storage ( ). Entities with the same set of components are grouped together for cache friendly iteration. The storage handles: Component add/remove — moves entities between archetypes. Query matching — finds all entities with a given component set. Sparse set indexing — O(1) component access by entity ID. Component healing validates and repairs component data using the schemas in . It normalizes vectors, clamps values, and fills missing fields with defaults. This makes save/load robust — corrupted or outdated save data is automatically healed. Entity lifecycle Prefabs defines reusable entity templates (spawnables) with pre configured components and SDF collision shapes: World snapshots Capture and restore world state for save/load, rewind, or debugging: Key files File Purpose , , , , phase scheduling, dependency ordering Component storage, queries, sparse set indexing Component schemas with types and normalization Auto repair invalid component data High level entity deletion with GPU cleanup Spawnable entity templates with SDF shapes


Galaxy Mythic Spiral Atlas

Galaxy Mythic Spiral Atlas
Rendering pipeline
Light, dust, and color
Adaptive scale
Studies
Controls
Research basis
See also

Architecture, art direction, performance policy, controls, and scientific limits of the adaptive WebGPU Galaxy playground demo. Galaxy Mythic Spiral Atlas Galaxy Mythic Spiral Atlas is an adaptive GPU orbital tracer demo in the Playground. It combines observed spiral galaxy structure with five deliberately enhanced fantasy studies. This page is for developers who tune its morphology, rendering, or performance governor. An orbital tracer is a procedural sample that follows an analytic galactic orbit. The demo is not a self gravitating N body simulation, and it does not use FMM to approximate pairwise gravity. Its scientific content is limited to population distributions, differential rotation, a separate spiral pattern speed, dust offsets, and transparent measurement semantics. Rendering pipeline Every active tracer stores two 16 bit angular values in one : orbital phase and epicyclic phase. One initialization bit distinguishes untouched allocation from live state. The compute shader advances this state before density selection, so the HUD's simulated count means actively updated orbital states. (Sources: , .) The position model derives disk radius, vertical thickness, stellar family, luminosity, and structural variation from a stable integer identity. Disk stars follow a cored to flat rotation curve. Spiral arms use a logarithmic phase field whose pattern speed remains distinct from each star's orbital speed. Arm width increases outward, while segment masks and feathers prevent perfectly continuous ribbons. Selected studies add a bar, tidal wake, resonant ring, outer arc, or sparse polar veil. (Sources: , .) Light, dust, and color The eight plane atlas stores old stars, young stars, H II emission, and dust in two atomic shards per family. Shards reduce avoidable


Galaxy Mythic Spiral Atlas

.) Light, dust, and color The eight plane atlas stores old stars, young stars, H II emission, and dust in two atomic shards per family. Shards reduce avoidable contention without changing the resolved image. The resolve applies wavelength dependent transmission: Optical depth measures how strongly material attenuates light along a sampled path. This lets dust lanes darken stars instead of adding nearly black light to an additive target. A separate rim term adds faint scattered color. Young blue populations and coral or magenta H II regions sit at different arm phase offsets from dust. (Source: .) The palette is an enhanced visualization, not unaided human vision. It retains a warm old population, cooler young clusters, emission regions, and dark dust, then grades those components into each study's fantasy palette. The final pass blooms only energy above a threshold, adds rare background stars and core diffraction, and applies a hue preserving ACES curve once at presentation. (Source: .) Adaptive scale The demo begins with one million active tracers and grows in allocation chunks. It has no configured particle count ceiling. Growth ends only when measured pressure, the 32 bit identity range, or a recoverable WebGPU allocation failure requires it. Shaders compile before large buffers allocate, and size dependent targets replace the previous target only after validation and out of memory scopes succeed. (Source: .) The fused pass simulates every active tracer and selects a spatially distributed subset for density work. Selection never falls below , or 62.5%, and changes by at most one cohort per governor adjustment. A low discrepancy permutation spreads a quota change across each 256 tracer block. It does not remove one visible contiguous population. The HUD says selected


Galaxy Mythic Spiral Atlas

A low discrepancy permutation spreads a quota change across each 256 tracer block. It does not remove one visible contiguous population. The HUD says selected , because projection and frustum rejection occur after quota selection. (Sources: , , .) GPU timestamps separate recurring clear, fused simulation density work, resolve, history, and presentation. A recursive model estimates fixed, simulated million, and selected million costs. The governor waits for fresh samples, excludes reset and target rebuild transients, and changes one quota slot per frame under pressure. Camera, study, and pointer discontinuities reject short term history to prevent ghost trails. (Source: .) State First planning uses four aggregate stel


Engine Getting Started

Engine Getting Started
Prerequisites
Bootstrap entry points
Import maps
Minimal flow
Where to look next
See also

Bring the engine up in a browser and understand its bootstrap entry points and minimal frame flow. Engine Getting Started Bring the engine up in a browser and understand the bootstrap entry points. Assumes Install & Run is done. Prerequisites A current browser that exposes WebGPU on the machine. Verify both and a successful call. The repo served over HTTP ( ). Bootstrap entry points Pick the bootstrap that matches your use case: Entry Use when You want the full engine runtime. You also want the editor + Plauna wired ( , ). You're building an app level entry. Import maps The engine groups imports into barrels so you can pull in a coherent set without long relative paths: — engine wide. — ECS. — rendering. — math. — dev tools. Minimal flow The engine is GPU first and ECS driven, so a typical session: 1. Bootstrap the engine against a WebGPU canvas (acquires the device + frame pipeline). 2. Create or load an ECS world . 3. Spawn entities and attach components (see for the component catalog). 4. Register systems (render, sim) that run each frame. 5. Start the frame loop — draws from ECS state; advances simulation. Note: Exact function signatures are generated into the Engine API Reference by . Run it, then browse for , , , and . Where to look next Rendering: — start with and . Simulation: . ECS components: . GPU layer: . See also Engine Architecture. Boot Sequence (OS level).


GPU Physics Engine

GPU Physics Engine
Architecture
PhysX 5 feature parity
GPU physics modules (15 files)
Existing engine systems
Features that exceed PhysX 5
Core rigid body pipeline
Extended simulation
Geometry & queries
Constants & limits
Pipeline execution order
Design decisions

A WebGPU compute physics engine with PhysX 5 feature parity — 15 WGSL modules covering rigid bodies, broadphase/narrowphase, the TGS solver, CCD, vehicles, character controller, FEM soft bodies, triggers, and mesh/heightfield queries. GPU Physics Engine A WebGPU compute based physics engine with full PhysX 5.4.1 feature parity: 15 modules in ( 400 KB total), all shaders in WGSL. It is a parallel implementation — no PhysX code is modified — designed for a future native migration. Every GPU accelerated feature in PhysX 5.4.1 (rigid bodies, broadphase, contact gen, solver, CCD, vehicles, CCT, soft bodies, triggers, scene queries, heightfield, triangle mesh) has a dedicated module. See the parity table. Architecture Key principles: WebGPU compute shaders (WGSL) for all parallel workloads. CPU orchestration for serial logic (islands, CCT, scene queries). Fixed pre allocated GPU buffers (PhysX 5 pattern) — overflow warns, never crashes. SoA (structure of arrays) layout for GPU cache efficiency. No PhysX code modified — parallel implementation for future migration. PhysX 5 feature parity Audited against PhysX 5.4.1. GPU physics modules (15 files) PhysX 5 feature Module Status GPU Rigid Bodies Built GPU Broadphase Built GPU Contact Gen (PCM) Built GPU Constraint Solver (TGS) Built Convex Hull Cooking Built Raycasting Built Speculative CCD Built Vehicle SDK Built Character Controller Built FEM Soft Bodies Built Trigger Events Built Scene Queries Built Heightfield Terrain Built Triangle Mesh Collider Built Existing engine systems Modules in the parent directory cover additional PhysX features, referenced from the GPU barrel export: PBD cloth ( ), articulations ( ), SDF mesh geometry ( ), XPBD solver ( ), MLS MPM soft body ( ), OGC contact ( ), CPU CCD ( ), shock propagation ( ),


GPU Physics Engine

export: PBD cloth ( ), articulations ( ), SDF mesh geometry ( ), XPBD solver ( ), MLS MPM soft body ( ), OGC contact ( ), CPU CCD ( ), shock propagation ( ), destruction ( + ), convex decomposition ( ), voxel mesh collider ( ), and GPU spatial hash ( ). Features that exceed PhysX 5 OGC contact model ( ) — SIGGRAPH 2025 penetration free barrier energy. MLS MPM ( ) — handles topology changes (melting, fracture). LBM wind ( ) — Lattice Boltzmann GPU wind field. Thermal particles ( ) — phase transitions, buoyancy, chemistry. Rope interaction ( ) — per fiber thermal (burn, wet, corrode). Core rigid body pipeline — central world manager owning all GPU buffers, body descriptions, and the island manager. 5 WGSL shaders (integrate, applyDeltas, deriveVelocity, sleepDetect, clearForces); CPU union find island manager (sleeping islands skip GPU dispatch); SoA layout; body types Dynamic (0), Kinematic (1), Static (2); shapes Sphere (0), Box (1), Capsule (2). — spatial hash broadphase. 4 WGSL shaders (computeAABB, clearHash, insertHash, findPairs); 27 neighbor cell query with layer/mask filtering. — analytic shape shape contact generation with persistent contact manifold (PCM). Pairs: sphere sphere, sphere box, box box (SAT 15 axes), sphere capsule, capsule capsule, ground plane. Contact data: normal, penetration, point, accumulated impulse, local anchors (A+B), featureId. — TGS Soft iterative solver (Box2D v3 / Catto 2023). Contact solve (bias velocity, Coulomb friction cone, restitution, impulse clamping, warm starting); D6 joint (ball, hinge, fixed, distance, cone limits); post solve relaxation pass. — CPU Quickhull 3D + GPU upload (PhysX 64 vertex GPU limit). — GPU parallel raycasting (ray sphere/box/capsule) with workgroup reduction; CPU fallback for synchronous queries. —


GPU Physics Engine

+ GPU upload (PhysX 64 vertex GPU limit). — GPU parallel raycasting (ray sphere/box/capsule) with workgroup reduction; CPU fallback for synchronous queries. — speculative CCD: AABB expansion by velocity × dt for CCD flagged bodies (bit 25), then TOI via conservative advancement. Extended simulation — per wheel suspension (spring damper) + tire force (simplified Pacejka); CPU manager for input and gear shifting; presets sedan/sports/truck/offroad; , , drive types FWD/RWD/AWD. — CPU driven kinematic CCT: Quake style recursive slide move (max 4 bounces), downward raycast ground detection (skin width 0.08 m, step height 0.35 m), 45° slope limit, step climbing, capsule (default) or box shape. — FEM soft body on tetra


Engine

Engine
In this section
Deep dives
Reference
Module map
Related concepts

Section index for the engine — the WebGPU runtime foundation of the stack (overview, architecture, getting started, API reference). Engine The WebGPU runtime foundation of the stack. Source: . In this section Overview — what the engine is and its modules. Architecture — how core, ECS, render, sim, net, and gameplay compose. Getting Started — bootstrap entry points and minimal flow. Deep dives Virtual GPU (vGPU) — the GPU abstraction every system builds on. ECS v2 — worlds, entities, components, systems, archetype storage. Rendering — the multi pass pipeline, lighting, and compositing. MorphField R2 — semantic fields, compiled Fieldlets, certified queries, assets, renderer contracts, and the gate controlled delivery checklist. Shaders & WGSL — modular shaders, the composer, and the preprocessor. Particle System — GPU particles, matter states, and the sim pipeline. Galaxy Mythic Spiral Atlas — adaptive orbital tracers, dust extinction, and fantasy spiral studies. Curl Noise Flow Atlas — packed GPU tracers and compute density flow art. Kuramoto Resonance Field — CPU and GPU phase oscillator labs with high count HDR visualization. Physics & Simulation — cloth, rope, fluids, and rigid bodies. GPU Physics Engine — WebGPU compute physics with PhysX 5 parity. Math Library — 350+ pure vector/matrix/quaternion/packing functions. Math Contract — required matrix, quaternion, projection, tolerance, and parity rules for shared math. Audio — procedural node graph synthesis and particle driven sound. Reference API Reference — per file symbol reference generated from source by (browse ). Module map Related concepts GPU Device Sharing Data Flow


Kuramoto Resonance Field

Freqora attribution and scientific boundary

The Playground's CPU and GPU Kuramoto laboratories, their exact mean-field dynamics, high-density HDR visualization, performance governors, controls, and scientific boundary. Kuramoto Resonance Field The Kuramoto Resonance Field demos turn collective phase synchronization into a large, interactive HDR sculpture. The CPU and GPU versions share the same five studies and renderer, but they integrate different numbers of real oscillators. Both report the integrated oscillator count separately from the stateless field sample count. Run the CPU demo Run the GPU demo Mathematical model For oscillator phase $\theta i$, natural frequency $f i$ in cycles per second, coupling $K$, and optional external drive $\lambda$, the demos integrate $$ \frac{d\theta i}{dt} = 2\pi f i + \frac{K}{N}\sum j \sin(\theta j \theta i) + \lambda\sin(2\pi f d t \theta i). $$ The complex order parameter $$ Z 1 = \frac{1}{N}\sum j e^{i\theta j}=R 1e^{i\psi} $$ measures first harmonic synchronization. $R 1$ approaches zero for a distributed population and one for phase lock. The demos also report $R 2= N^{ 1}\sum j e^{2i\theta j} $, which exposes two cluster and standing wave structure that can be hidden by $R 1$ alone. Uniform global coupling has an exact linear time reduction: $$ \frac{K}{N}\sum j\sin(\theta j \theta i) =K\left(\operatorname{Im}(Z 1)\cos\theta i \operatorname{Re}(Z 1)\sin\theta i\right). $$ This identity replaces an $O(N^2)$ pair loop with one $O(N)$ order parameter reduction and one $O(N)$ integration pass. It is exact for the all to all, equal weight model; it is not an approximation and does not apply unchanged to an arbitrary weighted network. The background and canonical model are covered by the Kuramoto review by Acebrón et al.. CPU path The CPU demo uses at a fixed 120 Hz


Kuramoto Resonance Field

weighted network. The background and canonical model are covered by the Kuramoto review by Acebrón et al.. CPU path The CPU demo uses at a fixed 120 Hz simulation step. It computes $Z 1$, advances every active phase from the same immutable state, and swaps two typed array views without copying the completed population. An adaptive governor changes the number of real CPU oscillators only after sustained timing evidence; it does not slow simulation time to hide load. The original pairwise engine functions remain available for weighted or small networks. Their in place output path snapshots its source, so reusing the input array cannot turn a simultaneous Euler step into an order dependent update. GPU path The GPU demo stores one phase per oscillator and starts with 1,048,576 active phases on a desktop adapter. Each fixed 120 Hz substep performs this sequence: 1. Integrate phases using the current reduced order parameter. 2. Accumulate partial $Z 1$ and $Z 2$ sums from the newly written phase buffer. 3. Complete the reduction before the next substep reads it. Separate uniform buffers preserve the time and parameters for every encoded substep. A near square two dimensional dispatch avoids the 65,535 workgroup limit on one dispatch dimension without dispatching a mostly empty 4,096 wide row. A persistent readback ring samples only the small order parameter result and rejects results from an earlier study generation. GPU timestamp queries, when supported, guide population growth using measured work instead of frame rate guesses alone. Study resets initialize and copy only the active range; newly exposed ranges are initialized as the population grows. The current desktop safety guard reserves at most $2^{24}$ real phases, subject to the adapter's storage buffer limit. This is


Kuramoto Resonance Field

as the population grows. The current desktop safety guard reserves at most $2^{24}$ real phases, subject to the adapter's storage buffer limit. This is an implementation allocation guard, not a theoretical Kuramoto limit. GPU implementations at the same $2^{24}$ scale have been reported in the literature; see Januszewski and Kostur's GPU Kuramoto implementation. High density field renderer The luminous field deliberately separates simulation state from display density. When field samples outnumber oscillators, repeated layers choose real oscillators by stable modulo identity; when oscillators outnumber samples, a rotating stratified mapping covers the complete population over time instead of permanent


Math Contract

Math Contract
Source of truth
Value representation
Matrix layout and order
Coordinate and camera rules
Projection depth
Quaternion rules
Units and ranges
Tolerance policy
Degenerate input policy
Determinism and side effects
WGSL parity
Acceptance checklist
See also

Contract for engine math values, matrix layout, quaternion order, WebGPU projection depth, units, tolerances, determinism, and WGSL parity. Math Contract This page defines the rules new engine, editor, Plauna, AGI, and WebGPU OS code must follow when it uses shared math. It locks the current runtime behavior before MathEngine grows beyond the existing modules. The contract is based on the current source in , , and . Source of truth Area Canonical source Notes Basic vectors, quaternions, and mat4 helpers Compatibility surface exported through , , and . Extended matrices Mat2/Mat3 and extended Mat4 helpers, including TRS compose/decompose. Extended quaternions Quaternion creation, conversion, interpolation, comparison, and orientation helpers. Camera projection/view composition Defaults to WebGPU projection depth for camera rendering. Gate 0 invariant tests Browser ES module checks for decompose, inverse, look at, WebGPU depth, quaternion, and camera finite output. New code should import from the narrow module it needs when possible. Broad app or compatibility surfaces may import from . Value representation Value Representation Contract Scalar JavaScript Use finite values unless the function explicitly documents non finite handling. Vec2 Plain array unless a specific API documents a typed array. Vec3 Plain array. World up is for camera helpers. Vec4 Plain array. Quaternion Identity is . and represent the same orientation. Mat3 Column major. Translation style 2D mat3 helpers store translation in the final column. Mat4 Column major. Translation lives at indices , , and . Functions must not mutate input arrays unless the name or signature makes mutation explicit, such as , , , or . Mutating the explicit parameter is allowed. (Source: , , .) Matrix layout and order Mat4


Math Contract

the name or signature makes mutation explicit, such as , , , or . Mutating the explicit parameter is allowed. (Source: , , .) Matrix layout and order Mat4 values use column major storage and column vector transform semantics. The engine applies the rightmost matrix first. is the camera contract used by . The same order should be used in render tests and tools. (Source: .) When composing transforms, use TRS helpers instead of manual index writes unless the code is a low level math helper. preserves translation and scale. If any scale axis is zero, near zero, or non finite, rotation is not recoverable, so it returns identity rotation instead of . (Source: ; verified by .) Coordinate and camera rules Rule Contract World up for camera and look at helpers. Camera forward in view space Negative Z. maps the target to negative Z. Transform forward treats forward as the negative local Z axis. View projection order . UI and DOM units Keep DOM/CSS pixel math outside core engine math unless a DOM specific adapter documents the conversion. The source currently has both render facing camera helpers and generic matrix helpers. New camera code should use or the WebGPU projection helpers from instead of reimplementing projection math. (Source: , .) Projection depth WebGPU render paths must use the WebGPU projection helpers. These map clip space Z into . Use case Helper Perspective, radians Perspective, degrees Orthographic Camera default with default options The legacy helpers , , and use OpenGL style depth. They remain available for compatibility and explicit OpenGL depth tests only. They must not be used in WebGPU render passes. (Source: ; verified by .) Quaternion rules Quaternions are . Rotation quaternions should be normalized before use in transforms, interpolation, and camera


Math Contract

(Source: ; verified by .) Quaternion rules Quaternions are . Rotation quaternions should be normalized before use in transforms, interpolation, and camera code. does not normalize for the caller. Pass a normalized axis or normalize the returned quaternion before using it as a rotation. and test assertions must treat and as equivalent orientations. (Source: .) Units and ranges Category Contract Angles Radians by default. Degree helpers include in the name. Time Seconds for runtime simulation and animation math unless the caller documents milliseconds. Color channels Normalized linear values for renderer math unless a function explicitly says sRGB or packed format. Depth WebGPU render depth is . Scale Zero scal


Math Library

Math Library
Design philosophy
Module map
Quick examples
Vectors
Matrices
GPU packing
Ray intersection

350+ pure, array-based, WebGPU-aligned math functions — vectors, matrices, quaternions, geometric primitives, GPU data packing, curves, color, and noise. Math Library 350+ pure functions for vectors, matrices, quaternions, geometric primitives, GPU data packing, and interpolation. All exported via and . Design philosophy Pure functions — no classes, no mutation of inputs; every function returns a new value. Array based — vectors are , quaternions are , matrices are . WebGPU aligned — projection matrices use a Z range (not like OpenGL). No dependencies — self contained, no external math libraries. For binding rules around matrix layout, multiplication order, quaternion order, projection depth, tolerance, and CPU/WGSL parity, see the Math Contract. Module map Module Functions Purpose 30 3D vectors: add, sub, scale, dot, cross, normalize, lerp, reflect, project, smoothDamp 12 2D vectors: add, sub, scale, dot, length, normalize, lerp, distance 15 Quaternions: slerp, fromAxisAngle, fromEuler, lookAt, multiply, inverse 15 4×4 matrices: perspective, orthographic, lookAt, inverse, multiply, fromRotationTranslation 8 Scalar: clamp, lerp, smoothstep, saturate, inverseLerp, remap 20 Rays: create, intersect (sphere, AABB, plane, triangle, capsule, OBB), transform 20 Planes: create, distance, project, intersect (ray, segment, plane), transform 15 Line segments: create, closest point (to point, segment, ray), distance 25 2D rectangles: create, contains, intersects, merge, grow, clamp 20 Dual quaternions: create, multiply, sclerp, transform point, toMat4 (DQS skinning) 20 GPU packing: half float, UNORM/SNORM, RGB9E5, R11G11B10F, octahedral normals 20 Geometry helpers: AABB, sphere, frustum, distance calculations 10 Color: HSL↔RGB, temperature→RGB, sRGB↔linear 15 Curves: bezier,


Math Library

octahedral normals 20 Geometry helpers: AABB, sphere, frustum, distance calculations 10 Color: HSL↔RGB, temperature→RGB, sRGB↔linear 15 Curves: bezier, catmull rom, hermite, arc length parameterization 10 Noise: simplex2D/3D, perlin, FBM, curl noise Quick examples Vectors Matrices GPU packing Ray intersection


MorphField R2 Renderer

Sparse residency shared by fields, voxels, and virtual textures

Nexel representation lab and truth chain

Structural Scale Lab and benchmark receipts

Ray-candidate regression resolution checkpoint

Phase 0: contracts, safety, and research baseline

Phase 1: certified analytic vertical slice

Phase 2: assets, spatial execution, and sparse residuals

Phase 4: oriented kernels, media, and bounded transparency

Phase 5: advanced lighting, path tracing, and adaptive quality

Phase 6: simulation and query integration

Phase 7: final Playground, hardening, and release gate

Architecture, public contracts, research provenance, verification evidence, and the gate-controlled implementation checklist for the additive MorphField renderer. MorphField R2 Renderer MorphField is an additive, opt in Engine renderer for semantic fields, sparse residuals, oriented kernels, and validated surface caches. A public Nexel describes scene intent. The compiler produces private Fieldlets and keeps the source scene authoritative. This page is the persistent R2 delivery record. An individual checklist box changes to only after its implementation, focused tests, and item specific evidence pass. A phase gate remains open until every required item and the integrated phase level evidence pass. Current release status Phase Gate Status on 2026 07 27 0. Contracts, safety, research Passed Twelve public Draft 2020 12 schema resources (eleven source resources plus the generated offline compound bundle), the checked mode specific capability profile, strict compiled ABI/query ingress, ownership, diagnostics, fixtures, provenance, and the frozen core profile baseline pass this gate. Release builders copy the schemas to their exact public routes. The current installed Chrome revision passes all 62 browser gates, including the 12 gate real device block. 1. Certified analytic slice Open Analytic compilation, CPU/GPU queries, conservative f32 certificates, direct tracing, a packed CPU built threaded GPU BVH, guarded stable analytic incremental projection and changed range GPU publication, close CSG/inside/seam/lifecycle coverage, and Playground scenes exist. A real compiler worker path, general incremental compilation, and the complete reference image gate remain open. 2. Assets and sparse residuals Open , certified CPU residual hierarchy, and representation planning exist. GPU


MorphField R2 Renderer

the complete reference image gate remain open. 2. Assets and sparse residuals Open , certified CPU residual hierarchy, and representation planning exist. GPU residency, radix/LBVH benchmarking, and fuzz evidence remain open. 3. Unified surface cache Open Regular extraction, rank aware QEF work, atomic publication, and clean room 2:1 transitions exist. Full Marching Cubes, Transvoxel compatibility, and manifold dual contouring gates remain open. 4. Kernels, media, transparency Open Bounded CPU kernel bins, certified medium integration, and layered OIT reference logic exist. Integrated GPU composition and stress gates remain open. 5. Lighting and quality Open Tail sensitive adaptive quality, native resolution automatic tiers, certified bound pruning, tier shadow policy, resolved/pending GPU admission guards, lighting selective lazy wavefront construction, hybrid shading, host safe composition, explicit scale depth aware reconstruction, and the renderer integrated bounded queue wavefront path pass the current portable and 12 gate real device suites. ReSTIR/SVGF/IBL and the complete reference image/energy gate remain open. 6. Simulation and queries Open Six external encoder GPU queries, fixed step scheduling, and compatible adapters exist. Full simulation parity and replay gates remain open. 7. Playground and release Open One public API demo exposes nine focused Nexel specimens, lighting and simulation scenarios, the independent Structural Scale Lab, validation controls, separated timing channels, and copyable receipts. Every specimen distinguishes semantic source, compiled family, active evaluator, query/collision availability, SDF/reference field classification, simulation ownership, and any diagnostic presentation glyph. The current source suite contains 62 gates: 50


MorphField R2 Renderer

availability, SDF/reference field classification, simulation ownership, and any diagnostic presentation glyph. The current source suite contains 62 gates: 50 device independent gates and 12 real device gates; all 62 pass on the current installed Chrome run with zero failures or skips. Adapter absence remains one explicit device required block. Long run benchmarks for every preset, release hardening, and the Full R2 gate remain open. The current code is a verified foundation and analytic vertical slice. It is not yet the Full R2 release. Architecture Source ownership is split by subsystem: Path Responsibility Nexel scene, validation, compiler, ABI, CPU BVH, and reference queries. Versioned encoding, decoding,


Engine Overview

Engine Overview
What it provides
Audience
Development principles
Top-level modules
Entry points
Next steps

The pure-browser, GPU-first runtime foundation — WebGPU device, frame graph, ECS, rendering, simulation, networking, and audio. Engine Overview The engine ( ) is the foundation of the whole stack: a pure browser, GPU first runtime providing the WebGPU device, frame graph, ECS, rendering, simulation, networking, and audio that every other subsystem builds on. What it provides A shared WebGPU device and frame pipeline (the OS's GPU service runs on this). An ECS for all runtime state. A rendering pipeline (passes, materials, shaders, lighting, post processing, volumes). Simulation systems (physics, particles, fluids, cloth, AI, world). Networking (protocol, replication, client/server) and a collab mesh. Audio , resources/assets , a modding layer, runtime UI , and dev tools . Audience Engine, graphics, and simulation developers. App developers usually consume the engine indirectly through the OS and Plauna; read this when you work on rendering, simulation, or low level GPU code. Development principles From : Pure browser runtime — no Node.js dependencies. GPU first — prefer compute shaders for heavy simulation. ECS driven — all state lives in components. Modular — each subsystem is independent and testable. Top level modules Module Path Purpose Core WebGPU device, frame graph/pipeline, math, memory, scheduler, platform, workers, save, profiling, ECS entities, components, systems, queries, storage, prefabs, world Render renderers, materials, passes, lighting, culling, post process, SDF, volumes, particles Sim physics, particles, fluids, cloth, AI, world simulation Net protocol, replication, client, server Collab multi user mesh: identity, integrity, presence, sync Audio audio core, synth, spatial audio Animation animation systems Gameplay rules, events, AI, narrative,


Engine Overview

multi user mesh: identity, integrity, presence, sync Audio audio core, synth, spatial audio Animation animation systems Gameplay rules, events, AI, narrative, perception Voxel / World , voxel and world systems Resources resource/package system Mod scripting API + sandbox UI / Tools , runtime UI, inspector/profiler Compat asset importers / compatibility Entry points — full engine bootstrap. — bootstrap that also wires the editor and Plauna ( ). — app level bootstrap. — import maps ( , , , , ). — version info. Next steps Engine Architecture — how the modules fit together. Engine Getting Started — boot and render something. Engine API Reference — per module symbol reference (run ).


Particle Long-Range Solvers

Particle Long-Range Solvers
Choose a backend
N-body encounter Playground
Configure a world
FMM pipeline
PME and experimental ESP
Validate and benchmark
Current limits
See also

Selection, configuration, implementation, and validation of the direct, FMM, PME, and experimental ESP particle-force backends. Particle Long Range Solvers The particle simulation has four mutually exclusive long range force backends. Use FMM for a large open domain, PME for a periodic domain, direct summation as the small system accuracy oracle, and ESP only as an experimental periodic alternative. These systems accelerate the same content dependent pair force as the existing N body solver; they are unrelated to Pai, BLT, HIER, or Ouroboros model training. (Sources: , , .) Choose a backend Backend Boundary Best fit Main tradeoff Open Small particle counts and reference validation Exact softened pair sum, but quadratic work Open Large or spatially clustered particle sets Approximate; current tree is uniform and capped at depth 5 Periodic Uniform periodic particle sets FFT/grid cost and periodic image physics Periodic Experiments with a smaller prolate window grid Wider grid assignment and real space work can erase the FFT saving Do not switch between open and periodic backends merely for speed. They solve different boundary value problems. FMM is the primary upgrade path for Particle Realms scenes because those scenes normally use an open world. Published comparisons likewise show that workload distribution matters: FMM can benefit strongly inhomogeneous systems while mesh methods can remain better for uniform periodic systems. GPU crossover points depend on hardware, particle distribution, requested accuracy, and expansion order. (Sources: Treecode and fast multipole method for N body simulation with CUDA, Adaptive fast multipole methods on the GPU, FMM and PME comparison.) N body encounter Playground The N Body Encounters demo separates gravitational accuracy from


Particle Long-Range Solvers

fast multipole methods on the GPU, FMM and PME comparison.) N body encounter Playground The N Body Encounters demo separates gravitational accuracy from visual sampling. Full precision macro bodies source and receive softened gravity through the open FMM backend. The 4,096 body Direct Reference uses a separate race free tiled direct kick. A packed 12 byte tracer population responds to at most three moving cluster cores, but never contributes mass to either force solve. The HUD reports mutual bodies, active tracers, quota selected tracers, allocated state, memory, solver timing, and FMM leaf diagnostics as separate quantities. (Sources: , .) The tracer renderer reuses the Particle Storm exact quota permutation. Every block of 256 active tracers contributes exactly candidates, the quality floor remains 160 of 256 candidates, and the governor changes no more than one cohort per adjustment. Tracer state has no preset count ceiling. Allocation stops at available GPU memory, storage binding limits, or the 32 bit identity limit. A learned cost model and separate GPU timestamps prevent expensive body solves from automatically thinning a cheap visual population. (Sources: , , .) The State First adapter submits one aggregate proxy for each active authored gravitating system plus one restricted tracer field proxy. This keeps bucket planning proportional to the number of semantic systems rather than the number of particles and avoids GPU readback. Raster profiles map to quota targets of , , , , or slots; the target is still approached by at most one slot per governor adjustment and can never cross the 62.5% floor. Bucket representation changes presentation policy only. It cannot alter macro body integration, tracer motion, allocation, or lifetime. (Sources: , .) The authored


Particle Long-Range Solvers

representation changes presentation policy only. It cannot alter macro body integration, tracer motion, allocation, or lifetime. (Sources: , .) The authored encounter studies use deterministic truncated disk, Plummer, or cored Dehnen like seeds. Restricted outer disk tracers add low mass visual resolution to bridges and counter tails, following the restricted particle approach used in foundational galaxy encounter work. These tracers are an artistic collisionless approximation. Color families, dust, starburst light, and sparkle are rendering proxies rather than gas dynamics, radiative transfer, or star formation. (Sources: Toomre and Toomre encounter models, , .) The 65,536 body Apex study is an explicit stres


Particle System

Particle System
Architecture
Per-frame pipeline
Emitter system
Matter states
Spawn shapes
GPU simulation
Advanced subsystems
Performance optimizations
Rendering
Audio integration
Key files
See also

The engine's flagship GPU particle system — matter states, emitters, the per-frame compute pipeline, advanced subsystems (thermal, SPH, flocking, bonds), performance tricks, and rendering. Particle System The engine's flagship subsystem: large scale GPU particles with physics, thermal simulation, chemistry, SPH fluids, SDF collision, flocking, and volumetric rendering. Everything runs on compute shaders via vGPU. Scale: the particle system spans 60+ simulation files and 30+ rendering files — the largest subsystem in the engine. This page covers the architecture and key concepts. Architecture Three distinct layers: Per frame pipeline Each frame in : 1. Emit — spawn new particles from active emitters into GPU buffers. 2. Alive list compaction — a GPU scan writes alive particle indices (skip dead slots). 3. Main sim — GPU compute: gravity, curl noise, forces, integration, lifetime. 4. Advanced systems — thermal, SPH, flocking, bonds, chemistry, constraints. 5. Sort — radix sort by camera distance for correct alpha blending. 6. Collisions — SDF collision against entity meshes + ground plane. 7. Light extraction — GPU compute finds the hottest particles → async readback → . 8. Render — SDF billboard at half res → additive composite onto the scene. Emitter system manages emitter presets and spawning. Matter states State Phase value Render mode Examples Solid Matte diffuse + specular Sparks, debris, snow Liquid Fresnel + refraction Water, blood, rain Gas Volumetric (Beer Lambert) Smoke, steam, fog Plasma Emissive glow Fire core, lightning, magic Spawn shapes provides configurable emission geometries: point , sphere (surface or volume), box , cone , ring (torus), and mesh surface (emit from mesh triangles via ). GPU simulation The core sim runs in — a large compute shader


Particle System

(surface or volume), box , cone , ring (torus), and mesh surface (emit from mesh triangles via ). GPU simulation The core sim runs in — a large compute shader processing all particles each frame. Buffer layout: Buffer Per particle data Stride Position 16 bytes Velocity 16 bytes Thermal 16 bytes Color 16 bytes packing: lower 8 bits = material index (0–15), upper bits = collision group ID. Encode: . Decode in WGSL: . Advanced subsystems Initialized via : Thermal & chemistry — temperature with material specific melt/boil points, latent heat, and phase transitions (16 material presets: water, metal, wax, lava, etc.). SPH fluids — smoothed particle hydrodynamics (pressure, viscosity, surface tension). SDF collision — particles collide with entity meshes via signed distance fields (sphere/box/cylinder), per entity SDF from . Flocking — boids (separation, alignment, cohesion) using a neighbor grid. Bonds — spring connections for soft body/cloth like behavior (async CPU readback for bond evaluation). Electromagnetic — electric/magnetic field forces, charged interactions. Constraints — distance/position/velocity constraints (rope, chains, attached particles). Event system — particle events (collision, death, threshold) that trigger sub emissions or gameplay actions. Performance optimizations Alive list compaction — a GPU scan builds an alive list of active indices; the main sim dispatches only threads via indirect dispatch. Radix sort — 4 bit radix sort replaces bitonic. For 100M particles: 24 dispatches (8 passes × 3) vs 289 for bitonic ( ). FBM noise pre bake — first bakes three decorrelated vector potential channels, then takes one periodic centered difference curl on the volume lattice. The octave count follows grid resolution and tiling period to avoid undersampling; at


Particle System

then takes one periodic centered difference curl on the volume lattice. The octave count follows grid resolution and tiling period to avoid undersampling; at period 16, 64³ uses two, 128³ uses three, and 256³ uses four. Configurations with fewer than two lattice samples per base noise cell are rejected. Creation resolves WebGPU validation and out of memory scopes before exposing the resources. Runtime tracers use one filtered instead of evaluating procedural curl per particle. (Source: .) Neighbor grid — spatial hash grid for O(1) neighbor queries (SPH, flocking, bonds), rebuilt each frame on GPU. Selectable long range solver — direct, open boundary FMM, periodic PME, or experimental periodic ESP. See Particle Long


Physics & Simulation

Physics & Simulation
Cloth simulation
Rope physics
Fluid simulation
Rigid body physics
PBD ragdoll
Simulation update
Key files

GPU-accelerated cloth, rope, fluids, and rigid bodies — the mass-spring cloth solver, PBD rope, SPH and Eulerian fluids, ECS rigid bodies, PBD ragdoll, and the per-frame simulation order. Physics & Simulation GPU accelerated cloth, rope, fluid volumes, and rigid body physics. All solvers run on compute shaders via vGPU. For the full WebGPU compute physics engine with PhysX 5 parity (rigid bodies, solver, CCD, vehicles, CCT, FEM soft bodies, mesh/heightfield queries), see GPU Physics Engine. Cloth simulation A mass spring cloth solver in . Each cloth is a grid of particles connected by structural, shear, and bending springs, solved on GPU compute. Configurable: stiffness (spring force coefficient), damping (velocity damping), per cloth gravity override, wind (directional force with turbulence noise), pin constraints (fixed vertices), and sphere/plane collision response. Rope physics A Position Based Dynamics (PBD) rope solver in . Ropes are chains of particles with distance constraints solved iteratively: PBD constraints — distance constraints with configurable compliance. Material properties — stiffness, damping, mass per unit length ( ). Particle interaction — ropes interact with the particle system ( ). GPU rendering — smooth tube rendering with normals and lighting ( ). Fluid simulation Two approaches: Lagrangian (SPH) — smoothed particle hydrodynamics via the particle system. Each fluid particle carries density, pressure, and viscosity; the solver computes inter particle forces using a neighbor grid ( ). Eulerian (grid based) — solves the Navier Stokes equations on a 3D grid using pressure projection and velocity advection, suitable for contained volumes (pools, rivers). Rigid body physics The ECS component drives rigid body simulation: body types (dynamic,


Physics & Simulation

and velocity advection, suitable for contained volumes (pools, rivers). Rigid body physics The ECS component drives rigid body simulation: body types (dynamic, kinematic, static), collider shapes (sphere, box, capsule, mesh via the component), forces (gravity, impulses, torques), and constraints (distance, hinge, ball socket). PBD ragdoll A Position Based Dynamics ragdoll solver for character physics — joint limits, bone chains, and muscle constraints. It integrates with the AGI system for learning based locomotion. Simulation update orchestrates all simulation systems each frame, in order: 1. ECS physics system tick (rigid bodies, colliders). 2. Cloth solver step (GPU compute). 3. Rope constraint solving (PBD iterations). 4. Particle simulation (main compute + advanced subsystems). 5. Fluid pressure solve (if active). Key files File Purpose Master simulation orchestrator Mass spring cloth solver Eulerian fluid volumes Rigid body physics system PBD rope solver Rope material properties SPH fluid solver Grid based fluid Distance/position constraints


EcsImports.js

EcsImports.js
Constants
Notes & Examples

<! 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. Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


EngineBootstrap.js

EngineBootstrap.js
Constants
Re-exports
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: EngineBootstrap.js Unified engine import for games and tests Single import point for all engine functionality: Math utilities ECS (Entity Component System) Rendering (meshes, shaders, pipelines) Tools (inspector, camera, physics sandbox) GPU utilities (buffers, WebGPU init) Simulation (particles, fluids) Configuration Constants Re exports , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , <! HUMAN NOTES


EngineBootstrap.js

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


EngineEditorBootstrap.js

EngineEditorBootstrap.js
Functions
async initializePlauna(options = {})
Constants
Re-exports
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: EngineEditorBootstrap.js Combined Engine + Editor entry point Use this as the entry point when you want the FULL library bundled: All engine modules (math, ECS, rendering, simulation, audio, tools) All editor modules (viewport, physics sim, particles, collab, UI) Usage: python bundle engine.py entry engine/EngineEditorBootstrap.js eager The bundled runtime exposes everything on window.PE / window.ParticleEngine: PE.vec3(), PE.createWorld(), PE.EditorApp, etc. Functions Constants Re exports , , , <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


EngineImports.js

EngineImports.js
Re-exports
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Global barrel for engine modules, grouped by domain. This is intended for games/tests/tools that want a single import and then access Math/Gpu/Ecs/Render/Tools/etc as namespaces. Re exports , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


MathImports.js

MathImports.js
Constants
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: MathImports: convenience barrel for engine math utilities. Provides both a grouped Math namespace and flat re exports for common ops. Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


RenderImports.js

RenderImports.js
Constants
Re-exports
Notes & Examples

<! 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. Constants Re exports <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


ToolsImports.js

ToolsImports.js
Constants
Re-exports
Notes & Examples


animation/index.js

animation/index.js
Exports
Notes & Examples

<! 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 No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


extractMotionClipFromFbxAscii(text, options = {})

extractMotionDatasetFromFbxAsciiEntries(entries, options = {})

async extractMotionDatasetFromFbxFiles(files, options = {})

async extractMotionDatasetFromFbxDirectoryHandle(dirHandle, 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. Functions <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


extractMotionDatasetFromGltf(gltf, options = {})

extractMotionClipFromGltf(gltf, animationIndex = 0, options = {})


animation/learning/MotionClip.js
Classes
class MotionClip
Notes & Examples

<! 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 <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


animation/learning/MotionDataset.js
Classes
class MotionDataset
Notes & Examples


buildJointPositionDataset(clip, options = {})

buildMotionFeatureIndex(dataset, options = {})

fillRagdollFeature(ragdoll, boneIndices, out, options = {})


animation/learning/MotionMatcher.js
Classes
class MotionMatcher
Notes & Examples


animation/learning/SkeletonHierarchy.js
Classes
class SkeletonHierarchy
Notes & Examples


animation/learning/index.js
Constants
Re-exports
Notes & Examples

<! 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. Constants Re exports , , , , , , , , , , , , <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/AssetCache.js

assets/AssetCache.js
Classes
class AssetCache
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/AssetCache.js — local engine cache (spec §3, cache://). Converted artifacts (engine binaries, preview meshes, thumbnails, colliders, SDFs, material packs) are cached under cache:// keyed by content hash so a re import of the same source is instant. The primary backend is the Origin Private File System (OPFS) — origin private and optimized for file access; an in memory Map backs environments without OPFS (Node tests, locked down contexts) so the rest of the runtime is backend agnostic. Classes Method Signature Summary Map a cache:// vpath (or bare key) to a flat, filesystem safe filename. Store bytes under a cache key. Returns the key written. Read bytes for a cache key, or null if absent. Best effort listing of known cache keys (memory index + OPFS entries). <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/AssetDeduper.js

assets/AssetDeduper.js
Functions
assetDeduperFallbackHash(data)
async hashContent(data)
classify(candidate, records)
Constants
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/AssetDeduper.js — content hash dedup (spec §3). Assets are deduplicated by source content hash. We separate source / mesh / material hashes so that the dedup rules can distinguish exact duplicates from variants and conflicts: same source hash = same source asset (exact duplicate) same name + different hash = version/conflict same mesh hash + diff material = variant same texture hash = shared texture Hashing prefers Web Crypto SHA 256; in a non secure context it falls back to a deterministic FNV 1a stamp (clearly tagged so callers know it isn't crypto). Functions Content hash of arbitrary data. Returns 'sha256:<hex ' (secure) or 'fnv1a:<hex ' (fallback). Async because Web Crypto digest is async. Classify a candidate against the existing records. Parameters: (Array) — existing AssetRecords Returns: } Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/AssetRecord.js

assets/AssetRecord.js
Functions
createAssetRecord(init = {})
createLicenseBlock(init = {})
licenseNeedsReview(license)
Constants
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/AssetRecord.js — the registry's record for one source asset. The asset registry (not the filesystem) is the source of truth. Each record tracks the source content hash, a primary virtual path, redundant backup paths, the set of converted engine artifacts, and license metadata. Records are deduplicated by source hash; variants/conflicts are linked, never merged blindly (see AssetDeduper / AssetRegistry). Functions Create an asset record. Parameters: (object) — No description in source JSDoc. License metadata is mandatory before import (unknown is allowed but flagged). Marketplace assets are licensed, not sold — track it and warn on restricted. True if the license is unknown or explicitly disallows engine conversion. Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/AssetRegistry.js

assets/AssetRegistry.js
Classes
class AssetRegistry
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/AssetRegistry.js — the source of truth (spec §3, rule 3). The registry (not the filesystem) owns asset identity. Sources are deduplicated by content hash; the registry links exact duplicates, variants, and conflicts rather than merging them blindly. Registering an already known source returns the canonical record (idempotent), so re importing the same file never produces a second asset. Classes Method Signature Summary Add a fully formed record (used internally / by the resolver). Register a source by its bytes. Hashes, classifies against existing records, and links duplicates/variants/conflicts. Record a converted artifact path against a registered asset. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/AssetResolver.js

assets/AssetResolver.js
Classes
class AssetResolver
Functions
backendFromCache(cache)
makeFetchBackend(base)
makeMemoryBackend(initial = {})
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/AssetResolver.js — virtual path resolution + backup repair (spec §3, rule 5). Files move, browser permissions expire, cloud mirrors lag. The resolver maps a scheme:// path to a concrete backend and, when reading a registered asset, tries the primary then each backup, verifying by content hash. If a backup matches the expected hash it repairs the primary; if a candidate's hash differs it is flagged a conflict (never silently accepted). Classes A backend is { async read(path) Uint8Array null, async write?(path, bytes) }. Schemes without a registered backend simply fail to resolve (caller falls back). Method Signature Summary Read raw bytes for a single virtual path, or null if unavailable. Resolve a registered asset's bytes with backup fallback + hash repair. Functions Adapt an AssetCache instance to a resolver backend (cache:// scheme). A read only backend that fetches relative to a base URL (asset://, cloud://). A simple in memory backend (temp:// drag drop, user:// session mounts). <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/CanonicalSpace.js

axisCorrectionQuat(upAxis = '+Y', forwardAxis = '+Z')

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/CanonicalSpace.js — the engine's canonical coordinate frame. Y = up, Z = forward, X = side (right), unit = meter, origin = logical root. Source files come from Blender/Maya/Max/CAD/Unity/Unreal/etc. with inconsistent axes, scale, and origin. We never trust source orientation and never rewrite it destructively — instead we compute a non destructive axis correction (a quaternion + uniform scale) that maps the declared source frame into this canonical frame, and store it on the model's ImportTransform. Functions Resolve an axis token ('+Y', ' Z', …) to a unit vector. Quaternion (xyzw) that rotates a vector from a source frame (declared by its up + forward axes) into the canonical Y up / Z forward frame. Parameters: (string) — e.g. '+Z' for Blender (string) — e.g. ' Y' for Blender Convert a row major 3x3 rotation matrix to a quaternion (xyzw). Rotate a 3 vector by a quaternion (xyzw). Constants — Common unit guesses for formats that don't carry units (e.g. STL). Returns a scale factor to convert the source unit to meters. These are guesses — the editor exposes an override per import. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/EngineModel.js

assets/EngineModel.js
Functions
createEngineModel(init = {})
createImportTransform(init = {})
createEngineNode(init = {})
createEngineMesh(init = {})
createEnginePrimitive(init = {})
layerStatus(model)
Constants
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/EngineModel.js — the unified runtime object. Core rule of the ingestion runtime: a model file is raw evidence, not the runtime object. The importer parses a source file into an EngineModel, which keeps every layer explicitly separate (source ≠ visual mesh ≠ material ≠ collider ≠ SDF ≠ skeleton ≠ animation ≠ runtime rig ≠ render surface). Layers that have not been built yet are explicitly null/empty — never faked — so the editor can show exactly what was detected vs generated. Corrections (axis/scale/origin, material fixes, rig edits) live in metadata as an ImportTransform / import profile and are NEVER baked destructively into the source: the original imported look must always be recoverable. Functions Create an empty EngineModel with every layer present but unbuilt. Parameters: (object) — No description in source JSDoc. Returns: engine model (mutable; the import pipeline fills it in) A non destructive correction applied at runtime (never baked into source). Confidence drives the auto apply / review / preview / neutral policy. A node in the preserved source hierarchy (transforms kept as authored). A mesh = a set of primitives (submeshes), each with its own material. A primitive/submesh: geometry + a single material binding. Report which layers are built (non empty) vs explicitly unbuilt. Constants — Canonical layer list — used by the editor to show built vs unbuilt layers. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/LicenseTracker.js

assets/LicenseTracker.js
Classes
class LicenseTracker
Constants
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/LicenseTracker.js — license metadata + import gate (spec §21). License metadata is mandatory before import. Marketplace assets are licensed, not sold, and portability varies. The hard rules: only import assets the user owns or is licensed to use; never rip copyrighted game assets; never bypass DRM; store license metadata; warn on unknown/restricted licenses. This gate is advisory by default (warn) and can be set strict (block) per project. Classes Method Signature Summary Record/normalize a license block for an asset id. Evaluate whether an asset may be imported. Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


leastVarianceAxis(model, nodeId, opts = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/geometry/PrincipalAxes.js — Principal Component Analysis of an EngineModel node's geometry. Small, dependency free, GPU free, and reusable: any engine system can ask for the natural axes of a mesh (oriented bounds, alignment, the axle of a wheel disc, the long axis of a barrel, etc.). PCA finds the orthogonal axes of greatest → least variance of the vertex cloud. A disc/cylinder is thin along its axle, so its axle is the axis of LEAST variance — orientation and mirror proof, unlike axis aligned guesses. Functions Jacobi eigen decomposition of a symmetric 3×3 (row major length 9 array). PCA of a node's mesh local vertex cloud. Returns: null} Convenience: the axis of LEAST variance (e.g. a wheel/disc axle), or null. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/humanoid/BoneMapper.js
Functions
mapBones(model, opts = {})
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/humanoid/BoneMapper.js — map a source skeleton's bones onto the canonical humanoid slots (HumanoidRig) by NAME first (Mixamo / VRM / generic rig conventions), then hierarchy for the spine chain. Every mapping is a hint; ambiguous/extra bones are reported as and missing required slots as so the editor can correct (rule 62). Pure + GPU free (gate testable). Functions Map a model's skeleton to canonical humanoid bones. Parameters: (object) — EngineModel (object) — No description in source JSDoc. Returns: } <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/humanoid/FingerGenerator.js
Functions
generateFingers(vertices, opts = {})
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/humanoid/FingerGenerator.js — synthesize finger bones from a hand mesh when the source skeleton has none (the browser friendly geometric approach: detect open hand fingertip "lobes", not ML). Method: 1. Build a hand frame from the wrist→fingertip direction; the lateral spread axis (fingers fan out) and palm normal (thinnest) come from 2 D PCA of the vertices in the plane perpendicular to forward. 2. Take the far band of vertices (toward the tips) and cluster them along the lateral axis — each cluster is one finger lobe. 3. Label the shortest extreme lobe as the thumb; order the rest index→pinky. 4. Emit a short straight bone chain (proximal→intermediate→distal→tip) per finger. If fewer than four lobes separate (a closed fist / low poly hand), report so the caller falls back to a single paddle. Pure geometry, GPU free, deterministic → unit testable. Functions Generate finger bones from hand vertices. Parameters: (number[][]) — world/model space points of the hand mesh (object) — { wrist:[x,y,z], forward:[x,y,z], side, fingerStart=0.5, gap=0.08, joints=4 } Returns: } <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/humanoid/FingerMapper.js
Functions
mapFingers(model, handNodeId)
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/humanoid/FingerMapper.js — detect EXISTING finger bones under a hand node by name (Mixamo "LeftHandIndex1..3", VRM "J Bip L Index Proximal", generic "index 01"), grouping them into canonical fingers with palm→tip joint order. Used before procedural generation: if the artist rigged fingers, keep them; only synthesize when none are found. Functions Map existing finger bones under a hand node. Parameters: (object) — EngineModel (string) — No description in source JSDoc. Returns: } <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/humanoid/HandRig.js
Functions
createFinger(init = {})
createHandRig(init = {})
Constants
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/humanoid/HandRig.js — hand + finger rig schema (spec §12). A hand is a wrist + up to five fingers, each a short bone chain. Fingers come from one of three sources: the source skeleton's named bones ( ), procedurally GENERATED from the hand mesh when the skeleton has none ( ), or a single paddle bone when the hand is a closed fist / too low poly ( ). Functions Parameters: (object) — { name, joints:[{position,nodeId?}], source } Parameters: (object) — No description in source JSDoc. Returns: a hand rig Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


extractHandVertices(model, handNodeId, thresh = 0.4, pose = null)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/humanoid/HandRigBuilder.js — build a hand rig for each hand of a humanoid. Priority: (1) use named finger bones if the skeleton has them; else (2) PROBE the hand mesh (vertices skinned to the hand joint) and GENERATE finger bones geometrically; else (3) a single paddle. Wrist + forward come from the humanoid rig (hand world position, and the lowerArm→hand direction). Functions Vertices skinned (weight ≥ thresh) to the hand joint, in node hierarchy SCENE space (so they match the wrist + the rendered mesh). is a node→world map. Build a single hand rig. Parameters: (object) — EngineModel (object) — { side, handNode, lowerArmNode, world? } Returns: HandRig Build both hands for a model that already has a humanoid rig; attaches them at model.rigs.hand = { left, right } and humanoidRig.hands. Returns: } <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/humanoid/HumanoidRig.js
Functions
createHumanoidRig(init = {})
boneSide(slot)
mirrorBone(slot)
Constants
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/humanoid/HumanoidRig.js — canonical humanoid bone slots + rig schema (spec §12). A humanoid is NOT its skeleton: it's a mapping from the source skeleton's bones onto a canonical slot set (Unity Mecanim / VRM style) plus rest pose + correction metadata, so animation can retarget and physics can build a ragdoll regardless of how the artist named or oriented the rig. Every mapping is a HINT with confidence; unmapped/ambiguous bones go to the editor. Functions Create a humanoid rig descriptor. Parameters: (object) — No description in source JSDoc. Is a canonical slot a left/right limb (vs a center/spine bone)? The mirrored slot for a left/right bone (e.g. leftHand ↔ rightHand), or null. Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/humanoid/HumanoidRigBuilder.js
Functions
buildHumanoidRig(model, opts = {})
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/humanoid/HumanoidRigBuilder.js — assemble a HumanoidRig from a model's skeleton (spec §12). Maps bones (BoneMapper), snapshots the rest pose, classifies the pose (T vs A) from the arm direction, and flags needsCorrection when required bones are missing — never guessing past the evidence. The rig is the retarget/ragdoll target: it references the source nodes, it does not bake. Functions Build a humanoid rig and attach it at model.rigs.humanoid. Parameters: (object) — EngineModel (object) — No description in source JSDoc. Returns: the HumanoidRig <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/humanoid/SkeletonHeal.js
Functions
humanoidBonePosition(rig, slot, pose)
healHumanoid(model, rig, pose)
analyzeSymmetry(model, pose)
healSkeleton(model, pose)
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/humanoid/SkeletonHeal.js — anatomy aware, NON DESTRUCTIVE skeleton repair. When a rig is missing or mislabels core bones, infer them from anatomy (the same heuristics auto riggers use): • Pelvis = the point between the two hip joints (and the retarget root must be the pelvis, NOT a ground/root motion bone — so a "Root"/Armature bone at the floor is replaced by the leg derived pelvis). • Missing spine / chest / neck are interpolated along the hips→head chain. • A missing left/right limb is MIRRORED from the present side across the body's sagittal plane (auto mirror). Inferred joints are written to (slot → position) — the source model is never modified. returns the real joint if it exists, else the synthesized one. Functions Real or synthesized world position for a canonical slot (or null). Repair a humanoid rig in place (non destructively): fills with inferred joints and with a list of what was repaired. Parameters: (object) — EngineModel (object) — model.rigs.humanoid (Map) — node hierarchy world map Returns: } Find the skeleton's plane of bilateral symmetry. Returns: null} Heal a generic skeleton by mirroring limbs that exist on only one side. Returns: } <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/humanoid/SkinPose.js
Functions
invert4(m)
buildBindPose(model)
jointPosition(pose, nodeId)
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/humanoid/SkinPose.js — scene space skeleton pose used by rig overlays + hand probing. IMPORTANT (verified with scripts/probe skeleton.py across real rigs): the correct space for placing the skeleton so it lands on the RENDERED mesh is the NODE HIERARCHY world, because the importer/renderer draw the (unskinned) mesh through that same node hierarchy + importTransform. instead lives in the armature local / unscaled space (e.g. hips ≈ 0.03 while the node hierarchy hips ≈ 2.77 with a ×100 mesh node scale), so using it for the overlay either collapses the skeleton (missing node scale) or double rotates it (re applying the armature transform). We therefore use the node hierarchy here; the IBMs are still imported and available (invert4) for true bind / retarget work later. Functions Invert a column major 4×4 (returns a new Float32Array, or null if singular). Scene space pose for every node = the node hierarchy world (TRS composed down the tree). This is exactly the space the renderer draws the mesh in, so the skeleton overlay + hand probing align with the mesh for any export. Parameters: (object) — EngineModel Returns: nodeId → 4×4 (column major) World position of a node in a pose map (or null). <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/import/Detectors.js
Functions
detectHierarchy(model)
detectParts(model)
detectSemanticDomain(model)
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/import/Detectors.js — hierarchy, part, and semantic detection (spec §6). These produce hints, never assertions: every detection carries a confidence and is editor correctable. Detection by name is the cheap first pass; geometry based detection (cylinders → wheels, symmetry, etc.) is layered in by the phase that needs it (vehicles, humanoids, weapons). Functions Summarize the preserved source hierarchy. Returns: } Detect semantic parts by node name. Populates model.detectedParts. Returns: } Roll detected parts up to a guessed runtime domain (vehicle/humanoid/weapon). Returns: } <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/import/FormatDetector.js
Functions
sniffMagic(head)
classOf(format)
detectFormat(name, head = null)
Constants
Re-exports
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/import/FormatDetector.js — detect format by extension + magic bytes (spec §5). Never trust the filename alone: the magic byte sniff wins when it disagrees with the extension, and a confidence is reported so the pipeline can fall back to the editor when unsure. Functions Sniff a format from a leading byte slice. Returns a format token or null. Pass at least the first 16 bytes for reliable results. Detect a file's format from its name and (optional) leading bytes. Parameters: (string) — filename or virtual path (Uint8Array ArrayBuffer) — leading bytes ( = 16 recommended) Returns: } Constants Re exports , , <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


extractGltfMaterialPayload(json, buffers = [], externalImages = null)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/import/GltfSceneImporter.js — full glTF/GLB scene → EngineModel. glTF is the preferred runtime delivery format (nodes, meshes, materials, skins, animations, buffers, textures). This importer parses the whole scene graph — not just motion — reusing the engine's accessor toolkit (core/math/MeshAttributeMath) to decode vertex/index data exactly. Materials and textures are preserved as raw blocks here and normalized in Phase 2; the original look must always be recoverable. Functions Parse a binary GLB into { json, bin }. Extract the recoverable glTF material/texture payload from already resolved buffers. This is shared by the full asset pipeline and the editor mesh importer so both paths normalize exactly the same source records. Import a glTF/GLB into an EngineModel. Parameters: (Uint8Array ArrayBuffer object) — GLB bytes, or a parsed gltf object (object) — { name, bin, readExternal } Returns: EngineModel Constants Re exports <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/import/GpuUploader.js
Functions
standardVertexLayout()
interleaveStandard(primitive)
uploadPrimitive(device, primitive)
uploadModel(device, model)
releaseModelGpu(model)
Constants
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/import/GpuUploader.js — upload EngineModel primitives to the GPU. Parsing is GPU free; this is the separate, device driven step (spec §9: upload GPU buffers incrementally). Each primitive is interleaved into a standard [position(3), normal(3), uv(2)] vertex layout (generating flat normals when a source lacks them) plus an optional index buffer, so the importer/viewer and the engine renderer can draw it with one shared layout. Buffers are recorded on ; flips true when all primitives upload. Functions The WebGPU vertex buffer layout matching interleaveStandard(). Interleave a primitive's attributes into the standard layout. Upload one primitive to the GPU. Records . Returns: the gpu descriptor Upload every primitive in a model. Returns the number uploaded. Free GPU buffers held by a model's primitives. Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


async parseToModel(format, data, opts = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/import/ImportPipeline.js — orchestrates the ingestion flow (spec §5 pipeline): detect → license gate → parse → normalize orientation → detect hierarchy/parts/domain → deduplicate/register. GPU upload is a separate explicit step (GpuUploader) because parsing must stay GPU free and worker able. Functions Parse raw bytes of a known format into an EngineModel (no GPU, no registry). Full import of a single file. Parameters: (object) — No description in source JSDoc. (string) — filename or virtual path (Uint8Array ArrayBuffer string) — source data (object) — AssetRegistry to dedup/register into (object) — LicenseTracker for the import gate (object) — license block for this source (object) — { readExternal, mtlText, unitHint, upAxis, forwardAxis, primary } Returns: } <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/import/ObjImporter.js
Functions
parseMtl(text)
importObj(data, opts = {})
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/import/ObjImporter.js — Wavefront OBJ (+ optional MTL) → EngineModel. OBJ is static geometry + simple material references. We preserve groups/objects and per face material assignment by splitting into one primitive per material group. Polygons are triangulated (fan). MTL parsing is light (names + a few PBR ish factors) and the full material decode happens in Phase 2. Functions Parse a minimal MTL into a map of name → material descriptor. Import OBJ text/bytes into an EngineModel. Parameters: (string Uint8Array) — OBJ source (object) — { name, mtl: Map string (mtl source) } <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/import/OrientationResolver.js
Functions
classifyConfidence(c)
resolveOrientation(model, opts = {})
Constants
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/import/OrientationResolver.js — axis/scale/origin inference (spec §6). Never trust source orientation; never bake corrections into source. We infer a non destructive ImportTransform (axis correction quat + scale + origin) with a confidence, and a policy decides whether to auto apply, mark reviewable, preview only, or stay neutral and require manual correction. Functions Infer an ImportTransform for a model. Parameters: (object) — EngineModel (uses sourceFormat + bounds) (object) — { unitHint, upAxis, forwardAxis } explicit overrides win Returns: } Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/import/PlyImporter.js
Functions
importPly(data, opts = {})
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/import/PlyImporter.js — Stanford PLY (ASCII + binary LE) → EngineModel. PLY is a point/mesh utility format. We read the vertex element (position + optional normal/color) and the face element (triangulated), producing one indexed primitive. Big endian binary is uncommon for web assets and is not supported here (the editor can flag it). Functions <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/import/StlImporter.js
Functions
importStl(data, opts = {})
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/import/StlImporter.js — STL (binary + ASCII) → EngineModel. STL is CAD/printable part geometry: triangles only, no materials, no hierarchy, no declared units. We import geometry faithfully and leave the unit guess to the OrientationResolver / editor. Output is a single non indexed primitive with per vertex positions and face normals. Functions Import STL bytes or text into an EngineModel. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/index.js

assets/index.js
Re-exports
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/index.js — Global Asset Ingestion Runtime barrel. Turns any source file into an EngineModel and a usable simulation object: decode → normalize → deduplicate → preserve hierarchy/materials/animations → generate colliders/SDF/rigs/surfaces → cache → spawn. Build status: [x] Phase 0 foundations (EngineModel, AssetRecord, vpath, canonical space) [x] Phase 1 asset core (dedup, cache/OPFS, registry, resolver, importers) [x] Phase 2 materials & textures (decode, bindings, segments, variants) [x] Phase 3 vehicles (wheel/chassis detect, rig builder, suspension/tire/sync) [x] Render reusable model rendering (shader/pipeline, GPU drawables, wheel spin, ModelRenderer) + geometry PCA — shared by demos, editor, and runtime so importing/viewing assets is one call. [ ] Phase 4 render surfaces [ ] Phase 5 humanoids, hands & weapons Re exports , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/material/EngineMaterial.js
Functions
defaultChannelMap(slot)
createEngineMaterial(init = {})
createTextureBinding(init = {})
hasTextureTransform(binding)
Constants
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/material/EngineMaterial.js — normalized material + texture binding schemas (spec §7). Materials are decoded, not guessed. Textures bind to surfaces (not loose images); UV sets, sampler wrap/filter, and texture transforms must survive import; packed channels are read exactly. The raw source material is always preserved on so the imported look stays recoverable even after engine normalization or shader model approximation. Functions glTF default packing: metallic=B, roughness=G, occlusion=R. Create a normalized engine material. Create a texture binding (a texture bound to a material slot on a surface). Has this binding a non identity UV transform (KHR texture transform)? Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


assets/material/MaterialImport.js
Functions
importMaterials(model)
Re-exports
Notes & Examples

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: engine/assets/material/MaterialImport.js — decode source materials into the normalized EngineMaterial (spec §7). Materials are decoded exactly, never guessed: UV sets, sampler wrap/filter, and KHR texture transform survive; packed channels are read per the format (metadata wins over filename). The raw material is preserved on so the imported look stays recoverable. Functions Decode every material in a model into EngineMaterial in place. Idempotent: a material already carrying is left untouched. Returns: the decoded materials Re exports , <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.