@umicat/three-sdk 1.25.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
  }
@@ -654,9 +654,24 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
654
654
  // separately-placed visible ground models — without this filter, a click
655
655
  // that visibly lands on the rendered ground can silently return the
656
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
+ };
657
671
  const pickEntityAt = (e) => {
658
672
  raycaster.setFromCamera(ndcFromEvent(e), camera);
659
- 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)));
660
675
  const hits = raycaster.intersectObjects(targets, true);
661
676
  if (hits.length === 0)
662
677
  return null;
@@ -881,7 +896,13 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
881
896
  const worldPos = new THREE.Vector3();
882
897
  const camSpace = new THREE.Vector3();
883
898
  const hits = [];
884
- 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;
885
906
  obj.getWorldPosition(worldPos);
886
907
  camSpace.copy(worldPos).applyMatrix4(camera.matrixWorldInverse);
887
908
  if (camSpace.z > -camera.near)
@@ -1808,6 +1829,27 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1808
1829
  disposeMeshInPlace(object);
1809
1830
  object = swapEntityObject(object, fresh, m.entityId);
1810
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
+ }
1811
1853
  if (m.patch?.water !== undefined) {
1812
1854
  // Colour and opacity could be patched in place, size cannot — one
1813
1855
  // rebuild path rather than two, same call this scene's load and the
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.25.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",