@umicat/three-sdk 0.17.2 → 0.18.0

package/README.md

@@ -73,6 +73,13 @@ 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.
+- **Skins are declared per asset and chosen per entity**
+  (`skins: { zombie: 'skins/zombieA.png' }`, then `skin: 'zombie'`). A body and
+  its wardrobe are separate files, so N bodies × M skins costs N + M assets
+  rather than N × M baked glb files. It is authored data rather than a call a
+  game makes, for the same reason the clip map is: a capability only reachable
+  from code is one most games never find, and an editor cannot offer a list it
+  cannot see.
 
 `validateScene` refuses duplicate ids, dangling parents, entities that would
 render nothing, trimesh colliders on dynamic bodies, and malformed quaternions —

package/dist/SceneLoader3D.d.ts

@@ -66,6 +66,7 @@ export interface LoadedScene3D {
  *  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;
+    skin?: string;
 }): Promise<{
     object: THREE.Object3D;
     clips: THREE.AnimationClip[];

package/dist/SceneLoader3D.js

@@ -1,9 +1,18 @@
 import * as THREE from 'three';
 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';
 function toVec(v, d = 0) {
     return new THREE.Vector3(v?.x ?? d, v?.y ?? d, v?.z ?? d);
 }
+/** Does this model deform with bones? Decides which clone it needs. */
+function isRigged(root) {
+    let rigged = false;
+    root.traverse((o) => { if (o.isSkinnedMesh)
+        rigged = true; });
+    return rigged;
+}
 function applyTransform(obj, e) {
     const t = e.transform;
     obj.position.copy(toVec(t.position));
@@ -62,6 +71,14 @@ export async function loadModelAsset(manifest, modelAssetId, opts = {}) {
     }
     const gltf = await new GLTFLoader().loadAsync((opts.assetBase ?? '') + asset.path);
     const object = gltf.scene;
+    if (opts.skin) {
+        const path = asset.skins?.[opts.skin];
+        if (!path) {
+            throw new Error(`[umicat] model '${modelAssetId}' has no skin '${opts.skin}'. It declares: ` +
+                `${Object.keys(asset.skins ?? {}).join(', ') || '(none)'}`);
+        }
+        await applySkin(object, path, { assetBase: opts.assetBase });
+    }
     if (asset.importScale !== undefined)
         object.scale.setScalar(asset.importScale);
     object.userData.modelAssetId = modelAssetId;
@@ -115,16 +132,31 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
     const clips = new Map();
     for (const [id, gltf] of loaded)
         clips.set(id, gltf.animations);
+    // Skins are fetched per entity and awaited before this function resolves, so
+    // 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 = [];
     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.
+            // Clone only when a second entity wants the same asset — the first one
+            // gets the loaded scene itself.
+            //
+            // **A rigged model must be cloned with `SkeletonUtils.clone`.**
+            // `Object3D.clone()` copies the bone hierarchy but leaves the cloned
+            // SkinnedMesh pointing at the ORIGINAL `Skeleton`, so every clone
+            // deforms with the first one's bones: a squad of guards all play the
+            // same animation in the same place, stacked on the leader, while each
+            // one's own mixer reports that it is playing something else. Nothing
+            // errors. This became load-bearing the moment one body plus a set of
+            // skins became the way characters ship — "many instances of one model"
+            // went from a corner to the main case.
             const used = [...entities.values()].some((o) => o.userData.modelAssetId === e.modelAssetId);
-            obj = used ? gltf.scene.clone(true) : gltf.scene;
+            obj = !used ? gltf.scene
+                : isRigged(gltf.scene) ? cloneRigged(gltf.scene)
+                    : gltf.scene.clone(true);
             obj.userData.modelAssetId = e.modelAssetId;
             if (asset.importScale)
                 obj.scale.setScalar(asset.importScale);
@@ -160,6 +192,23 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
                 mixers.push(mixer);
                 mixerFor.set(e.id, mixer);
             }
+            if (e.skin) {
+                const path = asset.skins?.[e.skin];
+                if (!path) {
+                    // Same contract as a missing clip: say which names DO exist. A skin
+                    // that silently doesn't apply looks exactly like a model built with
+                    // the wrong default, and you go looking in Blender.
+                    throw new Error(`entity '${e.id}' wants skin '${e.skin}', but model '${e.modelAssetId}' declares: ` +
+                        `${Object.keys(asset.skins ?? {}).join(', ') || '(none)'}`);
+                }
+                const target = obj;
+                skinJobs.push(applySkin(target, path, { assetBase: opts.assetBase }).then((r) => {
+                    if (r.repainted === 0) {
+                        throw new Error(`entity '${e.id}' skin '${e.skin}' repainted nothing — model ` +
+                            `'${e.modelAssetId}' has no material with a base-colour texture to replace`);
+                    }
+                }));
+            }
         }
         else {
             obj = makePrimitive(e);
@@ -173,6 +222,8 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
         applyTransform(obj, e);
         entities.set(e.id, obj);
     }
+    if (skinJobs.length)
+        await Promise.all(skinJobs);
     // Parent after every entity exists, so declaration order doesn't matter.
     for (const e of scene3d.entities) {
         const obj = entities.get(e.id);
@@ -220,8 +271,22 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
     // hits it immediately.
     {
         const bounds = new THREE.Box3();
+        // precise:true is load-bearing. Box3.expandByObject's default path, for any
+        // object exposing its own `.boundingBox` (only THREE.SkinnedMesh does),
+        // calls `object.computeBoundingBox()` and PERMANENTLY CACHES the result on
+        // the mesh — and for `bindMode: 'attached'` (GLTFLoader's default), that
+        // computation folds in each bone's absolute matrixWorld, so the cached box
+        // ends up sitting at the entity's placed-in-scene position. `raycast()`
+        // then treats that same cached box as LOCAL space and inverts matrixWorld
+        // before testing against it, so every ray misses. Net effect: any rigged
+        // model entity (a hero, an NPC) becomes permanently unraycastable — hit
+        // everywhere on screen except the one thing worth clicking — the moment
+        // this shadow-fitting pass runs. `precise:true` walks vertices directly
+        // instead and never touches `object.boundingBox`. Confirmed by direct
+        // repro against a shipped game's rigged `hero` entity: unclickable with
+        // the default call, hits correctly once this switched to precise.
         for (const o of entities.values())
-            bounds.expandByObject(o);
+            bounds.expandByObject(o, true);
         if (!bounds.isEmpty()) {
             const size = bounds.getSize(new THREE.Vector3());
             const centre = bounds.getCenter(new THREE.Vector3());

package/dist/Skin.d.ts

@@ -0,0 +1,82 @@
+import * as THREE from 'three';
+/**
+ * Repaint a character by swapping its base-colour texture.
+ *
+ * One rigged body plus N textures is how a character pack is actually shipped
+ * — the Kenney set every Umicat 3D game draws from has four bodies, seventeen
+ * clips and eighty-one skins painted on ONE shared UV layout, which is 324
+ * characters from 85 files. Baking the combinations instead would be 324 glb
+ * files, the same mesh and the same clips repeated 324 times, and a palette
+ * swap would cost a fresh megabyte-and-a-half download.
+ *
+ * It is a platform primitive rather than `mat.map = tex` in each game because
+ * of three traps, each of which fails quietly:
+ *
+ * **Clones share materials.** `gltf.scene.clone(true)` hands every clone the
+ * same material instance, so reskinning one zombie reskins the whole horde.
+ * `Tint.ts` exists for the same reason and its notes tell the same story: the
+ * bug reads as a gameplay bug, not a graphics one. Materials are therefore
+ * cloned per object, once, the first time it is skinned.
+ *
+ * **A plainly-loaded texture is upside down.** `GLTFLoader` sets `flipY =
+ * false` on everything it loads (glTF puts the UV origin top-left);
+ * `TextureLoader` defaults to `true`. So the obvious one-liner gives you a
+ * character wearing its own texture mirrored vertically — shoes on the head —
+ * and nothing anywhere reports a problem. The replacement copies its settings
+ * from the map it replaces, which also preserves the model's authored
+ * filtering: these skins are region maps, and a bilinear tap straddling two
+ * regions invents a colour that is in neither.
+ *
+ * **Not every material is skin.** A character carrying a sword has the sword's
+ * steel in the same subtree. Repainting every material would paint the blade
+ * with a face. The default target is "materials that already have a base
+ * colour map", which selects the textured body and leaves flat palette colours
+ * alone — and correctly follows through to attachments that ARE skin-painted,
+ * like the animal ears and tails, whose material is the character's own.
+ */
+export interface SkinOptions {
+    /**
+     * Narrow which materials get repainted, by exact name or pattern. Omit to
+     * repaint every material that already has a base-colour map, which is the
+     * right answer for a body-plus-props subtree.
+     */
+    material?: string | RegExp;
+    /**
+     * Reuse one `THREE.Texture` per url across every call. Default true — a
+     * squad of eight guards in the same uniform should download and upload one
+     * texture, not eight. Turn it off only if a game mutates the texture it gets.
+     */
+    cache?: boolean;
+    /** Where to resolve a relative url against, e.g. the project's asset host. */
+    assetBase?: string;
+}
+/** What a skin swap did, so a caller can tell "worked" from "hit nothing". */
+export interface SkinResult {
+    /** How many materials were repainted. Zero means the filter matched nothing. */
+    readonly repainted: number;
+    /** The texture now in use, for a game that wants to reuse it directly. */
+    readonly texture: THREE.Texture;
+}
+/**
+ * Put `texture` on `object` as its base colour. The synchronous half — use it
+ * when a game already holds the texture (a preloaded team colour, an atlas
+ * page); otherwise use `applySkin`, which fetches.
+ *
+ * The texture is NOT disposed on replacement: the map coming off usually came
+ * from the glb and is shared with every other instance of that model, so
+ * disposing it blanks the rest of the cast.
+ */
+export declare function applySkinTexture(object: THREE.Object3D, texture: THREE.Texture, opts?: SkinOptions): SkinResult;
+/**
+ * Fetch a skin texture and put it on `object`.
+ *
+ * Returns how many materials it actually repainted. **Zero is worth checking**
+ * — it means the filter matched nothing, which on a model whose body material
+ * has no texture at all is the difference between "reskinned" and "silently
+ * did nothing", and there is no other signal.
+ */
+export declare function applySkin(object: THREE.Object3D, url: string, opts?: SkinOptions): Promise<SkinResult>;
+/** Load (and by default cache) one skin texture. Exposed for preloading. */
+export declare function loadSkinTexture(url: string, cache?: boolean): Promise<THREE.Texture>;
+/** Drop the texture cache. For a game unloading a level, and for tests. */
+export declare function clearSkinCache(): void;

package/dist/Skin.js

@@ -0,0 +1,133 @@
+import * as THREE from 'three';
+/** Objects whose materials have already been given their own copies. */
+const isolated = new WeakSet();
+const textures = new Map();
+let loader = null;
+function matches(material, filter) {
+    if (filter === undefined) {
+        // Untextured materials are palette colours — a sword's steel, a cap's
+        // felt. They are not skin and must not be painted with one.
+        return material.map != null;
+    }
+    return typeof filter === 'string' ? material.name === filter : filter.test(material.name);
+}
+/**
+ * Give `object` its own copy of every material it uses, so painting it paints
+ * only it. Idempotent: the second call on the same object does nothing.
+ */
+function isolate(object) {
+    if (isolated.has(object))
+        return;
+    isolated.add(object);
+    object.traverse((o) => {
+        const mesh = o;
+        if (!mesh.isMesh)
+            return;
+        mesh.material = Array.isArray(mesh.material)
+            ? mesh.material.map((m) => m.clone())
+            : mesh.material.clone();
+    });
+}
+/**
+ * Point `texture` at the same sampling the map it replaces was authored with.
+ *
+ * This is the whole reason a skin swap is not a one-liner. `flipY` alone is
+ * the difference between a character and a character wearing its texture
+ * upside down, and it differs between the loader that produced the model and
+ * the loader producing the replacement.
+ */
+function matchSampling(texture, previous) {
+    if (previous) {
+        texture.flipY = previous.flipY;
+        texture.colorSpace = previous.colorSpace;
+        texture.wrapS = previous.wrapS;
+        texture.wrapT = previous.wrapT;
+        texture.magFilter = previous.magFilter;
+        texture.minFilter = previous.minFilter;
+        texture.anisotropy = previous.anisotropy;
+        texture.generateMipmaps = previous.generateMipmaps;
+        texture.channel = previous.channel;
+    }
+    else {
+        // No map to copy from: assume the glTF convention, since that is what
+        // every model this package loads was born as.
+        texture.flipY = false;
+        texture.colorSpace = THREE.SRGBColorSpace;
+    }
+    texture.needsUpdate = true;
+}
+/**
+ * Put `texture` on `object` as its base colour. The synchronous half — use it
+ * when a game already holds the texture (a preloaded team colour, an atlas
+ * page); otherwise use `applySkin`, which fetches.
+ *
+ * The texture is NOT disposed on replacement: the map coming off usually came
+ * from the glb and is shared with every other instance of that model, so
+ * disposing it blanks the rest of the cast.
+ */
+export function applySkinTexture(object, texture, opts = {}) {
+    isolate(object);
+    let repainted = 0;
+    const done = new Set();
+    object.traverse((o) => {
+        const mesh = o;
+        if (!mesh.isMesh)
+            return;
+        const list = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        for (const m of list) {
+            if (done.has(m) || !matches(m, opts.material))
+                continue;
+            done.add(m);
+            const std = m;
+            // Clone per material rather than sharing one Texture object across
+            // materials: sampling is copied from whatever each one had, and two
+            // materials in the same model need not have been authored the same.
+            const tex = texture.clone();
+            matchSampling(tex, std.map ?? null);
+            std.map = tex;
+            std.needsUpdate = true;
+            repainted += 1;
+        }
+    });
+    return { repainted, texture };
+}
+/**
+ * Fetch a skin texture and put it on `object`.
+ *
+ * Returns how many materials it actually repainted. **Zero is worth checking**
+ * — it means the filter matched nothing, which on a model whose body material
+ * has no texture at all is the difference between "reskinned" and "silently
+ * did nothing", and there is no other signal.
+ */
+export async function applySkin(object, url, opts = {}) {
+    const full = (opts.assetBase ?? '') + url;
+    const texture = await loadSkinTexture(full, opts.cache !== false);
+    return applySkinTexture(object, texture, opts);
+}
+/** Load (and by default cache) one skin texture. Exposed for preloading. */
+export function loadSkinTexture(url, cache = true) {
+    if (cache) {
+        const hit = textures.get(url);
+        if (hit)
+            return hit;
+    }
+    loader ?? (loader = new THREE.TextureLoader());
+    const p = loader.loadAsync(url).then((t) => {
+        t.flipY = false;
+        t.colorSpace = THREE.SRGBColorSpace;
+        return t;
+    });
+    if (cache) {
+        textures.set(url, p);
+        // A failed fetch must not be remembered as the answer: a skin that 404s
+        // once would then 404 for the rest of the session even after a fix.
+        p.catch(() => textures.delete(url));
+    }
+    return p;
+}
+/** Drop the texture cache. For a game unloading a level, and for tests. */
+export function clearSkinCache() {
+    for (const p of textures.values())
+        p.then((t) => t.dispose()).catch(() => { });
+    textures.clear();
+}

package/dist/editor/EditorDesignPlayer3D.d.ts

@@ -16,10 +16,20 @@ export interface EditorDesignPlayer3DOptions {
  * 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
  * platform's Edit tab can show a 3D game's layout the same way it already
- * does for 2D. Read-only: no drag, no gizmo, no apply-edit — the one
- * interaction is click-to-pick a world coordinate, posted to the host so a
- * person can point at a real spot instead of guessing one blind when telling
- * the AI where to place something.
+ * does for 2D.
+ *
+ * Two interactions:
+ * - **Click** an entity to select it — a bounding box frames it and a
+ *   marker reads off the exact world coordinate, posted to the host so a
+ *   person can point at a real spot instead of guessing one blind when
+ *   telling the AI where to place something.
+ * - **Drag** an entity to move it (Phase 1 of real editing, ground-plane
+ *   constrained — position only, no rotation/scale, no gizmo, no
+ *   Inspector). This function itself never writes anything — it only
+ *   moves the live THREE.Object3D and posts the final LOCAL position on
+ *   release (`umicat:editor:dragEnd3d`); the host owns turning that into a
+ *   disk write. Grabbing empty space/sky orbits instead, same convention
+ *   as Unity/Blender.
  *
  * Takes over `renderer`'s animation loop entirely for the rest of the page's
  * life — there is no scene-swap API and no teardown, matching how the

package/dist/editor/EditorDesignPlayer3D.js

@@ -1,14 +1,25 @@
 import * as THREE from 'three';
 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
 import { loadScene3D } from '../SceneLoader3D.js';
+import { applySkin } from '../Skin.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
  * platform's Edit tab can show a 3D game's layout the same way it already
- * does for 2D. Read-only: no drag, no gizmo, no apply-edit — the one
- * interaction is click-to-pick a world coordinate, posted to the host so a
- * person can point at a real spot instead of guessing one blind when telling
- * the AI where to place something.
+ * does for 2D.
+ *
+ * Two interactions:
+ * - **Click** an entity to select it — a bounding box frames it and a
+ *   marker reads off the exact world coordinate, posted to the host so a
+ *   person can point at a real spot instead of guessing one blind when
+ *   telling the AI where to place something.
+ * - **Drag** an entity to move it (Phase 1 of real editing, ground-plane
+ *   constrained — position only, no rotation/scale, no gizmo, no
+ *   Inspector). This function itself never writes anything — it only
+ *   moves the live THREE.Object3D and posts the final LOCAL position on
+ *   release (`umicat:editor:dragEnd3d`); the host owns turning that into a
+ *   disk write. Grabbing empty space/sky orbits instead, same convention
+ *   as Unity/Blender.
  *
  * Takes over `renderer`'s animation loop entirely for the rest of the page's
  * life — there is no scene-swap API and no teardown, matching how the
@@ -60,6 +71,12 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
     }
     let scene = null;
     const entityByObject = new Map();
+    // The reverse direction, and the authored data behind it. Picking only ever
+    // needed object→id; editing a PROPERTY needs to go the other way, and needs
+    // the manifest to resolve what a name like `skin: "zombieA"` refers to.
+    const objectByEntity = new Map();
+    let manifest = null;
+    let sceneData = null;
     const resize = () => {
         renderer.setSize(window.innerWidth, window.innerHeight);
         camera.aspect = window.innerWidth / window.innerHeight;
@@ -67,68 +84,207 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
     };
     resize();
     window.addEventListener('resize', resize);
+    const raycaster = new THREE.Raycaster();
+    const ndcFromEvent = (e) => {
+        const rect = renderer.domElement.getBoundingClientRect();
+        return new THREE.Vector2(((e.clientX - rect.left) / rect.width) * 2 - 1, -((e.clientY - rect.top) / rect.height) * 2 + 1);
+    };
+    // Only VISIBLE entity roots are ever raycast against. three.js's
+    // Mesh.raycast does NOT check `.visible` on its own (confirmed against the
+    // pinned three source — no such check in Raycaster.js or Object3D.raycast),
+    // and a real scene can ship an invisible collision box alongside
+    // separately-placed visible ground models — without this filter, a click
+    // that visibly lands on the rendered ground can silently return the
+    // collider's coordinates instead.
+    const pickEntityAt = (e) => {
+        raycaster.setFromCamera(ndcFromEvent(e), camera);
+        const targets = Array.from(entityByObject.keys()).filter((o) => o.visible !== false);
+        const hits = raycaster.intersectObjects(targets, true);
+        if (hits.length === 0)
+            return null;
+        let node = hits[0].object;
+        while (node) {
+            const id = entityByObject.get(node);
+            if (id)
+                return { entityId: id, entityRoot: node, point: hits[0].point };
+            node = node.parent;
+        }
+        return null;
+    };
     // Orbit-vs-click: a real drag moves the pointer more than a few px.
     let downX = 0;
     let downY = 0;
     let moved = false;
+    // Entity drag — Phase 1 of real editing (translate only, ground-plane
+    // constrained). Grabbing on an entity moves it; grabbing empty space/sky
+    // still orbits, same convention as Unity/Blender. Whether THIS gesture is
+    // a drag is decided synchronously in pointerdown (a raycast hit or not) —
+    // `OrbitControls`'s own pointerdown listener runs first (registered
+    // earlier) and always starts its internal drag bookkeeping, but its
+    // `onPointerMove`/related handlers re-check `this.enabled` on every event
+    // rather than only at attach time (confirmed against the pinned
+    // OrbitControls source), so disabling it HERE still correctly suppresses
+    // every subsequent move for this gesture; its `onPointerUp` cleanup does
+    // not check `enabled` at all, so re-enabling afterward never leaves it
+    // stuck. No drag state survives a scene reload — it's cleared on release,
+    // and a scene swap only ever happens via a full iframe reload anyway.
+    let dragEntity = null;
+    let dragEntityId = null;
+    let dragPlane = null;
+    let dragGrabOffset = null; // world-space, plane-point minus object position at grab time
     const onPointerDown = (e) => {
         downX = e.clientX;
         downY = e.clientY;
         moved = false;
+        if (!scene)
+            return;
+        const hit = pickEntityAt(e);
+        if (!hit)
+            return; // empty space — let OrbitControls own this gesture
+        const objectPos = hit.entityRoot.getWorldPosition(new THREE.Vector3());
+        const plane = new THREE.Plane(new THREE.Vector3(0, 1, 0), -objectPos.y);
+        const planePoint = new THREE.Vector3();
+        // Looking exactly parallel to the ground has no plane intersection —
+        // vanishingly rare for this camera (auto-framed, always angled down at
+        // the scene) but cheap to guard: fall through to orbit rather than
+        // start a drag from a garbage grab offset.
+        if (!raycaster.ray.intersectPlane(plane, planePoint))
+            return;
+        dragEntity = hit.entityRoot;
+        dragEntityId = hit.entityId;
+        dragPlane = plane;
+        dragGrabOffset = planePoint.sub(objectPos);
+        controls.enabled = false;
+        try {
+            renderer.domElement.setPointerCapture(e.pointerId);
+        }
+        catch {
+            // Multi-touch / an already-released pointer can throw here — never
+            // let that leave the gesture half-started (see the board-game touch
+            // lesson: an uncaught throw from setPointerCapture stranded a finger
+            // as permanently "down"). The drag still works via normal bubbling;
+            // capture is an enhancement (keeps it live if the cursor leaves the
+            // canvas mid-drag), not a requirement.
+        }
     };
     const onPointerMove = (e) => {
         if (Math.abs(e.clientX - downX) > 4 || Math.abs(e.clientY - downY) > 4)
             moved = true;
+        if (!dragEntity || !dragPlane || !dragGrabOffset || !scene)
+            return;
+        raycaster.setFromCamera(ndcFromEvent(e), camera);
+        const planePoint = new THREE.Vector3();
+        if (!raycaster.ray.intersectPlane(dragPlane, planePoint))
+            return; // looking parallel to the plane
+        const newWorldPos = planePoint.sub(dragGrabOffset);
+        if (dragEntity.parent)
+            dragEntity.parent.worldToLocal(newWorldPos);
+        dragEntity.position.copy(newWorldPos);
+        selectionBox.setFromObject(dragEntity);
     };
     const onPointerUp = (e) => {
+        try {
+            renderer.domElement.releasePointerCapture(e.pointerId);
+        }
+        catch {
+            // Already released, or never captured (e.g. this gesture never hit an
+            // entity) — nothing to do either way.
+        }
+        // A drag only really happened if the pointer actually moved — grabbing
+        // an entity and releasing without moving is a CLICK on it (case below),
+        // not a same-position no-op save.
+        if (moved && dragEntity && dragEntityId) {
+            window.parent.postMessage({
+                type: 'umicat:editor:dragEnd3d',
+                sceneId: opts.sceneId,
+                entityId: dragEntityId,
+                position: { x: dragEntity.position.x, y: dragEntity.position.y, z: dragEntity.position.z },
+            }, '*');
+        }
+        dragEntity = null;
+        dragEntityId = null;
+        dragPlane = null;
+        dragGrabOffset = null;
+        controls.enabled = true;
         if (moved || !scene)
             return;
-        const rect = renderer.domElement.getBoundingClientRect();
-        const mouse = new THREE.Vector2(((e.clientX - rect.left) / rect.width) * 2 - 1, -((e.clientY - rect.top) / rect.height) * 2 + 1);
-        const raycaster = new THREE.Raycaster();
-        raycaster.setFromCamera(mouse, camera);
-        // Only cast against VISIBLE entity roots. three.js's Mesh.raycast does
-        // NOT check `.visible` on its own (confirmed against the pinned three
-        // source — no such check in Raycaster.js or Object3D.raycast), and a
-        // real scene can ship an invisible collision box alongside separately-
-        // placed visible ground models — without this filter, a click that
-        // visibly lands on the rendered ground can silently return the
-        // collider's coordinates instead.
-        const targets = Array.from(entityByObject.keys()).filter((o) => o.visible !== false);
-        const hits = raycaster.intersectObjects(targets, true);
-        if (hits.length === 0)
+        // A plain click (no drag) — the existing read-a-coordinate behavior.
+        const hit = pickEntityAt(e);
+        if (!hit)
             return;
-        const hit = hits[0];
-        let node = hit.object;
-        let entityId = null;
-        let entityRoot = null;
-        while (node) {
-            const id = entityByObject.get(node);
-            if (id) {
-                entityId = id;
-                entityRoot = node;
-                break;
-            }
-            node = node.parent;
-        }
         marker.position.copy(hit.point);
         marker.visible = true;
         // Frame the whole entity the click landed on, not just the point on its
         // surface — `setFromObject` walks the root's full subtree, so a
         // multi-mesh entity (a model with separate parts) gets one box around
         // all of it, matching what "entityId" actually refers to.
-        if (entityRoot) {
-            selectionBox.setFromObject(entityRoot);
-            selectionBox.visible = true;
-        }
-        else {
-            selectionBox.visible = false;
-        }
-        window.parent.postMessage({ type: 'umicat:editor:pickPoint3d', x: hit.point.x, y: hit.point.y, z: hit.point.z, entityId }, '*');
+        selectionBox.setFromObject(hit.entityRoot);
+        selectionBox.visible = true;
+        window.parent.postMessage({ type: 'umicat:editor:pickPoint3d', x: hit.point.x, y: hit.point.y, z: hit.point.z, entityId: hit.entityId }, '*');
     };
     renderer.domElement.addEventListener('pointerdown', onPointerDown);
     renderer.domElement.addEventListener('pointermove', onPointerMove);
     renderer.domElement.addEventListener('pointerup', onPointerUp);
+    /**
+     * The FIRST host→iframe message this player has ever accepted.
+     *
+     * Everything until now went one way: the player reported picks and drags,
+     * and the host wrote them to disk. That works for a drag because the SDK
+     * itself already moved the object — the canvas was correct before the host
+     * heard about it. It does not work for a property edited in a panel: the
+     * host changes the file, the canvas knows nothing, and the edit is invisible
+     * until a rebuild. A property editor whose changes don't show is a property
+     * editor nobody trusts (a sibling 2D tool shipped exactly that bug — a new
+     * widget kind not wired into its live-patch path silently did nothing on
+     * canvas while the Inspector happily accepted the value).
+     *
+     * So: `patchEntity3d` in, `patchApplied3d` out. The ack matters as much as
+     * the patch — the host has ALREADY written the file by the time this runs,
+     * so a failure here means disk and canvas disagree, and the only way anyone
+     * finds out is if this says so.
+     *
+     * `patch` is an open bag deliberately: skin is the first field, and adding
+     * rotation/scale/visible later should be a new `if`, not a new message.
+     */
+    async function onHostMessage(event) {
+        // Source-identity, not origin: the host page and this iframe are on
+        // different origins by design (a CDN preview url), same as the checks the
+        // host does on messages coming the other way.
+        if (event.source !== window.parent)
+            return;
+        const data = event.data;
+        if (!data || typeof data !== 'object' || data.type !== 'umicat:editor:patchEntity3d')
+            return;
+        const m = data;
+        const done = (error) => {
+            if (error)
+                console.warn('[umicat/editor] 3D patch failed:', m.entityId, error);
+            window.parent.postMessage({ type: 'umicat:editor:patchApplied3d', entityId: m.entityId, ok: !error, error }, '*');
+        };
+        const object = objectByEntity.get(m.entityId);
+        if (!object)
+            return done(`no entity '${m.entityId}' in the scene being shown`);
+        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);
+            const path = asset?.skins?.[m.patch.skin];
+            if (!path) {
+                return done(`model '${authored?.modelAssetId ?? '(none)'}' declares no skin '${m.patch.skin}'. ` +
+                    `It has: ${Object.keys(asset?.skins ?? {}).join(', ') || '(none)'}`);
+            }
+            try {
+                const result = await applySkin(object, path, { assetBase: '' });
+                if (result.repainted === 0) {
+                    return done(`skin '${m.patch.skin}' repainted nothing — this model has no textured material`);
+                }
+            }
+            catch (e) {
+                return done(e instanceof Error ? e.message : String(e));
+            }
+        }
+        done();
+    }
+    window.addEventListener('message', (e) => { void onHostMessage(e); });
     // Design mode skips physics and animation entirely (loadScene3D's own
     // designMode flag) — there are no mixers to advance and no Rapier world to
     // step, so the loop only ever needs to render.
@@ -163,13 +319,16 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
     if (!sceneId)
         return; // no scene chosen yet — idle, waiting for the host
     try {
-        const manifest = await fetch('scenes3d/manifest.json').then((r) => r.json());
-        const scene3d = await fetch(`scenes3d/${sceneId}.json`).then((r) => r.json());
-        const loaded = await loadScene3D(scene3d, manifest, { assetBase: '', designMode: true });
+        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 });
         scene = loaded.scene;
         entityByObject.clear();
-        for (const [id, obj] of loaded.entities)
+        objectByEntity.clear();
+        for (const [id, obj] of loaded.entities) {
             entityByObject.set(obj, id);
+            objectByEntity.set(id, obj);
+        }
         marker.visible = false;
         scene.add(marker);
         selectionBox.visible = false;

package/dist/index.d.ts

@@ -10,6 +10,8 @@ export { Input3D } from './Input3D.js';
 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 type { SkinOptions, SkinResult } from './Skin.js';
 export { GameAudio } from './GameAudio.js';
 export type { GameAudioOptions, AudioClipSpec } from './GameAudio.js';
 export { setupScreenshotListener, takeScreenshot } from './capture/ScreenshotManager.js';

package/dist/index.js

@@ -11,6 +11,7 @@ export { CharacterAnimator } from './CharacterAnimator.js';
 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 { GameAudio } from './GameAudio.js';
 export { setupScreenshotListener, takeScreenshot } from './capture/ScreenshotManager.js';
 export { setupRecordingListener } from './capture/RecordingManager.js';

package/dist/scene3d.d.ts

@@ -80,6 +80,9 @@ export interface Entity3D {
         play?: string;
         loop?: boolean;
     };
+    /** 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;
     /** Free-form, read by game code. The 2D SDK's `properties` equivalent. */
     properties?: Record<string, unknown>;
     visible?: boolean;
@@ -101,6 +104,17 @@ export interface Entity3D {
  * model calls its walk cycle `Walk` fails the same way, only more quietly.
  */
 export type AnimationMap = Record<string, string>;
+/**
+ * Skin name → the texture that paints it, relative to the asset base.
+ *
+ * A character pack is one rigged body and many textures on one UV layout, so
+ * the body and its wardrobe are separate assets and the pairing is authored
+ * here rather than baked into a glb per combination. Declaring them means a
+ * scene picks a skin by name (`Entity3D.skin`) instead of a game writing load
+ * code, and an editor can offer the list — a capability only reachable from
+ * code is one most games never find.
+ */
+export type SkinMap = 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.
@@ -126,6 +140,8 @@ export interface ModelAsset3D {
     /** Resolved by the runtime against the project's asset base url. */
     path: string;
     animations?: AnimationMap;
+    /** Interchangeable textures for this model — `{ "zombie": "skins/zombieA.png" }`. */
+    skins?: SkinMap;
     /** Authoring correction applied at load: most models are not born 1 unit tall. */
     importScale?: number;
     /** Named attachment points — `{ "hand-right": { bone: "arm-right", ... } }`. */

package/package.json

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