@umicat/three-sdk 0.20.0 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,14 +4,25 @@ The three.js runtime for Umicat games, per ADR-033. Platform services come from
4
4
  `@umicat/platform-sdk` untouched; what lives here is the engine layer we own.
5
5
 
6
6
  **Status: published and in use.** `@umicat/three-sdk` is on npm; Balaboo (a
7
- tower defence that ships from `woodland/`) is built on it, and `umicat-template-3d`
8
- is what new 3D projects start from.
7
+ tower defence that ships from `woodland/`) is built on it, and every new 3D
8
+ project is forked from **`umicat-template`'s `template-3d` branch** — which is
9
+ what `gitManager.createGameFromFork` actually clones. (Not `umicat-template-3d`:
10
+ that was the scratch repo the template was developed in, and it has been
11
+ archived since 2026-09-11 precisely because two copies of a template is how
12
+ someone eventually edits the wrong one. This line named it for two weeks after
13
+ that, which is the same failure the note below describes.)
9
14
 
10
15
  What it has: the scene3d format and loader, physics wiring, a character
11
16
  controller and animator, an input layer that mounts on-screen controls on touch
12
- devices and binds keys everywhere, bone sockets, hit tints, audio, and the
13
- editor's screenshot/video-capture protocol. What it still does not have: an
14
- editor.
17
+ devices and binds keys everywhere, bone sockets, swappable skins and
18
+ attachments, hit tints, audio, the editor's screenshot/video-capture protocol,
19
+ and a read-and-write design view
20
+ (`EditorDesignPlayer3D`: click-to-pick, drag-to-move, a host→iframe patch
21
+ channel the platform Inspector drives, and drag-and-drop model placement —
22
+ `umicat:editor:dropModel3d` in, `umicat:editor:modelDropped3d` out — which
23
+ raycasts the drop point against the ground plane and fetches the GLB straight
24
+ from its CDN url, no manifest entry required). What it still does not have: a
25
+ rotate or scale gizmo, undo, or multi-select.
15
26
 
16
27
  > This paragraph said "seed, not a product — no input system, no character
17
28
  > controller, no audio, and no published package" for ten minor versions after
@@ -24,7 +35,8 @@ editor.
24
35
  │
25
36
  @umicat/three-sdk ThreeUmicat · scene3d · loadScene3D · physics · Input3D
26
37
  CharacterController3D · CharacterAnimator · GameAudio
27
- sockets · tints · setupScreenshotListener/setupRecordingListener
38
+ sockets · skins · attachments · tints
39
+ setupScreenshotListener/setupRecordingListener
28
40
  ▲
29
41
  your game gameplay
30
42
  ```
@@ -0,0 +1,38 @@
1
+ import * as THREE from 'three';
2
+ import type { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
3
+ import type { Attachment3D, Manifest3D, ModelAsset3D } from './scene3d.js';
4
+ /**
5
+ * Put the props a character is wearing on it, and take off whatever it was
6
+ * wearing before.
7
+ *
8
+ * **Whole-list, not incremental.** `applyAttachments(hero, …, [])` strips the
9
+ * character; passing a list makes it wear exactly that list. Idempotent, which
10
+ * is what both callers actually want: `loadScene3D` builds a character once,
11
+ * and an editor re-applies the list every time a person changes a dropdown. An
12
+ * add/remove API would make "what is this character wearing" a thing you have
13
+ * to replay history to answer.
14
+ *
15
+ * Which socket a prop goes in is resolved from the prop itself
16
+ * (`ModelAsset3D.socket`) unless the attachment overrides it — the character
17
+ * already declares where its sockets ARE, so naming the prop is normally the
18
+ * whole instruction.
19
+ */
20
+ /** What a wearer currently has on: attachment id (or socket) → the object. */
21
+ export type WornMap = Map<string, THREE.Object3D>;
22
+ export interface ApplyAttachmentsOptions {
23
+ /** Base url props resolve against. */
24
+ assetBase?: string;
25
+ /**
26
+ * Already-fetched props, keyed by model id. `loadScene3D` passes the batch
27
+ * it downloaded in parallel; anyone else can leave it out and have them
28
+ * fetched here.
29
+ */
30
+ preloaded?: Map<string, GLTF>;
31
+ /** What this wearer has on now, so it can be taken off first. */
32
+ previous?: WornMap;
33
+ /** Names the wearer in error messages — an entity id, usually. */
34
+ label?: string;
35
+ }
36
+ /** Drop the prop cache. For a game unloading a level, and for tests. */
37
+ export declare function clearAttachmentCache(): void;
38
+ export declare function applyAttachments(wearer: THREE.Object3D, wearerAsset: ModelAsset3D, manifest: Manifest3D, list: Attachment3D[], opts?: ApplyAttachmentsOptions): Promise<WornMap>;
@@ -0,0 +1,77 @@
1
+ import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
2
+ import { clone as cloneRigged } from 'three/examples/jsm/utils/SkeletonUtils.js';
3
+ import { attachToSocket } from './Sockets.js';
4
+ const cache = new Map();
5
+ let loader = null;
6
+ function fetchProp(url) {
7
+ const hit = cache.get(url);
8
+ if (hit)
9
+ return hit;
10
+ loader ?? (loader = new GLTFLoader());
11
+ const p = loader.loadAsync(url);
12
+ cache.set(url, p);
13
+ // A prop that 404s once must not 404 for the rest of the session.
14
+ p.catch(() => cache.delete(url));
15
+ return p;
16
+ }
17
+ /** Drop the prop cache. For a game unloading a level, and for tests. */
18
+ export function clearAttachmentCache() { cache.clear(); }
19
+ function isRigged(root) {
20
+ let rigged = false;
21
+ root.traverse((o) => { if (o.isSkinnedMesh)
22
+ rigged = true; });
23
+ return rigged;
24
+ }
25
+ /**
26
+ * Take one prop back off.
27
+ *
28
+ * The object's parent is the HOLDER `attachToSocket` created to carry the
29
+ * socket offset, and that is what has to go — removing the object alone
30
+ * leaves an empty holder on the bone, and enough dressing changes leave a
31
+ * character wearing a stack of invisible ones.
32
+ */
33
+ function detach(object) {
34
+ (object.parent ?? object).removeFromParent();
35
+ }
36
+ export async function applyAttachments(wearer, wearerAsset, manifest, list, opts = {}) {
37
+ const who = opts.label ? `entity '${opts.label}'` : `model '${wearerAsset.id}'`;
38
+ const models = new Map((manifest.models ?? []).map((m) => [m.id, m]));
39
+ // Resolve the whole list BEFORE touching the character. A bad prop halfway
40
+ // down otherwise leaves it half-dressed, which is worse than unchanged.
41
+ const resolved = [];
42
+ for (const a of list) {
43
+ const prop = models.get(a.modelAssetId);
44
+ if (!prop) {
45
+ throw new Error(`${who} attaches model '${a.modelAssetId}', which the manifest does not define. ` +
46
+ `It has: ${[...models.keys()].join(', ') || '(none)'}`);
47
+ }
48
+ const socketName = a.socket ?? prop.socket;
49
+ if (!socketName) {
50
+ throw new Error(`${who} attaches '${a.modelAssetId}' with no socket, and that model declares none of ` +
51
+ `its own — give the attachment a 'socket', or the model one`);
52
+ }
53
+ const socket = wearerAsset.sockets?.[socketName];
54
+ if (!socket) {
55
+ throw new Error(`${who} wants socket '${socketName}' for '${a.modelAssetId}', but model ` +
56
+ `'${wearerAsset.id}' has: ${Object.keys(wearerAsset.sockets ?? {}).join(', ') || '(none)'}`);
57
+ }
58
+ resolved.push({ key: a.id ?? socketName, name: a.id ?? prop.id, prop, socket });
59
+ }
60
+ const gltfs = await Promise.all(resolved.map(({ prop }) => opts.preloaded?.get(prop.id) ?? fetchProp((opts.assetBase ?? '') + prop.path)));
61
+ for (const object of opts.previous?.values() ?? [])
62
+ detach(object);
63
+ const worn = new Map();
64
+ resolved.forEach(({ key, name, prop, socket }, i) => {
65
+ const gltf = gltfs[i];
66
+ // Always a clone: one prop asset can be worn by a whole squad, and the
67
+ // first wearer must not end up holding everyone's sword.
68
+ const object = isRigged(gltf.scene) ? cloneRigged(gltf.scene) : gltf.scene.clone(true);
69
+ if (prop.importScale !== undefined)
70
+ object.scale.setScalar(prop.importScale);
71
+ object.userData.modelAssetId = prop.id;
72
+ object.name = name;
73
+ attachToSocket(wearer, socket, object);
74
+ worn.set(key, object);
75
+ });
76
+ return worn;
77
+ }
@@ -1,5 +1,6 @@
1
1
  import * as THREE from 'three';
2
2
  import { type Scene3D, type Manifest3D } from './scene3d.js';
3
+ import { type WornMap } from './Attachments.js';
3
4
  export interface LoadSceneOptions {
4
5
  /** Base url assets resolve against (the project's asset host). */
5
6
  assetBase?: string;
@@ -32,7 +33,7 @@ export interface LoadedScene3D {
32
33
  clips: Map<string, THREE.AnimationClip[]>;
33
34
  /** Entity id → its props, keyed by the attachment's `id` or, failing that,
34
35
  * the socket it went into. How a game reaches the sword it authored. */
35
- attachments: Map<string, Map<string, THREE.Object3D>>;
36
+ attachments: Map<string, WornMap>;
36
37
  /** Entity id → rigid body, when physics was supplied. */
37
38
  bodies: Map<string, any>;
38
39
  world?: any;
@@ -3,7 +3,7 @@ import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
3
3
  import { clone as cloneRigged } from 'three/examples/jsm/utils/SkeletonUtils.js';
4
4
  import { validateScene, IDENTITY_QUAT, } from './scene3d.js';
5
5
  import { applySkin } from './Skin.js';
6
- import { attachToSocket } from './Sockets.js';
6
+ import { applyAttachments } from './Attachments.js';
7
7
  function toVec(v, d = 0) {
8
8
  return new THREE.Vector3(v?.x ?? d, v?.y ?? d, v?.z ?? d);
9
9
  }
@@ -152,6 +152,7 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
152
152
  // whose cast pops from placeholder to costume a frame or two later.
153
153
  const skinJobs = [];
154
154
  const attachments = new Map();
155
+ const attachJobs = [];
155
156
  for (const e of scene3d.entities) {
156
157
  let obj;
157
158
  if (e.modelAssetId) {
@@ -225,36 +226,13 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
225
226
  }
226
227
  }));
227
228
  }
228
- for (const a of e.attachments ?? []) {
229
- const prop = models.get(a.modelAssetId); // prefetch already proved it exists
230
- // The prop knows where it belongs; the scene only has to say so when
231
- // it wants it somewhere else.
232
- const socketName = a.socket ?? prop.socket;
233
- if (!socketName) {
234
- throw new Error(`entity '${e.id}' attaches '${a.modelAssetId}' with no socket, and that model ` +
235
- `declares none of its own — give the attachment a 'socket', or the model one`);
236
- }
237
- const socket = asset.sockets?.[socketName];
238
- if (!socket) {
239
- throw new Error(`entity '${e.id}' wants socket '${socketName}' for '${a.modelAssetId}', but model ` +
240
- `'${e.modelAssetId}' has: ${Object.keys(asset.sockets ?? {}).join(', ') || '(none)'}`);
241
- }
242
- const propGltf = loaded.get(a.modelAssetId);
243
- // Always a clone: one prop asset can be worn by a whole squad, and the
244
- // first wearer must not end up holding everyone's sword.
245
- const propObj = isRigged(propGltf.scene)
246
- ? cloneRigged(propGltf.scene) : propGltf.scene.clone(true);
247
- if (prop.importScale !== undefined)
248
- propObj.scale.setScalar(prop.importScale);
249
- propObj.userData.modelAssetId = a.modelAssetId;
250
- propObj.name = a.id ?? a.modelAssetId;
251
- attachToSocket(obj, socket, propObj);
252
- let mine = attachments.get(e.id);
253
- if (!mine) {
254
- mine = new Map();
255
- attachments.set(e.id, mine);
256
- }
257
- mine.set(a.id ?? socketName, propObj);
229
+ if (e.attachments?.length) {
230
+ // Deferred with the skins: both fetch, and a caller that awaits
231
+ // `loadScene3D` should get a scene that is finished rather than one
232
+ // that arms itself a frame later.
233
+ const wearer = obj;
234
+ attachJobs.push(applyAttachments(wearer, asset, manifest, e.attachments, { assetBase: opts.assetBase, preloaded: loaded, label: e.id })
235
+ .then((worn) => { attachments.set(e.id, worn); }));
258
236
  }
259
237
  }
260
238
  else {
@@ -272,8 +250,8 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
272
250
  applyTransform(obj, e);
273
251
  entities.set(e.id, obj);
274
252
  }
275
- if (skinJobs.length)
276
- await Promise.all(skinJobs);
253
+ if (skinJobs.length || attachJobs.length)
254
+ await Promise.all([...skinJobs, ...attachJobs]);
277
255
  // Parent after every entity exists, so declaration order doesn't matter.
278
256
  for (const e of scene3d.entities) {
279
257
  const obj = entities.get(e.id);
@@ -1,7 +1,9 @@
1
1
  import * as THREE from 'three';
2
2
  import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
3
- import { loadScene3D } from '../SceneLoader3D.js';
3
+ import { loadScene3D, loadModelAsset } from '../SceneLoader3D.js';
4
4
  import { applySkin } from '../Skin.js';
5
+ import { applyAttachments } from '../Attachments.js';
6
+ import { singleModelManifest } from '../scene3d.js';
5
7
  /**
6
8
  * The 3D counterpart of `@umicat/phaser-sdk`'s `EditorDesignScene` (ADR-021)
7
9
  * — renders a scene's AUTHORED data with no game code and no save, so the
@@ -77,6 +79,9 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
77
79
  const objectByEntity = new Map();
78
80
  let manifest = null;
79
81
  let sceneData = null;
82
+ // What each entity is wearing right now, so a re-dress can take the old
83
+ // set off. `loadScene3D` hands this over; every patch replaces an entry.
84
+ let worn = new Map();
80
85
  const resize = () => {
81
86
  renderer.setSize(window.innerWidth, window.innerHeight);
82
87
  camera.aspect = window.innerWidth / window.innerHeight;
@@ -85,9 +90,26 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
85
90
  resize();
86
91
  window.addEventListener('resize', resize);
87
92
  const raycaster = new THREE.Raycaster();
88
- const ndcFromEvent = (e) => {
93
+ // Split out from the pointer-event version below so a host-posted
94
+ // `{x,y}` (no real PointerEvent exists for a drop that happened on the
95
+ // HOST page, over a DOM overlay sitting on top of this iframe) can go
96
+ // through the identical math.
97
+ const ndcFromClientXY = (clientX, clientY) => {
89
98
  const rect = renderer.domElement.getBoundingClientRect();
90
- return new THREE.Vector2(((e.clientX - rect.left) / rect.width) * 2 - 1, -((e.clientY - rect.top) / rect.height) * 2 + 1);
99
+ return new THREE.Vector2(((clientX - rect.left) / rect.width) * 2 - 1, -((clientY - rect.top) / rect.height) * 2 + 1);
100
+ };
101
+ const ndcFromEvent = (e) => ndcFromClientXY(e.clientX, e.clientY);
102
+ // The drag-to-move primitive (below) with no object already grabbed:
103
+ // raycast a screen point against a horizontal plane at `groundY` and
104
+ // return the world point, or null if the camera is looking edge-on to it.
105
+ // `clientX`/`clientY` are iframe-local — the host computes them by
106
+ // subtracting its own iframe's `getBoundingClientRect()` before posting,
107
+ // same convention the 2D editor's `computeDropWorldPos` already uses.
108
+ const raycastGroundPlane = (clientX, clientY, groundY) => {
109
+ raycaster.setFromCamera(ndcFromClientXY(clientX, clientY), camera);
110
+ const plane = new THREE.Plane(new THREE.Vector3(0, 1, 0), -groundY);
111
+ const point = new THREE.Vector3();
112
+ return raycaster.ray.intersectPlane(plane, point) ? point : null;
91
113
  };
92
114
  // Only VISIBLE entity roots are ever raycast against. three.js's
93
115
  // Mesh.raycast does NOT check `.visible` on its own (confirmed against the
@@ -226,25 +248,23 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
226
248
  renderer.domElement.addEventListener('pointermove', onPointerMove);
227
249
  renderer.domElement.addEventListener('pointerup', onPointerUp);
228
250
  /**
229
- * The FIRST host→iframe message this player has ever accepted.
230
- *
231
- * Everything until now went one way: the player reported picks and drags,
232
- * and the host wrote them to disk. That works for a drag because the SDK
233
- * itself already moved the object — the canvas was correct before the host
234
- * heard about it. It does not work for a property edited in a panel: the
235
- * host changes the file, the canvas knows nothing, and the edit is invisible
236
- * until a rebuild. A property editor whose changes don't show is a property
237
- * editor nobody trusts (a sibling 2D tool shipped exactly that bug — a new
238
- * widget kind not wired into its live-patch path silently did nothing on
239
- * canvas while the Inspector happily accepted the value).
251
+ * Host→iframe messages. `patchEntity3d` (0.18.0) was the first — everything
252
+ * before it went one way: the player reported picks and drags, and the
253
+ * host wrote them to disk, which works for a drag because the SDK itself
254
+ * already moved the object. A PROPERTY edited in a panel is the opposite:
255
+ * the host changes the file and the canvas knows nothing until a rebuild —
256
+ * a sibling 2D tool shipped exactly that bug once (a widget kind not wired
257
+ * into its live-patch path silently did nothing on canvas).
240
258
  *
241
- * So: `patchEntity3d` in, `patchApplied3d` out. The ack matters as much as
242
- * the patch — the host has ALREADY written the file by the time this runs,
243
- * so a failure here means disk and canvas disagree, and the only way anyone
244
- * finds out is if this says so.
259
+ * `dropModel3d` (0.22.0) is the second, for the Assets-panel drag-and-drop
260
+ * feature: a host-side drop has no live `THREE.Object3D` yet to self-apply
261
+ * the way a drag does, so the host can't "just do it and tell us" — it has
262
+ * to ask this player to place AND load the thing.
245
263
  *
246
- * `patch` is an open bag deliberately: skin is the first field, and adding
247
- * rotation/scale/visible later should be a new `if`, not a new message.
264
+ * Every message gets an ack. The host writes to disk either right before
265
+ * (`patchEntity3d`) or right after (`dropModel3d`, once it knows this
266
+ * succeeded) sending — so a silent failure here always means disk and
267
+ * canvas disagree, and nothing else would ever say so.
248
268
  */
249
269
  async function onHostMessage(event) {
250
270
  // Source-identity, not origin: the host page and this iframe are on
@@ -253,9 +273,18 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
253
273
  if (event.source !== window.parent)
254
274
  return;
255
275
  const data = event.data;
256
- if (!data || typeof data !== 'object' || data.type !== 'umicat:editor:patchEntity3d')
276
+ if (!data || typeof data !== 'object' || typeof data.type !== 'string')
257
277
  return;
258
- const m = data;
278
+ if (data.type === 'umicat:editor:patchEntity3d')
279
+ return onPatchEntity3d(data);
280
+ if (data.type === 'umicat:editor:dropModel3d')
281
+ return onDropModel3d(data);
282
+ }
283
+ /**
284
+ * `patch` is an open bag deliberately: skin is the first field, and adding
285
+ * rotation/scale/visible later should be a new `if`, not a new message.
286
+ */
287
+ async function onPatchEntity3d(m) {
259
288
  const done = (error) => {
260
289
  if (error)
261
290
  console.warn('[umicat/editor] 3D patch failed:', m.entityId, error);
@@ -264,6 +293,21 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
264
293
  const object = objectByEntity.get(m.entityId);
265
294
  if (!object)
266
295
  return done(`no entity '${m.entityId}' in the scene being shown`);
296
+ if (m.patch?.attachments !== undefined) {
297
+ const authored = sceneData?.entities.find((e) => e.id === m.entityId);
298
+ const asset = manifest?.models?.find((x) => x.id === authored?.modelAssetId);
299
+ if (!asset)
300
+ return done(`entity '${m.entityId}' has no model to hang props on`);
301
+ try {
302
+ // Whole-list, so the panel can say "this is the outfit" rather than
303
+ // having to work out a diff against what is already on.
304
+ const next = await applyAttachments(object, asset, manifest, m.patch.attachments, { assetBase: '', previous: worn.get(m.entityId), label: m.entityId });
305
+ worn.set(m.entityId, next);
306
+ }
307
+ catch (e) {
308
+ return done(e instanceof Error ? e.message : String(e));
309
+ }
310
+ }
267
311
  if (m.patch?.skin !== undefined) {
268
312
  const authored = sceneData?.entities.find((e) => e.id === m.entityId);
269
313
  const asset = manifest?.models?.find((x) => x.id === authored?.modelAssetId);
@@ -284,6 +328,61 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
284
328
  }
285
329
  done();
286
330
  }
331
+ /**
332
+ * Drag a model from the Assets panel onto the canvas: raycast the drop
333
+ * point against the ground plane (the exact technique drag-to-move already
334
+ * uses, just with no object grabbed yet to anchor the plane — groundY is
335
+ * always 0, since no scene declares a ground height today and every
336
+ * shipped scene's floor sits at the origin by convention), fetch + parse
337
+ * the GLB from its CDN url directly (`singleModelManifest` +
338
+ * `loadModelAsset` — no manifest entry needed, these two exports exist
339
+ * specifically for a one-off model with no authored id), and register it
340
+ * into the SAME maps the loader populates at scene-load time so it is
341
+ * immediately pickable (`pickEntityAt`) and draggable (`onPointerDown`/
342
+ * `onPointerMove`) with zero changes to either.
343
+ *
344
+ * The host persists this to `scenes3d/<id>.json` + `manifest.json` only
345
+ * AFTER seeing `ok:true` here — so `sceneData`/`manifest` are updated
346
+ * in-place too, to keep this session's own `patchEntity3d` (re-skin,
347
+ * attach a prop) working on the just-dropped entity before any reload
348
+ * picks the disk copy back up.
349
+ */
350
+ async function onDropModel3d(m) {
351
+ const done = (error, position) => {
352
+ if (error)
353
+ console.warn('[umicat/editor] 3D model drop failed:', m.entityId, error);
354
+ window.parent.postMessage({ type: 'umicat:editor:modelDropped3d', entityId: m.entityId, ok: !error, error, position }, '*');
355
+ };
356
+ if (!scene)
357
+ return done('no scene loaded yet');
358
+ if (objectByEntity.has(m.entityId))
359
+ return done(`entity '${m.entityId}' already exists in this scene`);
360
+ const worldPoint = raycastGroundPlane(m.x, m.y, 0);
361
+ if (!worldPoint)
362
+ return done('the drop point does not land on the ground plane (camera is looking edge-on)');
363
+ const modelAsset = { id: m.entityId, path: m.modelUrl, importScale: m.importScale };
364
+ let object;
365
+ try {
366
+ const loaded = await loadModelAsset(singleModelManifest(modelAsset), m.entityId, { assetBase: '' });
367
+ object = loaded.object;
368
+ }
369
+ catch (e) {
370
+ return done(e instanceof Error ? e.message : String(e));
371
+ }
372
+ object.position.copy(worldPoint);
373
+ // `Entity3D.castShadow` defaults true (scene3d.ts) — match that default
374
+ // for a dropped entity, same as every authored one already gets via
375
+ // `loadScene3D`.
376
+ object.traverse((n) => { n.castShadow = true; n.receiveShadow = true; });
377
+ scene.add(object);
378
+ entityByObject.set(object, m.entityId);
379
+ objectByEntity.set(m.entityId, object);
380
+ // Keep this session's own closure state consistent with what the host
381
+ // is about to write to disk — see the doc comment above.
382
+ sceneData?.entities.push({ id: m.entityId, modelAssetId: m.entityId, transform: { position: { ...worldPoint } } });
383
+ manifest?.models?.push(modelAsset);
384
+ done(undefined, { x: object.position.x, y: object.position.y, z: object.position.z });
385
+ }
287
386
  window.addEventListener('message', (e) => { void onHostMessage(e); });
288
387
  // Design mode skips physics and animation entirely (loadScene3D's own
289
388
  // designMode flag) — there are no mixers to advance and no Rapier world to
@@ -322,6 +421,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
322
421
  manifest = await fetch('scenes3d/manifest.json').then((r) => r.json());
323
422
  sceneData = await fetch(`scenes3d/${sceneId}.json`).then((r) => r.json());
324
423
  const loaded = await loadScene3D(sceneData, manifest, { assetBase: '', designMode: true });
424
+ worn = loaded.attachments;
325
425
  scene = loaded.scene;
326
426
  entityByObject.clear();
327
427
  objectByEntity.clear();
package/dist/index.d.ts CHANGED
@@ -11,6 +11,8 @@ export type { Input3DOptions, Input3DAction } from './Input3D.js';
11
11
  export { attachToSocket, findBone, boneNames } from './Sockets.js';
12
12
  export { flashTint, updateTints, isTinted } from './Tint.js';
13
13
  export { applySkin, applySkinTexture, loadSkinTexture, clearSkinCache } from './Skin.js';
14
+ export { applyAttachments, clearAttachmentCache } from './Attachments.js';
15
+ export type { WornMap, ApplyAttachmentsOptions } from './Attachments.js';
14
16
  export type { SkinOptions, SkinResult } from './Skin.js';
15
17
  export { GameAudio } from './GameAudio.js';
16
18
  export type { GameAudioOptions, AudioClipSpec } from './GameAudio.js';
package/dist/index.js CHANGED
@@ -12,6 +12,7 @@ export { Input3D } from './Input3D.js';
12
12
  export { attachToSocket, findBone, boneNames } from './Sockets.js';
13
13
  export { flashTint, updateTints, isTinted } from './Tint.js';
14
14
  export { applySkin, applySkinTexture, loadSkinTexture, clearSkinCache } from './Skin.js';
15
+ export { applyAttachments, clearAttachmentCache } from './Attachments.js';
15
16
  export { GameAudio } from './GameAudio.js';
16
17
  export { setupScreenshotListener, takeScreenshot } from './capture/ScreenshotManager.js';
17
18
  export { setupRecordingListener } from './capture/RecordingManager.js';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "0.20.0",
3
+ "version": "0.22.0",
4
4
  "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.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",