lecodes-sdk 1.0.0 → 1.1.0

package/src/bridges.d.ts

@@ -22,6 +22,11 @@ declare global {
     removeEntityFromScene(sceneId: number, entityId: number): void
     getSceneMaterial(sceneId: number): number
     warmRender(sceneId: number, onComplete: () => void): void
+    /** Compile every shader variant the scene's materials can need — sun / shadows / fog / skinning
+     *  and the dynamic-light key — on the backend's compiler threads, then call back. Materials
+     *  loaded later are queued in the background as they are created. Optional: a host without it
+     *  resolves at once (the SDK feature-detects). */
+    precompileShaders?(sceneId: number, onComplete: () => void): void
 
     createEntity(): number
     cloneEntity(entityId: number): number
@@ -53,11 +58,19 @@ declare global {
     /** Punctual light. `intensity` is luminous POWER in lumens; `falloff` is the metres of
      *  influence (filament's own default is 1 m, i.e. invisible, so it is always passed). */
     createPointLight?(entityId: number, intensity: number, color: number, falloff: number, castShadows: boolean): void
+    /** The lightmap bake takes this point light as a RECTANGLE of `width` x `height` metres (an area light: a ceiling
+     *  panel) in the light's local XZ plane, emitting along its local -Y with the same lumens; 0, 0 = a point again. */
+    setLightBakeArea?(entityId: number, width: number, height: number): void
     /** Live intensity for any light (sun: lux, point: lumens) — a flash animates instead of rebuilding. */
     setLightIntensity?(entityId: number, intensity: number): void
     setLightColor?(entityId: number, color: number): void
     /** `iblFetchId` (optional, -1 = none) names the scene's own probe; without it the host looks for a project-wide `ibl.ktx`. */
     setDefaultIbl(sceneId: number, intensity: number, iblFetchId?: number): void
+    /** The environment's intensity in lux, live (`scene.environmentIntensity`) — `setDefaultIbl` is
+     *  the only other way to change it and it rebuilds the cubemap and the IndirectLight from the
+     *  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: number, intensity: number): void
     setBloomOptions(sceneId: number, enabled: boolean, strength: number, quality: number): void
     setToneMapping?(sceneId: number, mode: number): void
     /** Exposure of the scene's camera — filament's physical model: `aperture` f-stops,
@@ -299,15 +312,19 @@ declare global {
     animatorSetBlend(animatorId: number, layer: number, dims: 1 | 2, slots: Uint16Array, positions: Float32Array, fade: number, speed: number, phases: Float32Array): void
     animatorSetBlendValue(animatorId: number, layer: number, x: number, y: number): void
     // Play a slot as the layer's one-shot, transitioned in over fadeIn (0 = cut) from whatever the layer
-    // showed (playing a blend MEMBER brings the whole blend back instead). A non-looping one-shot hands the
-    // layer back to the loop at the end, the hand-over firing fadeOut seconds BEFORE the end and the return
-    // transition taking fadeOut; fadeOut < 0 = not given (cut back; on a loopless layer hold the last frame).
+    // showed (playing a blend MEMBER brings the whole blend back instead). A non-looping one-shot plays to its
+    // end and hands the layer back to the loop THERE, the return transition taking fadeOut from its last pose
+    // (0 = cut back; on a loopless layer hold the last frame).
     // restart = rewind even if already playing (a restart is a new source: it transitions from the pose shown).
     animatorPlay(animatorId: number, slot: number, loop: boolean, speed: number, fadeIn: number, fadeOut: number, restart: boolean): void
     // TURN WARP for the slot's current play (right after animatorPlay): the node's turn from the clip's baked heading is
     // scaled to `radians` total; the pose keeps its own turn, the extra pivots about the planted foot. enabled false =
     // the clip's own turn. Optional: older hosts lack it.
     animatorSlotSetTurn?(animatorId: number, slot: number, radians: number, enabled: boolean): void
+    // WINDOW of the slot's current play (right after animatorPlay): the one-shot runs [start, end] clip seconds — enters
+    // at start (at end when backwards) if the play rewound, completes + hands over at end, clip events outside never fire.
+    // end < 0 = the clip's end. Loops ignore it. Optional: older hosts lack it (the whole clip plays).
+    animatorSlotSetWindow?(animatorId: number, slot: number, start: number, end: number): void
     // Release over `fade` (a transition toward what is left — the loop, or the rest pose): one slot; a
     // layer's one-shot + loop (slot -1); everything (layer -1).
     animatorStop(animatorId: number, layer: number, slot: number, fade: number): void
@@ -440,6 +457,36 @@ declare global {
     // anchor xyz, target xyz] (world) — a debug overlay's beam under the foot. False = no such foot.
     animatorFootState?(animatorId: number, side: number, out: Float32Array): boolean
 
+    // ---- IK chains + sockets (creator-anim anchors.cpp: the gun-master rig's hands) ----
+    // The chains are solved in the engine's LATE pass — after the app's update(dt) phase, before the
+    // dynamic bones and the skin flush — on the joints as the app left them: a world-target chain reaches
+    // the point / rotation given (or its target NODES, read by the engine then), an ANCHORED chain rides
+    // a live socket, keeping the animated end bone's pose relative to the same socket on the take's
+    // donor and following the playing clips' anchor spans between sockets. Nothing per frame from the
+    // SDK. Optional: a host without them has inert IK (the SDK warns once).
+    // kind 0 two-bone (the chain = the end entity, its parent, its grandparent) / 1 look-at. 0 = the
+    // entity is no joint of the animator.
+    animatorIkCreate?(animatorId: number, kind: 0 | 1, endEntityId: number): number
+    animatorIkDestroy?(animatorId: number, ik: number): void
+    // CANIM_IK_* order: [target xyz, pole xyz, has pole, weight, rotation xyzw, rotation weight, look-at
+    // axis xyz, look-at limit°, enabled, anchor time s].
+    animatorIkSet?(animatorId: number, ik: number, params: Float32Array): void
+    // Nodes the engine reads every late pass (0 = none): the target's world position, the pole's, the
+    // rotation node's world rotation — in place of the fixed floats above.
+    animatorIkNodes?(animatorId: number, ik: number, targetEntity: number, poleEntity: number, rotationEntity: number): void
+    // Anchor the chain to the live socket ('' = a world-target chain).
+    animatorIkAnchor?(animatorId: number, ik: number, socket: string): void
+    // out ← [reach error m, anchor delta m, anchor delta rad, applied weight]. False = no such chain.
+    animatorIkState?(animatorId: number, ik: number, out: Float32Array): boolean
+    // A socket: set '' = live, else a donor's name; on joint `jointEntityId` (a bone of the animator). A
+    // NODE socket (nodeEntityId != 0) is that entity, read every late pass (its world → the joint's
+    // space); else trs = [t.xyz, r.xyzw] fixed in the joint's space. No node and null trs = remove.
+    animatorSetSocket?(animatorId: number, set: string, name: string, jointEntityId: number, nodeEntityId: number, trs: Float32Array | null): void
+    // A clip's anchor spans for one bone: the donor set, one '\n'-joined socket name per span ('' = the
+    // joint itself), spans = (from, to, rotation 0..1) per span in NORMALIZED time. Empty spans + donor
+    // '' = remove; a clip without data takes no part in the anchor blend.
+    setClipAnchors?(clipSetId: number, clip: number, bone: string, donor: string, sockets: string, spans: Float32Array): void
+
     // ---- locomotion: the movement model + the clip selector, both engine-side ----
     // The intent (`locoSetInput`) becomes a desired velocity; the simulated velocity springs toward it
     // one fixed substep at a time (`locoStep`, given the capsule's place), and `locoUpdate` — called
@@ -496,45 +543,107 @@ declare global {
 
     // JoltPhysics. motionType: 0 static / 1 kinematic / 2 dynamic.
     physicsHasSupport(): boolean
-    /** Lightmap bake (docs/lightmap-plan.md) — a dev-time tool compiled into the desktop host only;
-     *  `lightmapBake` exists only where `lightmapHasSupport()` is true. Writes the raster (lightmap.png, an intermediate the CLI turns into lightmap.ktx2)
-     *  — one per atlas PAGE (`lightmap_<n>.png`, up to `maxPages` of `size` before the texel coarsens) —, the point lights' baked
-     *  irradiance (`lightmap-light[_<n>].png`, sRGB(E / lightScale), `lightRays` shadow rays toward a `lightRadius`-metre disc) when the
-     *  scene holds point lights, lightmap.bake (rects, pages, the baked lights) and lightmap.volume (`volumeCell` > 0)
-     *  into outDir (R = sun visibility, G = ambient occlusion) for the given static instances (GLB roots /
-     *  Mesh entities; `keysJoined` = one key per id, '
-'-joined). Synchronous; progress on stdout. */
+    /** Lightmap bake (packages/creator-bake) — a dev-time tool compiled into the desktop host only; `lightmapBake` exists
+     *  only where `lightmapHasSupport()` is true. Describes the given static instances (GLB roots / Mesh entities;
+     *  `keysJoined` = one key per id, '
+'-joined), the scene's brightest sun, its point lights (spherical emitters of
+     *  `lightRadius` metres) and its IBL to the bake, which traces them on the NVIDIA card — direct light plus
+     *  `bounceRays` Lambertian paths of `bounces` vertices per texel (0 / 0 = direct only) with `patchSamples` next-event
+     *  samples over the bright patches of a first direct pass — and writes
+     *  `<outDir>/<stem>.bake` + `<stem>-light[_n].ktx2` (irradiance in lux / lightScale, BC6H) + `<stem>-aux[_n].ktx2`
+     *  (sun / sky visibility + light direction); `split` adds `<stem>-direct[_n]` / `-indirect[_n]` page sets for the
+     *  SDK's two views; `denoise` runs OptiX's AI denoiser over 0 nothing, 1 the indirect part, 2 + the sky and the lamps, 3 + the sun; `filter` = the texel's reconstruction filter radius in texels (1 = ±1 texel tent, 0.5 = within the texel, 0 = the centre alone);
+     *  `probeSpacing` > 0 places REFLECTION PROBES on a grid of that many metres and writes `<stem>-probes.ktx2` (a BC6H atlas of octahedral
+     *  maps: one column of roughness-level tiles per probe, captured with `probeSize`² cube faces and `probeRays` paths per texel; the scene's
+     *  IBL cubemap is what an escaping ray sees; `probeIndoor` keeps only the probes under a roof (an open share of the sphere of at most 15 %) — the
+     *  outdoors reflects the sky through the texel's baked sky visibility instead; `volumeSpacing` (metres, 0 = none) bakes THE LIGHT GRID for movers — `<name>.lgrid`, named in the .bake's `volume`: per cell
+     *  in free space an ambient cube without the direct sun, links between neighbours a ray connects (what `setAmbientCube`
+     *  is fed from); `minSize` (metres, 0 = off) leaves every instance smaller than that along every axis out of the atlas — an occluder
+     *  only, `"small": true` + its `light` (an ambient cube baked where it stands) in the .bake, applied by lightmapObjectApply; `probeLayout` 0 = ROOMS (indoor points slide to their
+     *  room's middle and merge: one probe per room), 1 = GRID; `probeBox` = 6 floats, min xyz + max xyz, keeps the grid inside that box — null = the
+     *  receivers' bounds) and the grid into the .bake; `debugDir` (optional) gets the float layers per page. Synchronous; progress on stdout as
+     *  "[lightmap] …" lines, "[lightmap] done" on success. */
     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. */
-    /** `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. */
+    lightmapBake?(outDir: string, stem: string, entityIds: Uint32Array, keysJoined: string, size: number, texel: number, pages: number,
+                  sunRays: number, skyRays: number, lightRays: number, lightRadius: number, sunAngleDeg: number, bias: number, seed: number,
+                  bounceRays: number, bounces: number, patchSamples: number, split: boolean, denoise: number, filter: number,
+                  probeSpacing: number, probeSize: number, probeRays: number, probeIndoor: boolean, probeLayout: number, probeBox: Float32Array | null, minSize: number, volumeSpacing: number, emissiveNits: number, detailTexels: number, debugDir?: string,
+                  transmit?: string): boolean
+    /** Lightmap consumption: the next createGlb takes lightmap.filamat (the material behind that instance id) for its
+     *  OPAQUE materials and the masked twin for its MASK materials instead of the ubershader, and keeps TEXCOORD_1;
+     *  BLEND (glass) materials always keep the ubershader. 0xFFFFFFFF clears. The same call arms the foliage tier. */
     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).
-     *  volumeLightScale = the light VOLUME's own scale (movers); omitted or < 0 = same as lightScale. lightGamma = the light
-     *  store's curve, texel = sRGB(pow(E / lightScale, 1 / lightGamma)) — 1 (default) for the linear v2 store, 2 for the
-     *  square-root store bakes write since 2026-08-31 (the .bake's `lightGamma`). */
-    lightmapSetOptions?(ambientScale: number, sunStrength: number, aoStrength: number, lightScale: number, volumeLightScale?: number, lightGamma?: number): void
-    /** Bind the atlas page + this instance's rect (uv1 * [sx, sy] + [ox, oy]) and, unless 0xFFFFFFFF, the matching page of
-     *  the light atlas; the sun / IBL terms come from filament's per-frame uniforms inside the shader. Returns how many
+    /** The level-wide scale every lightmap-material instance shares (present and future): lux per encoded 1.0 of the
+     *  light atlas — the .bake's `lightScale` times whatever multiplier a debug knob wants. `emissiveNits` = the bake's
+     *  radiance of emission 1.0 (the .bake's `emissiveNits`): over 0 the statics' glow is drawn scene-referred with it -
+     *  a panel looks as bright as the light it gives; 0 = screen-referred. */
+    lightmapSetOptions?(lightScale: number, emissiveNits?: number): void
+    /** A MOVER'S SUN SHADOW ON THE BAKED STATICS: (dx, dy, dz) = TO the sun, (r, g, b) = its illuminance in lux, `on` =
+     *  the level's aux pages end in the bake's SUN MAP (the .bake's `sunMap`; never true without it). The lightmap
+     *  material takes the sun's part out of the baked light where the real-time shadow map says "in shadow". */
+    lightmapSunSet?(dx: number, dy: number, dz: number, r: number, g: number, b: number, on: boolean, levels?: number): void
+    /** The lightmap material's DATA views, level-wide: 0 = the picture, 1 lighting only (a white diffuse material under the camera's exposure), 2 albedo, 3 geometric normal,
+     *  4 shading normal, 5 sun visibility, 6 sky visibility, 7 the atlas texel checker (tinted per instance), 8 light
+     *  direction, 9 false-colour log10 lux over [p1, p2], 10 relief (E on the shading normal / E), 13 what the specular
+     *  reflects (the probe along the reflection, or the sky + baked light without one), 14 the probe map (grey = the probes' share of the reflection, tinted by the texel's pair), 15 the sky's path of the reflection alone, 16 the probes' path alone. */
+    lightmapDebug?(mode: number, p0?: number, p1?: number, p2?: number, p3?: number): void
+    /** The level's reflection probes, level-wide (every lightmap-material instance, present and future): the octahedral
+     *  atlas as a loaded texture (`<stem>-probes.ktx2`, `Texture.load` like a page), its layout (`oct` = level 0's tile edge,
+     *  `levels`, `perRow`), the probe count and the range the probe maps' records decode with (the .bake's `probes.encode`:
+     *  lo xyz, size xyz). WHICH probes a pixel reflects is baked into the pages: every aux page carries its probe map
+     *  under the page (per 4 x 4 block of texels the two probes those texels SEE — rays at bake time — and their weight).
+     *  Returns the probe count; an invalid texture id clears. */
+    lightmapProbesSet?(atlasTextureId: number, oct: number, levels: number, perRow: number, count: number,
+                       lox: number, loy: number, loz: number, sx: number, sy: number, sz: number): number
+    /** Bind the light page + the aux page + this instance's rect (uv1 * [sx, sy] + [ox, oy]) on every lightmap-material
+     *  instance of the entity (a GLB instance's renderables, or a Mesh entity's own) and move those renderables to light
+     *  channel 1 alone — a baked static takes nothing from the real-time sun and lamps (channel 0). Returns how many
      *  material instances took it (0 = not loaded lightmapped). */
-    lightmapApply?(entityId: number, textureId: number, sx: number, sy: number, ox: number, oy: number, lightTextureId: number): number
+    lightmapApply?(entityId: number, lightTextureId: number, auxTextureId: number, sx: number, sy: number, ox: number, oy: number, group?: number): number
+    /** A SMALL STATIC the atlas left out (the bake's `minSize`: `small` + `light` in the .bake): no rect — the light
+     *  baked where it stands goes into its material parameters. `data` = 27 floats: the ambient cube — per side of its
+     *  bounds (+x -x +y -y +z -z) the irradiance rgb in lux and the sky visibility — then probe a, probe b, a's weight
+     *  (65535 = no probe, 65534 = the sky). The textures = any page of the level (the probes' records sit under every
+     *  aux page). Returns the material instances that took it (0 = not loaded lightmapped). */
+    lightmapObjectApply?(entityId: number, lightTextureId: number, auxTextureId: number, data: Float32Array, group?: number): number
+    /** BAKED AMBIENT LIGHT for a mover, or anything on a standard or custom LIT shader: every renderable of the GLB
+     *  instance (or the Mesh entity) takes its diffuse indirect light from `data`'s ambient cube instead of the scene's
+     *  IBL, and the IBL's reflections through the sky visibility. `data` = 25 or 26 floats: six sides (+x -x +y -y +z -z) of
+     *  irradiance rgb in lux + one unused float each, the sky visibility (0 a room .. 1 the open sky), then optionally the
+     *  baked SUN visibility (1 when absent): the real-time directional light on it is multiplied by it — the baked
+     *  statics' shadow, they cast none in real time while a light grid is loaded. Lamps stay as they are. Cheap per frame. `null` = back to the IBL. Returns the renderables touched. */
+    setAmbientCube?(entityId: number, data: Float32Array | null): number
+    /** THE LIGHT GRID for movers (`lecodes lightmap bake` writes `<name>.lgrid`, the .bake's `volume` names it):
+     *  `lightVolumeLoad(fetchId)` hands the engine the fetched file (false = not a grid); `lightVolumeTrack(entityId, on)`
+     *  marks a GLB instance root or a Mesh entity as a MOVER — every frame the engine gives it the ambient cube of the
+     *  place it is at (`setAmbientCube`), blended from the reachable cells around it and eased over ~0.12 s;
+     *  `fixed` = a STATIC the atlas left out (glass, a material the lightmap shader declines): sampled once a grid, and
+     *  ignored when every primitive of it is baked;
+     *  `lightVolumeSample(x, y, z)` = that cube at a point (26 floats, null = no grid or no valid cell near), for tools;
+     *  `lightVolumeClear()` drops the grid and every mover's cube. */
+    lightVolumeLoad?(fetchId: number): boolean
+    lightVolumeTrack?(entityId: number, on: boolean, fixed?: boolean): void
+    lightVolumeClear?(): void
+    lightVolumeSample?(x: number, y: number, z: number): Float32Array | null
+    /** A light's channels (Filament's, 0..7). Every light is on channel 0 at creation; one that must reach BAKED statics
+     *  too (an unbaked lamp, a muzzle flash) is added to channel 1. */
+    setLightChannel?(entityId: number, channel: number, enable: boolean): void
     /** Shadow flags on every renderable of a GLB instance (Mesh has setCastShadows/setReceiveShadows). */
     setGlbShadows?(entityId: number, cast: boolean, receive: boolean): void
-    lightmapBake?(outDir: string, entityIds: Uint32Array, keysJoined: string, size: number, texel: number, sunRays: number, aoRays: number, aoDistance: number, bias: number, sunAngleDeg: number, volumeCell: number, maxPages: number, lightRays: number, lightRadius: number, bounceAlbedo?: number, bounceDistance?: number, bounceRays?: number, coplanarSkip?: number, denoise?: number): boolean
-    /** Light VOLUME for dynamic objects (docs/lightmap-plan.md §9). `lightmapVolumeLoad` turns a fetched
-     *  lightmap.volume (`fetchSystemId` from `_creatorUtils.fetch`) into RGBA8 3D textures and returns its
-     *  header as JSON — `{"texture":id,"dims":[nx,ny,nz],"min":[x,y,z],"cell":m,"light"?:id,"faces"?:n}` (`light` = the
-     *  point lights' block: a version-3 volume's six ambient-cube faces (+X −X +Y −Y +Z −Z, `faces` 6), a version-2
-     *  volume's one directionless value (`faces` 1) — uploaded either way as six face slabs stacked along z, so the
-     *  light texture's depth is nz × 6) — or "" on failure. */
-    lightmapVolumeLoad?(fetchSystemId: number): string
-    /** Make those textures THE volume (`textureId` 0xFFFFFFFF clears; `lightTextureId` 0xFFFFFFFF = no baked lights):
-     *  every lightmap-material instance without an atlas rect — loaded already or later — samples it at the pixel's
-     *  world position (+ half a `cell` along the normal). `size` = dims × cell. Returns how many instances switched. */
-    lightmapVolumeSet?(textureId: number, lightTextureId: number, minX: number, minY: number, minZ: number, sizeX: number, sizeY: number, sizeZ: number, cell: number): number
+    /** Foliage — the vegetation tier (`foliage.filamat` / `foliage-masked.filamat`, armed per model
+     *  through setNextGlbLightmapped; the engine knows the tier by its `benders` parameter). Level-wide wind: direction on
+     *  the ground (normalised by the host), strength = metres of sway at bendHeight, speed rad/s, gust 0..1. Applies to
+     *  every foliage instance, present and future. */
+    foliageSetWind?(dirX: number, dirZ: number, strength: number, speed: number, gust?: number): void
+    /** Level-wide sway options: bendHeight = metres above the instance origin where the full sway / touch applies,
+     *  touchStrength = metres a bender pushes, variation 0..1 = per-copy tint, sunWrap 0..1 = wrapped Lambert. */
+    foliageSetOptions?(bendHeight: number, touchStrength: number, variation: number, sunWrap: number): void
+    /** An entity whose live world position bends the vegetation within `radius` metres; <= 0 removes it. The host
+     *  writes the 8 benders nearest the camera to the shader each frame. */
+    foliageSetBender?(entityId: number, radius: number): void
+    /** 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: number, start: number, end: number): void
     physicsConfigure(gx: number, gy: number, gz: number, maxBodies: number): void
     setInterpolation(enabled: boolean): void
     // Shape/Physics/Trigger aspects: build a shape once, create bodies from it.
@@ -699,25 +808,43 @@ declare global {
     vehicleBodyId(vehicleId: number): number
     // 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
-    // constraint. Built ONCE from the pose the bones are in (that pose is the joints' neutral for the
-    // limits) and kept out of the world until ragdollActivate, which takes the bones' CURRENT pose,
-    // adds the bodies and gives every body one velocity; from then on the engine writes the bodies'
-    // poses onto the bone entities every frame AFTER the animator (bones not listed keep their
-    // animated local pose under the ragdolled parents — fingers, toes, a spine bone between two
-    // parts), until ragdollDeactivate. Every body carries its bone entity as user data, so
-    // physicsRaycast / contact events name the bone. Optional: a host without it has no ragdolls.
+    // constraint that carries a swing + twist MOTOR. Built ONCE from the pose the bones are in (that
+    // pose is the joints' neutral for the limits) and kept out of the world until ragdollActivate,
+    // which takes the bones' CURRENT pose and adds the bodies moving as the engine measured each bone
+    // over the last two frames (a swinging arm keeps swinging) plus a launch; from then on the engine
+    // writes the bodies' poses onto the bone entities every frame AFTER the animator, until
+    // ragdollDeactivate. POWERED (ragdollSetDrive): the motors pull every joint toward the relative
+    // rotation the ANIMATED pose shows (the engine hands the animator's pose to physics every frame,
+    // right after the animator wrote it and before the bodies overwrite it), and the root can be
+    // ANCHORED — the hips body kinematic on the animated hips — so a standing character stays in its
+    // animation while a hit jolts a limb and the motors bring it back; strength 0 with no anchor =
+    // limp. The skin joints under the hips that carry no part (the spine bones between two parts, the
+    // neck, the clavicles, fingers, toes) follow the animation while driven and HOLD their pose as the
+    // strength goes to 0 — a limp body never breathes with the loop playing underneath. Deactivating
+    // with a blend seeds the model's animator with the fallen pose, so whatever plays next
+    // transitions out of it (canimAnimatorSeedPose). Every body carries its bone entity as user
+    // data, so physicsRaycast / contact events name the bone. Optional: a host without it has no
+    // ragdolls.
     //   bones[partCount * 2]: bone entity, `to` entity (0 = a leaf: `length` along the parent's line;
     //                         a leaf ROOT points along the model's up)
-    //   settings — header[12]: version(2), partCount, stride(12), friction, linearDamping,
+    //   settings — header[16]: version(3), partCount, stride(12), friction, linearDamping,
     //              angularDamping (0 = Jolt's own), collide (0 = everything, 1 = the STATIC world and
     //              other such ragdolls only: dynamic bodies, character controllers and vehicles pass
-    //              through — Jolt's DEBRIS object/broadphase layer), freeze (1 = once every part is
-    //              asleep the bodies turn STATIC where they lie: the last pose keeps being written
-    //              onto the bones, raycasts still hit, nothing wakes them, the solver skips them;
-    //              ragdollActive reads false, ragdollDeactivate / ragdollActivate still work —
-    //              activate makes the parts dynamic again), freezeAfter (seconds in the world after which the freeze happens
-    //              regardless; 0 = no cap), reserved x3. A version-1 blob (header[8], stops after
-    //              angularDamping) is still accepted = collide everything, never freeze.
+    //              through — Jolt's DEBRIS object/broadphase layer), freeze (1 = once every part of a
+    //              LIMP body is asleep the bodies turn STATIC where they lie: the last pose keeps being
+    //              written onto the bones, raycasts still hit, nothing wakes them, the solver skips
+    //              them; ragdollActive reads false, ragdollDeactivate / ragdollActivate still work —
+    //              activate makes the parts dynamic again), freezeAfter (seconds LIMP after which the
+    //              freeze happens regardless; 0 = no cap), driveFrequency (Hz: the motors' position
+    //              spring), driveDamping (ratio, 1 = critical), driveTorque (N·m per kg of the part:
+    //              the motors' limit at strength 1), jointFriction (N·m per kg of the part: a torque
+    //              that resists any joint motion, motor or not), limits (0 = the part cones below;
+    //              1 = LEARNED: at the first activation that finds clips bound to the model's
+    //              animator the engine measures, per joint, how far the clips swing and twist it in
+    //              its constraint frame and rebuilds the joints to those ranges — the motors never
+    //              target a pose the limits forbid; no clips yet = the cones, measured at a later
+    //              activation), limitsMargin (degrees added on each side of a learned range),
+    //              reserved x1
     //   + partCount * 12: parentIndex (-1 = the root; always < the part's own index), radius, length
     //              (0 = up to the `to` bone), mass (kg; 0 = from the volume), swingDeg (cone
     //              half-angle), twistDeg (half-angle), hinge (0/1), hingeAxisX/Y/Z (in the MODEL
@@ -725,15 +852,23 @@ declare global {
     //              flat (2°) across the axis and [min, max] about it (a knee, an elbow)
     ragdollCreate?(rootEntityId: number, bones: Uint32Array, settings: Float32Array): number
     ragdollDestroy?(ragdollId: number): void
-    /** Pose the bodies from the bones' current transforms, add them to the world, set every body's
-     *  linear velocity. Already active = re-wake + velocity. false = unknown id / no world. */
+    /** 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. */
     ragdollActivate?(ragdollId: number, vx: number, vy: number, vz: number): boolean
-    /** Take the bodies out of the world; the animator owns the bones again from the next frame. */
-    ragdollDeactivate?(ragdollId: number): void
+    /** 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. */
+    ragdollDeactivate?(ragdollId: number, blend: number): void
     /** In the world AND at least one body still awake (a settled ragdoll reads false). */
     ragdollActive?(ragdollId: number): boolean
     /** The rigid body of part `index` (for physicsApplyImpulseAt / velocities). 0 if unknown. */
     ragdollBodyId?(ragdollId: number, index: number): number
+    /** 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. */
+    ragdollSetDrive?(ragdollId: number, strength: number, 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
     // (gravity, wind, drag, stiffness toward the animated shape, an angle cone, capsule / sphere
@@ -786,8 +921,9 @@ declare global {
     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
+    /** `sided` 1 = one-sided: while the capsule moves away from the chain's `side` it puts a bone it has run into over to that side instead of carrying it (an arm under a cape); 0 = pushes to the nearest surface. */
+    dynamicBoneColliderCreate?(entityId: number, ax: number, ay: number, az: number, bx: number, by: number, bz: number, radius: number, sided: number): number
+    dynamicBoneColliderSet?(colliderId: number, ax: number, ay: number, az: number, bx: number, by: number, bz: number, radius: number, sided: 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
@@ -1266,10 +1402,40 @@ declare global {
     removeNode(nodeId: number, childNode: any): void
     setContent(nodeId: number, oldChildren: any[], children: any[]): void
 
-    animateTo(nodeId: number, style: any): void
-    animateFrom(nodeId: number, style: any): void
+    // Legacy one-shot style tweens, implemented by the hosts that animate JS-side (web, Apple) and
+    // ABSENT on creator-pkg hosts since 2026-09-14 (they have the tween core below; the SDK's fallback
+    // only calls these where tweenCreate is missing): from the current values to `style` (animateTo)
+    // / from `style` to the current values (animateFrom), meta keys duration / delay / loop /
+    // loopMode / commit / layer in the bag.
+    animateTo?(nodeId: number, style: any): void
+    animateFrom?(nodeId: number, style: any): void
     toast(msg: string): void
 
+    // ---- Keyframe animation core (docs/timeline-plan.md; creator-tween) -------------------------
+    // ONE evaluator for UI style props, 3D node transforms / lights / cameras and 2D sprites: the SDK
+    // hands over a flat blob (layout in sdk/src/animate/tween/spec.ts — header, time-callbacks,
+    // easing tables, tracks of keyframes; string-valued lanes index `strings`, a track's target lane
+    // indexes `targets`: the element's `_id` handle for the UI domain, an entity / scene id for the
+    // 3D and 2D domains) and gets an id.
+    // Created = paused at t = 0, nothing applied. Ops: 0 play (from t = 0, a running one restarts),
+    // 1 pause, 2 resume, 3 cancel (drop, values stay where they are, no commit), 4 finish (jump to
+    // the end, commit, report finish). The host reports through the registered callback:
+    // kind 0 = call (index = the blob's call slot, fired when playback crosses its time, in time
+    // order, before finish), kind 1 = finish (the end was reached, one-shot only), kind 2 = a VALUE
+    // track's frame (index = the track's target slot — unique per world, then the lanes as plain number arguments —
+    // delivered synchronously after the evaluator's pass, never from inside it). Seek is in TOTAL
+    // ms (iterations included); tweenGetTime reads the position inside the current iteration,
+    // tweenGetElapsed the total. Clock 0 = host wall time (ui), 1 = game time (Time.scale, pause).
+    // Optional: the SDK feature-detects tweenCreate and falls back to animateTo / animateFrom
+    // (UI tracks, single values, timer clock) on hosts without it.
+    tweenCreate?(data: Float32Array, strings: string[], targets: any[]): number
+    tweenControl?(id: number, op: number): void
+    tweenSeek?(id: number, ms: number): void
+    tweenSetRate?(id: number, rate: number): void
+    tweenGetTime?(id: number): number
+    tweenGetElapsed?(id: number): number
+    registerTweenEvent?(callback: (id: number, kind: number, index: number) => void): void
+
     // Router over destinations. On hosts that implement openView (below), `screen`/`view` is any
     // view descriptor (not just a screen object) and the extra `transition` args apply; legacy
     // hosts receive screen objects only and ignore the extras.
@@ -1444,11 +1610,6 @@ declare global {
      *  exit programmatically, iOS/desktop, register nothing and the call is a no-op). */
     quit?(): void
 
-    animate(callback: (val: number) => void, duration: number): number
-    stopAnimation(id: number): void
-    pauseAnimation(id: number): void
-    resumeAnimation(id: number): void
-
     localStorageGetValue(key: string): string | null
     localStorageSetValue(key: string, value: string): void
     localStorageRemoveValue(key: string): void

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

@@ -34,6 +34,32 @@ test("the same asset present in the entries compiles to its URL", async () => {
   expect(js).not.toContain("./assets/lightmap.bake")
 })
 
+// Only the modules the bundle reaches are checked: a project keeps one entry per level, and a
+// level whose art is not on this machine must not fail an entry that never imports it.
+test("a missing asset in a module the entry never imports does not fail the compile", async () => {
+  const js = await compileProject({
+    name: "Unreached",
+    publicUrl: "https://le.codes",
+    entries: [
+      { path: "/main.ts", type: "text", text: "const scene = new Scene()\nconsole.log(scene)\n" },
+      { path: "/levels/lost.ts", type: "text", text: "export const lost = asset('./lost.glb')\n" },
+    ],
+  })
+  expect(js).not.toContain("lost.glb")
+})
+
+test("the same missing asset fails once the entry imports its module", async () => {
+  const compile = compileProject({
+    name: "Reached",
+    publicUrl: "https://le.codes",
+    entries: [
+      { path: "/main.ts", type: "text", text: "import { lost } from './levels/lost'\nconsole.log(lost)\n" },
+      { path: "/levels/lost.ts", type: "text", text: "export const lost = asset('./lost.glb')\n" },
+    ],
+  })
+  await expect(compile).rejects.toThrow("asset not found: ./lost.glb (levels/lost.ts:1)")
+})
+
 test("a commented-out asset() is not an asset at all", () => {
   const src = [
     "/** The atlas image — write `asset('./TileSet.png')`. */",

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

@@ -130,3 +130,22 @@ test("compileProject auto-detects the importer as entry and runs the registratio
   expect(js).toContain("app-side-effect")
   expect(js).toContain("register-side-effect")
 })
+
+test("design/ screens are never the entry — a design-only project has none, app code next to a design wins", () => {
+  // A Figma import: screens on the board, shared modules, no app yet. The largest root used to win.
+  const designOnly = detectEntry([
+    text("/design/screens/a4-40.ts", "import { at } from '../shared/figma'\nexport default UIScreen([])\n" + "// big\n".repeat(50)),
+    text("/design/shared/figma.ts", "export const at = () => ({})\n"),
+    text("/app.server.ts", "export function ping() { return 1 }\n"),
+  ])
+  expect(designOnly.entry).toBe("")
+  expect(designOnly.roots).toEqual([])
+
+  // The same project once the app exists: main.ts is the entry however small it is.
+  const withApp = detectEntry([
+    text("/design/screens/a4-40.ts", "export default UIScreen([])\n" + "// big\n".repeat(50)),
+    text("/main.ts", "Router.init(home)\n"),
+  ])
+  expect(withApp.entry).toBe("/main.ts")
+  expect(withApp.roots).toEqual(["/main.ts"])
+})

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

@@ -0,0 +1,27 @@
+import { test, expect } from "bun:test"
+import { compileServerBundle } from "../serverSplit"
+
+// The server bundle's file map is the whole project (a server module may import shared code), and
+// the bundler checks every `asset()` in that map. Seen live 2026-09-17: a Figma-exported design next
+// to app.server.ts failed the SERVER build with "asset not found: ../assets/figma/…" because the
+// map had the screens but not the binaries. Binaries are stubbed, design/ stays out.
+
+const text = (path: string, t: string) => ({ path, type: "text" as const, text: t })
+const res = (path: string) => ({ path, type: "resource" as const, fileSrc: "/uploads/x.bin" })
+
+test("a client screen's asset() does not break the server bundle", async () => {
+  const out = await compileServerBundle({
+    validate: false,
+    entries: [
+      text("/app.server.ts", "export const ping = async () => 1\n"),
+      text("/main.ts", "import { ping } from './app.server'\nconst hero = asset('./hero.png')\nping()\n"),
+      res("/hero.png"),
+      text("/design/screens/a4-40.ts", "export default UIScreen([ UIImage(asset('../assets/figma/a4-40/rectangle.png')), UIImage(asset('../assets/figma/a4-40/logo.svg')) ])\n"),
+      res("/design/assets/figma/a4-40/rectangle.png"),
+      text("/design/assets/figma/a4-40/logo.svg", "<svg/>"),
+    ],
+  })
+  expect(out).not.toBeNull()
+  expect(out!.code).toContain("ping")
+  expect(Object.keys(out!.manifest.modules)).toEqual(["app.server.ts"])
+})

package/src/compile/bundler.ts

@@ -4,7 +4,7 @@ import { createRequire } from "node:module"
 import { dirname, join, relative } from "node:path"
 import { fileURLToPath } from "node:url"
 import { collectAssetMacros, desugarAssetMacros, hasAssetMacro, type AssetMacroRef } from "./assetMacro"
-import type { ScanModule } from "./detectEntry"
+import { scanModulesFallback, type ScanModule } from "./detectEntry"
 import { hasAspectExtends, injectAspectNames } from "./aspectMacro"
 import { hasImportStatement, rewriteLibraryImports } from "./libraryImports"
 
@@ -132,8 +132,30 @@ export const scanModulesChisel = (files: MemoryFiles): Record<string, ScanModule
 }
 
 /**
- * Every `asset('…')` must name a file that's actually in the compile input — a missing one is a
- * COMPILE ERROR, never a fallback.
+ * The modules the bundle will actually contain: everything reachable from `entry` over static
+ * imports (chisel's scan, else the regex scanner — same graph detectEntry roots on). `sources` are
+ * the post-library-rewrite, pre-desugar texts, so a bare `from "acme-ui"` already points into
+ * `/__lib/<slug>/…` and follows through. A dynamic `import()` is not an edge for either scanner.
+ */
+const reachableFrom = (entry: string, sources: MemoryFiles): Set<string> => {
+  const graph = scanModulesChisel(sources) ?? scanModulesFallback(sources)
+  const seen = new Set<string>([ entry ])
+  const queue = [ entry ]
+  while (queue.length > 0) {
+    const file = queue.pop()!
+    for (const target of graph[file]?.imports ?? []) {
+      if (!seen.has(target)) { seen.add(target); queue.push(target) }
+    }
+  }
+  return seen
+}
+
+/**
+ * Every `asset('…')` in a module the bundle REACHES must name a file that's actually in the
+ * compile input — a missing one is a COMPILE ERROR, never a fallback. Modules the entry never
+ * imports are not checked: a project keeps one entry per level, and a level whose GLBs are not on
+ * this machine (gitignored art) must not fail the compile of an entry that never loads it — it
+ * fails its own compile, with the same message (fps-demo demo-logo.ts vs chernobyl, 2026-09-17).
  *
  * chisel used to turn an asset import with no backing module into `const x = "<the specifier>"`:
  * a relative source path nothing resolves at runtime, so the app got a silently broken reference
@@ -173,11 +195,15 @@ const bundleProjectChisel = async (
   //  - inject `static aspect = '<name>'` from `class … extends Aspect<'<name>', …>`
   const projFiles: MemoryFiles = {}
   const assetRefs: { file: string, ref: AssetMacroRef }[] = []
+  // What the module scanner sees: import-rewritten, NOT yet asset-desugared (a desugared asset is a
+  // default import of a non-module — the fallback scanner drops it, chisel's scan would not).
+  const scanSources: MemoryFiles = {}
   for (const [ k, v ] of Object.entries(files)) {
     const path = normalize(k)
     let src = v
     if (/\.[tj]sx?$/.test(path)) {
       if (hasImportStatement(src)) src = rewriteLibraryImports(src, slugs)
+      scanSources[path] = src
       if (hasAssetMacro(src)) {
         const found = collectAssetMacros(src, path)
         for (const ref of found) assetRefs.push({ file: path, ref })
@@ -198,6 +224,7 @@ const bundleProjectChisel = async (
       const path = normalize(`/__lib/${slug}/${k}`)
       let src = v
       if (/\.[tj]sx?$/.test(path)) {
+        scanSources[path] = src
         if (hasAssetMacro(src)) {
           const found = collectAssetMacros(src, path)
           for (const ref of found) assetRefs.push({ file: path, ref })
@@ -209,7 +236,10 @@ const bundleProjectChisel = async (
     }
   }
 
-  assertAssetsExist(assetRefs, projFiles)
+  if (assetRefs.length > 0) {
+    const reachable = reachableFrom(entry, scanSources)
+    assertAssetsExist(assetRefs.filter(({ file }) => reachable.has(file)), projFiles)
+  }
 
   const sdkFiles = collectSdkFiles(resolveSdkSrc())
   // Shipped bundles minify by default; edit-mode bundles pass `false` — mangling erases class