@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 +16 -5
- package/dist/editor/EditorDesignPlayer3D.js +102 -22
- package/package.json +1 -1
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
|
|
8
|
-
is
|
|
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,
|
|
13
|
-
editor's screenshot/video-capture protocol
|
|
14
|
-
|
|
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
|
-
|
|
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(((
|
|
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
|
-
*
|
|
234
|
-
*
|
|
235
|
-
*
|
|
236
|
-
*
|
|
237
|
-
*
|
|
238
|
-
*
|
|
239
|
-
*
|
|
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
|
-
*
|
|
246
|
-
*
|
|
247
|
-
*
|
|
248
|
-
*
|
|
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
|
-
*
|
|
251
|
-
*
|
|
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 !== '
|
|
276
|
+
if (!data || typeof data !== 'object' || typeof data.type !== 'string')
|
|
261
277
|
return;
|
|
262
|
-
|
|
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.
|
|
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",
|