@umicat/three-sdk 0.19.0 → 0.20.0

package/README.md

@@ -73,6 +73,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/SceneLoader3D.d.ts

@@ -30,6 +30,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, Map<string, THREE.Object3D>>;
     /** 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 { attachToSocket } from './Sockets.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,7 @@ 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();
     for (const e of scene3d.entities) {
         let obj;
         if (e.modelAssetId) {
@@ -209,8 +225,42 @@ 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);
+            }
         }
         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;
@@ -345,7 +395,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/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.20.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",