@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.
@@ -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;
@@ -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.8.0",
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",