@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 +18 -6
- package/dist/Attachments.d.ts +38 -0
- package/dist/Attachments.js +77 -0
- package/dist/SceneLoader3D.d.ts +2 -1
- package/dist/SceneLoader3D.js +11 -33
- package/dist/editor/EditorDesignPlayer3D.js +122 -22
- package/dist/index.d.ts +2 -0
- package/dist/index.js +1 -0
- 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
|
|
@@ -24,7 +35,8 @@ editor.
|
|
|
24
35
|
│
|
|
25
36
|
@umicat/three-sdk ThreeUmicat · scene3d · loadScene3D · physics · Input3D
|
|
26
37
|
CharacterController3D · CharacterAnimator · GameAudio
|
|
27
|
-
sockets ·
|
|
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
|
+
}
|
package/dist/SceneLoader3D.d.ts
CHANGED
|
@@ -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,
|
|
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;
|
package/dist/SceneLoader3D.js
CHANGED
|
@@ -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 {
|
|
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
|
-
|
|
229
|
-
|
|
230
|
-
//
|
|
231
|
-
//
|
|
232
|
-
const
|
|
233
|
-
|
|
234
|
-
|
|
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
|
-
|
|
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(((
|
|
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
|
-
*
|
|
230
|
-
*
|
|
231
|
-
*
|
|
232
|
-
*
|
|
233
|
-
*
|
|
234
|
-
*
|
|
235
|
-
*
|
|
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
|
-
*
|
|
242
|
-
*
|
|
243
|
-
*
|
|
244
|
-
*
|
|
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
|
-
*
|
|
247
|
-
*
|
|
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 !== '
|
|
276
|
+
if (!data || typeof data !== 'object' || typeof data.type !== 'string')
|
|
257
277
|
return;
|
|
258
|
-
|
|
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.
|
|
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",
|