@waica/engine 0.27.0 → 0.28.0

package/README.md

@@ -25,6 +25,14 @@ 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.28.0: 3D editor
+
+The editor edits 3D scenes (issue #173, ADR 0030). Scene files and game code are untouched; three engine seams become public, all additive:
+
+- **`raycastPick(camera, at, entities, extra?)`** is exported with its types (`PickTarget`, `PickedTarget`, `RaycastPick`, `ViewportFraction`). It is the raycast the Pointer uses in a 3D scene: every live Model root and the optional `extra` targets (`{ object, entity }`, where `entity` is an `Entity` or `'camera'`, tested whatever their layers), nearest hit first, with the ground plane y = 0 as the fallback point. `Pointer` behaves as before.
+- **`glbClipNames(bytes)`** returns a glb's animation clip names in file order (an unnamed clip is `animation_<index>`, as three names it), `[]` with none, and `null` for bytes that are not a glb or a JSON chunk that does not parse. It reads only the header and the JSON chunk, with no Node or DOM API beyond `TextDecoder`.
+- **`CameraRig.setViewCamera(camera | null)` and `CameraRig.sceneCamera`.** A host can draw a 3D scene through a camera of its own: while one is set, `game.camera` returns it, so the frame, the Pointer and `game.worldToScreen` follow it; `sceneCamera` keeps returning the camera the scene JSON places, and `setSceneCamera` keeps updating it. A 2D scene ignores the call with one warning. A game never sets one; the editor sets it only in edit mode, where its Game does not simulate.
+
 ## 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):
@@ -269,7 +277,7 @@ A scene declares its space (ADR 0027): `render.space: '2d'` (the default) or `'3
 - **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.
+- **Editor.** A 3D scene is edited through the Editor Camera (ADR 0030): in edit mode the viewport draws, picks and projects through an editor-owned perspective camera set with `game.cameraRig.setViewCamera(camera)` (`game.camera` returns it while set; `game.cameraRig.sceneCamera` keeps the one the JSON places; `null` restores it; a 2D scene ignores it with a warning). It starts at the scene camera's pose, orbits (middle button or Alt+left), pans (right button or Shift+middle), zooms (wheel), steps with the arrows, Shift+arrows, `+` and `-` on the focused viewport, frames the selection with `F`, and is remembered per scene; Play draws through the scene camera. A click picks through `raycastPick` (Models, and the icons of Suns, PointLights, meshless entities and the scene camera); `TransformControls` move, rotate and scale the selection (W, E, R; World or Local; Ctrl snaps to per-user steps), one undo per drag; a prefab drops where the ray meets a Model or the ground; an XZ grid and the helpers (the camera's frustum, each Sun's direction, each PointLight's range, each Collider's shape) draw in edit mode only. The inspector edits X/Y/Z, rotation and scale and a perspective camera's position, target and fov, and the Animator's clip fields list the glb's clips, read by `glbClipNames(bytes)`.
 
 ## State machines
 

package/dist/assets/glb-clip-names.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The names of a glb's animation clips, in file order, as three's loader
+ * names them: an unnamed clip is `animation_<index>`. Only the header and the
+ * JSON chunk are read, so bytes cut off after the JSON chunk still answer.
+ * `[]` for a glb with no animations; null for bytes that are not a glb or a
+ * JSON chunk that does not parse.
+ */
+export declare function glbClipNames(bytes: Uint8Array): string[] | null;

package/dist/assets/glb-clip-names.js

@@ -0,0 +1,49 @@
+// The clip names a glb carries, read from its JSON chunk alone (issue #173
+// CA-3): what the editor offers in its clip dropdowns and the MCP validates
+// clip references against, without loading the file. Pure: no Node or DOM API
+// beyond TextDecoder, so it runs in the browser, in Node and in a worker.
+/** The 12-byte glb header (magic, version, total length), then the 8-byte header of the first chunk, which must be JSON. */
+const HEADER_BYTES = 12;
+const CHUNK_HEADER_BYTES = 8;
+/** 'glTF' and 'JSON', read as little-endian uint32. */
+const GLB_MAGIC = 0x46546c67;
+const JSON_CHUNK = 0x4e4f534a;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** The glb's JSON document, or null when the bytes are not a glb or its JSON chunk is cut short or does not parse to an object. */
+function glbDocument(bytes) {
+    const start = HEADER_BYTES + CHUNK_HEADER_BYTES;
+    if (bytes.byteLength < start)
+        return null;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (view.getUint32(0, true) !== GLB_MAGIC || view.getUint32(HEADER_BYTES + 4, true) !== JSON_CHUNK)
+        return null;
+    const length = view.getUint32(HEADER_BYTES, true);
+    if (start + length > bytes.byteLength)
+        return null;
+    try {
+        const parsed = JSON.parse(new TextDecoder().decode(bytes.subarray(start, start + length)));
+        return isRecord(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The names of a glb's animation clips, in file order, as three's loader
+ * names them: an unnamed clip is `animation_<index>`. Only the header and the
+ * JSON chunk are read, so bytes cut off after the JSON chunk still answer.
+ * `[]` for a glb with no animations; null for bytes that are not a glb or a
+ * JSON chunk that does not parse.
+ */
+export function glbClipNames(bytes) {
+    const document = glbDocument(bytes);
+    if (!document)
+        return null;
+    const animations = Array.isArray(document.animations) ? document.animations : [];
+    return animations.map((animation, index) => {
+        const name = isRecord(animation) ? animation.name : undefined;
+        return typeof name === 'string' && name ? name : `animation_${index}`;
+    });
+}

package/dist/camera-rig.d.ts

@@ -17,17 +17,38 @@ export interface CameraFollowHost {
 /**
  * The Game's cameras. The orthographic one is built with the Game and frames
  * every 2D scene; a 3D scene swaps in a perspective one (built on first use).
- * `camera` is whichever the loaded scene uses (ADR 0027).
+ * `sceneCamera` is whichever the loaded scene uses (ADR 0027); `camera` is
+ * that one, or the host's view camera over a 3D scene while one is set.
  */
 export declare class CameraRig {
     readonly orthographic: THREE.OrthographicCamera;
     private perspective;
     private current;
+    /** A host-owned camera drawn through instead of the scene's (the editor's, issue #173). */
+    private view;
+    /** Set once the 2D-scene warning of setViewCamera was logged. */
+    private warnedFlatView;
     private aspect;
     /** How far the perspective camera's declared target was from its declared position. */
     private distance;
     constructor();
+    /**
+     * The camera the frame draws, the Pointer picks and `worldToScreen`
+     * projects through: the view camera over a 3D scene while one is set,
+     * else the scene camera.
+     */
     get camera(): GameCamera;
+    /** The camera placed from the scene's JSON, whatever view camera is set; `adopt` keeps updating it. */
+    get sceneCamera(): GameCamera;
+    /**
+     * Draws a 3D scene through `camera` instead of the scene camera, until
+     * cleared with null (issue #173 CA-1): the editor's own camera, which game
+     * code never sees because the editor's Game does not simulate. The rig fits
+     * its aspect to the view and lets it see the Emissive layer, as it does the
+     * scene camera. Over a 2D scene (or none yet) it has no effect and warns
+     * once; the camera is still kept, so it takes over when a 3D scene loads.
+     */
+    setViewCamera(camera: THREE.PerspectiveCamera | null): void;
     /** The distance from the perspective camera to the point it was aimed at; a snapshot reports its target from it. */
     get lookDistance(): number;
     /**

package/dist/camera-rig.js

@@ -5,12 +5,17 @@ import { placePerspectiveCamera, resolvePerspectiveCamera } from './scene-camera
 /**
  * The Game's cameras. The orthographic one is built with the Game and frames
  * every 2D scene; a 3D scene swaps in a perspective one (built on first use).
- * `camera` is whichever the loaded scene uses (ADR 0027).
+ * `sceneCamera` is whichever the loaded scene uses (ADR 0027); `camera` is
+ * that one, or the host's view camera over a 3D scene while one is set.
  */
 export class CameraRig {
     orthographic = new THREE.OrthographicCamera();
     perspective = null;
     current = this.orthographic;
+    /** A host-owned camera drawn through instead of the scene's (the editor's, issue #173). */
+    view = null;
+    /** Set once the 2D-scene warning of setViewCamera was logged. */
+    warnedFlatView = false;
     aspect = 1;
     /** How far the perspective camera's declared target was from its declared position. */
     distance = 1;
@@ -19,9 +24,38 @@ export class CameraRig {
         // Emissive drawables sit on their own layer; an unlit frame draws it in place.
         this.orthographic.layers.enable(EMISSIVE_LAYER);
     }
+    /**
+     * The camera the frame draws, the Pointer picks and `worldToScreen`
+     * projects through: the view camera over a 3D scene while one is set,
+     * else the scene camera.
+     */
     get camera() {
+        return this.view && this.current === this.perspective ? this.view : this.current;
+    }
+    /** The camera placed from the scene's JSON, whatever view camera is set; `adopt` keeps updating it. */
+    get sceneCamera() {
         return this.current;
     }
+    /**
+     * Draws a 3D scene through `camera` instead of the scene camera, until
+     * cleared with null (issue #173 CA-1): the editor's own camera, which game
+     * code never sees because the editor's Game does not simulate. The rig fits
+     * its aspect to the view and lets it see the Emissive layer, as it does the
+     * scene camera. Over a 2D scene (or none yet) it has no effect and warns
+     * once; the camera is still kept, so it takes over when a 3D scene loads.
+     */
+    setViewCamera(camera) {
+        if (camera && this.current !== this.perspective && !this.warnedFlatView) {
+            console.warn('[waica] setViewCamera has no effect over a 2D scene or none: its camera is orthographic');
+            this.warnedFlatView = true;
+        }
+        this.view = camera;
+        if (!camera)
+            return;
+        camera.layers.enable(EMISSIVE_LAYER);
+        camera.aspect = this.aspect;
+        camera.updateProjectionMatrix();
+    }
     /** The distance from the perspective camera to the point it was aimed at; a snapshot reports its target from it. */
     get lookDistance() {
         return this.distance;
@@ -58,10 +92,12 @@ export class CameraRig {
         camera.top = halfH;
         camera.bottom = -halfH;
         camera.updateProjectionMatrix();
-        if (!this.perspective)
-            return;
-        this.perspective.aspect = aspect;
-        this.perspective.updateProjectionMatrix();
+        for (const lens of [this.perspective, this.view]) {
+            if (!lens)
+                continue;
+            lens.aspect = aspect;
+            lens.updateProjectionMatrix();
+        }
     }
     /** One Simulation Step of the orthographic follow camera (deadzone, lookahead, smoothing, limits). */
     follow(cam, host, dt) {

package/dist/game.d.ts

@@ -255,7 +255,7 @@ export declare class Game {
     get projection(): 'isometric' | null;
     /** The live scene's space (`render.space`); `'2d'` with no scene (ADR 0027). */
     get space(): SceneSpace;
-    /** The camera the live scene draws with: orthographic in 2D scenes, perspective in 3D ones. */
+    /** The camera the live scene draws with: orthographic in 2D scenes, perspective in 3D ones, or a host's view camera over a 3D one (`cameraRig.setViewCamera`). */
     get camera(): GameCamera;
     /**
      * Where a logical point falls on the canvas, in CSS px from its top-left

package/dist/game.js

@@ -469,7 +469,7 @@ export class Game {
     get space() {
         return this.sceneSpace;
     }
-    /** The camera the live scene draws with: orthographic in 2D scenes, perspective in 3D ones. */
+    /** The camera the live scene draws with: orthographic in 2D scenes, perspective in 3D ones, or a host's view camera over a 3D one (`cameraRig.setViewCamera`). */
     get camera() {
         return this.cameraRig.camera;
     }

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { AssetLoader } from './assets/asset-loader.js';
 export type { AssetStatus } from './assets/asset-loader.js';
 export type { TextureBackend } from './assets/texture-backend.js';
 export { GltfModelBackend } from './assets/model-backend.js';
+export { glbClipNames } from './assets/glb-clip-names.js';
 export type { LoadedModel, ModelBackend } from './assets/model-backend.js';
 export type { ModelHandle, ModelOutcome } from './assets/model-cache.js';
 export { AudioSubsystem } from './audio/audio-subsystem.js';
@@ -49,6 +50,8 @@ export type { ActionName, InjectedActionOperation, InputBindings, InputOptions }
 export { ACTION_HELD_THRESHOLD, firstStandardPadValues, GAMEPAD_CODE_PREFIX, gamepadControl, } from './gamepad.js';
 export type { GamepadControl } from './gamepad.js';
 export { Pointer } from './pointer.js';
+export { raycastPick } from './pointer-raycast.js';
+export type { PickedTarget, PickTarget, RaycastPick, ViewportFraction } from './pointer-raycast.js';
 export type { PointerCamera, PointerDeps, PointerPick, PointerResolution } from './pointer.js';
 export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
 export type { RuntimeBridge, RuntimeBridgeActivation, RuntimeBridgeFailure, RuntimeControlRequest, RuntimeControlResult, RuntimeMetadata, RuntimeMode, } from './runtime-bridge.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 export { Game } from './game.js';
 export { AssetLoader } from './assets/asset-loader.js';
 export { GltfModelBackend } from './assets/model-backend.js';
+export { glbClipNames } from './assets/glb-clip-names.js';
 export { AudioSubsystem } from './audio/audio-subsystem.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
 export { isClipTarget } from './animation/clip-target.js';
@@ -23,6 +24,7 @@ export { resolveComponentUpdateSchedule } from './component-update-schedule.js';
 export { Input, DEFAULT_BINDINGS } from './input.js';
 export { ACTION_HELD_THRESHOLD, firstStandardPadValues, GAMEPAD_CODE_PREFIX, gamepadControl, } from './gamepad.js';
 export { Pointer } from './pointer.js';
+export { raycastPick } from './pointer-raycast.js';
 export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
 export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
 export { Stats } from './stats.js';

package/dist/pointer-raycast.d.ts

@@ -1,17 +1,35 @@
 import * as THREE from 'three/webgpu';
 import type { Entity } from './entity.js';
-import type { PointerPick } from './pointer.js';
 /** A position inside the letterboxed game viewport, as fractions of its width and height. */
 export interface ViewportFraction {
     nx: number;
     ny: number;
 }
+/** What an extra target picks: an entity (an editor's icon for it), or the scene camera's icon. */
+export type PickedTarget = Entity | 'camera';
+/** An object a ray is also tested against, and what a hit on it picks (issue #173 CA-2). */
+export interface PickTarget<Picked extends PickedTarget = PickedTarget> {
+    readonly object: THREE.Object3D;
+    readonly entity: Picked;
+}
+/** A 3D pick: the hit's world point, and the entity (or extra target) hit, or null on the ground. */
+export interface RaycastPick<Picked extends PickedTarget = Entity> {
+    readonly point: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+    };
+    readonly entity: Entity | Picked | null;
+}
 /**
  * The pick for a click on a 3D scene (issue #154 CA-12): a ray through the
  * letterboxed point, intersected with the roots of every live Model
- * (recursively, so a glTF's meshes count and a glTF still loading does not).
- * The nearest hit wins, with its world-space point. With no hit the pick has
- * no entity and the point where the ray meets the ground plane y = 0; a ray
- * that never meets it (it looks at the sky) yields no pick.
+ * (recursively, so a glTF's meshes count, posed where its skeleton is, and a
+ * glTF still loading does not) and with the `extra` targets a host adds (the
+ * editor's icons, issue #173 CA-2; one that is hidden, or whose entity is
+ * dead, is skipped). The nearest hit wins, with its
+ * world-space point. With no hit the pick has no entity and the point where
+ * the ray meets the ground plane y = 0; a ray that never meets it (it looks
+ * at the sky) yields no pick.
  */
-export declare function raycastPick(camera: THREE.PerspectiveCamera, at: ViewportFraction, entities: readonly Entity[]): PointerPick | null;
+export declare function raycastPick<Picked extends PickedTarget = Entity>(camera: THREE.PerspectiveCamera, at: ViewportFraction, entities: readonly Entity[], extra?: readonly PickTarget<Picked>[]): RaycastPick<Picked> | null;

package/dist/pointer-raycast.js

@@ -16,33 +16,63 @@ function modelRoots(entities) {
     }
     return roots;
 }
-/** The entity whose Model root `object` hangs under. */
-function ownerOf(object, roots) {
+/** What `object` picks: the target or Model root it hangs under, nearest first. */
+function ownerOf(object, owners) {
     for (let node = object; node; node = node.parent) {
-        const entity = roots.get(node);
-        if (entity)
-            return entity;
+        const owner = owners.get(node);
+        if (owner)
+            return owner;
     }
     return null;
 }
+/** Whether `target` is drawn and still picks something: itself and every ancestor visible, and its entity alive. */
+function isPickable(target) {
+    if (target.entity !== 'camera' && !target.entity.alive)
+        return false;
+    for (let node = target.object; node; node = node.parent) {
+        if (!node.visible)
+            return false;
+    }
+    return true;
+}
+/** The extra targets' hits: tested whatever their layers, since an editor overlay lives on the Emissive layer alone. */
+function extraHits(targets) {
+    if (targets.length === 0)
+        return [];
+    const own = raycaster.layers.mask;
+    raycaster.layers.enableAll();
+    try {
+        return raycaster.intersectObjects(targets.filter(isPickable).map((target) => target.object), true);
+    }
+    finally {
+        raycaster.layers.mask = own;
+    }
+}
 /**
  * The pick for a click on a 3D scene (issue #154 CA-12): a ray through the
  * letterboxed point, intersected with the roots of every live Model
- * (recursively, so a glTF's meshes count and a glTF still loading does not).
- * The nearest hit wins, with its world-space point. With no hit the pick has
- * no entity and the point where the ray meets the ground plane y = 0; a ray
- * that never meets it (it looks at the sky) yields no pick.
+ * (recursively, so a glTF's meshes count, posed where its skeleton is, and a
+ * glTF still loading does not) and with the `extra` targets a host adds (the
+ * editor's icons, issue #173 CA-2; one that is hidden, or whose entity is
+ * dead, is skipped). The nearest hit wins, with its
+ * world-space point. With no hit the pick has no entity and the point where
+ * the ray meets the ground plane y = 0; a ray that never meets it (it looks
+ * at the sky) yields no pick.
  */
-export function raycastPick(camera, at, entities) {
+// eslint-disable-next-line max-params -- the signature spec #173 fixes: the Pointer's three inputs plus the optional extra targets; bundling them would be an unrelated bag
+export function raycastPick(camera, at, entities, extra = []) {
     camera.updateMatrixWorld();
     raycaster.setFromCamera(new THREE.Vector2(at.nx * 2 - 1, 1 - at.ny * 2), camera);
     const roots = modelRoots(entities);
+    const owners = new Map(roots);
+    for (const target of extra)
+        owners.set(target.object, target.entity);
     // A click can land before the first frame has placed anything.
-    for (const root of roots.keys())
-        root.updateWorldMatrix(true, true);
-    const [hit] = raycaster.intersectObjects([...roots.keys()], true);
+    for (const object of owners.keys())
+        object.updateWorldMatrix(true, true);
+    const [hit] = [...raycaster.intersectObjects([...roots.keys()], true), ...extraHits(extra)].sort((a, b) => a.distance - b.distance);
     if (hit)
-        return { entity: ownerOf(hit.object, roots), point: { x: hit.point.x, y: hit.point.y, z: hit.point.z } };
+        return { entity: ownerOf(hit.object, owners), point: { x: hit.point.x, y: hit.point.y, z: hit.point.z } };
     const ground = raycaster.ray.intersectPlane(GROUND, new THREE.Vector3());
     return ground ? { entity: null, point: { x: ground.x, y: ground.y, z: ground.z } } : null;
 }

package/dist/runtime-view-snapshot.js

@@ -6,7 +6,8 @@ function vector(value) {
     return [clean(value.x), clean(value.y), clean(value.z)];
 }
 export function viewSnapshot(game) {
-    const camera = game.camera;
+    // The scene's own camera: a host's view camera is not part of the simulated game, and `lookDistance` is the scene camera's.
+    const camera = game.cameraRig.sceneCamera;
     if (!isPerspectiveCamera(camera)) {
         return { kind: 'orthographic', position: [clean(camera.position.x), clean(camera.position.y)], zoom: game.view };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",