lecodes-sdk 2.0.12 → 2.1.0

package/package.json

@@ -27,7 +27,7 @@
   },
   "scripts": {
     "build": "bun run build-types.ts",
-    "test": "bun test",
+    "test": "bun test --randomize",
     "typecheck": "tsc --noEmit",
     "docs:check": "node docs/check.mjs",
     "prompts:build": "bun prompts/compose.ts",
@@ -45,7 +45,7 @@
     "marcidb-embedded": "^0.14.1",
     "sharp": "^0.35.2"
   },
-  "version": "2.0.12",
+  "version": "2.1.0",
   "files": [
     "src",
     "dist",

package/prompts/3d-scene.md

@@ -5,8 +5,11 @@
 new Scene(options?: {
   ibl?: boolean                  // image-based ambient light; default TRUE — every scene has ambient
   environmentIntensity?: number  // IBL strength; default 20000
-  bloom?: boolean                // default false
-  bloomIntensity?: number        // default 0.2 (only with bloom: true)
+  postProcessing?: {             // the look: tone mapping, grading, a .cube LUT, bloom, vignette, AO, reflections, DoF
+    toneMapping?: 'aces' | 'neutral' | 'linear' | 'filmic', exposure?: number, contrast?: number, saturation?: number,
+    lut?: string, bloom?: boolean | { intensity?: number }, vignette?: boolean | { feather?: number },
+    ambientOcclusion?: boolean | { radius?: number }, screenSpaceReflections?: boolean, depthOfField?: boolean | { focusDistance?: number, aperture?: number }
+  }                              // live: scene.postProcessing.contrast = 1.1; .apply({ ... }) = the named fields only; .reset(); never assigned
   skybox?: ColorInput            // solid background / clear color
   antialias?: boolean            // 4× MSAA; default false
 })

package/src/bridges/app.d.ts

@@ -11,7 +11,7 @@
 // `?` on a method = an optional slot: a host that leaves it null gets no such JS method, so the SDK's
 // `typeof` feature-detects stay honest. The `HostApp` interface below adds the slots the runtime
 // calls that JS never sees (notifications to the host).
-import type { bytes } from "./types"
+import type { bytes, i32 } from "./types"
 
 declare global {
   // ---- World control (run/restart/quit — the platform's `location` analog) ----------------------
@@ -73,6 +73,23 @@ declare global {
      *  synchronous top level and the launcher always comes back unlocked. Optional — hosts
      *  without a rotatable screen (desktop, headless, macOS) omit it. Backs app.setOrientation. */
     setOrientation?(mode: string): void
+
+    // ---- Versions: the installed app (the HOST) vs the bundle running in it (OTA may part them) -----
+    /** The installed app's version string — Android versionName, iOS CFBundleShortVersionString.
+     *  Hosts that are not an app (desktop, headless, the web) omit it. Backs app.host.version. */
+    appVersion?(): string
+    /** The installed app's build number — Android versionCode, iOS CFBundleVersion read as an
+     *  integer (0 when it is not one). Backs app.host.build. */
+    appBuild?(): i32
+    /** The SDK version embedded in this host (CREATOR_PKG_SDK_VERSION, the runtime set's version — a
+     *  shell's lecodes-ios-sdk / lecodes-android-sdk release). The bundle's own is `// sdk:` of its
+     *  header (app.sdkVersion); the two differ once an OTA bundle runs on an older install. Backs
+     *  app.host.sdk. @custom */
+    runtimeVersion(): string
+    /** The `// last-updated:` line of the bundle the live world runs (its compile time, ISO 8601) or
+     *  null for a bundle without the line. The updater's downgrade rule reads the same line. Backs
+     *  app.bundle.updatedAt. @custom */
+    bundleUpdatedAt(): string | null
   }
 }
 

package/src/bridges/gl.d.ts

@@ -113,8 +113,35 @@ declare global {
      *  ktx every call, so it can never carry a slider. No-op until the scene has an IBL. Optional:
      *  hosts that predate it keep whatever `setDefaultIbl` set at open. */
     setEnvironmentIntensity?(sceneId: u32, intensity: f32): void
-    setBloomOptions(sceneId: u32, enabled: boolean, strength: f32, quality: u8): void
-    setToneMapping?(sceneId: u32, mode: u8): void
+    /** Bloom, every knob in one call (`scene.postProcessing.bloom`): `strength` 0..1 of the blurred
+     *  highlights added back, `threshold` = only what is brighter than 1.0 after exposure blooms,
+     *  `highlight` clamps one pixel's contribution (1000), `levels` 1..12 = how far the glow spreads,
+     *  `quality` 0..3, `lensFlare` = ghosts + halo, `dirtTextureId` (0xFFFFFFFF = none) a texture
+     *  multiplied into the bloom at `dirtStrength`. */
+    setBloomOptions(sceneId: u32, enabled: boolean, strength: f32, threshold: boolean, highlight: f32, levels: u8, quality: u8, lensFlare: boolean, dirtTextureId: u32, dirtStrength: f32): void
+    /** Vignette, a uniform of the grading pass (free to animate): `midPoint` 0..1 where the darkening
+     *  starts, `roundness` 0 (the aspect) .. 1 (a circle), `feather` 0..1, `color` 0xRRGGBBAA read as
+     *  linear. Optional: a host that predates it draws none. */
+    setVignetteOptions?(sceneId: u32, enabled: boolean, midPoint: f32, roundness: f32, feather: f32, color: u32): void
+    /** Colour grading: the operator and every adjustment baked into the view's ONE 3D LUT. `params` is
+     *  the fixed layout of `sdk/src/gl/postProcessing.ts` (`CG_*`, mirrored by creator.h's
+     *  ColorGradingParam; 39 floats, the last one = apply the LUT of setColorLut). A change re-bakes a 32³ table on the CPU, so the SDK coalesces
+     *  its writes per tick and quantises; an identical array is a no-op in the engine. Optional: a
+     *  host that predates it renders filament's default (ACES legacy). */
+    setColorGrading?(sceneId: u32, params: Float32Array): void
+    /** A custom 3D LUT after the operator, in display-referred sRGB: the TEXT of a `.cube` file
+     *  (`LUT_3D_SIZE n` + n³ `r g b` lines, red fastest), parsed by the engine once and applied while
+     *  the `CG_LUT` flag of setColorGrading is 1 (a LUT is removed by the flag, never by an empty
+     *  buffer: the bridge passes none). Baked into the same table. Optional. */
+    setColorLut?(sceneId: u32, cubeFetchId: bytes): void
+    /** Screen-space reflections (`scene.postProcessing.screenSpaceReflections`): what is on screen
+     *  reflects, by a ray march through the depth buffer — `maxDistance` metres, `thickness` metres a
+     *  surface extends behind its depth, `stride` pixels per step. Optional. */
+    setScreenSpaceReflections?(sceneId: u32, enabled: boolean, maxDistance: f32, thickness: f32, stride: f32): void
+    /** Depth of field: the camera focuses at `focusDistance` metres and the view blurs as if the lens
+     *  were at f/`aperture`, without touching the exposure (0 = the camera's own f-number), times
+     *  `strength` (1 = physical; a game's wide lens blurs little). Optional. */
+    setDepthOfField?(sceneId: u32, enabled: boolean, focusDistance: f32, aperture: f32, strength: f32): void
     /** Exposure of the scene's camera — filament's physical model: `aperture` f-stops,
      *  `shutterSpeed` seconds, `sensitivity` ISO (default f/16, 1/125 s, ISO 100 = EV100 15, bright
      *  sunlight). ISO ×2 = one stop brighter. Scene-referred light follows it; particle emission is
@@ -742,26 +769,32 @@ declare global {
     /** Distance fade for every instance of the entity's ASSET (present and future): the cards thin out between `start`
      *  and `end` metres from the camera and past `end` the LOD pass takes the instance out of the scene. end 0 = none. */
     foliageSetFade?(entityId: u32, start: f32, end: f32): void
+    /** @ifdef CREATOR_GL_PHYSICS */
     physicsConfigure(gx: f32, gy: f32, gz: f32, maxBodies: u32): void
-    /** @c setPhysicsInterpolation */
+    /** @c setPhysicsInterpolation @ifdef CREATOR_GL_PHYSICS */
     setInterpolation(enabled: boolean): void
     // Shape/Physics/Trigger aspects: build a shape once, create bodies from it.
+    /** @ifdef CREATOR_GL_PHYSICS */
     physicsBuildBox(hx: f32, hy: f32, hz: f32): u32
+    /** @ifdef CREATOR_GL_PHYSICS */
     physicsBuildSphere(radius: f32): u32
+    /** @ifdef CREATOR_GL_PHYSICS */
     physicsBuildCylinder(halfHeight: f32, radius: f32): u32
+    /** @ifdef CREATOR_GL_PHYSICS */
     physicsBuildCapsule(halfHeight: f32, radius: f32): u32
     /** Mesh shape from node-local triangles. convex=false → triangle mesh (static/kinematic/pick/character
      *  only; physicsCreateBody returns 0 for a dynamic one), convex=true → convex hull (any motion).
-     *  (sx,sy,sz) = world scale, applied natively. Returns 0 if the shape can't be built. @count vertexCount=vertices/3 */
+     *  (sx,sy,sz) = world scale, applied natively. Returns 0 if the shape can't be built. @count vertexCount=vertices/3 @ifdef CREATOR_GL_PHYSICS */
     physicsBuildMesh(vertices: Float32Array, indices: Uint32Array, convex: boolean, sx: f32, sy: f32, sz: f32): u32
-    /** Same from a loaded GLB root (non-skinned primitives, bind pose, baked sub-node transforms; cached per asset). */
+    /** Same from a loaded GLB root (non-skinned primitives, bind pose, baked sub-node transforms; cached per asset). @ifdef CREATOR_GL_PHYSICS */
     physicsBuildMeshFromEntity(entityId: u32, convex: boolean, sx: f32, sy: f32, sz: f32): u32
     /** Terrain collider (Shape { heightfield: true }, docs/terrain-plan.md §1.4): a Jolt HeightFieldShape over
      *  the grid `terrainCreate` draws (same arrays, same hole rule). Static / kinematic / pick / character
      *  ground only. (sx,sy,sz) = world scale. `physicsUpdateHeightField` rewrites a sample rectangle in
      *  place from the FULL arrays (live bodies keep the shape); heights beyond the range chosen at build
-     *  time (25 % headroom) clamp — the SDK rebuilds the shape when an edit leaves that range. Optional. */
+     *  time (25 % headroom) clamp — the SDK rebuilds the shape when an edit leaves that range. Optional. @ifdef CREATOR_GL_PHYSICS */
     physicsBuildHeightField?(heights: Float32Array, sizeX: u32, sizeZ: u32, cellSize: f32, holes: Uint8Array | null, sx: f32, sy: f32, sz: f32): u32
+    /** @ifdef CREATOR_GL_PHYSICS */
     physicsUpdateHeightField?(shapeId: u32, heights: Float32Array, sizeX: u32, sizeZ: u32, x0: u32, z0: u32, w: u32, h: u32, holes: Uint8Array | null): void
     /** A loaded GLB root's triangle soup — the one `physicsBuildMeshFromEntity` collides — as 9 floats per
      *  triangle in the asset root's space (empty when the entity is not a GLB). `Terrain.conform` stamps a
@@ -769,56 +802,63 @@ declare global {
     glbTriangles?(entityId: u32): Float32Array
     /** Offset a built shape's centre from the node's origin (Shape `origin`) — world units in the
      *  body's rotated, UNSCALED frame, sitting outside a mesh shape's scale wrapper. Sets rather
-     *  than accumulates; (0,0,0) clears it. Optional: an older host just centres on the node. */
+     *  than accumulates; (0,0,0) clears it. Optional: an older host just centres on the node. @ifdef CREATOR_GL_PHYSICS */
     physicsSetShapeOrigin?(shapeId: u32, x: f32, y: f32, z: f32): void
     /** Swap a live body's shape, keeping its id, velocity and transform (Shape.fit / a re-attach).
-     *  updateMass recomputes the inertia tensor. Refuses a triangle mesh on a dynamic body. */
+     *  updateMass recomputes the inertia tensor. Refuses a triangle mesh on a dynamic body. @ifdef CREATOR_GL_PHYSICS */
     physicsSetBodyShape?(bodyId: u32, shapeId: u32, updateMass: boolean): void
+    /** @ifdef CREATOR_GL_PHYSICS */
     physicsDestroyShape(shapeId: u32): void
-    /** sensor = trigger (overlap events, no response); pickOnly = raycast-only, non-colliding body. */
+    /** sensor = trigger (overlap events, no response); pickOnly = raycast-only, non-colliding body. @ifdef CREATOR_GL_PHYSICS */
     physicsCreateBody(entityId: u32, shapeId: u32, motion: i32, mass: f32, sensor: boolean, pickOnly: boolean): u32
+    /** @ifdef CREATOR_GL_PHYSICS */
     physicsSetPickable(bodyId: u32, pickable: boolean): void
     /** Surface friction of one body (0 = ice, ~1 = grippy asphalt). Values COMBINE as sqrt(a * b), so
      *  a low value on either side dominates. New bodies start at 0.6 — a neutral solid surface.
-     *  The vehicle wheel cast reads the GROUND body's value — this is what caps a car's cornering. */
+     *  The vehicle wheel cast reads the GROUND body's value — this is what caps a car's cornering. @ifdef CREATOR_GL_PHYSICS */
     physicsSetFriction(bodyId: u32, friction: f32): void
+    /** @ifdef CREATOR_GL_PHYSICS */
     physicsGetFriction(bodyId: u32): f64
-    /** Ray vs pickable bodies → hit entity id (0 = miss); fills `out` = [px,py,pz,nx,ny,nz,fraction]. @into out 7 */
+    /** Ray vs pickable bodies → hit entity id (0 = miss); fills `out` = [px,py,pz,nx,ny,nz,fraction]. @into out 7 @ifdef CREATOR_GL_PHYSICS */
     physicsRaycast(ox: f32, oy: f32, oz: f32, dx: f32, dy: f32, dz: f32, maxDist: f32, out?: Float32Array): u32
     /** Dev-time dump of the static collision geometry (docs/navmesh-plan.md §4) — the input of
      *  `lecodes navmesh bake`: every STATIC solid body's triangles in world space, as an NGEO file at
      *  `outPath`. `entityIds`/`areas` are per-entity overrides (area 0..15, 255 unwalkable, 254 skip).
-     *  Returns the triangle count (-1 = failed). Desktop hosts with physics only. */
+     *  Returns the triangle count (-1 = failed). Desktop hosts with physics only. @ifdef CREATOR_GL_PHYSICS */
     physicsStaticGeometry?(outPath: string, entityIds: Uint32Array, areas: Uint8Array): i32
     // CharacterController (Jolt CharacterVirtual). The character steps on the engine's FIXED clock like
     // every body (frame-rate independent) and is render-interpolated; the engine owns its gravity, so
     // the SDK never ticks it. Both velocity halves are LATCHED STATE, never one-shot events — JS runs
     // once per frame while the sim runs 0..4 sub-steps, so a one-shot would double-apply or vanish.
     // groundState: 0 OnGround / 1 OnSteepGround / 2 NotSupported / 3 InAir.
+    /** @ifdef CREATOR_GL_PHYSICS */
     characterCreate(entityId: u32, shapeId: u32, maxSlopeDeg: f32): u32
+    /** @ifdef CREATOR_GL_PHYSICS */
     characterDestroy(charId: u32): void
     /** This frame's HORIZONTAL command (world units/s), cleared once a step consumes it — no command
      *  means standing still, not coasting. Held across the frame's sub-steps, and it takes the axis
-     *  back from a latched velocity: the last writer owns X/Z. */
+     *  back from a latched velocity: the last writer owns X/Z. @ifdef CREATOR_GL_PHYSICS */
     characterMove(charId: u32, x: f32, z: f32): void
-    /** The same command including the vertical — free mode (gravityScale 0): swimming / flying. */
+    /** The same command including the vertical — free mode (gravityScale 0): swimming / flying. @ifdef CREATOR_GL_PHYSICS */
     characterMoveFree(charId: u32, x: f32, y: f32, z: f32): void
-    /** Seed the LATCHED ballistic vertical (jump / dash). No ground check. */
+    /** Seed the LATCHED ballistic vertical (jump / dash). No ground check. @ifdef CREATOR_GL_PHYSICS */
     characterSetVerticalVelocity(charId: u32, vy: f32): void
     /** Latch the whole velocity — it persists until a characterMove takes the axis back (knockback,
-     *  wall jump, launch pad, weightless flight). Gravity still acts on the vertical. */
+     *  wall jump, launch pad, weightless flight). Gravity still acts on the vertical. @ifdef CREATOR_GL_PHYSICS */
     characterSetVelocity(charId: u32, x: f32, y: f32, z: f32): void
-    /** Multiplier over the world gravity; 0 = free mode, which ALSO disables stick-to-floor + stairs. */
+    /** Multiplier over the world gravity; 0 = free mode, which ALSO disables stick-to-floor + stairs. @ifdef CREATOR_GL_PHYSICS */
     characterSetGravityScale(charId: u32, scale: f32): void
+    /** @ifdef CREATOR_GL_PHYSICS */
     characterSetMaxSlope(charId: u32, maxSlopeDeg: f32): void
     /** Swap the collider live (crouch / stand up), keeping the FEET planted. Returns false when the new
      *  shape doesn't fit where the character stands — nothing changed, so the caller retries later and
-     *  that retry is an exact headroom test. Optional: a host without it can't resize a character. */
+     *  that retry is an exact headroom test. Optional: a host without it can't resize a character. @ifdef CREATOR_GL_PHYSICS */
     characterSetShape?(charId: u32, shapeId: u32): boolean
-    /** The velocity the solver ENDED UP with after the last step (post-collision), not the command. @into out 3 */
+    /** The velocity the solver ENDED UP with after the last step (post-collision), not the command. @into out 3 @ifdef CREATOR_GL_PHYSICS */
     characterGetVelocity(charId: u32, out: Float32Array): void
+    /** @ifdef CREATOR_GL_PHYSICS */
     characterGetGroundState(charId: u32): i32
-    /** Discontinuous move (spawn / respawn / teleport) — also resets the interpolation pair. */
+    /** Discontinuous move (spawn / respawn / teleport) — also resets the interpolation pair. @ifdef CREATOR_GL_PHYSICS */
     characterSetPosition(charId: u32, x: f32, y: f32, z: f32): void
     // Vehicle (Jolt VehicleConstraint + WheeledVehicleController). One settings BLOB, so tuning knobs
     // never grow this ABI — layout (floats):
@@ -873,7 +913,9 @@ declare global {
     // wheel models itself from the state. Chassis space is forward -Z / up +Y (matching node.forward);
     // wheel positions are suspension attachment points in unscaled chassis space; `axle` pairs wheels
     // for the differentials + anti-roll bars.
+    /** @ifdef CREATOR_GL_PHYSICS */
     vehicleCreate(entityId: u32, shapeId: u32, settings: Float32Array): u32
+    /** @ifdef CREATOR_GL_PHYSICS */
     vehicleDestroy(vehicleId: u32): void
     /** ONE input vector, latched and applied once per fixed step: [throttle 0..1, steer −1..1 (a
      *  fraction of the wheels' maxSteerDeg, applied as is; with a column, where the hands aim),
@@ -882,12 +924,12 @@ declare global {
      *  neutral, negative = reverse — the engine never sees a gear list), clutch 0..1 (scales the clutch
      *  in the coupled engine/wheel solve), brake_0 … brake_n (N·m of brake torque per wheel, this
      *  step)]. A shorter vector leaves the rest as it was. Sticky; a non-zero throttle, steer or brake
-     *  wakes a sleeping car. */
+     *  wakes a sleeping car. @ifdef CREATOR_GL_PHYSICS */
     vehicleSetInput(vehicleId: u32, input: Float32Array): void
     /** Re-apply the TUNABLE half of the blob (same layout) to a live car — differential, per-wheel tire
      *  curves / traction / circle, engine torque/RPM/curve, clutch strength + capacity, steer lock, the
      *  column, anti-roll stiffness, tilt limit. Structural values (mass, centre of mass, wheel geometry,
-     *  the driven shares, suspension, whether an axle has a bar) are ignored: those need a re-create. */
+     *  the driven shares, suspension, whether an axle has a bar) are ignored: those need a re-create. @ifdef CREATOR_GL_PHYSICS */
     vehicleSetTuning?(vehicleId: u32, settings: Float32Array): void
     /** out = [speed, rpm, wheelsInContact, vx, vy, vz, wx, wy, wz, steerDeg, steerTorque] (w = chassis
      *  angular velocity, rad/s; steerDeg = where the road wheels are, right-positive; steerTorque = the
@@ -898,12 +940,12 @@ declare global {
      *  patch's sliding speeds, m/s, + = to the right / tread spinning up — force × speed is heat; load =
      *  the suspension's force on the wheel, N). slipLong is SIGNED (+ spinning up, − locking) and so is
      *  slipAngleDeg (+ the patch sliding to the tire's right). suspensionLength, steerDeg and spin are
-     *  what a wheel model's pose is built from — by the game, the SDK only exposes them. */
+     *  what a wheel model's pose is built from — by the game, the SDK only exposes them. @ifdef CREATOR_GL_PHYSICS */
     vehicleGetState(vehicleId: u32, out: Float32Array): void
     /** Teleport upright and clear all motion (velocities, engine RPM, wheel spin); the input vector is
-     *  zeroed — the SDK re-sends its own on the next early pass. */
+     *  zeroed — the SDK re-sends its own on the next early pass. @ifdef CREATOR_GL_PHYSICS */
     vehicleReset(vehicleId: u32, x: f32, y: f32, z: f32, qx: f32, qy: f32, qz: f32, qw: f32): void
-    /** The chassis rigid body, for the plain body calls (physicsApplyImpulse, …). 0 if unknown. */
+    /** The chassis rigid body, for the plain body calls (physicsApplyImpulse, …). 0 if unknown. @ifdef CREATOR_GL_PHYSICS */
     vehicleBodyId(vehicleId: u32): u32
     // Ragdoll (Jolt Ragdoll): a Model's skeleton handed to physics — one dynamic body per listed bone
     // (a capsule from the bone's origin to the next joint) joined to its parent part by a swing-twist
@@ -949,24 +991,26 @@ declare global {
     //              half-angle), twistDeg (half-angle), hinge (0/1), hingeAxisX/Y/Z (in the MODEL
     //              node's space), hingeMinDeg, hingeMaxDeg — a hinge is a swing-twist whose cone is
     //              flat (2°) across the axis and [min, max] about it (a knee, an elbow)
+    /** @ifdef CREATOR_GL_PHYSICS */
     ragdollCreate?(rootEntityId: u32, bones: Uint32Array, settings: Float32Array): u32
+    /** @ifdef CREATOR_GL_PHYSICS */
     ragdollDestroy?(ragdollId: u32): void
     /** Pose the bodies from the bones' current transforms and add them to the world, each moving as
      *  its bone was measured over the last two frames, plus the launch (vx, vy, vz) on every body.
-     *  Already active = re-wake + the launch. false = unknown id / no world. */
+     *  Already active = re-wake + the launch. false = unknown id / no world. @ifdef CREATOR_GL_PHYSICS */
     ragdollActivate?(ragdollId: u32, vx: f32, vy: f32, vz: f32): boolean
     /** Take the bodies out of the world. The bones get the bodies' last pose written against the
      *  parents' CURRENT worlds (move the model node under the hips first), and with `blend` > 0 the
      *  model's animator is seeded with it: whatever plays next transitions from the fallen pose over
-     *  `blend` seconds. */
+     *  `blend` seconds. @ifdef CREATOR_GL_PHYSICS */
     ragdollDeactivate?(ragdollId: u32, blend: f32): void
-    /** In the world AND at least one body still awake (a settled ragdoll reads false). */
+    /** In the world AND at least one body still awake (a settled ragdoll reads false). @ifdef CREATOR_GL_PHYSICS */
     ragdollActive?(ragdollId: u32): boolean
-    /** The rigid body of part `index` (for physicsApplyImpulseAt / velocities). 0 if unknown. */
+    /** The rigid body of part `index` (for physicsApplyImpulseAt / velocities). 0 if unknown. @ifdef CREATOR_GL_PHYSICS */
     ragdollBodyId?(ragdollId: u32, index: u32): u32
     /** The joint motors' strength (0..1 = the share of driveTorque; 0 = off = limp) and the root
      *  anchor (the hips body kinematic on the animated hips). Kept across activations; a driven or
-     *  anchored body never freezes. */
+     *  anchored body never freezes. @ifdef CREATOR_GL_PHYSICS */
     ragdollSetDrive?(ragdollId: u32, strength: f32, anchor: boolean): void
     // Dynamic bones (the SDK's DynamicBone; creator-anim canimDyn* behind creator-gl): secondary motion
     // for tails, ears, hair and cloaks — a bone tree under one root simulated as Verlet particle chains
@@ -1027,23 +1071,31 @@ declare global {
     dynamicBoneColliderSet?(colliderId: u32, ax: f32, ay: f32, az: f32, bx: f32, by: f32, bz: f32, radius: f32, sided: f32): void
     dynamicBoneColliderDestroy?(colliderId: u32): void
     // Legacy coupled shape+body (still used by the worker RigidBody).
+    /** @ifdef CREATOR_GL_PHYSICS */
     physicsCreateBox(entityId: u32, hx: f32, hy: f32, hz: f32, motionType: i32, mass: f32): u32
+    /** @ifdef CREATOR_GL_PHYSICS */
     physicsCreateSphere(entityId: u32, radius: f32, motionType: i32, mass: f32): u32
+    /** @ifdef CREATOR_GL_PHYSICS */
     physicsCreateCylinder(entityId: u32, halfHeight: f32, radius: f32, motionType: i32, mass: f32): u32
+    /** @ifdef CREATOR_GL_PHYSICS */
     physicsSetLinearVelocity(bodyId: u32, x: f32, y: f32, z: f32): void
-    /** @into out 3 */
+    /** @into out 3 @ifdef CREATOR_GL_PHYSICS */
     physicsGetLinearVelocity(bodyId: u32, out: Float32Array): void
     /** Angular velocity about each world axis, RADIANS/second — Jolt's unit; the SDK exposes degrees.
-     *  The only way to stop a spin: a position write leaves both velocities untouched. */
+     *  The only way to stop a spin: a position write leaves both velocities untouched. @ifdef CREATOR_GL_PHYSICS */
     physicsSetAngularVelocity?(bodyId: u32, x: f32, y: f32, z: f32): void
-    /** @into out 3 */
+    /** @into out 3 @ifdef CREATOR_GL_PHYSICS */
     physicsGetAngularVelocity?(bodyId: u32, out: Float32Array): void
+    /** @ifdef CREATOR_GL_PHYSICS */
     physicsApplyImpulse(bodyId: u32, x: f32, y: f32, z: f32): void
+    /** @ifdef CREATOR_GL_PHYSICS */
     physicsApplyImpulseAt?(bodyId: u32, x: f32, y: f32, z: f32, px: f32, py: f32, pz: f32): void
+    /** @ifdef CREATOR_GL_PHYSICS */
     physicsSetBodyPosition(bodyId: u32, x: f32, y: f32, z: f32): void
     /** The rotation twin (normalized host-side). Both snap the body's render-interpolation pair, so a
-     *  discontinuous move is drawn as one rather than as a one-frame slide/spin across the gap. */
+     *  discontinuous move is drawn as one rather than as a one-frame slide/spin across the gap. @ifdef CREATOR_GL_PHYSICS */
     physicsSetBodyRotation?(bodyId: u32, qx: f32, qy: f32, qz: f32, qw: f32): void
+    /** @ifdef CREATOR_GL_PHYSICS */
     physicsRemoveBody(bodyId: u32): void
 
     /** @custom */

package/src/gl/Scene.ts

@@ -19,22 +19,12 @@ import { Camera } from "./Camera"
 import { SceneAudio } from "./audio/SceneAudio"
 import { attachControls, type ControlsHandle, type ControlsOptions } from "./controls"
 import { Material } from "./Material"
+import { PostProcessing, type PostProcessingOptions } from "./postProcessing"
 import { Texture } from "./Texture"
 import { Node, nodes } from "./Node"
 import { glState } from "./state"
 import { registerTouchEndEvent, registerTouchStartEvent } from "./touch"
 
-export type AmbientOcclusionOptions = {
-  /** Strength of the darkening (default 1). */
-  intensity?: number
-  /** How far the occlusion reaches, in metres (default 0.3). */
-  radius?: number
-  /** Falloff contrast; >1 tightens it into the crease (default 1). */
-  power?: number
-  /** Sample count + filtering (default 'medium'). Not the buffer resolution — that stays half. */
-  quality?: "low" | "medium" | "high" | "ultra"
-}
-
 /** `SceneOptions.taa` / `scene.setAntialias("taa", 4, taa)`: the temporal anti-aliasing knobs. */
 export type TaaOptions = {
   /** Render the 3D at this fraction (0.5–1) and TAA-upscale it to the viewport; 1 = none. */
@@ -92,14 +82,10 @@ export type SceneOptions = {
    *  rather than inflating the lights: scaling lamps past what they physically emit gives bright
    *  fixtures in a black room, because it changes the RATIO, not the level. */
   exposureCompensation?: number
-  /** Bloom post-processing. */
-  bloom?: boolean
-  bloomIntensity?: number
-  /** Tone mapping operator. `'aces'` (default, filament's ACES legacy) desaturates bright colours
-   *  towards white — HDR fire reads pale; `'neutral'` (Khronos PBR Neutral) keeps hue and
-   *  saturation until very bright; `'linear'` clips each channel (what an engine without a
-   *  tonemapper shows — saturated, Unity-without-post-processing look); `'filmic'` (Uncharted). */
-  toneMapping?: "aces" | "neutral" | "linear" | "filmic"
+  /** The look: tone mapping, colour grading, a `.cube` LUT, bloom, vignette, ambient occlusion,
+   *  screen-space reflections, depth of field — as one object (`scene.postProcessing` after the
+   *  fact; every field is live, postProcessing.ts says which are free to animate). */
+  postProcessing?: PostProcessingOptions
   /** The sky. Three forms:
    *  - a colour — a flat clear colour;
    *  - `{ texture }` — a KTX1 **cubemap**, the sharp `<name>_skybox.ktx` that filament's `cmgen`
@@ -112,12 +98,6 @@ export type SceneOptions = {
    *  space after the opaque queue. No geometry, no meridian seam, no pole distortion — do NOT build
    *  a sky dome or a fullscreen equirect material by hand, both are strictly worse. */
   skybox?: ColorInput | "environment" | { texture: string }
-  /** Screen-space ambient occlusion — the contact darkening in creases and where props meet the
-   *  ground. Without it an IBL lights a crease exactly as brightly as an open face, so everything
-   *  reads as pasted onto the floor rather than standing on it. `true` takes defaults tuned for
-   *  human-scale props; `radius` is world-space metres and is the one knob that must follow the
-   *  scene's scale (~0.3 for objects on a table, ~0.6-1 for a yard of crates and containers). */
-  ambientOcclusion?: boolean | AmbientOcclusionOptions
   /** Distance fog / aerial perspective: distant geometry loses contrast so the eye reads depth, and
    *  the hard edge where a finite level ends against the skybox goes away. By default the fog applies
    *  at every distance — the skybox included — so the sky itself takes the fog colour and the horizon
@@ -215,6 +195,14 @@ export class Scene implements Presentable {
   readonly _touchStartListeners: Array<(ev: TouchStartEvent<Node | null>) => void> = []
 
   private _material?: Material
+  private readonly _postProcessing: PostProcessing
+  /** The scene's post-processing (postProcessing.ts): a live object — write a field
+   *  (`scene.postProcessing.contrast = 1.1`), or `apply({ ... })` several at once (named fields
+   *  only), `reset()` for the defaults. Read-only: there is nothing to assign. An overlay's grading
+   *  is its parent's; its bloom, vignette and the rest are its own. */
+  get postProcessing(): PostProcessing { return this._postProcessing }
+  /** An explicit throw, not a bare getter: a bundle evaluated in sloppy mode would swallow the assignment silently. */
+  set postProcessing(_: never) { throw new Error("scene.postProcessing is read-only: write a field, apply({ ... }) or reset()") }
 
   private static _active: Scene | null = null
   static get active(): Scene | null { return Scene._active }
@@ -245,12 +233,9 @@ export class Scene implements Presentable {
     }
     this._environmentIntensity = options.ibl === false ? 0 : (options.environmentIntensity ?? 20000)
     if (options.exposureCompensation !== undefined) this.camera.exposureCompensation = options.exposureCompensation
-    if (options.bloom) _creator.setBloomOptions(this._id, true, options.bloomIntensity ?? 0.2, 1)
-    if (options.toneMapping !== undefined && options.toneMapping !== "aces") {
-      _creator.setToneMapping?.(this._id, { neutral: 1, linear: 2, filmic: 3 }[options.toneMapping] ?? 0)
-    }
+    this._postProcessing = new PostProcessing(this._id)
+    if (options.postProcessing) this._postProcessing.apply(options.postProcessing)
     if (options.skybox !== undefined) this.skybox = options.skybox
-    if (options.ambientOcclusion) this.setAmbientOcclusion(options.ambientOcclusion)
     if (options.fog) this.setFog(options.fog)
     if (options.antialias !== undefined) {
       const a = options.antialias
@@ -302,12 +287,6 @@ export class Scene implements Presentable {
     _creator.setSkybox(this._id, Color.toPackedRgb(sky))
   }
 
-  /** Runtime form of `ambientOcclusion` (a graphics-settings menu). `false` turns it off. */
-  setAmbientOcclusion(options: boolean | AmbientOcclusionOptions): void {
-    const o: AmbientOcclusionOptions = typeof options === "object" ? options : {}
-    const quality = { low: 0, medium: 1, high: 2, ultra: 3 }[o.quality ?? "medium"] ?? 1
-    _creator.setAmbientOcclusionOptions?.(this._id, options !== false, o.intensity ?? 1, o.radius ?? 0.3, o.power ?? 1, quality)
-  }
 
   /** Runtime form of `fog` (weather, entering a building). `false` turns it off. */
   setFog(options: FogOptions | false): void {
@@ -349,10 +328,6 @@ export class Scene implements Presentable {
   setLodBias(bias: number): void {
     _creator.setLodBias?.(bias)
   }
-  /** Runtime form of `bloom` / `bloomIntensity` (a graphics-settings menu). */
-  setBloom(enabled: boolean, intensity = 0.2): void {
-    _creator.setBloomOptions(this._id, enabled, intensity, 1)
-  }
   /**
    * How bright the environment (IBL) lights the scene, in lux — `SceneOptions.environmentIntensity`
    * after the fact. Live: it changes the probe's intensity, not the probe, so it costs nothing and