@umicat/three-sdk 0.21.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
@@ -1,8 +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
5
  import { applyAttachments } from '../Attachments.js';
6
+ import { singleModelManifest } from '../scene3d.js';
6
7
  /**
7
8
  * The 3D counterpart of `@umicat/phaser-sdk`'s `EditorDesignScene` (ADR-021)
8
9
  * — renders a scene's AUTHORED data with no game code and no save, so the
@@ -89,9 +90,26 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
89
90
  resize();
90
91
  window.addEventListener('resize', resize);
91
92
  const raycaster = new THREE.Raycaster();
92
- 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) => {
93
98
  const rect = renderer.domElement.getBoundingClientRect();
94
- 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;
95
113
  };
96
114
  // Only VISIBLE entity roots are ever raycast against. three.js's
97
115
  // Mesh.raycast does NOT check `.visible` on its own (confirmed against the
@@ -230,25 +248,23 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
230
248
  renderer.domElement.addEventListener('pointermove', onPointerMove);
231
249
  renderer.domElement.addEventListener('pointerup', onPointerUp);
232
250
  /**
233
- * The FIRST host→iframe message this player has ever accepted.
234
- *
235
- * Everything until now went one way: the player reported picks and drags,
236
- * and the host wrote them to disk. That works for a drag because the SDK
237
- * itself already moved the object — the canvas was correct before the host
238
- * heard about it. It does not work for a property edited in a panel: the
239
- * host changes the file, the canvas knows nothing, and the edit is invisible
240
- * until a rebuild. A property editor whose changes don't show is a property
241
- * editor nobody trusts (a sibling 2D tool shipped exactly that bug — a new
242
- * widget kind not wired into its live-patch path silently did nothing on
243
- * 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).
244
258
  *
245
- * So: `patchEntity3d` in, `patchApplied3d` out. The ack matters as much as
246
- * the patch — the host has ALREADY written the file by the time this runs,
247
- * so a failure here means disk and canvas disagree, and the only way anyone
248
- * 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.
249
263
  *
250
- * `patch` is an open bag deliberately: skin is the first field, and adding
251
- * 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.
252
268
  */
253
269
  async function onHostMessage(event) {
254
270
  // Source-identity, not origin: the host page and this iframe are on
@@ -257,9 +273,18 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
257
273
  if (event.source !== window.parent)
258
274
  return;
259
275
  const data = event.data;
260
- if (!data || typeof data !== 'object' || data.type !== 'umicat:editor:patchEntity3d')
276
+ if (!data || typeof data !== 'object' || typeof data.type !== 'string')
261
277
  return;
262
- 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) {
263
288
  const done = (error) => {
264
289
  if (error)
265
290
  console.warn('[umicat/editor] 3D patch failed:', m.entityId, error);
@@ -303,6 +328,61 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
303
328
  }
304
329
  done();
305
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
+ }
306
386
  window.addEventListener('message', (e) => { void onHostMessage(e); });
307
387
  // Design mode skips physics and animation entirely (loadScene3D's own
308
388
  // designMode flag) — there are no mixers to advance and no Rapier world to
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "0.21.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",