lecodes-sdk 0.20.0 → 1.0.0

package/src/bridges.d.ts

@@ -106,6 +106,8 @@ declare global {
      *  flat skybox. */
     setSkyboxTexture?(sceneId: number, fetchId: number): void
     setSceneMultiSampleAntiAliasing(sceneId: number, enabled: boolean, scale: number): void
+    /** Filament View::setStencilBufferEnabled (Scene.stencil). Optional. */
+    setSceneStencil?(sceneId: number, enabled: boolean): void
     /** Render resolution: `renderScale` (0.25–1) = fixed 3D-buffer scale vs the viewport (the UI is
      *  untouched; a host that owns the 3D texture resizes it, one rendering into the swapchain may
      *  ignore it), `dynamicResolution` = engine-adaptive scaling under that down to `minScale`.
@@ -118,6 +120,23 @@ declare global {
      *  anisotropy` does that automatically (a scene's env runs before its nodes build). Optional:
      *  hosts that predate it keep isotropic filtering and the SDK skips the call. */
     setTextureAnisotropy?(level: number): void
+    /** Engine-wide cap on texture size (`Texture.maxSize` / `SceneOptions.maxTextureSize`): a
+     *  KTX2 wider or taller than `size` loses its top mip levels on load, a glTF PNG/JPEG is
+     *  downsampled; 0 = no cap. Reaches textures created AFTER the call — a loaded level keeps
+     *  its textures, so a settings menu applies it on the next level load. `createTexture` flag
+     *  2 (FULL_SIZE) exempts one texture (lightmap pages). Optional: hosts that predate it load
+     *  full-size textures and the SDK skips the call. */
+    setTextureMaxSize?(size: number): void
+    /** Depth-reading effects on / off (`scene.setDepthEffects`): soft particles (`depthFade`) and
+     *  projected decals read the scene depth, which costs a half-res depth pre-pass of every opaque
+     *  draw. Off = no pre-pass, hard-edged particles, decal sets draw nothing. Engine-wide, live.
+     *  Optional: hosts that predate it keep the effects and the SDK skips the call. */
+    setDepthEffects?(enabled: boolean): void
+    /** LOD distance (`scene.setLodBias`): the LOD pass' screen-size thresholds × `bias` — 2 = every
+     *  level switches at half the distance, 0.5 = full detail twice as far; 1 = the defaults
+     *  (0.30 / 0.12 / 0.05 of the viewport height). Engine-wide, live, clamped 0.25..8. Optional:
+     *  hosts without the LOD pass ignore it and the SDK skips the call. */
+    setLodBias?(bias: number): void
     setMaterialGlobalParameter(sceneId: number, i: number, x: number, y: number, z: number, w: number): void
     getCameraFov(sceneId: number, fovType: number): number
     /** The scene camera's projection: VERTICAL fov in degrees + near/far clip distances (defaults
@@ -136,7 +155,9 @@ declare global {
 
     /** `uv1` (optional, 2 floats per vertex) is the lightmap UV set (Geometry.uv1); absent → the
      *  host duplicates `uv` into UV1. Hosts that predate the argument ignore it. */
-    setMesh(entityId: number, materialId: number, vertices: Float32Array, normals: Float32Array, indices: Uint16Array, uv: Float32Array, meshType: number, uv1?: Float32Array): void
+    /** `colors` (Geometry.colors) is 4 bytes RGBA per vertex for a `requires: [color]` material;
+     *  a host that predates it draws the mesh white. */
+    setMesh(entityId: number, materialId: number, vertices: Float32Array, normals: Float32Array, indices: Uint16Array, uv: Float32Array, meshType: number, uv1?: Float32Array, colors?: Uint8Array): void
     // Terrain (gl/Terrain.ts ↔ creator-gl/src/terrain.cpp, docs/terrain-plan.md §1.4): a heightmap grid of
     // sizeX × sizeZ samples `cellSize` apart (+X across columns, +Z across rows, height on +Y, sample 0 at
     // the node origin), drawn as one renderable per `chunk`×`chunk` cells on internal children of the
@@ -157,10 +178,26 @@ declare global {
     setInstancedMeshMaterial(entityId: number, materialId: number): void
     setInstancedMeshShadows(entityId: number, cast: boolean, receive: boolean): void
     setCulling(entityId: number, culling: boolean): void
+    /** Filament RenderableManager::setPriority — the coarse draw order, 0..7 (Mesh.renderPriority).
+     *  Optional: an older host leaves everything at the default 4. */
+    setRenderPriority?(entityId: number, priority: number): void
+    /** Filament MaterialInstance::setDepthCulling / setDepthWrite — per-instance overrides of the
+     *  depth state baked into the shader package (Material.depthTest / depthWrite). Optional. */
+    setMaterialDepthTest?(materialInstanceId: number, enable: boolean): void
+    setMaterialDepthWrite?(materialInstanceId: number, enable: boolean): void
+    /** Filament MaterialInstance::setCullingMode: 0 none (double-sided), 1 front, 2 back. Optional. */
+    setMaterialCulling?(materialInstanceId: number, mode: number): void
+    /** Filament MaterialInstance stencil state in one call (Material.stencil): `test` 0 always, 1 never,
+     *  2 less, 3 lessEqual, 4 greater, 5 greaterEqual, 6 equal, 7 notEqual; the ops 0 keep, 1 zero,
+     *  2 replace, 3 increment, 4 decrement, 5 invert. Optional. */
+    setMaterialStencil?(materialInstanceId: number, write: boolean, test: number, ref: number, onPass: number, onFail: number, onDepthFail: number, readMask: number, writeMask: number): void
     setCastShadows(entityId: number, culling: boolean): void
     setReceiveShadows(entityId: number, culling: boolean): void
 
-    createTexture(systemId: number, onComplete: (id: number, width: number, height: number) => void, onReject: () => void): void
+    /** Decode a fetched image into a texture. `flags` (optional, Texture.load): bit 1 = LINEAR data
+     *  (a normal map — store RGBA8, not sRGB); unset / absent = colour, sRGB. A host that ignores
+     *  it loads colour correctly and normal maps wrongly. KTX2 decides by its own header. */
+    createTexture(systemId: number, onComplete: (id: number, width: number, height: number) => void, onReject: () => void, flags?: number): void
     // Texture from a baked _creatorCanvas surface (RGBA8, already rasterized — synchronous, no decode).
     createTextureFromCanvas(surfaceId: number): number
     updateTextureFromCanvas(texId: number, surfaceId: number): void
@@ -237,9 +274,11 @@ declare global {
     // interp 0 linear/1 step/2 cubic, comps, keyCount, times…, values…)*]. Returns a one-clip set id (0 = bad).
     createClipFromTracks(names: string, data: Float32Array): number
     getClipSetInfo(clipSetId: number): { name: string, duration: number, trackCount: number }[]
-    // A sub-range [start, end] seconds of one clip as a NEW single-clip set (index 0), re-timed to 0;
-    // interior keys copied, boundary values interpolated in at the cut points; events re-timed. 0 = bad id/range.
-    sliceClip(clipSetId: number, clip: number, start: number, end: number): number
+    // A clip DERIVED from one of the set as a NEW single-clip set (index 0) — AnimationClip.from(clip, { mirror,
+    // from, to }): the mirror (left ↔ right on the set's own rig, the GLB's node tree: contacts swapped, heading
+    // negated), then the [start, end] window re-timed to 0 (start < 0 = whole, end < 0 = the clip's end; boundary
+    // values interpolated in, events re-timed). 0 = bad id / range, or a mirror asked of a set without a rig.
+    deriveClip(clipSetId: number, clip: number, mirror: boolean, start: number, end: number): number
     // Clip events on the CLIP: normalized times (sorted ascending). Every slot bound to the clip, in every
     // animator, fires slot event type 4 + i on crossing event i. Empty = clear.
     setClipEvents(clipSetId: number, clip: number, times: Float32Array): void
@@ -304,7 +343,7 @@ declare global {
     // One curve of a slot's clip at `time` seconds (< 0 = the slot's clock now): which 0 φ (-1 = no gait)
     // / 1 travel (m) / 2 yaw (rad, + = left) / 3 speed (m/s) / 4-5 unit travel direction x / z
     // (model space, held through stills — integrate dir × d(travel) for the root's 2D path).
-    animatorSlotCurveAt(animatorId: number, slot: number, which: 0 | 1 | 2 | 3 | 4 | 5, time: number): number
+    animatorSlotCurveAt(animatorId: number, slot: number, which: 0 | 1 | 2 | 3 | 4 | 5 | 6, time: number): number
     // out ← [curve sample dt, total travel (m), mean speed (m/s), in-place flag]. False = unbound slot.
     animatorSlotCurveInfo(animatorId: number, slot: number, out: Float32Array): boolean
     animatorSlotTurn(animatorId: number, slot: number): number          // the clip's total root yaw, rad
@@ -445,6 +484,12 @@ declare global {
      *  [minX,minY,minZ, maxX,maxY,maxZ] — zeros for an empty / not-yet-loaded subtree. What
      *  `Shape.fit()` measures. Optional: absent on hosts predating the binding. */
     computeBoundingBox?(entityId: number): Float32Array
+    /** DEBUG pick: the closest TRIANGLE under a screen point (logical px) among the loaded GLB instances —
+     *  entityId = one Model's root, 0 = every instance — CPU-skinned with the joints' CURRENT pose, both
+     *  faces. JSON string (`Model.pickTriangle` parses it: node, mesh, primitive, triangle, hit point,
+     *  the three vertices with their raw JOINTS_0/WEIGHTS_0 pairs), "" on a miss. One full CPU skin per
+     *  call — click-rate only. Optional: a debug tool, hosts may lack it. */
+    pickTriangle?(entityId: number, screenX: number, screenY: number): string
     setColliderFromMesh(entityId: number, meshEntityId: number, form: number): void
     setColliderBox(entityId: number, centerX: number, centerY: number, centerZ: number, sizeX: number, sizeY: number, sizeZ: number): void
     setColliderSphere(entityId: number, centerX: number, centerY: number, centerZ: number, radius: number): void
@@ -462,7 +507,9 @@ declare global {
     lightmapHasSupport?(): boolean
     /** Lightmap consumption (docs/lightmap-plan.md §3): the next createGlb takes lightmap.filamat (the material
      *  behind that instance id) instead of the ubershader and keeps TEXCOORD_1; UINT32_MAX clears. */
-    setNextGlbLightmapped?(materialInstanceId: number): void
+    /** `maskedMaterialInstanceId` (2026-09-11): the tier's masked twin for the asset's alpha-MASK materials
+     *  (foliage cards); a host without it ignores the argument and keeps those on the ubershader. */
+    setNextGlbLightmapped?(materialInstanceId: number, maskedMaterialInstanceId?: number): void
     /** The level-wide knobs every lightmap-material instance shares (applied to the ones that exist and to every one
      *  created afterwards): the sun-mask shadow math (ambientScale, sunStrength), how much baked AO applies (aoStrength,
      *  1 = all) and the light atlas' / volume's physical irradiance per encoded 1.0 (lightScale; 0 = no baked lights).
@@ -567,43 +614,86 @@ declare global {
     characterSetPosition(charId: number, x: number, y: number, z: number): void
     // Vehicle (Jolt VehicleConstraint + WheeledVehicleController). One settings BLOB, so tuning knobs
     // never grow this ABI — layout (floats):
-    //   header[21]: version(5), mass, comAuto, comY,
-    //               engTorque, engMaxRpm, engIdleRpm, engInertia, engBraking, clutchStrength,
+    //   header[34]: version(15), mass, comAuto, comY,
+    //               engTorque, engMaxRpm, engIdleRpm (0 = no floor: the engine can stall, the game
+    //                 holds idle and cranks it), engInertia, engBraking, clutchStrength,
     //               diffRatio (<= 0 = a fully OPEN differential),
     //               antiRoll (the bar's stiffness as a FRACTION of the wheel spring; 0 = no bars),
     //               maxTiltDeg,
-    //               steerLockDeg, steerAtSpeedDeg, steerSpeedMs, steerRateDeg (speed-sensitive
-    //                 steering: the lock falls to steerAtSpeedDeg by steerSpeedMs and the wheels turn
-    //                 no faster than steerRateDeg per second; 0/0/0 = the raw lock, instantly),
     //               aeroDownforce, aeroDrag (each a fraction of the car's own WEIGHT at 30 m/s, scaled
     //                 by v² from there; 0/0 = no aero, Jolt's own behaviour),
+    //               steerMode (0 = `steer` is the wheel angle as a fraction of the lock; 1 = `steer`
+    //                 is where the driver's HANDS aim a steering column the engine integrates every
+    //                 sub-step: I·θ̈ = T_hand + T_align·(1 − assist) + T_stop − damping·θ̇ − friction,
+    //                 T_hand = clamp(handStiffness·(steer·lock − θ), ±handTorque·steerForce),
+    //                 steerForce = the input's per-frame hold — the game's policy on when the hands let go,
+    //                 T_align = the steered tires' lateral force × (pneumatic trail collapsing to
+    //                 trailFloor × trail at the curve's peak + caster) — heavy at speed, light past
+    //                 the peak, self-centring, counter-steering in a slide),
+    //               colInertia, colDamping, colFriction (the patch's dry friction, fades out by 1.5 m/s),
+    //               colCaster, colTrail, colTrailFloor (the aligning torque's arms — read in BOTH
+    //                 modes; steerTorque is reported either way, the force-feedback signal),
+    //               colHandTorque, colHandStiffness, colAssist (power steering),
+    //               colRateDeg (the HANDS' top turning speed, deg/s — they cannot push a wheel that
+    //                 outruns them, they can still hold it; the free column is uncapped; 0 = none),
+    //               colStopDeg, colStopTorque, colStopDamping (the end stop: over the last colStopDeg
+    //                 before the lock the rack pushes back colStopTorque × depth² N·m and damps by
+    //                 colStopDamping × depth N·m·s/rad — progressive, viscous rubber; 0 band = the
+    //                 hard clamp only),
+    //               colBearing (the column's own dry friction, N·m, at any speed — rack and bearings),
+    //               colHandRamp (seconds the hands' torque builds to colHandTorque over; 0 = instant),
+    //               clutchCapacity (N·m the clutch passes before it slips, × the clutch scalar; 0 = Jolt's
+    //                 viscous clutch alone),
     //               wheelCount, curveCount
     //   + curveCount * 2: the engine's normalized torque curve (x = rpm/maxRpm, y = torque/maxTorque);
     //                     0 points keeps Jolt's default
-    //   + wheelCount * 15: px, py, pz, radius, width, maxSteerDeg, drive, brakeTorque, handBrakeTorque,
-    //                      axle, travel, stiffness, damping, grip, tireCurve (0 = road, 1 = arcade)
-    // NO gear list and no wheel node ids: the gearbox is the SDK's (see vehicleSetTransmission) and the
-    // SDK poses the wheel nodes itself. Chassis space is forward -Z / up +Y (matching node.forward);
+    //   + per wheel, VARIABLE length: 15 fixed floats — px, py, pz, radius, width, maxSteerDeg,
+    //                      driven (the wheel's SHARE of the engine's torque: an axle's share is the sum
+    //                      of its two, the left/right split their ratio; every wheel 0 = no drive at
+    //                      all), axle, travel, stiffness, damping,
+    //                      traction (the longitudinal impulse clamp as a multiple of friction × load;
+    //                      1 = the physical tire, Jolt's sample runs 10), circle (friction circle 0..1:
+    //                      the share of lateral capacity the longitudinal impulse in use takes away;
+    //                      0 = the two axes independent), sideCount, forwardCount — then
+    //                      sideCount × (slip angle °, friction) and forwardCount × (slip ratio,
+    //                      friction). Tire curves are POINTS the SDK sends (its presets are SDK-side);
+    //                      0 points keeps Jolt's own curve.
+    // In steerMode 0 the steering input is RAW: `steer` × each wheel's maxSteerDeg, per fixed step —
+    // any taper / rate limit is the game's. In mode 1 `steer` is where the hands aim the wheel.
+    // NO gear list, no pedals and no wheel node ids: the gearbox is the game's (a ratio + clutch in
+    // the input vector), the brakes are a torque per wheel in the same vector, and the game poses its
+    // 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.
     vehicleCreate(entityId: number, shapeId: number, settings: Float32Array): number
     vehicleDestroy(vehicleId: number): void
-    /** forward/right in [-1,1], brake/handBrake in [0,1]. Sticky; any non-zero input wakes the car. */
-    vehicleSetInput(vehicleId: number, forward: number, right: number, brake: number, handBrake: number): void
-    /** The SDK's gearbox, latched and applied once per fixed step: `ratio` is the ONE ratio the car is
-     *  running (0 = neutral, negative = reverse — the engine never sees a gear list) and `clutch` is
-     *  the 0..1 shift envelope scaling the clutch in the coupled engine/wheel solve. */
-    vehicleSetTransmission(vehicleId: number, ratio: number, clutch: number): void
-    /** Re-apply the TUNABLE half of the blob (same layout) to a live car — differential, per-wheel grip,
-     *  engine torque/RPM/curve, clutch strength, steering lock/taper/rate, brake torques, tilt limit.
-     *  Structural values (mass, centre of mass, wheel geometry, driven wheels, suspension, anti-roll)
-     *  are ignored: those need a re-create. */
+    /** 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),
+     *  steerForce 0..1 (with a column: how firmly the hands hold the wheel — the game's per-frame
+     *  policy on letting go; without one, ignored), ratio (the ONE gear ratio the car runs: 0 =
+     *  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. */
+    vehicleSetInput(vehicleId: number, 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. */
     vehicleSetTuning?(vehicleId: number, settings: Float32Array): void
-    /** out = [speed, rpm, wheelsInContact, vx, vy, vz] + per wheel
-     *  [contact, slipLong, slipAngleDeg, suspensionLength, steerDeg, spin]. The last three per wheel are
-     *  its VISUAL POSE — the SDK's Wheel aspect builds the node transform from them. */
+    /** 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
+     *  tires' self-aligning torque on the steering, N·m, + = pulls right — the force-feedback signal,
+     *  reported in both steering modes)
+     *  + per wheel [contact, slipLong, slipAngleDeg, suspensionLength, steerDeg, spin, fLat, fLong, vLat, vSlip, load]
+     *  (fLat/fLong = the tire's forces, N, + = to its right / pushing the car forward; vLat/vSlip = the
+     *  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. */
     vehicleGetState(vehicleId: number, out: Float32Array): void
-    /** Teleport upright and clear all motion (velocities, engine RPM, gear, wheel spin). */
+    /** 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. */
     vehicleReset(vehicleId: number, x: number, y: number, z: number, qx: number, qy: number, qz: number, qw: number): void
     /** The chassis rigid body, for the plain body calls (physicsApplyImpulse, …). 0 if unknown. */
     vehicleBodyId(vehicleId: number): number
@@ -644,6 +734,61 @@ declare global {
     ragdollActive?(ragdollId: number): boolean
     /** The rigid body of part `index` (for physicsApplyImpulseAt / velocities). 0 if unknown. */
     ragdollBodyId?(ragdollId: number, index: number): number
+    // 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
+    // (gravity, wind, drag, stiffness toward the animated shape, an angle cone, capsule / sphere
+    // colliders, a floor plane, bone length, neighbour links) in an engine stage AFTER the late phase
+    // and BEFORE the skin flush: the animator, an active ragdoll and late-phase JS bone writes are the
+    // input, the simulated local rotations the output. Bones the animator does not drive keep their
+    // bind pose as the target; driven ones follow their clip. Optional: a host without it shows the
+    // animation alone.
+    //   bones[boneCount]: entity ids — the root first, every other bone a child of an earlier one.
+    //   settings — header[28]: version(1), boneCount, boneStride(7), then the chain params: weight
+    //              (0..1 animation → simulation; 0 = off, re-arms on the animated pose), follow (0..1 of
+    //              the root's travel carried onto the particles; 0 = full whip), wind xyz (m/s², world),
+    //              link (0..1 neighbour-link strength), rate (substep Hz, ≤ 4 substeps per frame),
+    //              teleport (a root jump past this many metres resets the chain), floor (0/1), floor
+    //              point xyz, floor normal xyz (the floor slots are overridden by dynamicBoneSetFloor),
+    //              floorFriction (a Coulomb coefficient: a resting particle's slide loses up to friction · g · dt of
+    //              speed per substep), iterations
+    //              (constraint passes per substep, 1..8, default 4; a long rope may want 8), side (the
+    //              cloth's outside, one-sided colliders: 0 none, 1 away from the root bone's axis, 2 the
+    //              next xyz in the root bone's frame), side xyz, guideHold (0..1: guides re-applied after
+    //              every constraint pass with this fraction of their weight; 0 = once before the passes),
+    //              edges (1 = the bone segments and links collide with the capsules too, not only the particles),
+    //              spin (> 0: the chain in the parent bone's rotating frame + its centrifugal / Euler forces × spin;
+    //              0 = the translational frame, no turn forces), spinInertia (s: the cloth's own rotation follows the body's with this time constant — behind on a start, past the back on a stop; 0 = glued)
+    //   + boneCount × 7: radius (m), stiffness (0..1 per 1/60 s toward the animated shape), damping
+    //              (0..1 velocity lost per 1/60 s), gravity (m/s² along world −Y), angleLimit (degrees off
+    //              the animated direction, 0 = none), mass (relative, 0 = 1: a bone-length constraint
+    //              moves its two ends in inverse proportion; the root is kinematic; < 0 = PINNED, the bone
+    //              rides the animation), give (m, pinned bones: a soft pin — a collider may push the bone
+    //              this far off its animated place, its local translation is written back too; 0 = hard)
+    //   links: (a, b) bone index pairs held at their rest distance (a cloak's columns; two linked leaves
+    //          link their virtual tips too, so a hem stays a hem); optional.
+    dynamicBoneCreate?(modelRootId: number, bones: Uint32Array, settings: Float32Array, links?: Uint16Array): number
+    dynamicBoneDestroy?(id: number): void
+    /** Retune a live chain: the same blob as create (the bone rows too when the count matches). */
+    dynamicBoneSet?(id: number, settings: Float32Array): void
+    /** The floor the particles stay above: mode 0 none / 1 the plane (point, normal) / 2 probe — the
+     *  engine casts a ray from the chain root down every frame (the ground probe, the model root
+     *  excluded) and uses the hit; no hit / no physics world = no floor that frame. */
+    dynamicBoneSetFloor?(id: number, mode: 0 | 1 | 2, x: number, y: number, z: number, nx: number, ny: number, nz: number): void
+    /** The next frame snaps the chain onto the animated pose (a teleport, a cut). */
+    dynamicBoneReset?(id: number): void
+    /** The colliders this chain collides with (dynamicBoneColliderCreate ids); replaces the list. */
+    dynamicBoneSetColliders?(id: number, colliderIds: Uint32Array): void
+    /** The particles' world positions (bones first, then the leaves' virtual tips), 3 floats each into
+     *  `out`; returns the count written — a debug overlay. */
+    dynamicBoneParticles?(id: number, out: Float32Array): number
+    // guides: rows × 5 — bone index (in the chain's bone order), world x y z, weight — world points the
+    // bones' particles are drawn to before the constraints; null / empty clears; refreshed every frame
+    dynamicBoneTargets?(id: number, rows: Float32Array | null): void
+    /** A capsule a → b in the entity's local space (a == b = a sphere) that rides the entity — a bone
+     *  of the body the chains must not pass through. Returns a collider id (0 on failure). */
+    dynamicBoneColliderCreate?(entityId: number, ax: number, ay: number, az: number, bx: number, by: number, bz: number, radius: number): number
+    dynamicBoneColliderSet?(colliderId: number, ax: number, ay: number, az: number, bx: number, by: number, bz: number, radius: number): void
+    dynamicBoneColliderDestroy?(colliderId: number): void
     // Legacy coupled shape+body (still used by the worker RigidBody).
     physicsCreateBox(entityId: number, hx: number, hy: number, hz: number, motionType: number, mass: number): number
     physicsCreateSphere(entityId: number, radius: number, motionType: number, mass: number): number
@@ -681,6 +826,23 @@ declare global {
     spawnParticles(entityId: number, count: number): void
     setParticleSystemConfig(entityId: number, data: Float32Array): void
 
+    // Projected decals (creator-gl src/decals.h; SDK gl/DecalSet.ts). A set on an entity = one
+    // renderable of `capacity` (0 = 256) unit boxes drawn with the material instance (decal.filamat)
+    // — each box projects its atlas cell onto the opaque scene behind it through the scene depth
+    // buffer. A record is 27 floats in the SET entity's space: X Y Z axes scaled by the box's
+    // width / height / depth (Z = out of the surface), centre, atlas rect u0 v0 u1 v1, tint rgba,
+    // life (s, 0 = forever), fadeIn (s), fadeOut (s), capStart, capEnd (tilt of the image's bottom /
+    // top edge in unit space — mitred trail joints, 0 = square), alphaStart, alphaEnd (opacity
+    // multipliers at the bottom / top edge — a gradient along the image). addDecal returns the slot (0xFFFFFFFF = no
+    // set; a full set recycles its oldest); updateDecal keeps the slot's birth time. Optional:
+    // a host without them draws no decals (the SDK warns once).
+    createDecalSet?(entityId: number, materialInstanceId: number, capacity: number): void
+    addDecal?(entityId: number, record: Float32Array): number
+    updateDecal?(entityId: number, slot: number, record: Float32Array): void
+    removeDecal?(entityId: number, slot: number): void
+    clearDecals?(entityId: number): void
+    decalCount?(entityId: number): number
+
     createNoise(): number
     setNoiseFrequency(noiseId: number, frequency: number): void
     setNoiseOctaves(noiseId: number, octaves: number): void
@@ -960,6 +1122,72 @@ declare global {
     crowdRead(crowdId: number, out: Float32Array): number
   }
 
+  // ---- Game audio (creator-audio) ----------------------------------------------------------------
+  // docs/audio-plan.md. Whole clips decoded up front, a fixed voice pool (play allocates nothing),
+  // 3D sources the engine follows per frame, mixer buses with insert effects, reverb zones,
+  // occlusion. OPTIONAL as a block: the SDK gates on `typeof _creatorAudio !== 'undefined' &&
+  // hasSupport()` and stays inert (silent Sound, inert Voice) without it. Present on hosts built with
+  // CREATOR_PKG_AUDIO (desktop first; Android / Apple pending — parity `audio-game`). The headless
+  // renderer provides a RECORDER (plays are logged, nothing is mixed). Every parameter block is a
+  // fixed-order Float32Array (creator-audio.h CAUD_SRC_* / the effect param orders).
+  var _creatorAudio: {
+    hasSupport(): boolean
+    /** Decode the bytes behind a fetch system id (WAV / MP3 / FLAC / OGG Vorbis) on the engine's
+     *  loader thread; mono unless `stereo`. onDone(clipId, durationSeconds, channels). */
+    loadClip(systemId: number, stereo: boolean, onDone: (clipId: number, duration: number, channels: number) => void, onReject: (message: string) => void): void
+    releaseClip(clipId: number): void
+    /** Bus id by name (-1 unknown); 0 master, 1 sfx, 2 music, 3 ui, 4 voice. */
+    busId(name: string): number
+    /** Creates (or finds) an app-defined bus under master. -1 when the 16 slots are full. */
+    createBus(name: string): number
+    setBusVolume(bus: number, volume: number): void
+    setBusMuted(bus: number, muted: boolean): void
+    /** kind 1 reverb [roomSize, damping, width, mix, preDelay] · 2 echo [delay, decay, mix] ·
+     *  3 lowpass [cutoffHz]; an empty array turns the effect off. Changes are smoothed. */
+    setBusEffect(bus: number, kind: number, params: Float32Array): void
+    stopBus(bus: number, fade: number): void
+    /** A 3D emitter. `attachSource` binds it to an entity the engine follows every frame;
+     *  `setSourcePosition` places an unbound one (playAt). */
+    createSource(): number
+    attachSource(sourceId: number, entityId: number): void
+    /** [minDistance, maxDistance, rolloff (0 none 1 inverse 2 linear 3 exp), coneInnerDeg,
+     *  coneOuterDeg, coneOuterGain, doppler, spread, occlusion (0/1), bus]. */
+    setSourceParams(sourceId: number, params: Float32Array): void
+    setSourcePosition(sourceId: number, x: number, y: number, z: number): void
+    stopSource(sourceId: number, fade: number): void
+    sourceVoices(sourceId: number): number
+    destroySource(sourceId: number): void
+    /** The listener entity; 0 = the active scene camera (the default). */
+    setListener(entityId: number): void
+    setListenerOptions(dopplerFactor: number): void
+    /** HRTF binaural rendering for the `maxVoices` nearest spatial voices (headphones); the rest keep panning. */
+    setHrtf(enabled: boolean, maxVoices: number): void
+    /** Whether the engine's time scale (Time.scale) also pitches the sfx bus. Default false (pause = mute only). */
+    setTimeScalePitch(enabled: boolean): void
+    /** → a voice token (0 = nothing played: the pool refused, the clip is not ready). bus -1 = the
+     *  source's bus (sfx for 2D). pan is 2D only. */
+    play(clipId: number, sourceId: number, bus: number, volume: number, pitch: number, loop: boolean, priority: number, fadeIn: number, startAt: number, pan: number): number
+    setVoiceVolume(token: number, volume: number): void
+    setVoicePitch(token: number, pitch: number): void
+    setVoicePan(token: number, pan: number): void
+    stopVoice(token: number, fade: number): void
+    voicePlaying(token: number): boolean
+    voiceTime(token: number): number
+    /** THE ended listener (single slot per JS world): called once per tick with the tokens of the
+     *  voices that ended since the previous tick — natural end, stop, steal. */
+    setOnEnded(callback: ((tokens: Float32Array) => void) | null): void
+    stopAll(fade: number): void
+    /** A reverb volume: shape 0 box (dims = full size) / 1 sphere (dims[0] = diameter), in the
+     *  entity's local units; `blend` metres of crossfade inside the border; reverb params as for
+     *  setBusEffect kind 1. The listener inside blends the zone's reverb onto `bus`. */
+    createZone(): number
+    attachZone(zoneId: number, entityId: number): void
+    setZone(zoneId: number, shape: number, dims: Float32Array, blend: number, bus: number, reverb: Float32Array): void
+    destroyZone(zoneId: number): void
+    /** [voicesPlaying, voicesMono, voicesStereo, stolen, clips, clipBytes, peak, sampleRate, listenerZone, zoneBlend, hrtfVoices]. */
+    stats(): Float32Array
+  }
+
   // ---- UI engine (creator-ui) ------------------------------------------------------------------
   var _creatorUI: {
     // Global back-press fallback (app.onBackPressed): a PROPERTY the SDK writes, not a call —
@@ -989,6 +1217,11 @@ declare global {
     // Content-property push. Props: "value" (input/textarea text), "focus" (boolean — focus/blur
     // the input, opening/dismissing the keyboard; rides this channel so programmatic focus needs
     // no new ABI method), plus element-specific ones ("src", "text", …).
+    // An image "src" (here and at creation) is a url string, { _id } (a host buffer), { svg },
+    // { canvasSurface } (a baked Canvas), or { scene2d: sceneId } — a LIVE 2D scene the host draws
+    // into the node's laid-out box every frame with the scene's own camera (native: c2dDrawSceneGL
+    // into a per-node framebuffer; no intrinsic size, the scene needs no openScene). The engine's
+    // simulation must still step each frame for it (native: c2dTick when nothing is presented).
     updateNode(nodeId: number, prop: string, value: any): void
     setSourceRect(nodeId: number, x: number, y: number, w: number, h: number): void
 
@@ -1100,7 +1333,7 @@ declare global {
     disposeFetch(systemId: number): void
     // ---- Local filesystem (the SDK `files` global) ----------------------------------------------
     // The read/write/delete half of `fetchLocal`, for hosts where the app OWNS a filesystem
-    // (desktop). All five are OPTIONAL and stand or fall together: a sandboxed host (web, mobile)
+    // (desktop). All seven are OPTIONAL and stand or fall together: a sandboxed host (web, mobile)
     // implements none of them and `files.supported` is false there.
     //
     // ASYNC, like `fetch`: file IO must not block the frame, so each takes an onComplete/onReject
@@ -1130,6 +1363,16 @@ declare global {
     deleteLocal?(path: string, recursive: boolean, onComplete: () => void, onReject: (err: Error) => void): void
     /** Create a directory and any missing parents. An existing directory is success. */
     mkdirLocal?(path: string, onComplete: () => void, onReject: (err: Error) => void): void
+    /** List a directory (added 2026-09-11, same optional set). Settles with an array of entries —
+     *  `name` = basename, `path` = relative to the listed directory with `/` separators (equals
+     *  `name` unless `recursive`), `kind`, `size` in bytes (0 for a directory), `modified` in ms
+     *  since the epoch — SORTED by `path`, so two runs and two hosts agree. Symlinks are followed
+     *  for `kind`; anything that is neither file nor directory is skipped. A MISSING directory is a
+     *  null result (like the readers); a path that is a file, or an unreadable directory, rejects. */
+    listLocal?(path: string, recursive: boolean, onComplete: (entries: { name: string; path: string; kind: "file" | "dir"; size: number; modified: number }[] | null) => void, onReject: (err: Error) => void): void
+    /** One entry's metadata (`name`, `kind`, `size`, `modified` — see `listLocal`) for a file or a
+     *  directory, or null when there is nothing at `path`. */
+    statLocal?(path: string, onComplete: (entry: { name: string; kind: "file" | "dir"; size: number; modified: number } | null) => void, onReject: (err: Error) => void): void
     openFilePicker(onComplete: (res: any) => void, onReject: () => void, multiple: boolean, accept?: string): void
     // Present the OS media share sheet for a host buffer (`systemId` — a File/response id), with an
     // optional caption. iOS: the share sheet also offers "Save to Files"/Photos. Web: saves (downloads)
@@ -1158,7 +1401,11 @@ declare global {
     /** Continuous input poll by channel id (SDK `InputChannel`): 0 MouseX, 1 MouseY (logical px,
      *  last known cursor position inside the viewport), 2 MouseDX, 3 MouseDY (motion accumulated
      *  during the PREVIOUS frame — unaccelerated/raw where the OS offers it, counts while locked),
-     *  4 WheelX, 5 WheelY (wheel notches, previous frame), 6 PointerLocked (0/1), 7 GamepadCount;
+     *  4 WheelX, 5 WheelY (wheel notches, previous frame), 6 PointerLocked (0/1), 7 GamepadCount,
+     *  8 PointerOnUI (0/1: the primary pointer went DOWN on something the UI claimed — an
+     *  interactive node, a scrollable, an editable, a modal backdrop — and is still held; stays 1
+     *  wherever the cursor goes until the release, so a drag that started on a HUD control never
+     *  becomes camera look; always 0 while pointer-locked and for touch-only hosts without a UI claim);
      *  gamepad p at 16 + 16·p: +0 Connected, +1 LeftX, +2 LeftY, +3 RightX, +4 RightY (−1..1,
      *  +Y = down like the web), +5 LeftTrigger, +6 RightTrigger (0..1). Unknown channel → 0.
      *  "Previous frame" = the host's own frame boundary (the event pump / rAF / fixed step), so

package/src/canvas/Canvas.ts

@@ -35,6 +35,11 @@ const OP = {
   DRAW_IMAGE: 30,
 } as const
 
+// Above this many buffered values, a buffer that is STILL growing between bakes is a leak, not a
+// drawing (a dense static picture is a few thousand; a 15 Hz graph without reset() passes this in
+// seconds and doubles its frame cost every minute).
+const CMD_GROWTH_WARN = 20000
+
 const ALIGN = { left: 0, center: 1, right: 2, start: 3, end: 4 } as const
 const BASELINE = { alphabetic: 0, top: 1, middle: 2, bottom: 3, hanging: 4, ideographic: 5 } as const
 const JOIN = { miter: 0, round: 1, bevel: 2 } as const
@@ -76,6 +81,11 @@ export class Canvas {
   // also refreshes the on-screen image node(s) via _creatorUI — the UI consumer the 2D/3D texture
   // hooks below don't cover. Stays a bare flag so a non-UI canvas never references the UI bridge.
   private _uiBound = false
+  // Growth watch: the command buffer is a RECORDING that every bake replays in full, so a canvas
+  // redrawn every frame without `reset()` gets slower with every update. `_bakeSurface` compares the
+  // buffer against the previous bake and warns once when it keeps growing past the threshold.
+  private _lastBakeLen = 0
+  private _warnedGrowth = false
 
   constructor(width: number, height: number, opts: { pixelRatio?: number } = {}) {
     this.width = width
@@ -198,6 +208,17 @@ export class Canvas {
 
   /** @internal — rasterize the recorded commands into the surface; returns the surface id. */
   _bakeSurface(): number {
+    const len = this._cmd.length
+    if (!this._warnedGrowth && len > CMD_GROWTH_WARN && this._lastBakeLen > 0 && len > this._lastBakeLen) {
+      this._warnedGrowth = true
+      console.warn(
+        `[canvas] ${this.width}×${this.height}: the command buffer keeps growing (${len} values, ` +
+        `${this._lastBakeLen} at the previous bake) — a Canvas records every call and each update() ` +
+        `replays all of it, so a redraw that never calls reset() gets slower every frame. ` +
+        `Call canvas.reset() before redrawing (or toBitmap() + reset() to flatten a drawing).`,
+      )
+    }
+    this._lastBakeLen = len
     const buf = new Float32Array(this._cmd)
     this._surfaceId = _creatorCanvas.rasterize(this._surfaceId, this.width, this.height, this.pixelRatio, buf, buf.length, this._refs)
     return this._surfaceId

package/src/compile/__tests__/compile.test.ts

@@ -39,6 +39,17 @@ test("a 2D project (new Scene2D) is marked 2d: enable and gl: disable", async ()
   expect(js).toContain("_creator2d.createScene")
 })
 
+test("a 3D project with a Canvas is NOT marked 2d: enable (Canvas keeps a `_creator2d.` texture path)", async () => {
+  const js = await compileProject({
+    name: "Car",
+    publicUrl: "https://le.codes",
+    entries: [ { path: "/main.ts", type: "text", text: "const c = new Canvas(64, 64)\nc.update()\nnew Scene().open()\n" } ],
+  })
+  expect(js).toContain("_creator2d.") // the canvas 2D-texture path survives tree-shaking
+  expect(js).not.toContain("// 2d: enable") // …but no Scene2D → the 2D engine is not in use
+  expect(js).not.toContain("// gl: disable")
+})
+
 test("2D and 3D bundles are DISJOINT (tree-shake drops the other engine)", async () => {
   const twoD = await compileProject({
     name: "2D", publicUrl: "https://le.codes", header: false,

package/src/compile/compileProject.ts

@@ -69,21 +69,22 @@ export type CompileOptions = {
   serverUrl?: string
 }
 
-export const compileProject = async (opts: CompileOptions): Promise<string> => {
-  // Client bundle: every *.server.ts becomes its RPC/channel stub (server code stays server-side).
-  const entries = stubServerEntries(opts.entries, opts.serverUrl ?? "")
-  const entry = opts.entryOverride ?? detectEntry(entries, scanModulesChisel).entry
-  if (!entry) {
-    throw new Error("Couldn't find an entrypoint (no .ts/.js project file — name yours main.ts). Pass entryOverride.")
-  }
+/** The bundle + its map SEPARATELY (the platform deploy writes the map as a sibling `.js.map`; the
+ *  preview inlines it) plus the entrypoint the compile used. `code` carries the metadata header
+ *  unless `header: false`; `map` is already shifted past that header. */
+export type CompileResult = { code: string, map: string | null, entry: string }
 
+/** Turn compile entries into the bundler's module map — the per-kind rules of the deployable
+ *  bundle (resource → URL export, shader → per-backend URL template, .svg → SvgSource, .json →
+ *  data, code verbatim). Exported for callers that build a `libraries` map from entries. */
+export const entriesToFiles = (entries: CompileEntry[], opts: { publicUrl: string, localAssets?: boolean }): Record<string, string> => {
   const files: Record<string, string> = {}
   for (const e of entries) {
     if (e.type === "resource") {
       if (opts.localAssets && !e.remote) {
         // The host resolves the asset by name at runtime (reads the local file → systemId); the
         // "id:" prefix is the host's local-resource URL scheme (parsed by the UI + 2D texture paths).
-        const name = e.path.split(/[\\/]/).pop() ?? e.path
+        const name = e.path.split(/[\/]/).pop() ?? e.path
         files[e.path] = `export default ("id:" + _creatorUtils.fetchLocal(${JSON.stringify(name)}))`
       } else {
         files[e.path] = `export default "${opts.publicUrl}${e.fileSrc ?? ""}"`
@@ -98,7 +99,7 @@ export const compileProject = async (opts: CompileOptions): Promise<string> => {
         // desktop host reports "desktop" on Windows and "opengl" on Linux, iOS "metal".
         // Only entries the CLI actually compiled+staged carry `shadersLocal`; server artifacts
         // (URLs) and un-staged ones keep the URL forms below.
-        const name = shaders[0].src.split(/[\\/]/).pop() ?? ""
+        const name = shaders[0].src.split(/[\/]/).pop() ?? ""
         const [prefix, suffix = ".filamat"] = name.split("_opengl")
         files[e.path] = `export default ("id:" + _creatorUtils.fetchLocal(${JSON.stringify(prefix + "_")} + _creator.backend + ${JSON.stringify(suffix)}))`
       } else if (shaders.length > 0) {
@@ -117,16 +118,30 @@ export const compileProject = async (opts: CompileOptions): Promise<string> => {
       files[e.path] = e.text ?? ""
     }
   }
+  return files
+}
 
+export const compileProjectWithMap = async (opts: CompileOptions): Promise<CompileResult> => {
+  // Client bundle: every *.server.ts becomes its RPC/channel stub (server code stays server-side).
+  const entries = stubServerEntries(opts.entries, opts.serverUrl ?? "")
+  const entry = opts.entryOverride ?? detectEntry(entries, scanModulesChisel).entry
+  if (!entry) {
+    throw new Error("Couldn't find an entrypoint (no .ts/.js project file — name yours main.ts). Pass entryOverride.")
+  }
+
+  const files = entriesToFiles(entries, opts)
   const { code, map } = await bundleProjectWithMap(
     entry, files, opts.format ?? "esm", opts.minify, opts.editor, opts.libraries, opts.sourcemap ?? true,
   )
-  if (opts.header === false) {
-    return map ? `${code}\n${inlineSourceMapComment(map)}` : code
-  }
+  if (opts.header === false) return { code, map, entry }
   const header = buildHeader(opts.name, code, { icon: opts.icon, fonts: opts.fontsHeader, icons: opts.iconsHeader })
-  if (!map) return header + code
-  // Shift the map down past the header (prepended before the code); the inline comment lands last.
+  // Shift the map down past the header (prepended before the code).
   const headerLines = (header.match(/\n/g) ?? []).length
-  return `${header}${code}\n${inlineSourceMapComment(offsetSourceMap(map, headerLines))}`
+  return { code: header + code, map: map ? offsetSourceMap(map, headerLines) : null, entry }
+}
+
+/** The bundle as ONE string, the map inlined at its end (the shipped/preview form). */
+export const compileProject = async (opts: CompileOptions): Promise<string> => {
+  const { code, map } = await compileProjectWithMap(opts)
+  return map ? `${code}\n${inlineSourceMapComment(map)}` : code
 }

package/src/compile/header.ts

@@ -33,8 +33,11 @@ export const buildHeader = (name: string, code: string, opts: HeaderOptions = {}
   else if (code.includes("_creator.createEngine")) header += `// gl: defer\n`
 
   // 2D (creator-2d) — non-exclusive: emitted alongside `gl: disable` so hosts skip Filament and a
-  // 2D-aware host brings up the lightweight sokol engine instead.
-  if (code.includes("_creator2d.")) header += `// 2d: enable\n`
+  // 2D-aware host brings up the lightweight sokol engine instead. Keyed on the scene constructor
+  // (like GL above), NOT on any `_creator2d.` reference: Canvas carries a 2D-texture path
+  // (`canvas.texture()` → `_creator2d.createTextureFromCanvas`) that chisel keeps in a pure-3D
+  // bundle, and nothing 2D works without a Scene2D anyway.
+  if (code.includes("_creator2d.createScene")) header += `// 2d: enable\n`
 
   if (code.includes("_creator.createARController")) header += `// ar: enable\n`
 
@@ -61,7 +64,7 @@ export const buildHeader = (name: string, code: string, opts: HeaderOptions = {}
 /** Same engine signals the header uses, for callers that need the project kind (e.g. icon type). */
 export const detectProjectKind = (code: string): "ar" | "ui" | "2d" | "3d" => {
   if (code.includes("_creator.createARController")) return "ar"
-  if (code.includes("_creator2d.")) return "2d"
+  if (code.includes("_creator2d.createScene")) return "2d"
   if (!code.includes("_creator.")) return "ui"
   return "3d"
 }