@umicat/three-sdk 0.19.0 → 0.21.0

package/README.md

@@ -24,7 +24,8 @@ editor.
         │
 @umicat/three-sdk       ThreeUmicat · scene3d · loadScene3D · physics · Input3D
                         CharacterController3D · CharacterAnimator · GameAudio
-                        sockets · tints · setupScreenshotListener/setupRecordingListener
+                        sockets · skins · attachments · tints
+                        setupScreenshotListener/setupRecordingListener
         ▲
    your game            gameplay
 ```
@@ -73,6 +74,11 @@ Each rule is a decision:
   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.
+- **What a character wears is authored on the entity**
+  (`attachments: [{ modelAssetId: 'sword' }]`). Because the character already
+  says where its sockets are and the prop already says which one it belongs in,
+  naming the prop is the whole declaration — a knight in armour is data, not
+  equip code written once per game.
 - **A prop declares which socket it belongs in** (`socket: 'hand-right'` on the
   sword, `sockets: { 'hand-right': {...} }` on the character). Both halves are
   properties of the MODEL, not of any game — a cap goes on a head in every game

package/dist/Attachments.d.ts

@@ -0,0 +1,38 @@
+import * as THREE from 'three';
+import type { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import type { Attachment3D, Manifest3D, ModelAsset3D } from './scene3d.js';
+/**
+ * Put the props a character is wearing on it, and take off whatever it was
+ * wearing before.
+ *
+ * **Whole-list, not incremental.** `applyAttachments(hero, …, [])` strips the
+ * character; passing a list makes it wear exactly that list. Idempotent, which
+ * is what both callers actually want: `loadScene3D` builds a character once,
+ * and an editor re-applies the list every time a person changes a dropdown. An
+ * add/remove API would make "what is this character wearing" a thing you have
+ * to replay history to answer.
+ *
+ * Which socket a prop goes in is resolved from the prop itself
+ * (`ModelAsset3D.socket`) unless the attachment overrides it — the character
+ * already declares where its sockets ARE, so naming the prop is normally the
+ * whole instruction.
+ */
+/** What a wearer currently has on: attachment id (or socket) → the object. */
+export type WornMap = Map<string, THREE.Object3D>;
+export interface ApplyAttachmentsOptions {
+    /** Base url props resolve against. */
+    assetBase?: string;
+    /**
+     * Already-fetched props, keyed by model id. `loadScene3D` passes the batch
+     * it downloaded in parallel; anyone else can leave it out and have them
+     * fetched here.
+     */
+    preloaded?: Map<string, GLTF>;
+    /** What this wearer has on now, so it can be taken off first. */
+    previous?: WornMap;
+    /** Names the wearer in error messages — an entity id, usually. */
+    label?: string;
+}
+/** Drop the prop cache. For a game unloading a level, and for tests. */
+export declare function clearAttachmentCache(): void;
+export declare function applyAttachments(wearer: THREE.Object3D, wearerAsset: ModelAsset3D, manifest: Manifest3D, list: Attachment3D[], opts?: ApplyAttachmentsOptions): Promise<WornMap>;

package/dist/Attachments.js

@@ -0,0 +1,77 @@
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { clone as cloneRigged } from 'three/examples/jsm/utils/SkeletonUtils.js';
+import { attachToSocket } from './Sockets.js';
+const cache = new Map();
+let loader = null;
+function fetchProp(url) {
+    const hit = cache.get(url);
+    if (hit)
+        return hit;
+    loader ?? (loader = new GLTFLoader());
+    const p = loader.loadAsync(url);
+    cache.set(url, p);
+    // A prop that 404s once must not 404 for the rest of the session.
+    p.catch(() => cache.delete(url));
+    return p;
+}
+/** Drop the prop cache. For a game unloading a level, and for tests. */
+export function clearAttachmentCache() { cache.clear(); }
+function isRigged(root) {
+    let rigged = false;
+    root.traverse((o) => { if (o.isSkinnedMesh)
+        rigged = true; });
+    return rigged;
+}
+/**
+ * Take one prop back off.
+ *
+ * The object's parent is the HOLDER `attachToSocket` created to carry the
+ * socket offset, and that is what has to go — removing the object alone
+ * leaves an empty holder on the bone, and enough dressing changes leave a
+ * character wearing a stack of invisible ones.
+ */
+function detach(object) {
+    (object.parent ?? object).removeFromParent();
+}
+export async function applyAttachments(wearer, wearerAsset, manifest, list, opts = {}) {
+    const who = opts.label ? `entity '${opts.label}'` : `model '${wearerAsset.id}'`;
+    const models = new Map((manifest.models ?? []).map((m) => [m.id, m]));
+    // Resolve the whole list BEFORE touching the character. A bad prop halfway
+    // down otherwise leaves it half-dressed, which is worse than unchanged.
+    const resolved = [];
+    for (const a of list) {
+        const prop = models.get(a.modelAssetId);
+        if (!prop) {
+            throw new Error(`${who} attaches model '${a.modelAssetId}', which the manifest does not define. ` +
+                `It has: ${[...models.keys()].join(', ') || '(none)'}`);
+        }
+        const socketName = a.socket ?? prop.socket;
+        if (!socketName) {
+            throw new Error(`${who} attaches '${a.modelAssetId}' with no socket, and that model declares none of ` +
+                `its own — give the attachment a 'socket', or the model one`);
+        }
+        const socket = wearerAsset.sockets?.[socketName];
+        if (!socket) {
+            throw new Error(`${who} wants socket '${socketName}' for '${a.modelAssetId}', but model ` +
+                `'${wearerAsset.id}' has: ${Object.keys(wearerAsset.sockets ?? {}).join(', ') || '(none)'}`);
+        }
+        resolved.push({ key: a.id ?? socketName, name: a.id ?? prop.id, prop, socket });
+    }
+    const gltfs = await Promise.all(resolved.map(({ prop }) => opts.preloaded?.get(prop.id) ?? fetchProp((opts.assetBase ?? '') + prop.path)));
+    for (const object of opts.previous?.values() ?? [])
+        detach(object);
+    const worn = new Map();
+    resolved.forEach(({ key, name, prop, socket }, i) => {
+        const gltf = gltfs[i];
+        // Always a clone: one prop asset can be worn by a whole squad, and the
+        // first wearer must not end up holding everyone's sword.
+        const object = isRigged(gltf.scene) ? cloneRigged(gltf.scene) : gltf.scene.clone(true);
+        if (prop.importScale !== undefined)
+            object.scale.setScalar(prop.importScale);
+        object.userData.modelAssetId = prop.id;
+        object.name = name;
+        attachToSocket(wearer, socket, object);
+        worn.set(key, object);
+    });
+    return worn;
+}

package/dist/SceneLoader3D.d.ts

@@ -1,5 +1,6 @@
 import * as THREE from 'three';
 import { type Scene3D, type Manifest3D } from './scene3d.js';
+import { type WornMap } from './Attachments.js';
 export interface LoadSceneOptions {
     /** Base url assets resolve against (the project's asset host). */
     assetBase?: string;
@@ -30,6 +31,9 @@ export interface LoadedScene3D {
     /** 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 → its props, keyed by the attachment's `id` or, failing that,
+     *  the socket it went into. How a game reaches the sword it authored. */
+    attachments: Map<string, WornMap>;
     /** Entity id → rigid body, when physics was supplied. */
     bodies: Map<string, any>;
     world?: any;

package/dist/SceneLoader3D.js

@@ -3,6 +3,7 @@ import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
 import { clone as cloneRigged } from 'three/examples/jsm/utils/SkeletonUtils.js';
 import { validateScene, IDENTITY_QUAT, } from './scene3d.js';
 import { applySkin } from './Skin.js';
+import { applyAttachments } from './Attachments.js';
 function toVec(v, d = 0) {
     return new THREE.Vector3(v?.x ?? d, v?.y ?? d, v?.z ?? d);
 }
@@ -115,6 +116,20 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
     // 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));
+    // Props are referenced only from `attachments`, so a set built from
+    // `modelAssetId` alone leaves every sword unfetched and every attachment
+    // silently empty-handed.
+    for (const e of scene3d.entities) {
+        for (const a of e.attachments ?? []) {
+            // Checked HERE rather than at attach time so the message can name the
+            // wearer: the generic prefetch error fires first and only knows the id.
+            if (!models.has(a.modelAssetId)) {
+                throw new Error(`entity '${e.id}' attaches model '${a.modelAssetId}', which the manifest does not define. ` +
+                    `It has: ${[...models.keys()].join(', ') || '(none)'}`);
+            }
+            needed.add(a.modelAssetId);
+        }
+    }
     const loaded = new Map();
     if (needed.size) {
         const loader = new GLTFLoader();
@@ -136,6 +151,8 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
     // a caller that awaits `loadScene3D` gets a scene that is finished — not one
     // whose cast pops from placeholder to costume a frame or two later.
     const skinJobs = [];
+    const attachments = new Map();
+    const attachJobs = [];
     for (const e of scene3d.entities) {
         let obj;
         if (e.modelAssetId) {
@@ -209,8 +226,19 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
                     }
                 }));
             }
+            if (e.attachments?.length) {
+                // Deferred with the skins: both fetch, and a caller that awaits
+                // `loadScene3D` should get a scene that is finished rather than one
+                // that arms itself a frame later.
+                const wearer = obj;
+                attachJobs.push(applyAttachments(wearer, asset, manifest, e.attachments, { assetBase: opts.assetBase, preloaded: loaded, label: e.id })
+                    .then((worn) => { attachments.set(e.id, worn); }));
+            }
         }
         else {
+            if (e.attachments?.length) {
+                throw new Error(`entity '${e.id}' has attachments but no model to hang them on`);
+            }
             obj = makePrimitive(e);
         }
         obj.name = e.name ?? e.id;
@@ -222,8 +250,8 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
         applyTransform(obj, e);
         entities.set(e.id, obj);
     }
-    if (skinJobs.length)
-        await Promise.all(skinJobs);
+    if (skinJobs.length || attachJobs.length)
+        await Promise.all([...skinJobs, ...attachJobs]);
     // Parent after every entity exists, so declaration order doesn't matter.
     for (const e of scene3d.entities) {
         const obj = entities.get(e.id);
@@ -345,7 +373,7 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
         ? entities.get(scene3d.camera.target) : undefined;
     const want = new THREE.Vector3();
     return {
-        scene, camera, entities, mixers, mixerFor, clips, bodies, world,
+        scene, camera, entities, mixers, mixerFor, clips, attachments, bodies, world,
         get cameraYaw() { return camYaw; },
         get cameraPitch() { return camPitch; },
         orbit(dYaw, dPitch) {

package/dist/editor/EditorDesignPlayer3D.js

@@ -2,6 +2,7 @@ import * as THREE from 'three';
 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
 import { loadScene3D } from '../SceneLoader3D.js';
 import { applySkin } from '../Skin.js';
+import { applyAttachments } from '../Attachments.js';
 /**
  * The 3D counterpart of `@umicat/phaser-sdk`'s `EditorDesignScene` (ADR-021)
  * — renders a scene's AUTHORED data with no game code and no save, so the
@@ -77,6 +78,9 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
     const objectByEntity = new Map();
     let manifest = null;
     let sceneData = null;
+    // What each entity is wearing right now, so a re-dress can take the old
+    // set off. `loadScene3D` hands this over; every patch replaces an entry.
+    let worn = new Map();
     const resize = () => {
         renderer.setSize(window.innerWidth, window.innerHeight);
         camera.aspect = window.innerWidth / window.innerHeight;
@@ -264,6 +268,21 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
         const object = objectByEntity.get(m.entityId);
         if (!object)
             return done(`no entity '${m.entityId}' in the scene being shown`);
+        if (m.patch?.attachments !== undefined) {
+            const authored = sceneData?.entities.find((e) => e.id === m.entityId);
+            const asset = manifest?.models?.find((x) => x.id === authored?.modelAssetId);
+            if (!asset)
+                return done(`entity '${m.entityId}' has no model to hang props on`);
+            try {
+                // Whole-list, so the panel can say "this is the outfit" rather than
+                // having to work out a diff against what is already on.
+                const next = await applyAttachments(object, asset, manifest, m.patch.attachments, { assetBase: '', previous: worn.get(m.entityId), label: m.entityId });
+                worn.set(m.entityId, next);
+            }
+            catch (e) {
+                return done(e instanceof Error ? e.message : String(e));
+            }
+        }
         if (m.patch?.skin !== undefined) {
             const authored = sceneData?.entities.find((e) => e.id === m.entityId);
             const asset = manifest?.models?.find((x) => x.id === authored?.modelAssetId);
@@ -322,6 +341,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
         manifest = await fetch('scenes3d/manifest.json').then((r) => r.json());
         sceneData = await fetch(`scenes3d/${sceneId}.json`).then((r) => r.json());
         const loaded = await loadScene3D(sceneData, manifest, { assetBase: '', designMode: true });
+        worn = loaded.attachments;
         scene = loaded.scene;
         entityByObject.clear();
         objectByEntity.clear();

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export type { Input3DOptions, Input3DAction } from './Input3D.js';
 export { attachToSocket, findBone, boneNames } from './Sockets.js';
 export { flashTint, updateTints, isTinted } from './Tint.js';
 export { applySkin, applySkinTexture, loadSkinTexture, clearSkinCache } from './Skin.js';
+export { applyAttachments, clearAttachmentCache } from './Attachments.js';
+export type { WornMap, ApplyAttachmentsOptions } from './Attachments.js';
 export type { SkinOptions, SkinResult } from './Skin.js';
 export { GameAudio } from './GameAudio.js';
 export type { GameAudioOptions, AudioClipSpec } from './GameAudio.js';

package/dist/index.js

@@ -12,6 +12,7 @@ export { Input3D } from './Input3D.js';
 export { attachToSocket, findBone, boneNames } from './Sockets.js';
 export { flashTint, updateTints, isTinted } from './Tint.js';
 export { applySkin, applySkinTexture, loadSkinTexture, clearSkinCache } from './Skin.js';
+export { applyAttachments, clearAttachmentCache } from './Attachments.js';
 export { GameAudio } from './GameAudio.js';
 export { setupScreenshotListener, takeScreenshot } from './capture/ScreenshotManager.js';
 export { setupRecordingListener } from './capture/RecordingManager.js';

package/dist/scene3d.d.ts

@@ -59,6 +59,27 @@ export interface Collider3D {
     /** Offset from the entity's own origin. */
     offset?: Vec3;
 }
+/**
+ * Something this entity wears or carries.
+ *
+ * The pairing that makes this short is already in the manifest from both ends
+ * — the character says where its sockets are, the prop says which one it
+ * belongs in — so `{ modelAssetId: 'sword' }` is usually the whole thing. A
+ * knight in armour becomes authored data rather than equip code written per
+ * game, which is the same reason `skin` and `animation.play` are data.
+ */
+export interface Attachment3D {
+    /** Manifest id of the prop. */
+    modelAssetId: string;
+    /**
+     * Which of the wearer's sockets. Omit to use the prop's own declared
+     * `socket` — override only to put something where it does not normally go
+     * (a shield strapped to the back, a torch in the off hand).
+     */
+    socket?: string;
+    /** Optional name, so game code can find this one again to swap or drop it. */
+    id?: string;
+}
 export interface Entity3D {
     /** Stable, authored, unique within the scene. */
     id: string;
@@ -83,6 +104,8 @@ export interface Entity3D {
     /** Which skin to wear, by name from the model's `skins` — see `SkinMap`.
      *  Omit to keep whatever texture the glb itself was built with. */
     skin?: string;
+    /** Props worn or carried on this entity's sockets — see `Attachment3D`. */
+    attachments?: Attachment3D[];
     /** Free-form, read by game code. The 2D SDK's `properties` equivalent. */
     properties?: Record<string, unknown>;
     visible?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umicat/three-sdk",
-  "version": "0.19.0",
+  "version": "0.21.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",