@umicat/three-sdk 1.24.0 → 1.26.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.
@@ -876,6 +876,12 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
876
876
  obj.userData.properties = e.properties;
877
877
  if (e.visible === false)
878
878
  obj.visible = false;
879
+ // `editorHidden` is authoring state, not game state — it hides the entity
880
+ // in the DESIGN VIEW and nowhere else. A scene loaded by the running game
881
+ // ignores it entirely, which is what separates it from `visible` and is
882
+ // why it can be toggled freely without changing what players see.
883
+ if (opts.designMode && e.editorHidden)
884
+ obj.visible = false;
879
885
  applyTransform(obj, e);
880
886
  entities.set(e.id, obj);
881
887
  }
@@ -535,6 +535,20 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
535
535
  // is here because the thing most likely to break on a rebuild is not the
536
536
  // geometry (visibly wrong) but the instance SWAP: a gizmo still pointing at
537
537
  // the disposed mesh renders its handles and moves nothing.
538
+ // Test-only — which entities are selected, and where one is. Both exist for
539
+ // the ground-marquee regression: the claim there is "the ground did NOT
540
+ // move AND both Parts got selected", and neither half is observable from
541
+ // the host protocol alone (a drag that moves nothing posts nothing).
542
+ globalThis.__umicatSelectedIds =
543
+ () => [...multiSelected].map((o) => entityByObject.get(o)).filter((id) => !!id);
544
+ globalThis.__umicatEntityWorldPos =
545
+ (entityId) => {
546
+ const o = objectByEntity.get(entityId);
547
+ if (!o)
548
+ return null;
549
+ const p = o.getWorldPosition(new THREE.Vector3());
550
+ return { x: p.x, y: p.y, z: p.z };
551
+ };
538
552
  globalThis.__umicatEntityMesh =
539
553
  (entityId) => {
540
554
  const o = objectByEntity.get(entityId);
@@ -640,9 +654,24 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
640
654
  // separately-placed visible ground models — without this filter, a click
641
655
  // that visibly lands on the rendered ground can silently return the
642
656
  // collider's coordinates instead.
657
+ /**
658
+ * Hidden or locked — either way the canvas ignores it. Hidden entities are
659
+ * not drawn; locked ones stay visible but inert, which is the whole point:
660
+ * a ground plane you can see, build on, and never accidentally grab.
661
+ *
662
+ * Mirrors 2D's `editorHidden`/`editorLocked` semantics exactly, down to
663
+ * sharing one hit-test skip.
664
+ */
665
+ const isInert = (entityId) => {
666
+ if (!entityId)
667
+ return false;
668
+ const a = sceneData?.entities.find((en) => en.id === entityId);
669
+ return a?.editorHidden === true || a?.editorLocked === true;
670
+ };
643
671
  const pickEntityAt = (e) => {
644
672
  raycaster.setFromCamera(ndcFromEvent(e), camera);
645
- const targets = Array.from(entityByObject.keys()).filter((o) => o.visible !== false);
673
+ const targets = Array.from(entityByObject.keys())
674
+ .filter((o) => o.visible !== false && !isInert(entityByObject.get(o)));
646
675
  const hits = raycaster.intersectObjects(targets, true);
647
676
  if (hits.length === 0)
648
677
  return null;
@@ -867,7 +896,13 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
867
896
  const worldPos = new THREE.Vector3();
868
897
  const camSpace = new THREE.Vector3();
869
898
  const hits = [];
870
- for (const obj of objectByEntity.values()) {
899
+ for (const [entityId, obj] of objectByEntity) {
900
+ // A marquee must skip hidden and locked entities for the same reason a
901
+ // click does — otherwise locking the ground would stop you grabbing it
902
+ // but still let a box-select scoop it up, which is a lock that does not
903
+ // lock.
904
+ if (isInert(entityId))
905
+ continue;
871
906
  obj.getWorldPosition(worldPos);
872
907
  camSpace.copy(worldPos).applyMatrix4(camera.matrixWorldInverse);
873
908
  if (camSpace.z > -camera.near)
@@ -1214,6 +1249,36 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1214
1249
  catch { /* enhancement only */ }
1215
1250
  return;
1216
1251
  }
1252
+ // Drag-to-move applies ONLY to something already selected. Dragging from
1253
+ // an UNSELECTED entity starts a marquee instead, and a click that never
1254
+ // moves still selects it on release.
1255
+ //
1256
+ // Why: a plain left-drag used to mean "move whatever is under the
1257
+ // cursor", which made box-select unreachable in the most ordinary scene
1258
+ // there is. A baseplate-style ground is a real entity covering the whole
1259
+ // viewport, so there was no empty pixel to start a marquee from — the
1260
+ // ⌘/Ctrl path below was added for exactly that, and then nobody could
1261
+ // find it, which this codebase has already learned is the same as not
1262
+ // having it.
1263
+ //
1264
+ // No professional editor binds "move the object" to a bare left-drag:
1265
+ // Unity's scene view always rubber-bands and reserves movement for the
1266
+ // gizmo handles, Unreal gives left-drag to the camera, Blender box-selects
1267
+ // by default. Requiring a selection first is the cheapest rule that gets
1268
+ // the same guarantee — a marquee can always be started — while keeping
1269
+ // click-then-drag, which casual users expect and Roblox has.
1270
+ if (!multiSelected.has(hit.entityRoot)) {
1271
+ pendingClickHit = hit;
1272
+ marqueeCandidate = true;
1273
+ marqueeAdditive = false;
1274
+ marqueeStartX = e.clientX;
1275
+ marqueeStartY = e.clientY;
1276
+ try {
1277
+ renderer.domElement.setPointerCapture(e.pointerId);
1278
+ }
1279
+ catch { /* enhancement only */ }
1280
+ return;
1281
+ }
1217
1282
  marqueeCandidate = false;
1218
1283
  pendingClickHit = null;
1219
1284
  const objectPos = hit.entityRoot.getWorldPosition(new THREE.Vector3());
@@ -1460,6 +1525,14 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1460
1525
  if (hudSelectedId)
1461
1526
  selectHudEntity(null);
1462
1527
  }
1528
+ else if (!modifierHeldAtDown && pendingClickHit) {
1529
+ // A plain click on an unselected entity. It reaches here rather than
1530
+ // the drag path because selecting is now the precondition FOR
1531
+ // dragging — so the first click selects and the second gesture moves.
1532
+ applySelection([pendingClickHit.entityRoot], pendingClickHit.point);
1533
+ if (hudSelectedId)
1534
+ selectHudEntity(null);
1535
+ }
1463
1536
  else if (!modifierHeldAtDown && scene) {
1464
1537
  clearWorldSelection();
1465
1538
  if (hudSelectedId)
@@ -1756,6 +1829,27 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1756
1829
  disposeMeshInPlace(object);
1757
1830
  object = swapEntityObject(object, fresh, m.entityId);
1758
1831
  }
1832
+ if (m.patch?.editorHidden !== undefined || m.patch?.editorLocked !== undefined) {
1833
+ const authored = sceneData?.entities.find((e) => e.id === m.entityId);
1834
+ if (!authored)
1835
+ return done(`no entity '${m.entityId}' in the scene being shown`);
1836
+ if (m.patch.editorHidden !== undefined)
1837
+ authored.editorHidden = m.patch.editorHidden;
1838
+ if (m.patch.editorLocked !== undefined)
1839
+ authored.editorLocked = m.patch.editorLocked;
1840
+ // Hidden affects the DESIGN VIEW only; the running game never reads
1841
+ // these. `visible` is the game's own field and is left alone — an
1842
+ // entity authored invisible stays invisible when it is unhidden here.
1843
+ object.visible = authored.visible !== false && authored.editorHidden !== true;
1844
+ // Dropping out of the selection on the way out: a hidden or locked
1845
+ // entity that stayed selected would keep its gizmo on screen, grabbable,
1846
+ // which is precisely what both flags exist to prevent.
1847
+ if ((authored.editorHidden || authored.editorLocked) && multiSelected.has(object)) {
1848
+ const next = new Set(multiSelected);
1849
+ next.delete(object);
1850
+ applySelection([...next]);
1851
+ }
1852
+ }
1759
1853
  if (m.patch?.water !== undefined) {
1760
1854
  // Colour and opacity could be patched in place, size cannot — one
1761
1855
  // rebuild path rather than two, same call this scene's load and the
@@ -1823,6 +1917,15 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1823
1917
  if (error)
1824
1918
  console.warn('[umicat/editor] 3D model drop failed:', m.entityId, error);
1825
1919
  window.parent.postMessage({ type: 'umicat:editor:modelDropped3d', entityId: m.entityId, ok: !error, error, position }, '*');
1920
+ // Select what was just placed. Every editor does this, and since
1921
+ // drag-to-move now REQUIRES a selection, a freshly dropped entity that
1922
+ // was not selected could not be nudged without clicking it first —
1923
+ // which is a strange thing to ask of someone who just put it there.
1924
+ if (!error) {
1925
+ const placed = objectByEntity.get(m.entityId);
1926
+ if (placed)
1927
+ applySelection([placed]);
1928
+ }
1826
1929
  };
1827
1930
  if (!scene)
1828
1931
  return done('no scene loaded yet');
@@ -1874,6 +1977,15 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1874
1977
  if (error)
1875
1978
  console.warn('[umicat/editor] 3D primitive drop failed:', m.entityId, error);
1876
1979
  window.parent.postMessage({ type: 'umicat:editor:primitiveDropped3d', entityId: m.entityId, ok: !error, error, position, collider }, '*');
1980
+ // Select what was just placed. Every editor does this, and since
1981
+ // drag-to-move now REQUIRES a selection, a freshly dropped entity that
1982
+ // was not selected could not be nudged without clicking it first —
1983
+ // which is a strange thing to ask of someone who just put it there.
1984
+ if (!error) {
1985
+ const placed = objectByEntity.get(m.entityId);
1986
+ if (placed)
1987
+ applySelection([placed]);
1988
+ }
1877
1989
  };
1878
1990
  if (!scene)
1879
1991
  return done('no scene loaded yet');
package/dist/scene3d.d.ts CHANGED
@@ -239,6 +239,27 @@ export interface Entity3D {
239
239
  heightfield?: Heightfield3D;
240
240
  /** ADR-050 — a body of water. Also mutually exclusive with the above. */
241
241
  water?: Water3D;
242
+ /**
243
+ * Editor-only authoring state, mirroring 2D's `editorHidden`/`editorLocked`
244
+ * exactly (Figma's eye and padlock).
245
+ *
246
+ * `editorHidden` hides the entity in the DESIGN VIEW only — the running game
247
+ * is unaffected, which is what separates it from `visible`. `editorLocked`
248
+ * leaves it visible but inert: it cannot be clicked, dragged or caught by a
249
+ * marquee.
250
+ *
251
+ * Lock earns its place here for a specific reason. Drag-to-move now needs a
252
+ * selection so that a full-viewport ground cannot swallow every marquee; the
253
+ * complementary fix is being able to take the ground out of the running
254
+ * entirely, which is what Roblox Studio's Lock is for and why it exists
255
+ * there.
256
+ *
257
+ * **A locked entity cannot be right-clicked either**, so there has to be
258
+ * another way back — 2D has a Hierarchy panel, 3D does not, so the
259
+ * empty-space context menu carries "Unlock all".
260
+ */
261
+ editorHidden?: boolean;
262
+ editorLocked?: boolean;
242
263
  collider?: Collider3D;
243
264
  /**
244
265
  * ADR-047 — marks this Part for SUBTRACTION the next time it (or a
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.24.0",
3
+ "version": "1.26.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",