@umicat/three-sdk 1.8.0 → 1.9.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/dist/SceneLoader3D.d.ts
CHANGED
|
@@ -54,6 +54,7 @@ export interface LoadedScene3D {
|
|
|
54
54
|
update(dt: number): void;
|
|
55
55
|
dispose(): void;
|
|
56
56
|
}
|
|
57
|
+
export declare function applyTransform(obj: THREE.Object3D, e: Entity3D): void;
|
|
57
58
|
export declare const MATERIAL_LIBRARY: Record<string, {
|
|
58
59
|
color: string;
|
|
59
60
|
roughness: string;
|
package/dist/SceneLoader3D.js
CHANGED
|
@@ -20,7 +20,7 @@ function isRigged(root) {
|
|
|
20
20
|
rigged = true; });
|
|
21
21
|
return rigged;
|
|
22
22
|
}
|
|
23
|
-
function applyTransform(obj, e) {
|
|
23
|
+
export function applyTransform(obj, e) {
|
|
24
24
|
const t = e.transform;
|
|
25
25
|
obj.position.copy(toVec(t.position));
|
|
26
26
|
const q = t.rotation ?? IDENTITY_QUAT;
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import * as THREE from 'three';
|
|
2
2
|
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
|
|
3
|
-
import { loadScene3D, loadModelAsset, makePrimitive } from '../SceneLoader3D.js';
|
|
3
|
+
import { loadScene3D, loadModelAsset, makePrimitive, applyTransform } from '../SceneLoader3D.js';
|
|
4
4
|
import { applySkin } from '../Skin.js';
|
|
5
5
|
import { applyAttachments } from '../Attachments.js';
|
|
6
6
|
import { singleModelManifest, defaultColliderForPrimitive, groundRestOffset } from '../scene3d.js';
|
|
@@ -393,6 +393,20 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
393
393
|
scale: { x: o.scale.x, y: o.scale.y, z: o.scale.z },
|
|
394
394
|
};
|
|
395
395
|
};
|
|
396
|
+
// ADR-045 — test-only readback of an entity's WORLD position, distinct
|
|
397
|
+
// from `__umicatEntityTransform` above which returns LOCAL (parent-
|
|
398
|
+
// relative) position. Needed because `Object3D.attach()` (reparenting)
|
|
399
|
+
// deliberately CHANGES local position to preserve world position — a
|
|
400
|
+
// test asserting "position unchanged across a reparent" must check
|
|
401
|
+
// world, not local, or it fails on perfectly correct behavior.
|
|
402
|
+
globalThis.__umicatEntityWorldPosition =
|
|
403
|
+
(entityId) => {
|
|
404
|
+
const o = objectByEntity.get(entityId);
|
|
405
|
+
if (!o)
|
|
406
|
+
return null;
|
|
407
|
+
const p = o.getWorldPosition(new THREE.Vector3());
|
|
408
|
+
return { x: p.x, y: p.y, z: p.z };
|
|
409
|
+
};
|
|
396
410
|
// ADR-044 — test-only readback of a Part's live material state: whether
|
|
397
411
|
// its async-loaded textures actually landed (`hasMap`/`hasRoughnessMap`),
|
|
398
412
|
// what repeat they resolved to (proves `materialRepeatFor`'s size-based
|
|
@@ -463,6 +477,14 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
463
477
|
let lookDragging = false;
|
|
464
478
|
let lastLookX = 0;
|
|
465
479
|
let lastLookY = 0;
|
|
480
|
+
// ADR-045 — right-click-NO-drag opens the context menu; right-click-DRAG
|
|
481
|
+
// orbits the camera (the look-drag state just above). Same "orbit-vs-
|
|
482
|
+
// click" distinction `downX`/`downY`/`moved` already draws for the LEFT
|
|
483
|
+
// button, tracked separately because `onPointerDown`'s button===2 branch
|
|
484
|
+
// returns before ever touching those.
|
|
485
|
+
let rightDownX = 0;
|
|
486
|
+
let rightDownY = 0;
|
|
487
|
+
let rightMoved = false;
|
|
466
488
|
// Entity drag — Phase 1 of real editing (translate only, ground-plane
|
|
467
489
|
// constrained). Grabbing on an entity moves it; grabbing empty space/sky
|
|
468
490
|
// still orbits, same convention as Unity/Blender. Whether THIS gesture is
|
|
@@ -597,6 +619,9 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
597
619
|
lookDragging = true;
|
|
598
620
|
lastLookX = e.clientX;
|
|
599
621
|
lastLookY = e.clientY;
|
|
622
|
+
rightDownX = e.clientX;
|
|
623
|
+
rightDownY = e.clientY;
|
|
624
|
+
rightMoved = false;
|
|
600
625
|
try {
|
|
601
626
|
renderer.domElement.setPointerCapture(e.pointerId);
|
|
602
627
|
}
|
|
@@ -675,6 +700,8 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
675
700
|
};
|
|
676
701
|
const onPointerMove = (e) => {
|
|
677
702
|
if (lookDragging) {
|
|
703
|
+
if (Math.abs(e.clientX - rightDownX) > 4 || Math.abs(e.clientY - rightDownY) > 4)
|
|
704
|
+
rightMoved = true;
|
|
678
705
|
applyLookDelta(e.clientX - lastLookX, e.clientY - lastLookY);
|
|
679
706
|
lastLookX = e.clientX;
|
|
680
707
|
lastLookY = e.clientY;
|
|
@@ -715,6 +742,33 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
715
742
|
catch {
|
|
716
743
|
// Already released, or never captured.
|
|
717
744
|
}
|
|
745
|
+
// ADR-045 — a right-click that didn't rotate the camera opens the
|
|
746
|
+
// context menu. Same hit-test + selection side effects a left click
|
|
747
|
+
// already runs (marker/selectionBox/gizmo + `pickPoint3d`) — Roblox
|
|
748
|
+
// itself selects-on-right-click too, so right-clicking an unselected
|
|
749
|
+
// Part both selects it AND opens its menu in one action, rather than
|
|
750
|
+
// requiring a left-click first. Empty space still deselects, but
|
|
751
|
+
// still posts the menu message (with `entityId: null`) — the host
|
|
752
|
+
// decides whether an empty-space menu is worth showing (e.g. Paste).
|
|
753
|
+
if (!scene || rightMoved)
|
|
754
|
+
return;
|
|
755
|
+
const hit = pickEntityAt(e);
|
|
756
|
+
if (!hit) {
|
|
757
|
+
clearWorldSelection();
|
|
758
|
+
if (hudSelectedId)
|
|
759
|
+
selectHudEntity(null);
|
|
760
|
+
window.parent.postMessage({ type: 'umicat:editor:contextMenu3d', entityId: null, clientX: e.clientX, clientY: e.clientY }, '*');
|
|
761
|
+
return;
|
|
762
|
+
}
|
|
763
|
+
if (hudSelectedId)
|
|
764
|
+
selectHudEntity(null);
|
|
765
|
+
marker.position.copy(hit.point);
|
|
766
|
+
marker.visible = true;
|
|
767
|
+
selectionBox.setFromObject(hit.entityRoot);
|
|
768
|
+
selectionBox.visible = true;
|
|
769
|
+
gizmo.attach(hit.entityRoot, camera);
|
|
770
|
+
window.parent.postMessage({ type: 'umicat:editor:pickPoint3d', x: hit.point.x, y: hit.point.y, z: hit.point.z, entityId: hit.entityId }, '*');
|
|
771
|
+
window.parent.postMessage({ type: 'umicat:editor:contextMenu3d', entityId: hit.entityId, clientX: e.clientX, clientY: e.clientY }, '*');
|
|
718
772
|
return;
|
|
719
773
|
}
|
|
720
774
|
if (e.button !== 0)
|
|
@@ -832,6 +886,8 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
832
886
|
return onDropModel3d(data);
|
|
833
887
|
if (data.type === 'umicat:editor:dropPrimitive3d')
|
|
834
888
|
return onDropPrimitive3d(data);
|
|
889
|
+
if (data.type === 'umicat:editor:createEntity3d')
|
|
890
|
+
return onCreateEntity3d(data);
|
|
835
891
|
if (data.type === 'umicat:editor:deleteEntity3d')
|
|
836
892
|
return onDeleteEntity3d(data);
|
|
837
893
|
if (data.type === 'umicat:editor:setGizmoMode3d') {
|
|
@@ -935,6 +991,26 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
935
991
|
// explicit refresh here, same as a live drag already does.
|
|
936
992
|
selectionBox.setFromObject(object);
|
|
937
993
|
}
|
|
994
|
+
if (m.patch?.parent !== undefined) {
|
|
995
|
+
// ADR-045 Phase 2 — reparent. `Object3D.attach` (standard three.js
|
|
996
|
+
// API) moves `object` under the new parent AND recomputes its local
|
|
997
|
+
// transform so its WORLD position/rotation/scale is unchanged —
|
|
998
|
+
// grouping an entity must not visually move it. `null` means attach
|
|
999
|
+
// to the scene root.
|
|
1000
|
+
const newParentObject = m.patch.parent === null ? scene : objectByEntity.get(m.patch.parent);
|
|
1001
|
+
if (!newParentObject)
|
|
1002
|
+
return done(`no parent entity '${m.patch.parent}' in the scene being shown`);
|
|
1003
|
+
newParentObject.attach(object);
|
|
1004
|
+
const authored = sceneData?.entities.find((en) => en.id === m.entityId);
|
|
1005
|
+
if (authored) {
|
|
1006
|
+
if (m.patch.parent === null)
|
|
1007
|
+
delete authored.parent;
|
|
1008
|
+
else
|
|
1009
|
+
authored.parent = m.patch.parent;
|
|
1010
|
+
}
|
|
1011
|
+
if (gizmo.attached === object)
|
|
1012
|
+
selectionBox.setFromObject(object);
|
|
1013
|
+
}
|
|
938
1014
|
if (m.patch?.attachments !== undefined) {
|
|
939
1015
|
const authored = sceneData?.entities.find((e) => e.id === m.entityId);
|
|
940
1016
|
const asset = manifest?.models?.find((x) => x.id === authored?.modelAssetId);
|
|
@@ -1128,6 +1204,101 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
1128
1204
|
sceneData?.entities.push(entity);
|
|
1129
1205
|
done(undefined, { x: object.position.x, y: object.position.y, z: object.position.z }, collider);
|
|
1130
1206
|
}
|
|
1207
|
+
/**
|
|
1208
|
+
* ADR-045 — spawn a COMPLETE, host-supplied entity at its OWN authored
|
|
1209
|
+
* transform. The generic counterpart to `dropModel3d`/`dropPrimitive3d`
|
|
1210
|
+
* (both raycast-based: host sends a screen pixel, SDK finds where it
|
|
1211
|
+
* lands on the ground) — Paste/Duplicate need the opposite: place at an
|
|
1212
|
+
* EXPLICIT position (the original's, or a small offset from it), never
|
|
1213
|
+
* a raycast. Registers into the same `entityByObject`/`objectByEntity`/
|
|
1214
|
+
* `scene`/`sceneData` as every other creation path, so the result is
|
|
1215
|
+
* immediately pickable/draggable with zero changes to `pickEntityAt` or
|
|
1216
|
+
* the gizmo.
|
|
1217
|
+
*
|
|
1218
|
+
* Reuses `applyTransform` (position AND rotation AND scale — unlike a
|
|
1219
|
+
* fresh drop, a copy must preserve the ORIGINAL's full transform, not
|
|
1220
|
+
* just land at a ground point with identity rotation/scale) and, for a
|
|
1221
|
+
* model entity carrying a `skin`/`attachments`, best-effort re-applies
|
|
1222
|
+
* them too (logged, not fatal — a cosmetic miss on a re-skin must not
|
|
1223
|
+
* block the entity from existing at all, unlike a direct user-initiated
|
|
1224
|
+
* patch where failing loudly is correct).
|
|
1225
|
+
*/
|
|
1226
|
+
async function onCreateEntity3d(m) {
|
|
1227
|
+
const e = m.entity;
|
|
1228
|
+
const done = (error) => {
|
|
1229
|
+
if (error)
|
|
1230
|
+
console.warn('[umicat/editor] 3D entity create failed:', e.id, error);
|
|
1231
|
+
window.parent.postMessage({ type: 'umicat:editor:entityCreated3d', entityId: e.id, ok: !error, error }, '*');
|
|
1232
|
+
};
|
|
1233
|
+
if (!scene)
|
|
1234
|
+
return done('no scene loaded yet');
|
|
1235
|
+
if (objectByEntity.has(e.id))
|
|
1236
|
+
return done(`entity '${e.id}' already exists in this scene`);
|
|
1237
|
+
let object;
|
|
1238
|
+
if (e.modelAssetId) {
|
|
1239
|
+
const asset = manifest?.models?.find((x) => x.id === e.modelAssetId);
|
|
1240
|
+
if (!asset)
|
|
1241
|
+
return done(`entity references model '${e.modelAssetId}', which the manifest does not define`);
|
|
1242
|
+
try {
|
|
1243
|
+
const loaded = await loadModelAsset(singleModelManifest(asset), e.modelAssetId, { assetBase: '' });
|
|
1244
|
+
object = loaded.object;
|
|
1245
|
+
}
|
|
1246
|
+
catch (err) {
|
|
1247
|
+
return done(err instanceof Error ? err.message : String(err));
|
|
1248
|
+
}
|
|
1249
|
+
object.traverse((n) => { n.castShadow = e.castShadow !== false; n.receiveShadow = true; });
|
|
1250
|
+
if (e.skin) {
|
|
1251
|
+
const path = asset.skins?.[e.skin];
|
|
1252
|
+
if (path) {
|
|
1253
|
+
try {
|
|
1254
|
+
await applySkin(object, path, { assetBase: '' });
|
|
1255
|
+
}
|
|
1256
|
+
catch (err) {
|
|
1257
|
+
console.warn('[umicat/editor] re-skin on create failed (kept base texture):', e.id, err);
|
|
1258
|
+
}
|
|
1259
|
+
}
|
|
1260
|
+
}
|
|
1261
|
+
if (e.attachments?.length) {
|
|
1262
|
+
try {
|
|
1263
|
+
const worn_ = await applyAttachments(object, asset, manifest, e.attachments, { assetBase: '', label: e.id });
|
|
1264
|
+
worn.set(e.id, worn_);
|
|
1265
|
+
}
|
|
1266
|
+
catch (err) {
|
|
1267
|
+
console.warn('[umicat/editor] re-attaching props on create failed (created bare):', e.id, err);
|
|
1268
|
+
}
|
|
1269
|
+
}
|
|
1270
|
+
}
|
|
1271
|
+
else if (e.primitive) {
|
|
1272
|
+
object = makePrimitive(e);
|
|
1273
|
+
object.castShadow = e.primitive.kind !== 'plane';
|
|
1274
|
+
object.receiveShadow = true;
|
|
1275
|
+
}
|
|
1276
|
+
else {
|
|
1277
|
+
// Neither model nor primitive — an empty transform/pivot node.
|
|
1278
|
+
// ADR-045 Phase 2's "Group as Model" container is exactly this.
|
|
1279
|
+
object = new THREE.Group();
|
|
1280
|
+
}
|
|
1281
|
+
applyTransform(object, e);
|
|
1282
|
+
// Honor an authored `parent` the same way `loadScene3D`'s own spawn loop
|
|
1283
|
+
// does — a pasted copy of a grouped entity carries its `parent` field
|
|
1284
|
+
// along (Copy reads the full entity JSON verbatim), and the authored
|
|
1285
|
+
// `transform` on such an entity is PARENT-LOCAL, not world. Defaulting
|
|
1286
|
+
// to `scene.add` here would silently place it at scene root with its
|
|
1287
|
+
// local offset misread as a world position — right on screen until the
|
|
1288
|
+
// next load, which WOULD honor `parent` and jump it.
|
|
1289
|
+
let parentObject = scene;
|
|
1290
|
+
if (e.parent) {
|
|
1291
|
+
const resolved = objectByEntity.get(e.parent);
|
|
1292
|
+
if (!resolved)
|
|
1293
|
+
return done(`entity references parent '${e.parent}', which does not exist in this scene`);
|
|
1294
|
+
parentObject = resolved;
|
|
1295
|
+
}
|
|
1296
|
+
parentObject.add(object);
|
|
1297
|
+
entityByObject.set(object, e.id);
|
|
1298
|
+
objectByEntity.set(e.id, object);
|
|
1299
|
+
sceneData?.entities.push(e);
|
|
1300
|
+
done();
|
|
1301
|
+
}
|
|
1131
1302
|
/**
|
|
1132
1303
|
* Frees a subtree's GPU resources the same way the whole-scene `dispose()`
|
|
1133
1304
|
* in `SceneLoader3D.ts` does (geometry + material + every texture field a
|
|
@@ -1244,6 +1415,34 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
1244
1415
|
e.preventDefault();
|
|
1245
1416
|
window.parent.postMessage({ type: 'umicat:editor:requestUndo3d' }, '*');
|
|
1246
1417
|
}
|
|
1418
|
+
else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'c' && gizmo.attached) {
|
|
1419
|
+
// ADR-045 — same "ask, don't act" shape as Undo above: the CLIPBOARD
|
|
1420
|
+
// lives on the host (Copy is a pure read of the host's own scene
|
|
1421
|
+
// copy), so this player can't act on it locally the way Delete does.
|
|
1422
|
+
const entityId = entityByObject.get(gizmo.attached);
|
|
1423
|
+
if (entityId) {
|
|
1424
|
+
e.preventDefault();
|
|
1425
|
+
window.parent.postMessage({ type: 'umicat:editor:requestCopy3d', entityId }, '*');
|
|
1426
|
+
}
|
|
1427
|
+
}
|
|
1428
|
+
else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'x' && gizmo.attached) {
|
|
1429
|
+
const entityId = entityByObject.get(gizmo.attached);
|
|
1430
|
+
if (entityId) {
|
|
1431
|
+
e.preventDefault();
|
|
1432
|
+
window.parent.postMessage({ type: 'umicat:editor:requestCut3d', entityId }, '*');
|
|
1433
|
+
}
|
|
1434
|
+
}
|
|
1435
|
+
else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'v') {
|
|
1436
|
+
e.preventDefault();
|
|
1437
|
+
window.parent.postMessage({ type: 'umicat:editor:requestPaste3d' }, '*');
|
|
1438
|
+
}
|
|
1439
|
+
else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'd' && gizmo.attached) {
|
|
1440
|
+
const entityId = entityByObject.get(gizmo.attached);
|
|
1441
|
+
if (entityId) {
|
|
1442
|
+
e.preventDefault();
|
|
1443
|
+
window.parent.postMessage({ type: 'umicat:editor:requestDuplicate3d', entityId }, '*');
|
|
1444
|
+
}
|
|
1445
|
+
}
|
|
1247
1446
|
});
|
|
1248
1447
|
// WASD/QE fly-camera + Shift speed boost — held-STATE, not a discrete
|
|
1249
1448
|
// action, so this is a separate keydown/keyup PAIR rather than folded
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@umicat/three-sdk",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.9.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",
|