@umicat/three-sdk 0.20.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
 ```

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;
@@ -32,7 +33,7 @@ export interface LoadedScene3D {
     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, Map<string, THREE.Object3D>>;
+    attachments: Map<string, WornMap>;
     /** Entity id → rigid body, when physics was supplied. */
     bodies: Map<string, any>;
     world?: any;

package/dist/SceneLoader3D.js

@@ -3,7 +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 { attachToSocket } from './Sockets.js';
+import { applyAttachments } from './Attachments.js';
 function toVec(v, d = 0) {
     return new THREE.Vector3(v?.x ?? d, v?.y ?? d, v?.z ?? d);
 }
@@ -152,6 +152,7 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
     // 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) {
@@ -225,36 +226,13 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
                     }
                 }));
             }
-            for (const a of e.attachments ?? []) {
-                const prop = models.get(a.modelAssetId); // prefetch already proved it exists
-                // The prop knows where it belongs; the scene only has to say so when
-                // it wants it somewhere else.
-                const socketName = a.socket ?? prop.socket;
-                if (!socketName) {
-                    throw new Error(`entity '${e.id}' 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 = asset.sockets?.[socketName];
-                if (!socket) {
-                    throw new Error(`entity '${e.id}' wants socket '${socketName}' for '${a.modelAssetId}', but model ` +
-                        `'${e.modelAssetId}' has: ${Object.keys(asset.sockets ?? {}).join(', ') || '(none)'}`);
-                }
-                const propGltf = loaded.get(a.modelAssetId);
-                // 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 propObj = isRigged(propGltf.scene)
-                    ? cloneRigged(propGltf.scene) : propGltf.scene.clone(true);
-                if (prop.importScale !== undefined)
-                    propObj.scale.setScalar(prop.importScale);
-                propObj.userData.modelAssetId = a.modelAssetId;
-                propObj.name = a.id ?? a.modelAssetId;
-                attachToSocket(obj, socket, propObj);
-                let mine = attachments.get(e.id);
-                if (!mine) {
-                    mine = new Map();
-                    attachments.set(e.id, mine);
-                }
-                mine.set(a.id ?? socketName, propObj);
+            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 {
@@ -272,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);

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/package.json

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