@umicat/three-sdk 0.1.0

package/README.md

@@ -0,0 +1,108 @@
+# @umicat/three-sdk
+
+The three.js runtime for Umicat games, per ADR-033. Platform services come from
+`@umicat/platform-sdk` untouched; what lives here is the engine layer we own.
+
+**Status: seed, not a product.** It loads a scene, runs physics, and proves the
+platform seam. It has no editor, no input system, no character controller, no
+audio, and no published package. Nothing in production uses it.
+
+```
+@umicat/platform-sdk        identity · saves · gameData · rooms · ai · voice · dialogue
+        ▲                              (shared with @umicat/phaser-sdk)
+        │
+@umicat/three-sdk       ThreeUmicat · scene3d format · loadScene3D · physics wiring
+        ▲
+   your game            gameplay
+```
+
+## What is proven, and by what
+
+`npm test` runs a real three.js game in a real browser against a host speaking
+the real wire protocol. **Only the host page and the backend behind it are
+mocked — every line of SDK is the shipped code.**
+
+| claim | test |
+|---|---|
+| a 3D game does the real handshake and gets identity | `host` is `umicat-home-ui`, not `standalone` |
+| cloud saves go over RPC, not to localStorage | round-trip, plus the host's RPC log |
+| runtime AI uses the same channel | `ai.complete` returns `{ok, text}` per the protocol |
+| scene3d builds the authored scene | entity count, parenting, the right clip playing |
+| physics runs | a crate dropped from y=6 settles on the ground and does not fall through |
+| design mode is render-only | same entities, zero mixers, zero bodies |
+| authoring mistakes fail loudly | duplicate ids and missing clips throw at load, naming the clips that exist |
+
+`slice.png` is the scene those assertions describe, rendered.
+
+## The scene3d format
+
+`src/scene3d.ts`. It inherits ADR-021's answer to *what does the editor edit* —
+design data on disk, no save loaded — because that answer is engine-neutral. It
+does **not** inherit the 2D schema, which does not survive three dimensions.
+
+Each rule is a decision:
+
+- **Rotation is a quaternion**, not Euler angles — those are order-dependent and
+  interpolate badly, so an editor round-tripping them drifts.
+- **Ids are authored and stable.** The editor, the runtime and saves all refer to
+  entities by id; regenerating them on load breaks every reference on first edit.
+- **Transforms are local to `parent`.** Storing world transforms makes
+  reparenting a lie.
+- **Assets are referenced by id**, never by path — paths change on re-import.
+- **Colliders are explicit.** A render mesh used as a dynamic collider is the
+  classic way to ship a game that is correct and unplayably slow.
+- **Animation clips are mapped semantically per asset** (`{ walk: 'Walk' }`).
+  Guessing that every model calls its walk cycle `Walk` fails silently; an
+  independent review's cross-rig retarget returned zero matched bones and zero
+  tracks, which is the same class of failure, quieter.
+
+`validateScene` refuses duplicate ids, dangling parents, entities that would
+render nothing, trimesh colliders on dynamic bodies, and malformed quaternions —
+at load, because every one of them otherwise appears as a blank screen later.
+
+## Solved: the character that disappeared once the camera moved
+
+Worth keeping, because the symptom pointed everywhere except at the cause.
+
+In the Courtyard sample the fox rendered at boot and was gone after walking,
+leaving flat ground. Every measurement said it should be visible: 18 draw calls
+and 5,042 triangles that frame, `hero.visible === true`, bones at sensible world
+positions, and three's own `Vector3.project(camera)` putting the character at
+NDC **(0, 0)** — dead centre — while the centre of the frame was a single flat
+colour. A canvas read-back agreed with the screenshot, so it was the render and
+not the capture.
+
+**It was the ground.** `makePrimitive` laid the plane down with
+`mesh.rotation.x = -Math.PI / 2`, and `applyTransform` then set the object's
+quaternion from the entity's authored rotation — identity — **discarding it**.
+So every "ground" stood upright as a 40x40 wall. At boot the camera and the
+character were on the same side of it and the picture looked right, with the
+wall reading as ground. Walk past it and the camera is behind a wall, still
+pointing correctly at a character it can no longer see. A raycast through the
+frame centre said it in one line: `ground` at 9.79m, `fox` at 13.89m.
+
+Fixed by rotating the **geometry** (`PlaneGeometry(...).rotateX(-Math.PI/2)`)
+rather than the object, so an entity's authored rotation is never overwritten.
+After the fix the same raycast returns `fox` at 13.89m then `ground` at 18.05m —
+which matches the hand-computed ground crossing exactly.
+
+Two lessons kept deliberately. **A correct-looking measurement can be measuring
+the right thing about the wrong scene**: NDC (0,0) was true the whole time, the
+character *was* centred, behind a wall. And **the first render looked fine**,
+which is how a construction bug this total survived a screenshot.
+
+One real bug was fixed while chasing it and is unrelated but worth having: a
+`SkinnedMesh`'s bounding sphere comes from the bind pose and does not follow the
+bones, so three.js culls a character against a stale volume once it moves.
+`loadScene3D` sets `frustumCulled = false` on skinned meshes.
+
+## What is deliberately missing
+
+No character controller (Rapier's `KinematicCharacterController` is the intended
+basis), no input, no audio, no editor, no HUD, no asset pipeline integration, no
+published build. Those are the next slice's scope, and pretending otherwise
+would be a worse lie than the gap.
+
+`ThreeUmicat.dialogue` has **no default renderer**: a game passes `opts.renderer`
+or it throws. A 3D dialogue box is a design question nobody has answered, and
+shipping a broken default would be worse than requiring an explicit one.

package/dist/CharacterController3D.d.ts

@@ -0,0 +1,71 @@
+import type * as THREE from 'three';
+/** The Rapier surface this controller needs, typed structurally. */
+interface RapierRuntime {
+    ColliderDesc: any;
+    RigidBodyDesc: any;
+}
+export interface CharacterOptions {
+    /** Capsule half-height (excluding the caps) and radius. */
+    halfHeight?: number;
+    radius?: number;
+    /** Metres per second on flat ground. */
+    speed?: number;
+    /** Max step the character walks up without jumping. */
+    stepHeight?: number;
+    /** Steeper than this and they slide instead of climbing. Degrees. */
+    maxSlopeDegrees?: number;
+    gravity?: number;
+    /** Start position. */
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+/**
+ * A kinematic character: walks, collides with walls, climbs steps, falls.
+ *
+ * Rapier ships the hard part (`KinematicCharacterController` with autostep,
+ * ground snapping and slope limits), so this is glue — but glue with one trap
+ * in it, which an independent review hit and documented before I did:
+ *
+ * **Gravity is an acceleration, not a displacement.** Feeding the controller
+ * `-9.81 / 60` each frame asks it to move down at a constant 0.16 m per step,
+ * which looks like falling and is not. It passes a wall test and fails a step
+ * test, because a constant downward push fights autostep every frame. So
+ * vertical velocity accumulates while airborne and resets on landing, and the
+ * grounded state applies only a small downward bias — enough for snap-to-ground
+ * to keep contact on slopes and stairs, not enough to pin the character down.
+ */
+export declare class CharacterController3D {
+    private readonly world;
+    readonly body: any;
+    readonly collider: any;
+    private readonly controller;
+    private verticalVelocity;
+    private readonly opts;
+    constructor(world: any, RAPIER: RapierRuntime, options?: CharacterOptions);
+    get grounded(): boolean;
+    get position(): {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /**
+     * Move for one step. `dir` is a desired direction in world space (y ignored);
+     * it is normalised here so diagonals aren't faster than cardinals — a bug old
+     * enough to have a name.
+     */
+    update(dt: number, dir: {
+        x: number;
+        z: number;
+    }): void;
+    /** Copy the simulated position onto the rendered object. */
+    syncTo(object: THREE.Object3D, yOffset?: number): void;
+    /** Face the direction of travel; ignores tiny inputs so idle doesn't spin. */
+    faceTowards(object: THREE.Object3D, dir: {
+        x: number;
+        z: number;
+    }, dt: number, turnRate?: number): void;
+}
+export {};

package/dist/CharacterController3D.js

@@ -0,0 +1,83 @@
+/**
+ * A kinematic character: walks, collides with walls, climbs steps, falls.
+ *
+ * Rapier ships the hard part (`KinematicCharacterController` with autostep,
+ * ground snapping and slope limits), so this is glue — but glue with one trap
+ * in it, which an independent review hit and documented before I did:
+ *
+ * **Gravity is an acceleration, not a displacement.** Feeding the controller
+ * `-9.81 / 60` each frame asks it to move down at a constant 0.16 m per step,
+ * which looks like falling and is not. It passes a wall test and fails a step
+ * test, because a constant downward push fights autostep every frame. So
+ * vertical velocity accumulates while airborne and resets on landing, and the
+ * grounded state applies only a small downward bias — enough for snap-to-ground
+ * to keep contact on slopes and stairs, not enough to pin the character down.
+ */
+export class CharacterController3D {
+    constructor(world, RAPIER, options = {}) {
+        this.world = world;
+        this.verticalVelocity = 0;
+        this.opts = {
+            halfHeight: options.halfHeight ?? 0.5,
+            radius: options.radius ?? 0.35,
+            speed: options.speed ?? 4,
+            stepHeight: options.stepHeight ?? 0.4,
+            maxSlopeDegrees: options.maxSlopeDegrees ?? 50,
+            gravity: options.gravity ?? 9.81,
+        };
+        const p = options.position ?? { x: 0, y: 2, z: 0 };
+        this.body = world.createRigidBody(RAPIER.RigidBodyDesc.kinematicPositionBased().setTranslation(p.x, p.y, p.z));
+        this.collider = world.createCollider(RAPIER.ColliderDesc.capsule(this.opts.halfHeight, this.opts.radius), this.body);
+        // The offset is the skin the solver keeps between the character and
+        // geometry; too small and it jitters against walls, too large and it floats.
+        this.controller = world.createCharacterController(0.02);
+        this.controller.setUp({ x: 0, y: 1, z: 0 });
+        this.controller.enableAutostep(this.opts.stepHeight, this.opts.radius * 0.5, true);
+        this.controller.enableSnapToGround(this.opts.stepHeight * 0.75);
+        this.controller.setMaxSlopeClimbAngle((this.opts.maxSlopeDegrees * Math.PI) / 180);
+        this.controller.setApplyImpulsesToDynamicBodies(true);
+    }
+    get grounded() { return this.controller.computedGrounded(); }
+    get position() { return this.body.translation(); }
+    /**
+     * Move for one step. `dir` is a desired direction in world space (y ignored);
+     * it is normalised here so diagonals aren't faster than cardinals — a bug old
+     * enough to have a name.
+     */
+    update(dt, dir) {
+        const len = Math.hypot(dir.x, dir.z);
+        const nx = len > 0 ? (dir.x / len) * this.opts.speed * dt : 0;
+        const nz = len > 0 ? (dir.z / len) * this.opts.speed * dt : 0;
+        if (this.grounded) {
+            // Small constant bias, not accumulated gravity: enough for snap-to-ground
+            // to hold contact over stairs and slopes without pinning the character.
+            this.verticalVelocity = -this.opts.gravity * dt;
+        }
+        else {
+            this.verticalVelocity -= this.opts.gravity * dt;
+        }
+        this.controller.computeColliderMovement(this.collider, {
+            x: nx, y: this.verticalVelocity * dt, z: nz,
+        });
+        const move = this.controller.computedMovement();
+        const t = this.body.translation();
+        this.body.setNextKinematicTranslation({ x: t.x + move.x, y: t.y + move.y, z: t.z + move.z });
+    }
+    /** Copy the simulated position onto the rendered object. */
+    syncTo(object, yOffset = 0) {
+        const t = this.body.translation();
+        object.position.set(t.x, t.y + yOffset, t.z);
+    }
+    /** Face the direction of travel; ignores tiny inputs so idle doesn't spin. */
+    faceTowards(object, dir, dt, turnRate = 10) {
+        if (Math.hypot(dir.x, dir.z) < 0.01)
+            return;
+        const want = Math.atan2(dir.x, dir.z);
+        let delta = want - object.rotation.y;
+        while (delta > Math.PI)
+            delta -= Math.PI * 2;
+        while (delta < -Math.PI)
+            delta += Math.PI * 2;
+        object.rotation.y += delta * Math.min(1, turnRate * dt);
+    }
+}

package/dist/Input3D.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Keyboard movement, in the smallest form that is still correct.
+ *
+ * Reads key STATE rather than key events, because an event-driven controller
+ * drops input whenever a frame lands between keydown and the read, and holds a
+ * direction forever if the keyup is lost (alt-tab is the classic way to lose
+ * one). `dispose()` matters: a listener left on window outlives the scene.
+ */
+export declare class Input3D {
+    private readonly target;
+    private readonly held;
+    private readonly onDown;
+    private readonly onUp;
+    private readonly onBlur;
+    constructor(target?: Window);
+    isDown(...codes: string[]): boolean;
+    /** Camera-relative would need the camera; this is world-axis movement. */
+    direction(): {
+        x: number;
+        z: number;
+    };
+    /** Test seam: drive the controller without synthesising DOM events. */
+    press(code: string): void;
+    release(code: string): void;
+    dispose(): void;
+}

package/dist/Input3D.js

@@ -0,0 +1,44 @@
+/**
+ * Keyboard movement, in the smallest form that is still correct.
+ *
+ * Reads key STATE rather than key events, because an event-driven controller
+ * drops input whenever a frame lands between keydown and the read, and holds a
+ * direction forever if the keyup is lost (alt-tab is the classic way to lose
+ * one). `dispose()` matters: a listener left on window outlives the scene.
+ */
+export class Input3D {
+    constructor(target = window) {
+        this.target = target;
+        this.held = new Set();
+        this.onDown = (e) => { this.held.add(e.code); };
+        this.onUp = (e) => { this.held.delete(e.code); };
+        this.onBlur = () => { this.held.clear(); };
+        target.addEventListener('keydown', this.onDown);
+        target.addEventListener('keyup', this.onUp);
+        // Losing focus mid-press would otherwise leave the character walking.
+        target.addEventListener('blur', this.onBlur);
+    }
+    isDown(...codes) { return codes.some((c) => this.held.has(c)); }
+    /** Camera-relative would need the camera; this is world-axis movement. */
+    direction() {
+        let x = 0, z = 0;
+        if (this.isDown('KeyW', 'ArrowUp'))
+            z -= 1;
+        if (this.isDown('KeyS', 'ArrowDown'))
+            z += 1;
+        if (this.isDown('KeyA', 'ArrowLeft'))
+            x -= 1;
+        if (this.isDown('KeyD', 'ArrowRight'))
+            x += 1;
+        return { x, z };
+    }
+    /** Test seam: drive the controller without synthesising DOM events. */
+    press(code) { this.held.add(code); }
+    release(code) { this.held.delete(code); }
+    dispose() {
+        this.target.removeEventListener('keydown', this.onDown);
+        this.target.removeEventListener('keyup', this.onUp);
+        this.target.removeEventListener('blur', this.onBlur);
+        this.held.clear();
+    }
+}

package/dist/SceneLoader3D.d.ts

@@ -0,0 +1,49 @@
+import * as THREE from 'three';
+import { type Scene3D, type Manifest3D } from './scene3d.js';
+export interface LoadSceneOptions {
+    /** Base url assets resolve against (the project's asset host). */
+    assetBase?: string;
+    /** Provide the physics module to get colliders; omit for a render-only load
+     *  (which is what an editor's design view wants — see ADR-021). */
+    rapier?: RapierLike;
+    /** Design view: spawn the authored scene, run no game logic, play no clips. */
+    designMode?: boolean;
+}
+/** The slice of Rapier we use, typed structurally so this module needn't depend on it. */
+export interface RapierLike {
+    World: new (gravity: {
+        x: number;
+        y: number;
+        z: number;
+    }) => any;
+    RigidBodyDesc: any;
+    ColliderDesc: any;
+}
+export interface LoadedScene3D {
+    scene: THREE.Scene;
+    camera: THREE.PerspectiveCamera;
+    /** Entity id → the object spawned for it. The stable handle game code uses. */
+    entities: Map<string, THREE.Object3D>;
+    mixers: THREE.AnimationMixer[];
+    /** Entity id → its mixer, for games that drive clips themselves. */
+    mixerFor: Map<string, THREE.AnimationMixer>;
+    /** Model asset id → every clip that model shipped with. A game switching
+     *  between idle and walk needs the clips, not just the one playing. */
+    clips: Map<string, THREE.AnimationClip[]>;
+    /** Entity id → rigid body, when physics was supplied. */
+    bodies: Map<string, any>;
+    world?: any;
+    /** Advance animation + physics. Call once per frame with seconds. */
+    update(dt: number): void;
+    dispose(): void;
+}
+/**
+ * Turn scene3d design data into a running three.js scene.
+ *
+ * The 2D SDK's `loadWorldScene` → `spawnEntity` path, in three dimensions and
+ * with the same contract: **this reads authored design data and nothing else.**
+ * No save is loaded, no game code runs. That separation is ADR-021's, already
+ * settled and shipped for 2D, and it is the reason an editor can render a scene
+ * without starting a game.
+ */
+export declare function loadScene3D(scene3d: Scene3D, manifest: Manifest3D, opts?: LoadSceneOptions): Promise<LoadedScene3D>;

package/dist/SceneLoader3D.js

@@ -0,0 +1,238 @@
+import * as THREE from 'three';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { validateScene, IDENTITY_QUAT, } from './scene3d.js';
+function toVec(v, d = 0) {
+    return new THREE.Vector3(v?.x ?? d, v?.y ?? d, v?.z ?? d);
+}
+function applyTransform(obj, e) {
+    const t = e.transform;
+    obj.position.copy(toVec(t.position));
+    const q = t.rotation ?? IDENTITY_QUAT;
+    obj.quaternion.set(q[0], q[1], q[2], q[3]);
+    if (typeof t.scale === 'number')
+        obj.scale.setScalar(t.scale);
+    else if (t.scale)
+        obj.scale.copy(toVec(t.scale, 1));
+}
+function makePrimitive(e) {
+    const p = e.primitive;
+    const s = p.size ?? { x: 1, y: 1, z: 1 };
+    const geom = p.kind === 'box' ? new THREE.BoxGeometry(s.x, s.y, s.z)
+        : p.kind === 'sphere' ? new THREE.SphereGeometry(s.x / 2, 24, 16)
+            : p.kind === 'cylinder' ? new THREE.CylinderGeometry(s.x / 2, s.x / 2, s.y, 24)
+                // Lay the plane down by rotating the GEOMETRY, not the object. Rotating the
+                // object is the obvious move and it is wrong: applyTransform sets the
+                // object's quaternion from the entity's authored rotation straight
+                // afterwards, silently discarding it — which left every "ground" standing
+                // upright like a wall. It renders convincingly until the camera crosses to
+                // the far side, at which point the scene becomes a flat fill and every
+                // measurement still says the character is dead centre, because it is —
+                // behind a 40x40 wall.
+                : new THREE.PlaneGeometry(s.x, s.z).rotateX(-Math.PI / 2);
+    const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({
+        color: new THREE.Color(p.color ?? '#c8c8c8'), roughness: 0.85,
+    }));
+    mesh.castShadow = p.kind !== 'plane';
+    mesh.receiveShadow = true;
+    return mesh;
+}
+/**
+ * Turn scene3d design data into a running three.js scene.
+ *
+ * The 2D SDK's `loadWorldScene` → `spawnEntity` path, in three dimensions and
+ * with the same contract: **this reads authored design data and nothing else.**
+ * No save is loaded, no game code runs. That separation is ADR-021's, already
+ * settled and shipped for 2D, and it is the reason an editor can render a scene
+ * without starting a game.
+ */
+export async function loadScene3D(scene3d, manifest, opts = {}) {
+    const problems = validateScene(scene3d);
+    if (problems.length) {
+        // Loudly, at load. A scene with a dangling parent or a duplicate id fails
+        // as a blank screen an hour later otherwise.
+        throw new Error(`scene3d '${scene3d.id}' is invalid:\n  - ${problems.join('\n  - ')}`);
+    }
+    const scene = new THREE.Scene();
+    if (scene3d.environment?.background)
+        scene.background = new THREE.Color(scene3d.environment.background);
+    if (scene3d.environment?.fog) {
+        const f = scene3d.environment.fog;
+        scene.fog = new THREE.Fog(new THREE.Color(f.color), f.near, f.far);
+    }
+    for (const l of scene3d.lights ?? []) {
+        const colour = new THREE.Color(l.color ?? '#ffffff');
+        const light = l.kind === 'directional' ? new THREE.DirectionalLight(colour, l.intensity ?? 1)
+            : l.kind === 'hemisphere' ? new THREE.HemisphereLight(colour, new THREE.Color(l.groundColor ?? '#444444'), l.intensity ?? 1)
+                : l.kind === 'point' ? new THREE.PointLight(colour, l.intensity ?? 1)
+                    : new THREE.AmbientLight(colour, l.intensity ?? 1);
+        if (l.position && 'position' in light)
+            light.position.copy(toVec(l.position));
+        if (l.castShadow && 'castShadow' in light)
+            light.castShadow = true;
+        light.name = l.id;
+        scene.add(light);
+    }
+    // Load each referenced model ONCE and clone per entity. Two entities sharing
+    // a model must not download it twice.
+    const models = new Map((manifest.models ?? []).map((m) => [m.id, m]));
+    const needed = new Set(scene3d.entities.map((e) => e.modelAssetId).filter(Boolean));
+    const loaded = new Map();
+    if (needed.size) {
+        const loader = new GLTFLoader();
+        await Promise.all([...needed].map(async (id) => {
+            const asset = models.get(id);
+            if (!asset)
+                throw new Error(`scene3d references model '${id}', which the manifest does not define`);
+            const url = (opts.assetBase ?? '') + asset.path;
+            loaded.set(id, await loader.loadAsync(url));
+        }));
+    }
+    const entities = new Map();
+    const mixers = [];
+    const mixerFor = new Map();
+    const clips = new Map();
+    for (const [id, gltf] of loaded)
+        clips.set(id, gltf.animations);
+    for (const e of scene3d.entities) {
+        let obj;
+        if (e.modelAssetId) {
+            const gltf = loaded.get(e.modelAssetId);
+            const asset = models.get(e.modelAssetId);
+            // SkeletonUtils.clone would be needed for skinned meshes sharing a model;
+            // a single instance per asset is the case the slice covers, so clone only
+            // when a second entity wants the same asset.
+            const used = [...entities.values()].some((o) => o.userData.modelAssetId === e.modelAssetId);
+            obj = used ? gltf.scene.clone(true) : gltf.scene;
+            obj.userData.modelAssetId = e.modelAssetId;
+            if (asset.importScale)
+                obj.scale.setScalar(asset.importScale);
+            obj.traverse((o) => {
+                const mesh = o;
+                if (!mesh.isMesh)
+                    return;
+                mesh.castShadow = true;
+                mesh.receiveShadow = true;
+                // A SkinnedMesh's bounding sphere is computed from the BIND pose and
+                // does not follow the bones. Once the object moves, three.js culls it
+                // against a stale volume and the character vanishes — at exactly the
+                // moment it starts walking, which is the worst possible time and reads
+                // as "the model disappeared" rather than "culling is wrong". Cost is
+                // one extra draw call per character; the alternative is recomputing the
+                // bounds every frame.
+                if (mesh.isSkinnedMesh)
+                    mesh.frustumCulled = false;
+            });
+            if (!opts.designMode && e.animation?.play && gltf.animations.length) {
+                const clipName = asset.animations?.[e.animation.play] ?? e.animation.play;
+                const clip = gltf.animations.find((c) => c.name === clipName);
+                if (!clip) {
+                    // Say which names exist. "Walk not found" with no list is the single
+                    // most annoying asset error there is.
+                    throw new Error(`entity '${e.id}' wants clip '${e.animation.play}' → '${clipName}', but ` +
+                        `model '${e.modelAssetId}' has: ${gltf.animations.map((c) => c.name).join(', ') || '(none)'}`);
+                }
+                const mixer = new THREE.AnimationMixer(obj);
+                const action = mixer.clipAction(clip);
+                action.setLoop(e.animation.loop === false ? THREE.LoopOnce : THREE.LoopRepeat, Infinity);
+                action.play();
+                mixers.push(mixer);
+                mixerFor.set(e.id, mixer);
+            }
+        }
+        else {
+            obj = makePrimitive(e);
+        }
+        obj.name = e.name ?? e.id;
+        obj.userData.entityId = e.id;
+        if (e.properties)
+            obj.userData.properties = e.properties;
+        if (e.visible === false)
+            obj.visible = false;
+        applyTransform(obj, e);
+        entities.set(e.id, obj);
+    }
+    // Parent after every entity exists, so declaration order doesn't matter.
+    for (const e of scene3d.entities) {
+        const obj = entities.get(e.id);
+        if (e.parent)
+            entities.get(e.parent).add(obj);
+        else
+            scene.add(obj);
+    }
+    // Physics, when asked for. A design-time load skips it entirely.
+    const bodies = new Map();
+    let world;
+    if (opts.rapier && !opts.designMode) {
+        const g = scene3d.gravity ?? { x: 0, y: -9.81, z: 0 };
+        world = new opts.rapier.World(g);
+        for (const e of scene3d.entities) {
+            if (!e.collider)
+                continue;
+            const R = opts.rapier;
+            const p = e.transform.position;
+            const off = e.collider.offset ?? { x: 0, y: 0, z: 0 };
+            const desc = e.collider.body === 'fixed' ? R.RigidBodyDesc.fixed()
+                : e.collider.body === 'kinematic' ? R.RigidBodyDesc.kinematicPositionBased()
+                    : R.RigidBodyDesc.dynamic();
+            desc.setTranslation(p.x + off.x, p.y + off.y, p.z + off.z);
+            const q = e.transform.rotation ?? IDENTITY_QUAT;
+            desc.setRotation({ x: q[0], y: q[1], z: q[2], w: q[3] });
+            const body = world.createRigidBody(desc);
+            const s = e.collider.shape;
+            const shape = s.kind === 'box' ? R.ColliderDesc.cuboid(s.halfExtents.x, s.halfExtents.y, s.halfExtents.z)
+                : s.kind === 'sphere' ? R.ColliderDesc.ball(s.radius)
+                    : s.kind === 'capsule' ? R.ColliderDesc.capsule(s.halfHeight, s.radius)
+                        : null;
+            if (!shape)
+                throw new Error(`entity '${e.id}': trimesh colliders are not supported yet`);
+            world.createCollider(shape, body);
+            bodies.set(e.id, body);
+        }
+    }
+    const camera = new THREE.PerspectiveCamera(scene3d.camera?.fov ?? 55, 1, 0.1, 500);
+    const camOffset = toVec(scene3d.camera?.offset ?? { x: 0, y: 4, z: 8 });
+    camera.position.copy(camOffset);
+    const followTarget = scene3d.camera?.kind === 'follow' && scene3d.camera.target
+        ? entities.get(scene3d.camera.target) : undefined;
+    return {
+        scene, camera, entities, mixers, mixerFor, clips, bodies, world,
+        update(dt) {
+            for (const m of mixers)
+                m.update(dt);
+            if (world) {
+                world.step();
+                // Dynamic bodies drive their objects; fixed ones never move, and a
+                // kinematic body is driven BY the game, so neither is read back.
+                for (const [id, body] of bodies) {
+                    const e = scene3d.entities.find((x) => x.id === id);
+                    if (e.collider?.body !== 'dynamic')
+                        continue;
+                    const obj = entities.get(id);
+                    const t = body.translation();
+                    const r = body.rotation();
+                    obj.position.set(t.x, t.y, t.z);
+                    obj.quaternion.set(r.x, r.y, r.z, r.w);
+                }
+            }
+            if (followTarget) {
+                const want = followTarget.position.clone().add(camOffset);
+                camera.position.lerp(want, Math.min(1, dt * 6));
+                camera.lookAt(followTarget.position.x, followTarget.position.y + 1, followTarget.position.z);
+            }
+        },
+        dispose() {
+            for (const m of mixers)
+                m.stopAllAction();
+            scene.traverse((o) => {
+                const mesh = o;
+                if (mesh.geometry)
+                    mesh.geometry.dispose();
+                const mat = mesh.material;
+                if (Array.isArray(mat))
+                    mat.forEach((m) => m.dispose());
+                else
+                    mat?.dispose();
+            });
+        },
+    };
+}

package/dist/ThreeUmicat.d.ts

@@ -0,0 +1,23 @@
+import { UmicatCore } from '@umicat/platform-sdk/core/UmicatCore.js';
+import type { UmicatInitOptions } from '@umicat/platform-sdk/core/UmicatCore.js';
+import { DialogueModule } from '@umicat/platform-sdk/dialogue/DialogueModule.js';
+export type { UmicatInitOptions };
+/**
+ * Umicat platform services for a three.js game.
+ *
+ * The entire point of ADR-033's extraction: identity, cloud saves, shared game
+ * data, multiplayer, runtime AI and voice arrive here **unchanged** from
+ * `@umicat/platform-sdk` — the same code paths a Phaser game uses, talking the same
+ * protocol to the same host. This class exists only to add what needs a
+ * renderer, and to report its own version in the handshake.
+ *
+ * Dialogue starts with no default renderer. A three.js game supplies one (DOM
+ * overlay or in-scene), or passes `opts.renderer` per call; there is no
+ * built-in box yet, and pretending otherwise would ship a broken default.
+ */
+export declare class ThreeUmicat extends UmicatCore {
+    /** Scripted (authored, non-AI) dialogue. Supply a renderer when playing. */
+    readonly dialogue: DialogueModule<unknown, unknown>;
+    private constructor();
+    static init(options?: UmicatInitOptions): Promise<ThreeUmicat>;
+}

package/dist/ThreeUmicat.js

@@ -0,0 +1,26 @@
+import { UmicatCore } from '@umicat/platform-sdk/core/UmicatCore.js';
+import { DialogueModule } from '@umicat/platform-sdk/dialogue/DialogueModule.js';
+/** Kept in sync with package.json on each publish. */
+const SDK_VERSION = '0.0.1';
+/**
+ * Umicat platform services for a three.js game.
+ *
+ * The entire point of ADR-033's extraction: identity, cloud saves, shared game
+ * data, multiplayer, runtime AI and voice arrive here **unchanged** from
+ * `@umicat/platform-sdk` — the same code paths a Phaser game uses, talking the same
+ * protocol to the same host. This class exists only to add what needs a
+ * renderer, and to report its own version in the handshake.
+ *
+ * Dialogue starts with no default renderer. A three.js game supplies one (DOM
+ * overlay or in-scene), or passes `opts.renderer` per call; there is no
+ * built-in box yet, and pretending otherwise would ship a broken default.
+ */
+export class ThreeUmicat extends UmicatCore {
+    constructor(transport) {
+        super(transport);
+        this.dialogue = new DialogueModule(this.saves, () => transport.locale ?? 'en', () => transport.user?.name ?? null);
+    }
+    static async init(options = {}) {
+        return new ThreeUmicat(await UmicatCore.connect(SDK_VERSION, options));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { ThreeUmicat } from './ThreeUmicat.js';
+export type { UmicatInitOptions } from './ThreeUmicat.js';
+export * from './scene3d.js';
+export { loadScene3D } from './SceneLoader3D.js';
+export { CharacterController3D } from './CharacterController3D.js';
+export type { CharacterOptions } from './CharacterController3D.js';
+export { Input3D } from './Input3D.js';
+export type { LoadedScene3D, LoadSceneOptions } from './SceneLoader3D.js';
+export { ORIENTATION_DIMENSIONS } from '@umicat/platform-sdk/orientation.js';
+export type { Orientation } from '@umicat/platform-sdk/orientation.js';
+export { RpcError } from '@umicat/platform-sdk/core/Transport.js';
+export type { UmicatUser } from '@umicat/platform-sdk/protocol.js';

package/dist/index.js

@@ -0,0 +1,15 @@
+// @umicat/three-sdk — the three.js runtime for Umicat games.
+//
+// Platform services come from @umicat/platform-sdk untouched. What lives here is
+// the engine layer ADR-033 says we own: the scene3d design format, the loader
+// that turns it into a three.js scene with physics, and the runtime glue.
+export { ThreeUmicat } from './ThreeUmicat.js';
+export * from './scene3d.js';
+export { loadScene3D } from './SceneLoader3D.js';
+export { CharacterController3D } from './CharacterController3D.js';
+export { Input3D } from './Input3D.js';
+// Re-exported so a game imports one package for the common case. A game should
+// not have to know that identity and saves come from a different package than
+// the renderer.
+export { ORIENTATION_DIMENSIONS } from '@umicat/platform-sdk/orientation.js';
+export { RpcError } from '@umicat/platform-sdk/core/Transport.js';

package/dist/scene3d.d.ts

@@ -0,0 +1,152 @@
+/**
+ * The `scene3d` design-data format.
+ *
+ * ADR-021 settled *what* the editor edits — design data on disk, no save loaded
+ * — and that answer is engine-neutral, so this format inherits it directly. What
+ * it does NOT inherit is the 2D schema: an independent review was right that
+ * `{x, y, rotation, scaleX, scaleY, depth}` does not survive the jump. Three
+ * dimensions need rotation that composes without gimbal problems, a parent
+ * hierarchy, materials that can be shared, and colliders that are authored
+ * rather than derived.
+ *
+ * Design rules, each of which is a decision rather than an accident:
+ *
+ * - **Rotation is a quaternion.** Euler angles are order-dependent and
+ *   interpolate badly; an editor that round-trips them will drift.
+ * - **Ids are stable and authored.** The editor, the runtime and the save file
+ *   all refer to entities by id, so regenerating them on load would break every
+ *   reference the moment a scene is edited.
+ * - **Transforms are local, relative to `parent`.** World transforms are derived.
+ *   Storing world transforms makes reparenting a lie.
+ * - **Assets are referenced by id, never by path.** Paths change when an asset
+ *   is re-imported or re-hosted; the manifest owns the mapping.
+ * - **Colliders are explicit.** Using a render mesh as a dynamic collider is the
+ *   classic way to make a game that is correct and unplayably slow.
+ */
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/** `[x, y, z, w]` — a unit quaternion. */
+export type Quat = [number, number, number, number];
+export interface Transform3D {
+    position: Vec3;
+    /** Defaults to identity when absent. */
+    rotation?: Quat;
+    /** Uniform or per-axis; defaults to 1. */
+    scale?: number | Vec3;
+}
+export type ColliderShape = {
+    kind: 'box';
+    halfExtents: Vec3;
+} | {
+    kind: 'sphere';
+    radius: number;
+} | {
+    kind: 'capsule';
+    halfHeight: number;
+    radius: number;
+}
+/** Static geometry only. Never use this for a dynamic body. */
+ | {
+    kind: 'trimesh';
+};
+export interface Collider3D {
+    shape: ColliderShape;
+    /** `fixed` walls and ground, `dynamic` props, `kinematic` things the game moves. */
+    body: 'fixed' | 'dynamic' | 'kinematic';
+    /** Offset from the entity's own origin. */
+    offset?: Vec3;
+}
+export interface Entity3D {
+    /** Stable, authored, unique within the scene. */
+    id: string;
+    name?: string;
+    /** Id of another entity in this scene; the transform is relative to it. */
+    parent?: string;
+    transform: Transform3D;
+    /** Manifest asset id for a glTF model. */
+    modelAssetId?: string;
+    /** A built-in shape, for blocking out a scene before art exists. */
+    primitive?: {
+        kind: 'box' | 'sphere' | 'plane' | 'cylinder';
+        size?: Vec3;
+        color?: string;
+    };
+    collider?: Collider3D;
+    /** Which clip to play on spawn, by SEMANTIC name — see `AnimationMap`. */
+    animation?: {
+        play?: string;
+        loop?: boolean;
+    };
+    /** Free-form, read by game code. The 2D SDK's `properties` equivalent. */
+    properties?: Record<string, unknown>;
+    visible?: boolean;
+}
+/**
+ * Semantic clip name → the clip actually inside the model.
+ *
+ * Authored per asset, never guessed. The review's cross-rig retarget experiment
+ * returned a clip with zero matched bones and zero tracks, and assuming every
+ * model calls its walk cycle `Walk` fails the same way, only more quietly.
+ */
+export type AnimationMap = Record<string, string>;
+export interface ModelAsset3D {
+    id: string;
+    /** Resolved by the runtime against the project's asset base url. */
+    path: string;
+    animations?: AnimationMap;
+    /** Authoring correction applied at load: most models are not born 1 unit tall. */
+    importScale?: number;
+}
+export interface Light3D {
+    id: string;
+    kind: 'directional' | 'hemisphere' | 'ambient' | 'point';
+    color?: string;
+    /** Second colour for `hemisphere` (the ground half). */
+    groundColor?: string;
+    intensity?: number;
+    position?: Vec3;
+    castShadow?: boolean;
+}
+export interface Scene3D {
+    schemaVersion: 1;
+    id: string;
+    name?: string;
+    environment?: {
+        background?: string;
+        fog?: {
+            color: string;
+            near: number;
+            far: number;
+        };
+    };
+    gravity?: Vec3;
+    lights?: Light3D[];
+    entities: Entity3D[];
+    camera?: {
+        kind: 'follow' | 'fixed';
+        /** Entity id to follow, for `follow`. */
+        target?: string;
+        offset?: Vec3;
+        fov?: number;
+    };
+}
+export interface Manifest3D {
+    schemaVersion: 1;
+    initialScene: string;
+    scenes: {
+        id: string;
+        file: string;
+    }[];
+    models?: ModelAsset3D[];
+}
+/** Identity quaternion, spelled out so callers don't have to remember the order. */
+export declare const IDENTITY_QUAT: Quat;
+export declare function vec3(x?: number, y?: number, z?: number): Vec3;
+/**
+ * Validate a scene enough to fail loudly at author time rather than as a blank
+ * screen at play time. Returns the problems; empty means usable.
+ */
+export declare function validateScene(scene: Scene3D): string[];

package/dist/scene3d.js

@@ -0,0 +1,62 @@
+/**
+ * The `scene3d` design-data format.
+ *
+ * ADR-021 settled *what* the editor edits — design data on disk, no save loaded
+ * — and that answer is engine-neutral, so this format inherits it directly. What
+ * it does NOT inherit is the 2D schema: an independent review was right that
+ * `{x, y, rotation, scaleX, scaleY, depth}` does not survive the jump. Three
+ * dimensions need rotation that composes without gimbal problems, a parent
+ * hierarchy, materials that can be shared, and colliders that are authored
+ * rather than derived.
+ *
+ * Design rules, each of which is a decision rather than an accident:
+ *
+ * - **Rotation is a quaternion.** Euler angles are order-dependent and
+ *   interpolate badly; an editor that round-trips them will drift.
+ * - **Ids are stable and authored.** The editor, the runtime and the save file
+ *   all refer to entities by id, so regenerating them on load would break every
+ *   reference the moment a scene is edited.
+ * - **Transforms are local, relative to `parent`.** World transforms are derived.
+ *   Storing world transforms makes reparenting a lie.
+ * - **Assets are referenced by id, never by path.** Paths change when an asset
+ *   is re-imported or re-hosted; the manifest owns the mapping.
+ * - **Colliders are explicit.** Using a render mesh as a dynamic collider is the
+ *   classic way to make a game that is correct and unplayably slow.
+ */
+/** Identity quaternion, spelled out so callers don't have to remember the order. */
+export const IDENTITY_QUAT = [0, 0, 0, 1];
+export function vec3(x = 0, y = 0, z = 0) { return { x, y, z }; }
+/**
+ * Validate a scene enough to fail loudly at author time rather than as a blank
+ * screen at play time. Returns the problems; empty means usable.
+ */
+export function validateScene(scene) {
+    const problems = [];
+    if (scene.schemaVersion !== 1)
+        problems.push(`unknown schemaVersion ${scene.schemaVersion}`);
+    const ids = new Set();
+    for (const e of scene.entities ?? []) {
+        if (!e.id)
+            problems.push('an entity has no id');
+        else if (ids.has(e.id))
+            problems.push(`duplicate entity id '${e.id}'`);
+        ids.add(e.id);
+        if (!e.modelAssetId && !e.primitive) {
+            problems.push(`entity '${e.id}' has neither a model nor a primitive — it would render nothing`);
+        }
+        if (e.collider?.body === 'dynamic' && e.collider.shape.kind === 'trimesh') {
+            problems.push(`entity '${e.id}' uses a trimesh collider on a dynamic body; use a convex shape`);
+        }
+        if (e.transform?.rotation && e.transform.rotation.length !== 4) {
+            problems.push(`entity '${e.id}' rotation must be a quaternion [x,y,z,w]`);
+        }
+    }
+    for (const e of scene.entities ?? []) {
+        if (e.parent && !ids.has(e.parent))
+            problems.push(`entity '${e.id}' parents to missing '${e.parent}'`);
+    }
+    if (scene.camera?.kind === 'follow' && scene.camera.target && !ids.has(scene.camera.target)) {
+        problems.push(`camera follows missing entity '${scene.camera.target}'`);
+    }
+    return problems;
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@umicat/three-sdk",
+  "version": "0.1.0",
+  "description": "Three.js runtime for Umicat games: the scene3d design format, its loader with physics, a kinematic character controller, and the Umicat platform via @umicat/platform-sdk.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && npm run build:example && node --test scripts/*.test.mjs",
+    "build:example": "../umicat-template/node_modules/esbuild/bin/esbuild example/src/main.js --bundle --format=esm --outfile=example/public/game.js --alias:@umicat/three-sdk=./dist/index.js --log-level=warning"
+  },
+  "dependencies": {
+    "@dimforge/rapier3d-compat": "^0.14.0",
+    "three": "0.186.0",
+    "@umicat/platform-sdk": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/three": "^0.185.4",
+    "typescript": "^5.3.3"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}