@umicat/three-sdk 0.5.0 → 0.6.0

package/dist/SceneLoader3D.d.ts

@@ -46,4 +46,19 @@ export interface LoadedScene3D {
  * settled and shipped for 2D, and it is the reason an editor can render a scene
  * without starting a game.
  */
+/** One model from the manifest, loaded on its own.
+ *
+ *  `loadScene3D` only fetches what the SCENE references, which is everything a
+ *  game needs until the first thing that appears at runtime — a weapon picked
+ *  up, a projectile, a dropped item. Without this, a game reaches for
+ *  GLTFLoader itself and re-implements asset-base resolution and importScale
+ *  slightly differently from the loader beside it.
+ *
+ *  Returns a fresh object each call, so two swords do not share one transform. */
+export declare function loadModelAsset(manifest: Manifest3D, modelAssetId: string, opts?: {
+    assetBase?: string;
+}): Promise<{
+    object: THREE.Object3D;
+    clips: THREE.AnimationClip[];
+}>;
 export declare function loadScene3D(scene3d: Scene3D, manifest: Manifest3D, opts?: LoadSceneOptions): Promise<LoadedScene3D>;

package/dist/SceneLoader3D.js

@@ -45,6 +45,28 @@ function makePrimitive(e) {
  * settled and shipped for 2D, and it is the reason an editor can render a scene
  * without starting a game.
  */
+/** One model from the manifest, loaded on its own.
+ *
+ *  `loadScene3D` only fetches what the SCENE references, which is everything a
+ *  game needs until the first thing that appears at runtime — a weapon picked
+ *  up, a projectile, a dropped item. Without this, a game reaches for
+ *  GLTFLoader itself and re-implements asset-base resolution and importScale
+ *  slightly differently from the loader beside it.
+ *
+ *  Returns a fresh object each call, so two swords do not share one transform. */
+export async function loadModelAsset(manifest, modelAssetId, opts = {}) {
+    const asset = (manifest.models ?? []).find((m) => m.id === modelAssetId);
+    if (!asset) {
+        const have = (manifest.models ?? []).map((m) => m.id).join(', ');
+        throw new Error(`[umicat] manifest has no model '${modelAssetId}'. It has: ${have || '(none)'}`);
+    }
+    const gltf = await new GLTFLoader().loadAsync((opts.assetBase ?? '') + asset.path);
+    const object = gltf.scene;
+    if (asset.importScale !== undefined)
+        object.scale.setScalar(asset.importScale);
+    object.userData.modelAssetId = modelAssetId;
+    return { object, clips: gltf.animations };
+}
 export async function loadScene3D(scene3d, manifest, opts = {}) {
     const problems = validateScene(scene3d);
     if (problems.length) {

package/dist/Sockets.d.ts

@@ -0,0 +1,38 @@
+import * as THREE from 'three';
+import type { Socket3D } from './scene3d';
+/**
+ * Put a thing in a character's hand.
+ *
+ * A held object is not a child of the character — it is a child of a BONE, so
+ * it inherits that bone's animated transform and follows the swing for free.
+ * Parenting to the model root instead produces a sword that hovers politely
+ * beside a character doing all the work.
+ *
+ * The catch, and the reason this is a platform primitive rather than four
+ * lines in each game: **nothing guarantees a rig has a hand bone.** The
+ * character every 3D Umicat game ships with has seven bones — root, two legs,
+ * torso, two arms, head — and no wrist at all. So "the hand" is a position
+ * along the arm bone, found by tuning, and it is a property of that model.
+ * Every game re-deriving it by eye is how you get twelve games with the sword
+ * in twelve slightly different places.
+ */
+export interface Attachment {
+    /** The bone it ended up on — useful when you want to check your work. */
+    readonly bone: THREE.Bone;
+    /** The wrapper that carries the socket offset; the object is its child. */
+    readonly holder: THREE.Object3D;
+    detach(): void;
+}
+/** Find a bone by exact name anywhere under `root`. */
+export declare function findBone(root: THREE.Object3D, name: string): THREE.Bone | null;
+/** Every bone name under `root` — what an error message should offer. */
+export declare function boneNames(root: THREE.Object3D): string[];
+/**
+ * Attach `object` to a socket on `root`.
+ *
+ * Throws if the bone is missing, and says which bones DO exist. A silent miss
+ * here is the worst outcome available: the weapon stays parented where it was,
+ * usually at the world origin, and the character walks around empty-handed
+ * while every line of the game's equip logic reports success.
+ */
+export declare function attachToSocket(root: THREE.Object3D, socket: Socket3D, object: THREE.Object3D): Attachment;

package/dist/Sockets.js

@@ -0,0 +1,48 @@
+import * as THREE from 'three';
+/** Find a bone by exact name anywhere under `root`. */
+export function findBone(root, name) {
+    let found = null;
+    root.traverse((o) => { if (!found && o.isBone && o.name === name)
+        found = o; });
+    return found;
+}
+/** Every bone name under `root` — what an error message should offer. */
+export function boneNames(root) {
+    const out = [];
+    root.traverse((o) => { if (o.isBone)
+        out.push(o.name); });
+    return out;
+}
+/**
+ * Attach `object` to a socket on `root`.
+ *
+ * Throws if the bone is missing, and says which bones DO exist. A silent miss
+ * here is the worst outcome available: the weapon stays parented where it was,
+ * usually at the world origin, and the character walks around empty-handed
+ * while every line of the game's equip logic reports success.
+ */
+export function attachToSocket(root, socket, object) {
+    const bone = findBone(root, socket.bone);
+    if (!bone) {
+        throw new Error(`[umicat] no bone "${socket.bone}" on this model. It has: ${boneNames(root).join(', ') || '(no bones at all)'}`);
+    }
+    // A holder, not the object itself: the socket offset and whatever transform
+    // the object arrives with are different things, and baking them together
+    // means a game cannot move the object within the hand without losing the
+    // socket. It also makes detaching exact.
+    const holder = new THREE.Object3D();
+    holder.name = `socket:${socket.bone}`;
+    if (socket.position)
+        holder.position.set(socket.position.x, socket.position.y, socket.position.z);
+    if (socket.rotation)
+        holder.rotation.set(socket.rotation.x, socket.rotation.y, socket.rotation.z);
+    if (socket.scale !== undefined)
+        holder.scale.setScalar(socket.scale);
+    holder.add(object);
+    bone.add(holder);
+    return {
+        bone,
+        holder,
+        detach() { holder.removeFromParent(); },
+    };
+}

package/dist/index.d.ts

@@ -1,13 +1,15 @@
 export { ThreeUmicat } from './ThreeUmicat.js';
 export type { UmicatInitOptions } from './ThreeUmicat.js';
 export * from './scene3d.js';
-export { loadScene3D } from './SceneLoader3D.js';
+export { loadScene3D, loadModelAsset } from './SceneLoader3D.js';
 export { CharacterController3D } from './CharacterController3D.js';
 export type { CharacterOptions, CharacterState, CharacterInput } from './CharacterController3D.js';
 export { CharacterAnimator } from './CharacterAnimator.js';
 export type { ClipMap, CharacterAnimatorOptions } from './CharacterAnimator.js';
 export { Input3D } from './Input3D.js';
-export type { Input3DOptions } from './Input3D.js';
+export type { Input3DOptions, Input3DAction } from './Input3D.js';
+export { attachToSocket, findBone, boneNames } from './Sockets.js';
+export type { Attachment } from './Sockets.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';

package/dist/index.js

@@ -5,10 +5,11 @@
 // 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 { loadScene3D, loadModelAsset } from './SceneLoader3D.js';
 export { CharacterController3D } from './CharacterController3D.js';
 export { CharacterAnimator } from './CharacterAnimator.js';
 export { Input3D } from './Input3D.js';
+export { attachToSocket, findBone, boneNames } from './Sockets.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.

package/dist/scene3d.d.ts

@@ -92,6 +92,26 @@ export interface Entity3D {
  * model calls its walk cycle `Walk` fails the same way, only more quietly.
  */
 export type AnimationMap = Record<string, string>;
+/**
+ * Where a held object sits on a character, named by what it is FOR rather
+ * than by which bone it happens to hang off.
+ *
+ * Rigs do not necessarily have a hand bone — this character's has seven bones
+ * and the arm is one of them, so a sword hangs off `arm-right` with an offset
+ * that puts it where a hand would be. That offset is a property of the MODEL,
+ * not of any game, so it travels in the manifest: tune it once and every game
+ * using this character gets a sword in the right place.
+ */
+export interface Socket3D {
+    /** Bone to hang from. Names are exact; the loader reports what it found. */
+    bone: string;
+    /** Offset in the bone's local space. */
+    position?: Vec3;
+    /** Euler angles in radians, applied in the bone's local space. */
+    rotation?: Vec3;
+    /** Uniform scale for whatever is attached. */
+    scale?: number;
+}
 export interface ModelAsset3D {
     id: string;
     /** Resolved by the runtime against the project's asset base url. */
@@ -99,6 +119,8 @@ export interface ModelAsset3D {
     animations?: AnimationMap;
     /** Authoring correction applied at load: most models are not born 1 unit tall. */
     importScale?: number;
+    /** Named attachment points — `{ "hand-right": { bone: "arm-right", ... } }`. */
+    sockets?: Record<string, Socket3D>;
 }
 export interface Light3D {
     id: string;

package/package.json

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