@waica/engine 0.25.0 → 0.27.0

package/README.md

@@ -25,6 +25,36 @@ A `Game` draws through three's `WebGPURenderer` (ADR 0025): WebGPU when the brow
 - **Tests under happy-dom.** happy-dom has no GPU: a project test that builds a `Game` replaces `WebGPURenderer` from `three/webgpu` with a fake (it previously replaced `WebGLRenderer` from `three`), whose `init()` resolves.
 - **Run Sessions.** A Run Session waits for the Render Backend before it reports ready, steps or screenshots, and its snapshots carry `backend`. A renderer that cannot initialize ends `start_project` with a runtime error that names the failure.
 
+## Migrating to 0.27.0: 3D animation
+
+A glTF's clips play (issue #166, ADR 0029): a `Model` keeps its `handle`, an `Animator` beside it plays the clips, a `StateMachine` drives either kind of Clip Target through one seam, and a 3D character turns to face its walk. Every 2D scene file loads as it did; the seam is additive, one type changes (`TriggerEnv.clipFinished`) and two behaviours change (`play` restarts a finished clip, a `CharacterMotor` turns by default):
+
+- **The state machine plays through the Clip Target.** `StateMachine` no longer names `AnimatedSprite`: it plays each state's clip through the first sibling that satisfies `isClipTarget` (`{ current, clipNames, clipFinished, clipsPending?, play(name), setFlipX? }`), which is the `AnimatedSprite` in a 2D scene and the `Animator` in a 3D one. A project component that plays clips can be that target by exposing the same members. A target whose clips are pending (`clipsPending`: an Animator whose glb is still loading) is asked anyway and remembers the request; a sprite with no clips is not pending and still warns about its states. A mirrored directional clip on a target without `setFlipX` plays unmirrored and warns once per state.
+- **`TriggerEnv.clipFinished`.** Code that builds a `TriggerEnv` for `evaluateTrigger` or `nextTransition` (tests of role graphs, mostly) adds `clipFinished: false`; the new `clip:end` trigger reads it.
+- **`play(current)` restarts a finished clip.** `AnimatedSprite.play(name)` is still a no-op for the clip that is running, but once a `loop: false` clip has ended, playing it again restarts it from frame 0 (and clears `clipFinished`). A project that re-entered a state to keep holding a one-shot's last frame now sees the clip replay; keep the entity in its state instead.
+- **A `CharacterMotor` turns by default.** `turnSpeed` (degrees per second, default 540) turns the entity's yaw toward where it walks; set `turnSpeed: 0` to snap, and keep the yaw out of your own code's hands or they will fight. The kinematic body is unaffected.
+
+## Migrating to 0.26.0: 3D scenes
+
+A scene can declare a 3D space (issue #154, ADR 0027). Nothing about a 2D scene changes — every existing scene file loads as it did — but a few types and one build setting do:
+
+- **`game.camera` is a union.** It is `THREE.OrthographicCamera | THREE.PerspectiveCamera`: the orthographic one in every 2D scene, a perspective one in a 3D scene. Code that read `game.camera.left/right/top/bottom` narrows first (`camera instanceof THREE.OrthographicCamera`, or `isPerspectiveCamera(camera)`), or goes through `game.worldToScreen(point)`. `game.view` and `setViewHeight()` are the orthographic zoom: under a perspective camera they change nothing.
+- **`SceneCameraJson` is a union.** The existing block (optionally `kind: 'orthographic'`) or `{ kind: 'perspective', position?, target?, fov?, near?, far? }`. `resolveSceneCamera` keeps returning the orthographic block with no `kind`; a perspective block gets its own defaults. A scene's camera must match its space (`validate_project` reports a mismatch).
+- **Scene entities take 3-number positions.** `position` is `[x, y]` (z = 0, as before) or `[x, y, z]`, and an entity may declare `rotation: [x, y, z]` in degrees (Euler order XYZ) and `scale: [x, y, z]`. In a 2D scene `z` is still only draw order.
+- **`ArchetypeArt.kind` and the editor's art `kind` gain `'model'`** (`.glb` and `.gltf`), and `ParamSpec.kind` gains `'model'` and `'vector3'`. Code that switches over these kinds handles the new member.
+- **Components declare their space on the class (issue #159).** `Component` has an optional `static space: 'both' | '2d' | '3d'`, and `TWO_D_COMPONENTS` and `THREE_D_COMPONENTS` are no longer exported: `componentSpaceOf(Class)` and `componentSpaceMismatch(space, Class)` read the marker. The behaviors of `@waica/behaviors` that read or move x/y as the orthographic plane, or need a 2D sibling to work (the motors, `Chaser`, `Hazard`, `MeleeAttack`, `Interactable`, `Patrol`, `ClickToMove`, and the particle cues `DamagePuff`, `DustPuffs`, `DustTrail` and `SwingSparks`, which need a `ParticleEmitter`) are tagged `'2d'`, so a project that put one in a 3D scene now gets `component-space-mismatch` from `validate_project` where it used to validate clean. A project-owned component opts in with its own `static space`. 3D scenes also simulate (ADR 0028): the engine and the CLI depend on `@dimforge/rapier3d-deterministic-compat`, loaded only by a 3D scene, and a project's bundle gets one extra async chunk for it. `game.query`'s 2D forms throw in a 3D scene.
+- **`Pointer.injectClick(x, y)` may return `null`.** In a 3D scene `x` and `y` are canvas pixels and a ray that meets neither a model nor the ground yields no pick; in a 2D scene it still always returns one.
+- **One three.** `GLTFLoader` and `SkeletonUtils` import the bare `'three'`, the engine draws with `'three/webgpu'`. Every bundler of a project that uses `Model` (or any three addon) aliases the bare specifier to the WebGPU build, and only it:
+
+  ```ts
+  // vite.config.ts
+  export default defineConfig({
+    resolve: { alias: [{ find: /^three$/, replacement: 'three/webgpu' }] },
+  })
+  ```
+
+  `three/webgpu`, `three/tsl` and `three/addons/*` are left alone. Projects created by `create_project` after this release carry the alias; an earlier project adds it by hand. The same alias goes in a project's Vitest config if its tests import plain `'three'`.
+
 ## Hitbox Collision Layers and Masks
 
 Every `Hitbox` belongs to one named Collision Layer and declares the other layers in which it is interested through a Collision Mask:
@@ -207,13 +237,58 @@ A scene can be lit (issue #78, ADR 0026). Without lighting and without a Post Ef
 
 The CPU reference of a light-map texel — `lightFalloff`, `lightVisibility`, `lightMapValue` — is exported for tools and tests; the shader follows it.
 
+## 3D scenes
+
+A scene declares its space (ADR 0027): `render.space: '2d'` (the default) or `'3d'`. `game.space` reports the live scene's, `'2d'` with no scene. In a 3D scene `z` is a world axis (Y is up, the ground is the XZ plane, the default camera looks down −Z), the frame is drawn straight to the canvas with a depth buffer deciding what is in front, and there is no layer band, y-sort, isometric projection, Sprite Batch or light-map. `render.post` still works. `validate_project` rejects `render.sort`, `render.projection` and `render.batch` in a 3D scene, a 2D component on a 3D scene's entities and a 3D component in a 2D scene (`component-space-mismatch`). A component declares its space on its class, `static space = '2d' | '3d' | 'both'` (absent means both): `Sprite`, `AnimatedSprite`, `Tilemap`, `Solid`, `DynamicBody`, `Hitbox`, `Light`, `ParticleEmitter` and the behaviors of `@waica/behaviors` that read or move x/y as the orthographic plane or need a 2D sibling (the motors, `Chaser`, `Hazard`, `MeleeAttack`, `Interactable`, `Patrol`, `ClickToMove`, and the particle cues `DamagePuff`, `DustPuffs`, `DustTrail`, `SwingSparks`) are `'2d'`; `Model`, `Sun`, `PointLight`, `Collider`, `RigidBody` and `CharacterMotor` are `'3d'`; `StateMachine`, the behaviors that only react to an overlap or read y as up, and a project-owned component without a marker are allowed in both (a project-owned component says otherwise with its own `static space`).
+
+```json
+{
+  "waicaScene": 3,
+  "render": { "space": "3d", "lighting": { "ambient": { "color": "#b8c8ff", "intensity": 0.6 } } },
+  "camera": { "kind": "perspective", "position": [0, 5.5, 11], "target": [0, 0.8, 0], "fov": 50 },
+  "entities": [
+    { "name": "Ground", "scale": [24, 1, 24], "components": [{ "type": "Model", "props": { "shape": "plane", "color": 5081930 } }] },
+    { "name": "Tree", "position": [4, 0, -1], "components": [{ "type": "Model", "props": { "src": "src/art/tree.glb" } }] },
+    { "name": "Daylight", "components": [{ "type": "Sun", "props": { "direction": [-0.5, -1, -0.35], "intensity": 3 } }] },
+    { "name": "Lamp", "position": [2.5, 0, 3.5], "components": [{ "type": "PointLight", "props": { "intensity": 14, "distance": 10, "offsetY": 1.2 } }] }
+  ]
+}
+```
+
+- **Camera.** `{ kind: 'perspective', position, target, fov, near, far }`, defaults `[0, 5, 10]`, `[0, 0, 0]`, 60, 0.1, 1000; `follow` and the 2D fields are not accepted. A 3D scene without a camera block gets the defaults. The camera is fixed by the scene; game code may move `game.camera`. `resize()` keeps the letterbox and sets the camera's aspect from the letterboxed size. Camera Fade and Flash work in 3D; Shake does nothing.
+- **Model.** Draws a glTF/glb from `src` (a `waica:` uri or a project path under `src/art/`, loaded once through `game.assets.model(uri)`) or a primitive `shape` (`'box'`, `'sphere'`, `'plane'` — the plane lies on the ground) of a `color` (`0xrrggbb`) and a uniform `size`, with a standard (lit) material. With both `src` and `shape`, `src` wins. The entity's `position`, `rotation` and `scale` place it; `color` and `size` follow the inspector live, a new `src` or `shape` rebuilds it. `handle` is the `ModelHandle` of the file it draws (null for a primitive): its clips play through an `Animator` beside it.
+- **Animator.** Plays the glTF clips of the `Model` beside it (ADR 0029): one `AnimationMixer` over the entity's own clone, advanced by the Simulation Step, nothing per render frame. It is the 3D Clip Target, so a `StateMachine` plays each state's clip through it and `clip:end` fires when a `loop: false` clip finishes. Params: `initialClip` (plays when the file settles, if nothing asked for a clip before it loaded — a `play` before the model loads is remembered and applied then; `clipsPending` is true meanwhile, so a `StateMachine` asks for its state's clip anyway) and `fade` (seconds of crossfade, default 0.15; `0` cuts). The `clips` prop, authored in JSON like `AnimatedSprite.clips`, holds per-clip overrides keyed by the glTF clip name: `{ loop: false }` plays once and holds the last pose, `{ speed: 2 }` doubles the rate; they are read when the actions are built, as the file settles. A Model rebuild (a new `src` or `shape`) is noticed on the next step: the Animator drops the mixer over the old clone, attaches to the new one and asks for the clip it was playing. Clip names match the file exactly (a state's `clip` override maps `idle` to a pack's `Idle`); an unknown name warns once. `inspect_runtime` shows `{ loaded, current, time, playing, poseHash }`. In a 2D scene it creates nothing and `play` is a no-op; without a `Model` file beside it it warns once at runtime and `validate_project` reports `animator-without-model` per scene entity (an instance may complete its prefab with a `Model.src` override), while `missing-clip` checks its states, `initialClip` and override keys against the glb's clips, on the prefab and again only on an instance that changes them.
+- **Lights.** The Ambient Light of a 3D scene drives one `THREE.AmbientLight` the Game owns (`render.lighting.ambient` and `game.lighting.ambient`, full white by default). `Sun` is a directional light: `direction` `[x, y, z]` in world space (default `[-1, -2, -1]`), `color`, `intensity`. `PointLight` shines from its entity plus `offsetX/Y/Z`: `color`, `intensity`, `distance` (0 = unlimited), `decay` (default 2). Both create nothing in a 2D scene, follow their props live and leave with their entity. No shadows. three's lights are physically based: a point light of intensity 1 is dim, so a scene tunes intensities (the smoke example uses 3 for the Sun and 14 for the lamp).
+- **`game.worldToScreen(point)`.** `{ x, y, z? }` in logical coordinates to canvas CSS pixels inside the letterbox, or `null` when a perspective camera cannot see the point (behind its near plane). Anchored Pieces and spatial audio go through the same projection: in 3D a piece behind the camera is hidden, sounds attenuate by the 3D distance from the camera and pan by where they land on screen.
+- **Picking.** A click in a 3D scene casts a ray through the letterboxed point against every live `Model` (a glTF still loading is skipped) and resolves `PointerPick` with the nearest hit's entity and its world-space point (`point.z`). With no hit the entity is `null` and the point is where the ray meets the ground plane y = 0; a ray at the sky yields no pick.
+- **Assets.** `game.assets.model(uri)` returns a `ModelHandle` at once: `root` is empty until the file settles, then holds your own clone of the cached glTF (skinned meshes cloned with `SkeletonUtils.clone`), `animations` its clips, `settled` resolves `'loaded'` or `'failed'`. One backend load per URL for the Game's life; `status` counts models with textures, `preload` routes `.glb`/`.gltf` to them, `GameOptions.models` replaces the real `GLTFLoader` backend (`ModelBackend { load(url) }`) for a project's own tests. Only a `.glb`, or a `.gltf` with every buffer and image embedded as a `data:` uri, works in the editor (which serves each file from a `blob:` url) and in a built project (which hashes every art file's name): a `.gltf` that points at an external `.bin` or textures loads empty there, and `validate_project` warns (`gltf-external-resource`).
+- **Simulation.** A 3D scene gets one Rapier world (ADR 0028, `@dimforge/rapier3d-deterministic-compat` 0.21.0), stepped once per Simulation Step after every component's `onUpdate`. `simulation: { gravity: [x, y, z] }` in the scene sets its gravity (default `[0, -9.81, 0]`; a `simulation` block in a 2D scene is an error, `invalid-scene-simulation`). Rapier is imported dynamically by the first 3D scene that loads, counts as a pending asset (`game.assets.ready()` and `game.ready()` of a Game with a live 3D scene wait for it, and `game.ready()` rejects naming the package if it fails), and a 2D project never loads it. Steps taken while it loads run every component update and skip only the physics. `GameOptions.physics` replaces the import for a project's own tests.
+- **Collider.** `shape` (`'box'`, `'sphere'`, `'capsule'`), `size` (a box's full extents), `radius`, `height` (a capsule's end-to-end height), `offset` (in the entity's local frame), `sensor`, `layer`, `collidesWith`, `friction`, `restitution`. Alone on an entity it is a fixed wall or floor, created at the entity's position and rotation and scaled by its `scale` (box size and capsule height per axis, a sphere's radius by the largest axis, a capsule's by the larger of x and z); moving the entity later does not move it. A capsule's `height` is at least twice its radius (a shorter one would be a taller sphere). `validate_project` reports `invalid-collider-param` for an unknown shape, a non-positive dimension, a radius or height under 0.01, a capsule shorter than twice its radius, an `offset` that is not three finite numbers, a bad layer or mask and a friction or restitution outside 0 to 1; at runtime such a Collider creates no body and warns once.
+- **RigidBody.** `type` (`'dynamic'` or `'kinematic'`), `mass`, `gravityScale`, `linearDamping`, `angularDamping`, `lockRotations`, `velocity` (initial). It needs a `Collider` on the same entity (`rigid-body-without-collider`). A dynamic body is Rapier's: the engine writes the entity's position and rotation from it after every step; `linearVelocity` (get and set) and `applyImpulse` are its public API (`grounded` is always false on it). A kinematic body is a character: each step it moves through Rapier's character controller by `desiredVelocity` (`{ x, z }`, set by a motor) and its own vertical velocity under gravity, climbs steps up to `stepHeight`, stands on slopes up to `maxSlope` degrees and slides down steeper ones, sticks to the ground within `snapDistance`, pushes dynamic bodies, ignores sensors, and `jump(speed)` launches it while `grounded` and reports whether it did. Setting its entity's position teleports it, with no fall speed left. `validate_project` reports a `type` outside its options, a number outside its range or a `velocity` that is not three numbers as `invalid-rigid-body-param`; at runtime such a body is not created and one warning says why. `CharacterMotor` (`@waica/behaviors`) is the stock motor: `speed`, `jumpSpeed`, `turnSpeed` and five action names, walking on the world axes (`-z` is forward, diagonals at the cardinal speed), consuming the jump press only when it jumped; `character-motor-without-body` reports one without a kinematic `RigidBody` and a `Collider`, and `invalid-character-motor-param` a param outside the range its spec declares.
+- **Character.** A 3D character faces where it walks by turning, not by directional clips or flips (issue #166): each step it has a non-zero desired velocity, `CharacterMotor` turns the entity's yaw toward it through `turnYawToward(node, dirX, dirZ, turnSpeed, dt)` (`@waica/behaviors`; the target yaw is `atan2(dirX, dirZ)`, so a glTF's +z front leads; the shortest arc, at most `turnSpeed` degrees per second), and with no input, or a `speed` of 0, the yaw holds. `turnSpeed` defaults to 540 (about a third of a second for a U-turn), `0` snaps, and the kinematic body is unaffected: it keeps the rotation it spawned with, so give a turning character a `Collider` that looks the same from every side — a capsule or a sphere with no x/z `offset` — or the model and a box or offset collider disagree about where it ends. The `character` role (`CHARACTER_ROLE`, `CHARACTER_STATE_GRAPH`, `characterUpdate`) is the 3D counterpart of `player`: `idle`, `walk`, `jump` and `fall` on the signals its update emits by reading the kinematic `RigidBody` — `land` plus `move` (planar speed above 0.1 u/s) or `stop` on the ground, `rise` or `fall` in the air once it has vertical speed (air with none — the spawn, the steps while Rapier loads, the step after a teleport — reports nothing) — while the motor keeps reading the input itself; an `Animator` beside the machine plays each state's clip (a per-state `clip` maps `idle` to a pack's `Idle`). A project registers it with `defineRole('character', CHARACTER_ROLE)` in `src/roles/character.ts`; `validate_project` recognizes a `@waica/behaviors` role passed by reference there, so its states report no `no-state-code`.
+- **Contacts and sensors.** Components on an entity with a solid `Collider` get `onBodyContact({ entity, other, normal, point })` once per step for each entity they touch, the normal pointing from the entity to the other; kinematic bodies included, so a character hears the floor and the walls it touches. A `Collider{ sensor: true }` is the 3D `Hitbox`: it fires `onCollide(other)` every step it overlaps another collider, on each side whose `collidesWith` names the other's `layer` (ADR 0016); a solid collider is told only if it declares its own mask, and a sensor with the default mask (`['*']`) is not told about fixed solid colliders (the level's walls and floors), as a Hitbox never sees a Solid — a mask naming their layer still is.
+- **Queries.** `game.query` gains 3D forms told apart by argument shape: `ray(origin, direction, maxDistance, filter?)` returns the first solid collider (`{ entity, collider, distance, point, normal }`, sensors never block it), `area({ shape: 'box', center, size } | { shape: 'sphere', center, radius }, filter?)` and `point(at, filter?)` return the entities whose sensor colliders intersect or contain them, `nearest(at, filter?)` the closest transform with `z`. The filter object is the 2D one; its `where` runs after Rapier has answered, so it may throw or change the scene, and `area` answers `[]` for a volume that is not a finite box or sphere. A form in the other space's scene throws an error naming the space. Rapier updates what queries read inside the step, so the engine refreshes it when bodies came or went.
+- **Runtime Snapshot.** `space`, `view` (`{ kind: 'orthographic', position, zoom }` or `{ kind: 'perspective', position, target, fov }`) and, in a 3D scene, `lighting.sun[]` and `lighting.pointLights[]`, and `physics: { state: 'loading' | 'ready' | 'failed', gravity, bodies: [{ entity, id, type: 'fixed' | 'dynamic' | 'kinematic', velocity, grounded }] }` (bodies in spawn order, never filtered).
+- **Editor.** A 3D scene opens read-only: the viewport draws it through its perspective camera (the one Play uses) with no gesture, grid or gizmo; the inspector edits X/Y/Z, rotation and scale, and a perspective camera's position, target and fov.
+
+## State machines
+
+A `StateMachine` owns a character's per-frame logic: its `states` and their `transitions` are prefab data, the state code comes from the role's logic set (`defineRole`, `defineStates`), and `current` names the active state. Each transition is `{ on, to }`; a trigger is one of:
+
+- `input:<action>` — an unconsumed press of the action this Simulation Step; the transition spends it.
+- `timer:<seconds>` — the state has been active for at least that long (exact at the fixed step: `timer:0.3` is 18 steps).
+- `signal:<name>` — the state code queued `fsm.signal(name)` this step or the last.
+- `clip:end` — the Clip Target reports the clip the current state asked for finished (issue #166). It fires on the step after the clip's last frame has been held for its whole duration, and never for a looping clip (`validate_project` warns `clip-end-on-looping-clip`, the directional `<state>-<dir>` clips and the contract's fallbacks included). A state whose clip the target lacks keeps the previous clip playing but never reads its end as its own. Re-entering a state whose one-shot clip already ended replays it.
+
+Entering a state plays the clip of its name (or its `clip` override) through the entity's **Clip Target**: the first sibling component that plays clips — an `AnimatedSprite` in a 2D scene, an `Animator` in a 3D one — found by `isClipTarget` (a `play` function and a `clipNames` member), not by class. The directional contract resolves `<state>-<dir>` against the target's `clipNames` and mirrors only a target that defines `setFlipX`; a mirrored clip on a target without it plays unmirrored and warns once per state. A turn that only mirrors the running clip (west playing east flipped) re-applies the mirror and leaves the clip alone — a finished one-shot keeps its last frame — while a turn onto another clip name plays it. A clip the target lacks warns once and keeps the previous one; a target whose clips are pending (an `Animator` whose glb is loading) is asked anyway and remembers the request.
+
 ## Component lifecycle
 
 Waica keeps the lifecycle boundaries distinct:
 
 1. `Entity.add()` mounts a component and calls its `onReady` immediately. This remains component insertion order so setup behavior does not silently move.
 2. During each simulated frame, entities keep their existing entity order. When an entity's turn begins, `Game` snapshots and resolves that entity's component `onUpdate` schedule, then dispatches only that schedule.
-3. Physical `onContact` hooks run from `DynamicBody` while it updates. Hitbox `onCollide` hooks run after all entity component updates. Their existing component dispatch order is unchanged.
+3. Physical `onContact` hooks run from `DynamicBody` while it updates. After all entity component updates a 3D scene's physics world steps and `onBodyContact` follows, then Hitbox `onCollide` hooks run, then sensor `onCollide` hooks. Their existing component dispatch order is unchanged.
 4. `Game.onUpdate` callbacks run after component updates, collisions, and camera work; input end-of-frame handling follows them.
 5. `Entity.destroy()` calls `onDestroy` in component insertion order.
 
@@ -380,5 +455,6 @@ game.assets.status // { pending, loaded, failed } — a fresh object on every re
 - **`preload(uris)`.** Requests every uri and resolves once all of them settled, failures included. A component that later asks for the same resolved URL is a cache hit.
 - **`status`.** `pending` is current; `loaded` and `failed` are cumulative for the Game and only grow until `dispose()`. A host that wants a loading bar reads it from `game.onUpdate`.
 - **Failure rule.** A texture that fails to load is recorded, not thrown: `console.warn('[waica] assets: failed to load "<url>"', error)` once per Game per URL, `failed` counts it, `ready()` resolves, and every consumer falls back to its flat material — `Sprite` and `Tilemap` drop the failed map, dispose their clone and render their `color` again; `AnimatedSprite` never installs the failed sheet's clone, so that sheet's frames show a plain white quad. Asking for that URL again on the same Game is a cached failure — no retry, no second warning.
+- **Models.** `game.assets.model(uri)` is the glTF half of the same cache (see [3D scenes](#3d-scenes)): one load per URL, `status` and `ready()` count it, `preload` routes `.glb` and `.gltf` to it.
 - **`GameOptions.textures`.** Replaces the real `THREE.TextureLoader` backend for that Game (ADR 0013's seam, applied to textures): `happy-dom` decodes no images, so a project's own tests inject a backend that resolves at once. The Runtime Bridge reports `assets` in its metadata under the `'assets'` capability, and a Run Session waits for `pending === 0` at readiness, after a `scene` operation and before every screenshot.
 

package/dist/anchored-pieces.d.ts

@@ -1,5 +1,6 @@
+import { type ViewCamera } from './camera-projection.js';
 import type { Entity } from './entity.js';
-import type { PointerCamera, PointerResolution } from './pointer.js';
+import type { PointerResolution } from './pointer.js';
 import type { RuntimeSnapshotUi } from './runtime-inspection.js';
 import type { Stats, StatValue } from './stats.js';
 /** Options for `game.ui.attach` (issue #72). */
@@ -43,7 +44,7 @@ export interface ViewportRect {
 }
 /** What the Game tells the anchored layer each time it places: read live, never cached. */
 export interface AnchorView {
-    camera: PointerCamera;
+    camera: ViewCamera;
     /** The game viewport: see gameViewport. */
     viewport: ViewportRect;
     projection: 'isometric' | null;

package/dist/anchored-pieces.js

@@ -1,3 +1,4 @@
+import { pixelsPerUnit, worldToNormalized } from './camera-projection.js';
 import { projectIsometric } from './projection.js';
 import { placeholders, renderStat } from './ui-bindings.js';
 /**
@@ -154,8 +155,8 @@ export class AnchoredPieces {
         layer.style.top = `${viewport.y}px`;
         layer.style.width = `${viewport.width}px`;
         layer.style.height = `${viewport.height}px`;
-        // The camera frames exactly viewHeight world units vertically (Game.resize).
-        layer.style.setProperty('--waica-unit', `${viewport.height / (camera.top - camera.bottom)}px`);
+        // Orthographic: the camera frames exactly viewHeight world units vertically (Game.resize).
+        layer.style.setProperty('--waica-unit', `${pixelsPerUnit(camera, viewport.height)}px`);
         // Before any instance's style writes below: getAnimations() flushes style.
         for (const instance of this.instances)
             followGameTime(instance);
@@ -165,6 +166,7 @@ export class AnchoredPieces {
             instance.placed = placement;
             instance.host.style.left = `${placement.x}px`;
             instance.host.style.top = `${placement.y}px`;
+            instance.host.style.visibility = placement.behind ? 'hidden' : '';
             byDepth.push([instance, placement.depth]);
         }
         // Lower on screen draws on top, like y-sort; the sort is stable, so
@@ -252,19 +254,21 @@ export class AnchoredPieces {
 function anchorPoint(instance, projection) {
     if (instance.frozen)
         return instance.frozen;
-    const { x, y } = instance.entity.position;
+    const { x, y, z } = instance.entity.position;
     const render = projection === 'isometric' ? projectIsometric(x, y) : { x, y };
-    return { x: render.x + instance.offset[0], y: render.y + instance.offset[1] };
+    return { x: render.x + instance.offset[0], y: render.y + instance.offset[1], z };
 }
 /**
  * The anchor point in whole CSS px from the game viewport's top-left
  * corner: the exact inverse of the Pointer's screen→world mapping.
  */
 function locate(instance, view) {
-    const anchor = anchorPoint(instance, view.projection);
-    const { camera, viewport } = view;
-    const nx = (anchor.x - (camera.position.x + camera.left)) / (camera.right - camera.left);
-    const ny = (camera.position.y + camera.top - anchor.y) / (camera.top - camera.bottom);
+    const at = worldToNormalized(view.camera, anchorPoint(instance, view.projection));
+    // Behind a perspective camera there is no place on screen to put it.
+    if (!at)
+        return { x: 0, y: 0, clipped: true, depth: 1, behind: true };
+    const { nx, ny } = at;
+    const { viewport } = view;
     return {
         x: whole(nx * viewport.width),
         y: whole(ny * viewport.height),

package/dist/animation/clip-player.d.ts

@@ -14,6 +14,13 @@ export declare class ClipPlayer {
     private fps;
     private loop;
     private t;
+    /**
+     * Whether a non-looping clip has played through: its time reached
+     * `frames.length / fps` (the moment the last frame has been held for its
+     * whole duration), with the fixed-step epsilon so 30 steps of 1/60 s end a
+     * 0.5 s clip on the 30th. A looping clip never finishes; `set` clears it.
+     */
+    get finished(): boolean;
     set(clip: ClipDef): void;
     /** Advances the clock and returns the sheet frame to show. */
     advance(dt: number): number;

package/dist/animation/clip-player.js

@@ -8,6 +8,15 @@ export class ClipPlayer {
     fps = 1;
     loop = true;
     t = 0;
+    /**
+     * Whether a non-looping clip has played through: its time reached
+     * `frames.length / fps` (the moment the last frame has been held for its
+     * whole duration), with the fixed-step epsilon so 30 steps of 1/60 s end a
+     * 0.5 s clip on the 30th. A looping clip never finishes; `set` clears it.
+     */
+    get finished() {
+        return !this.loop && this.t + SIMULATION_TIME_EPSILON >= this.frames.length / this.fps;
+    }
     set(clip) {
         this.frames = clip.frames.length > 0 ? clip.frames : [0];
         this.fps = clip.fps;

package/dist/animation/clip-target.d.ts

@@ -0,0 +1,38 @@
+import type { Component } from '../component.js';
+/**
+ * The Clip Target (issue #166): the one sibling component a StateMachine
+ * plays clips through — `AnimatedSprite` in a 2D scene, `Animator` in a 3D
+ * one. The machine asks for a clip by name on entering a state, reads which
+ * names exist and which one runs, and learns from `clipFinished` that a
+ * one-shot clip ended (the `clip:end` trigger). `setFlipX` is the 2D
+ * directional contract's mirror; a target without it is never flipped.
+ */
+export interface ClipTarget {
+    /** The clip playing now, undefined (or absent) before the first `play`. */
+    readonly current?: string;
+    /** Every name `play` accepts. */
+    readonly clipNames: readonly string[];
+    /** True once a non-looping clip reached its end; false again after `play`. */
+    readonly clipFinished: boolean;
+    /**
+     * True while the target expects clips it cannot list yet (an Animator
+     * whose glb is loading): the machine asks for a clip anyway and the target
+     * remembers the request. Absent or false, an empty `clipNames` means the
+     * target has no clips, and a missing clip warns.
+     */
+    readonly clipsPending?: boolean;
+    play(name: string): void;
+    /**
+     * The 2D mirror. A target without it is never flipped: a directional clip
+     * resolved through a mirror plays unmirrored there, and the machine warns
+     * once per state.
+     */
+    setFlipX?(flip: boolean): void;
+}
+/**
+ * Duck-typed like the facing provider: the first sibling with a `play`
+ * function and a `clipNames` member is the target, whatever its class. The
+ * member is tested with `in`, never read: a target computes `clipNames` in a
+ * getter, and this runs on every Simulation Step of every machine.
+ */
+export declare function isClipTarget(component: Component): component is Component & ClipTarget;

package/dist/animation/clip-target.js

@@ -0,0 +1,9 @@
+/**
+ * Duck-typed like the facing provider: the first sibling with a `play`
+ * function and a `clipNames` member is the target, whatever its class. The
+ * member is tested with `in`, never read: a target computes `clipNames` in a
+ * getter, and this runs on every Simulation Step of every machine.
+ */
+export function isClipTarget(component) {
+    return 'play' in component && typeof component.play === 'function' && 'clipNames' in component;
+}

package/dist/animation/pose-hash.d.ts

@@ -0,0 +1,10 @@
+import * as THREE from 'three/webgpu';
+/** The 32-bit FNV-1a hash of `text` (UTF-8), as eight lowercase hex digits. Synchronous and dependency-free, the same on every backend. */
+export declare function fnv1a(text: string): string;
+/**
+ * A fingerprint of a rig's pose (issue #166 CA-10): FNV-1a over every bone's
+ * local quaternion and position rounded to 1e-4, in skeleton order, skeleton
+ * by skeleton. Empty with no skinned mesh under `root`. Two frames of the same
+ * clip differ; the same step of the same clip hashes alike on every platform.
+ */
+export declare function poseHash(root: THREE.Object3D): string;

package/dist/animation/pose-hash.js

@@ -0,0 +1,43 @@
+import * as THREE from 'three/webgpu';
+const FNV_OFFSET = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+/** The 32-bit FNV-1a hash of `text` (UTF-8), as eight lowercase hex digits. Synchronous and dependency-free, the same on every backend. */
+export function fnv1a(text) {
+    let hash = FNV_OFFSET;
+    for (const byte of new TextEncoder().encode(text)) {
+        hash ^= byte;
+        hash = Math.imul(hash, FNV_PRIME) >>> 0;
+    }
+    return hash.toString(16).padStart(8, '0');
+}
+const round = (value) => (Math.round(value * 1e4) / 1e4).toFixed(4);
+/** A skinned mesh, typed for what a glTF gives it (the generics three leaves at `any`). */
+function isSkinnedMesh(object) {
+    return object instanceof THREE.SkinnedMesh;
+}
+/** The skinned meshes under `root`, in traversal order. */
+function skinnedMeshesUnder(root) {
+    const found = [];
+    root.traverse((object) => {
+        if (isSkinnedMesh(object))
+            found.push(object);
+    });
+    return found;
+}
+/**
+ * A fingerprint of a rig's pose (issue #166 CA-10): FNV-1a over every bone's
+ * local quaternion and position rounded to 1e-4, in skeleton order, skeleton
+ * by skeleton. Empty with no skinned mesh under `root`. Two frames of the same
+ * clip differ; the same step of the same clip hashes alike on every platform.
+ */
+export function poseHash(root) {
+    const parts = [];
+    for (const mesh of skinnedMeshesUnder(root)) {
+        for (const bone of mesh.skeleton.bones) {
+            const { x, y, z, w } = bone.quaternion;
+            const { x: px, y: py, z: pz } = bone.position;
+            parts.push([x, y, z, w, px, py, pz].map(round).join(','));
+        }
+    }
+    return parts.length === 0 ? '' : fnv1a(parts.join(';'));
+}

package/dist/archetype.d.ts

@@ -16,8 +16,8 @@ export interface ArchetypeArt {
     file: string;
     /** Registry URI resolved by the archetype at runtime. */
     uri: string;
-    /** What kind of asset this is — a sprite sheet or texture, or a sound file. */
-    kind: 'image' | 'sound';
+    /** What kind of asset this is — a sprite sheet or texture, a sound file, or a glTF model. */
+    kind: 'image' | 'sound' | 'model';
 }
 /** The conventional contract exported by every archetype package. */
 export interface ArchetypeManifest {

package/dist/assets/asset-loader.d.ts

@@ -1,10 +1,12 @@
 import * as THREE from 'three/webgpu';
+import { type ModelBackend } from './model-backend.js';
+import { type ModelHandle } from './model-cache.js';
 import { type TextureBackend } from './texture-backend.js';
-/** `game.assets.status`: a fresh snapshot of the cache's counters, cumulative for the Game. */
+/** `game.assets.status`: a fresh snapshot of the caches' counters, textures and models together, cumulative for the Game. */
 export interface AssetStatus {
     /** Requested URLs that have not settled yet. */
     pending: number;
-    /** Settled URLs whose image arrived. */
+    /** Settled URLs whose image or model arrived. */
     loaded: number;
     /** Settled URLs whose load failed — recorded, warned once, never retried. */
     failed: number;
@@ -18,6 +20,8 @@ export interface TextureHandle {
 export interface AssetLoaderOptions {
     /** Replaces the real `THREE.TextureLoader` implementation (ADR 0013); defaults to it. */
     backend?: TextureBackend;
+    /** Replaces the real `GLTFLoader` implementation behind `model()`; defaults to it. */
+    models?: ModelBackend;
     /**
      * Resolves a uri for `preload()` the way the scene loader resolves every
      * prefab's string prop (`resolveProps` in scene.ts). Looked up on every
@@ -28,7 +32,7 @@ export interface AssetLoaderOptions {
     resolveAsset?: (uri: string) => string;
 }
 /**
- * The engine's texture cache (`game.assets`, ADR 0019): keep-all for the
+ * The engine's asset cache (`game.assets`, ADR 0019): keep-all for the
  * Game's whole life, keyed by the URL as received, one backend load and one
  * base texture per URL. `ready()` is the **Assets Ready** signal — a
  * promise beside the synchronous scene load — and a failed image is
@@ -37,8 +41,11 @@ export interface AssetLoaderOptions {
  */
 export declare class AssetLoader {
     private readonly backend;
+    private readonly models;
     private readonly resolveAsset;
     private readonly entries;
+    /** Work other than a texture or a model that counts as an asset (the physics module), until it settles. */
+    private readonly tracked;
     private pendingCount;
     private loadedCount;
     private failedCount;
@@ -52,10 +59,25 @@ export declare class AssetLoader {
      * settlement of that URL, which also fires on a cache hit.
      */
     texture(url: string): TextureHandle;
+    /**
+     * The consumer entry for glTF (Model): requests `url` — already resolved
+     * by `resolveProps` — and returns at once a root that fills with the
+     * consumer's own clone of the parsed file when it settles, with the file's
+     * animation clips. One backend load per URL, kept for the Game's life.
+     */
+    model(url: string): ModelHandle;
+    /**
+     * Counts `work` as an asset (the physics module is one): `pending` is one
+     * higher until it settles, then `loaded` or, when it rejects, `failed` with
+     * one warning naming `label`. Assets Ready waits for it. Never rejects.
+     */
+    track(work: Promise<unknown>, label: string): void;
     /**
      * Requests every uri ahead of time, each resolved through the registered
-     * scene catalog. Resolves once all of them settled, failures included —
-     * a failure still only warns once, the same as a component's request.
+     * scene catalog: a `.glb` or `.gltf` goes to the model cache, anything
+     * else to the texture cache. Resolves once all of them settled, failures
+     * included — a failure still only warns once, the same as a component's
+     * request.
      */
     preload(uris: string[]): Promise<void>;
     /**
@@ -69,6 +91,7 @@ export declare class AssetLoader {
     ready(): Promise<void>;
     /** Disposes every cached base exactly once and forgets everything; called by `Game.dispose()`. */
     dispose(): void;
+    private settleTracked;
     private request;
     private load;
     /** One backend load as an outcome, never a rejection — a backend that throws synchronously included. */

package/dist/assets/asset-loader.js

@@ -1,4 +1,6 @@
 import * as THREE from 'three/webgpu';
+import { GltfModelBackend } from './model-backend.js';
+import { ModelCache } from './model-cache.js';
 import { ThreeTextureBackend } from './texture-backend.js';
 import { reportRejection } from '../report-rejection.js';
 /**
@@ -18,8 +20,13 @@ function cloneOf(base) {
     clone.version = base.version;
     return clone;
 }
+/** Whether a resolved uri names a glTF file: `.glb` or `.gltf`, ignoring a query string or fragment. */
+function isModelUrl(url) {
+    const path = (url.split(/[?#]/, 1)[0] ?? '').toLowerCase();
+    return path.endsWith('.glb') || path.endsWith('.gltf');
+}
 /**
- * The engine's texture cache (`game.assets`, ADR 0019): keep-all for the
+ * The engine's asset cache (`game.assets`, ADR 0019): keep-all for the
  * Game's whole life, keyed by the URL as received, one backend load and one
  * base texture per URL. `ready()` is the **Assets Ready** signal — a
  * promise beside the synchronous scene load — and a failed image is
@@ -28,18 +35,27 @@ function cloneOf(base) {
  */
 export class AssetLoader {
     backend;
+    models;
     resolveAsset;
     entries = new Map();
+    /** Work other than a texture or a model that counts as an asset (the physics module), until it settles. */
+    tracked = new Set();
     pendingCount = 0;
     loadedCount = 0;
     failedCount = 0;
     constructor(options = {}) {
         this.backend = options.backend ?? new ThreeTextureBackend();
+        this.models = new ModelCache(options.models ?? new GltfModelBackend());
         this.resolveAsset = options.resolveAsset ?? ((uri) => uri);
     }
     /** A fresh object on every read: `pending` is current, `loaded` and `failed` only grow until `dispose()`. */
     get status() {
-        return { pending: this.pendingCount, loaded: this.loadedCount, failed: this.failedCount };
+        const models = this.models.counts;
+        return {
+            pending: this.pendingCount + models.pending,
+            loaded: this.loadedCount + models.loaded,
+            failed: this.failedCount + models.failed,
+        };
     }
     /**
      * The consumer entry (Sprite, AnimatedSprite, Tilemap): requests `url`
@@ -60,13 +76,41 @@ export class AssetLoader {
         }
         return { texture, settled: entry.settled };
     }
+    /**
+     * The consumer entry for glTF (Model): requests `url` — already resolved
+     * by `resolveProps` — and returns at once a root that fills with the
+     * consumer's own clone of the parsed file when it settles, with the file's
+     * animation clips. One backend load per URL, kept for the Game's life.
+     */
+    model(url) {
+        return this.models.handle(url);
+    }
+    /**
+     * Counts `work` as an asset (the physics module is one): `pending` is one
+     * higher until it settles, then `loaded` or, when it rejects, `failed` with
+     * one warning naming `label`. Assets Ready waits for it. Never rejects.
+     */
+    track(work, label) {
+        this.pendingCount += 1;
+        const settled = work.then(() => this.settleTracked(settled, 'loaded'), (error) => {
+            console.warn(`[waica] assets: failed to load "${label}"`, error);
+            this.settleTracked(settled, 'failed');
+        });
+        this.tracked.add(settled);
+    }
     /**
      * Requests every uri ahead of time, each resolved through the registered
-     * scene catalog. Resolves once all of them settled, failures included —
-     * a failure still only warns once, the same as a component's request.
+     * scene catalog: a `.glb` or `.gltf` goes to the model cache, anything
+     * else to the texture cache. Resolves once all of them settled, failures
+     * included — a failure still only warns once, the same as a component's
+     * request.
      */
     async preload(uris) {
-        await Promise.all(uris.map((uri) => this.request(this.resolveAsset(uri)).settled));
+        await Promise.all(uris.map((uri) => {
+            const url = this.resolveAsset(uri);
+            // A resolver may hand back a url with no extension (a blob: or data: one): the uri as written still names the file.
+            return isModelUrl(uri) || isModelUrl(url) ? this.models.preload(url) : this.request(url).settled;
+        }));
     }
     /**
      * Assets Ready: resolves the first time `pending` is 0 after the call —
@@ -77,20 +121,32 @@ export class AssetLoader {
      * first frame with the textures in place.
      */
     async ready() {
-        while (this.pendingCount > 0) {
+        while (this.status.pending > 0) {
             const inFlight = [...this.entries.values()].filter((entry) => entry.outcome === null);
-            await Promise.all(inFlight.map((entry) => entry.settled));
+            await Promise.all([...inFlight.map((entry) => entry.settled), ...this.models.inFlight(), ...this.tracked]);
         }
     }
     /** Disposes every cached base exactly once and forgets everything; called by `Game.dispose()`. */
     dispose() {
         for (const entry of this.entries.values())
             entry.base.dispose();
+        this.models.dispose();
         this.entries.clear();
+        this.tracked.clear();
         this.pendingCount = 0;
         this.loadedCount = 0;
         this.failedCount = 0;
     }
+    settleTracked(settled, outcome) {
+        // A dispose() in flight already forgot it and reset the counters.
+        if (!this.tracked.delete(settled))
+            return;
+        this.pendingCount -= 1;
+        if (outcome === 'loaded')
+            this.loadedCount += 1;
+        else
+            this.failedCount += 1;
+    }
     request(url) {
         const existing = this.entries.get(url);
         if (existing)

package/dist/assets/model-backend.d.ts

@@ -0,0 +1,21 @@
+import type * as THREE from 'three/webgpu';
+/** What a model backend hands the cache: the glTF's scene graph and its animation clips. */
+export interface LoadedModel {
+    scene: THREE.Group;
+    animations: THREE.AnimationClip[];
+}
+/**
+ * The seam between `game.assets.model()` and the browser (ADR 0013's move,
+ * applied to glTF — ADR 0019). `load` resolves once the file behind `url` is
+ * parsed, embedded textures included; it rejects on a load error and never
+ * throws synchronously. A test injects `FakeModelBackend`
+ * (assets/test-helpers.ts) through `GameOptions.models`.
+ */
+export interface ModelBackend {
+    load(url: string): Promise<LoadedModel>;
+}
+/** The real implementation: one `GLTFLoader` per Game, wrapped in a promise. */
+export declare class GltfModelBackend implements ModelBackend {
+    private readonly loader;
+    load(url: string): Promise<LoadedModel>;
+}

package/dist/assets/model-backend.js

@@ -0,0 +1,21 @@
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+/** What a loader reports (an `ErrorEvent`, a string, an `Error`) as an `Error` naming the file. */
+function asError(error, url) {
+    if (error instanceof Error)
+        return error;
+    return new Error(`failed to load "${url}"`, { cause: error });
+}
+/** The real implementation: one `GLTFLoader` per Game, wrapped in a promise. */
+export class GltfModelBackend {
+    loader = new GLTFLoader();
+    load(url) {
+        return new Promise((resolve, reject) => {
+            try {
+                this.loader.load(url, (gltf) => resolve({ scene: gltf.scene, animations: gltf.animations }), undefined, (error) => reject(asError(error, url)));
+            }
+            catch (error) {
+                reject(asError(error, url));
+            }
+        });
+    }
+}