@waica/engine 0.24.0 → 0.26.0

package/README.md

@@ -25,6 +25,27 @@ 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.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:
@@ -183,13 +204,69 @@ Under batching, the object a sprite adds to its entity is a hidden placement anc
 
 How much batching saves depends on how interleaved a scene is: one texture over the whole scene draws in one call, while a top-down scene that alternates many textures by y gains little. Runtime Snapshots are unchanged — batches are not entities, and sprites report the same state either way.
 
+## Lighting and Post Effects
+
+A scene can be lit (issue #78, ADR 0026). Without lighting and without a Post Effect a scene is drawn exactly as before: one render straight into the canvas, no render target.
+
+```json
+"render": {
+  "lighting": { "ambient": { "color": "#5a6a9a", "intensity": 0.3 } },
+  "post": {
+    "vignette": { "intensity": 0.45, "radius": 0.35 },
+    "colorGrade": { "tint": "#ffeedd", "contrast": 1.1, "saturation": 0.9 }
+  }
+}
+```
+
+- **Ambient Light.** `render.lighting.ambient` is where no light reaches: `color` (`#rrggbb`, default `#ffffff`) times `intensity` (0..1, default 1). `game.lighting.ambient` reads it and sets it at runtime, field by field (`game.lighting.ambient = { intensity: 0.2 }`), so a day/night cycle is a `game.time.tween` whose `onUpdate` sets it. Setting it lights a scene that declared none. It dies with its scene: a scene load or swap takes the next scene's value.
+- **Light.** A component: `radius` (logical units), `color`, `intensity` (≥ 0), `bands` (0 smooth, up to 16 equal steps), `softness` (0 hard shadow edge, up to 1), `castShadows` (default true) and `offsetX`/`offsetY` from its entity. Its falloff is `1 − smoothstep(d / radius)`, measured in logical space, so on an isometric screen it is a 2:1 ellipse. Lights add to the Ambient Light and never darken; the sum clamps at 1. A scene with a live Light is lit even without `render.lighting`, but under full Ambient Light (`#ffffff`, 1) a light changes no pixel, so such a frame skips the light-map altogether. `game.lighting.lights` lists them.
+- **Occlusion.** Only Tilemap `solidTiles` stop light: a point whose line to the light crosses a solid tile other than its own is in shadow, while the solid tile itself keeps the light that reaches it (its lit face). Every Tilemap of the scene contributes; the grid is rebuilt only when a Tilemap spawns, is destroyed or changes its tiles. Props with a `Solid` and moving entities cast no shadow.
+- **Emissive.** `Sprite`, `AnimatedSprite` and `ParticleEmitter` take `emissive: true`: drawn after the light-map at full brightness (a flame, sparks), still in their own order and Sprite Batch runs. Every drawable discards its fully transparent texels, so an Emissive drawable behind a lit sprite shows through that sprite's transparent texels and stays hidden behind its opaque ones. Engine-wise they sit on `EMISSIVE_LAYER`; `setEmissive(object, true)` puts any three.js object there.
+- **How a lit frame is drawn.** The scene without its Emissive drawables goes straight to the canvas as always; then a light-map — an 8-bit target the size of the fixed `resolution` (nearest upscale), or of the drawing buffer without one — cleared to the Ambient Light and lit by one quad per Light is multiplied over it; then the Emissive drawables. The multiply works on the canvas's sRGB values, so Ambient Light 1 with no light leaves the frame identical.
+- **Post Effects.** `render.post.vignette` (`intensity` and `radius`, 0..1) darkens towards the corners; `render.post.colorGrade` (`tint`, `contrast` and `saturation` 0..2, 1 = unchanged) grades the frame. With either on, the frame (lighting and Emissive drawables included) renders into an 8-bit target at the light-map's size, drawn exactly as onto the canvas (sRGB-encoded, blending on sRGB values, so no sprite edge changes), and one full-screen pass grades it and writes it to the canvas. `game.post.vignette` and `game.post.colorGrade` read and set them field by field over the current values, like the ambient (null turns one off); they die with their scene. Camera Effects stay above and are never altered.
+- **Validation and snapshots.** `validate_project` reports an out-of-range render field as `invalid-scene-render` and a Light param outside its range as `invalid-light-param`, naming it; at runtime out-of-range values are clamped. Every Runtime Snapshot carries `lighting: { ambient, lights: [{ entity, id, x, y, radius, color, intensity, bands, softness, castShadows }] }` in logical coordinates and `post: { vignette, colorGrade }` (null when off).
+
+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. glTF animations load with the file (`ModelHandle.animations`) and are not played yet.
+- **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` 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`.
+- **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.
+
 ## 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.
 
@@ -356,5 +433,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/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));
+            }
+        });
+    }
+}

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

@@ -0,0 +1,47 @@
+import * as THREE from 'three/webgpu';
+import type { ModelBackend } from './model-backend.js';
+export type ModelOutcome = 'loaded' | 'failed';
+/**
+ * What a consumer gets from `game.assets.model(url)`: a root that is empty
+ * until the glTF settles and then holds the consumer's own clone of it, the
+ * file's animation clips (empty until then, and for a failed load), and when
+ * the file settled. The cached glTF itself is never handed out.
+ */
+export interface ModelHandle {
+    readonly root: THREE.Group;
+    readonly animations: readonly THREE.AnimationClip[];
+    readonly settled: Promise<ModelOutcome>;
+}
+/** The cache's counters, summed into `game.assets.status` beside the textures'. */
+export interface ModelCounts {
+    pending: number;
+    loaded: number;
+    failed: number;
+}
+/**
+ * The model half of `game.assets` (ADR 0019): keep-all for the Game's whole
+ * life, keyed by the URL as received, one backend load and one parsed glTF
+ * per URL, counted like the texture cache so Assets Ready waits for it. A
+ * failed file is recorded and warned about once, never retried.
+ */
+export declare class ModelCache {
+    private readonly backend;
+    private readonly entries;
+    private pendingCount;
+    private loadedCount;
+    private failedCount;
+    constructor(backend: ModelBackend);
+    get counts(): ModelCounts;
+    /** The consumer entry: requests `url` and returns a handle whose root fills with a clone once the file settles. */
+    handle(url: string): ModelHandle;
+    /** Requests `url` ahead of time; resolves with its outcome. */
+    preload(url: string): Promise<ModelOutcome>;
+    /** The settlements of every file that has not settled yet, for Assets Ready. */
+    inFlight(): Promise<ModelOutcome>[];
+    /** Disposes every cached glTF exactly once and forgets everything. */
+    dispose(): void;
+    private request;
+    private load;
+    /** One backend load as an outcome, never a rejection — a backend that throws synchronously included. */
+    private attempt;
+}

package/dist/assets/model-cache.js

@@ -0,0 +1,117 @@
+import * as THREE from 'three/webgpu';
+import { clone as cloneWithSkeleton } from 'three/addons/utils/SkeletonUtils.js';
+function isMesh(object) {
+    return object instanceof THREE.Mesh;
+}
+/** The textures a material references, for disposal. */
+function texturesOf(material) {
+    const values = Object.values(material);
+    return values.filter((value) => value instanceof THREE.Texture);
+}
+/** Disposes the geometry, materials and textures a glTF scene owns. */
+function disposeScene(scene) {
+    scene.traverse((object) => {
+        if (!isMesh(object))
+            return;
+        object.geometry.dispose();
+        const materials = Array.isArray(object.material) ? object.material : [object.material];
+        for (const material of materials) {
+            for (const texture of texturesOf(material))
+                texture.dispose();
+            material.dispose();
+        }
+    });
+}
+/**
+ * The model half of `game.assets` (ADR 0019): keep-all for the Game's whole
+ * life, keyed by the URL as received, one backend load and one parsed glTF
+ * per URL, counted like the texture cache so Assets Ready waits for it. A
+ * failed file is recorded and warned about once, never retried.
+ */
+export class ModelCache {
+    backend;
+    entries = new Map();
+    pendingCount = 0;
+    loadedCount = 0;
+    failedCount = 0;
+    constructor(backend) {
+        this.backend = backend;
+    }
+    get counts() {
+        return { pending: this.pendingCount, loaded: this.loadedCount, failed: this.failedCount };
+    }
+    /** The consumer entry: requests `url` and returns a handle whose root fills with a clone once the file settles. */
+    handle(url) {
+        const entry = this.request(url);
+        const root = new THREE.Group();
+        const animations = [];
+        const settled = entry.settled.then((outcome) => {
+            const model = entry.base;
+            if (outcome === 'loaded' && model && this.entries.get(url) === entry) {
+                root.add(cloneWithSkeleton(model.scene));
+                animations.push(...model.animations);
+            }
+            return outcome;
+        });
+        return { root, animations, settled };
+    }
+    /** Requests `url` ahead of time; resolves with its outcome. */
+    preload(url) {
+        return this.request(url).settled;
+    }
+    /** The settlements of every file that has not settled yet, for Assets Ready. */
+    inFlight() {
+        return [...this.entries.values()].filter((entry) => entry.outcome === null).map((entry) => entry.settled);
+    }
+    /** Disposes every cached glTF exactly once and forgets everything. */
+    dispose() {
+        for (const entry of this.entries.values())
+            if (entry.base)
+                disposeScene(entry.base.scene);
+        this.entries.clear();
+        this.pendingCount = 0;
+        this.loadedCount = 0;
+        this.failedCount = 0;
+    }
+    request(url) {
+        const existing = this.entries.get(url);
+        if (existing)
+            return existing;
+        const entry = { base: null, outcome: null, settled: Promise.resolve('failed') };
+        // Registered and counted before the backend runs, so a backend that
+        // throws synchronously still settles this very entry.
+        this.entries.set(url, entry);
+        this.pendingCount += 1;
+        entry.settled = this.load(url, entry);
+        return entry;
+    }
+    async load(url, entry) {
+        const attempt = await this.attempt(url);
+        // A dispose() in flight already forgot this entry: only the settlement is still owed.
+        if (this.entries.get(url) !== entry) {
+            if (attempt.outcome === 'loaded')
+                disposeScene(attempt.model.scene);
+            return attempt.outcome;
+        }
+        if (attempt.outcome === 'loaded') {
+            entry.base = attempt.model;
+            this.loadedCount += 1;
+        }
+        else {
+            console.warn(`[waica] assets: failed to load "${url}"`, attempt.error);
+            this.failedCount += 1;
+        }
+        entry.outcome = attempt.outcome;
+        this.pendingCount -= 1;
+        return attempt.outcome;
+    }
+    /** One backend load as an outcome, never a rejection — a backend that throws synchronously included. */
+    async attempt(url) {
+        try {
+            return { outcome: 'loaded', model: await this.backend.load(url) };
+        }
+        catch (error) {
+            return { outcome: 'failed', error };
+        }
+    }
+}