@umicat/three-sdk 1.9.0 → 1.11.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.
@@ -265,6 +265,19 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
265
265
  selectionBox.visible = false;
266
266
  selectionBox.renderOrder = 998;
267
267
  selectionBox.material.depthTest = false;
268
+ // ADR-046 — multi-select (box-select + ⌘/Ctrl-click). `multiSelected` is
269
+ // now the ONE authoritative source of truth for "what's selected" — the
270
+ // single-select visuals above (`gizmo.attached`/`selectionBox`) are kept
271
+ // IN SYNC with it whenever it holds exactly one entity (every selection
272
+ // change routes through `applySelection` below, which is the only place
273
+ // that writes to any of these), rather than being a second independent
274
+ // notion of selection the way "gizmo attachment IS the selection state"
275
+ // used to read before this existed. `multiBoxes` is an EXTRA per-entity
276
+ // highlight box, used ONLY for the 2+ case — the existing singular
277
+ // `selectionBox` above still owns the 1-entity case unchanged, so a
278
+ // single click never grows a second, redundant box.
279
+ let multiSelected = new Set();
280
+ const multiBoxes = new Map();
268
281
  // The Move/Rotate/Scale transform gizmo — shows (and is only hit-testable)
269
282
  // on the current mode's handles once something is selected. `gizmo.root`
270
283
  // is added to the scene once, at scene-load time, right alongside the
@@ -272,6 +285,15 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
272
285
  // render loop below) so it follows the selected entity and keeps a
273
286
  // roughly constant on-screen size as the camera orbits/zooms.
274
287
  const gizmo = new TransformGizmo3D();
288
+ // ADR-046 Phase 3b — the shared pivot a multi-selection's gizmo attaches
289
+ // to instead of detaching outright. An invisible `Object3D` (never
290
+ // rendered — only ever a gizmo attachment point), repositioned to the
291
+ // selection's world-space centroid with IDENTITY rotation/scale every
292
+ // time `applySelection` runs for a 2+ selection. Added to the scene
293
+ // once at scene-load time, same as `marker`/`selectionBox` — it has no
294
+ // visible geometry so leaving it in permanently (just repositioned) is
295
+ // harmless.
296
+ const groupPivot = new THREE.Object3D();
275
297
  // Orientation gizmo — a small corner compass tracking the main camera's
276
298
  // rotation only (never its position/zoom), same convention every 3D DCC
277
299
  // uses: X=red, Y=green, Z=blue. Rendered as a second, tiny scene into a
@@ -377,6 +399,14 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
377
399
  // dropped model's `importScale` means that's almost never true).
378
400
  globalThis.__umicatGizmoAttachedScale =
379
401
  () => gizmo.attached ? { x: gizmo.attached.scale.x, y: gizmo.attached.scale.y, z: gizmo.attached.scale.z } : null;
402
+ // ADR-046 Phase 3b — test-only: distinguishes "gizmo attached to a REAL
403
+ // single entity" from "gizmo attached to the shared group pivot" — both
404
+ // report non-null from `__umicatGizmoAttachedScale` above, so a test
405
+ // asserting Phase 3a's old "no gizmo for 2+" behavior needs this to
406
+ // tell the two apart (that behavior is superseded by Phase 3b's shared
407
+ // pivot, not removed outright).
408
+ globalThis.__umicatGizmoAttachedIsGroupPivot =
409
+ () => gizmo.attached === groupPivot;
380
410
  // Test-only — an arbitrary entity's current LOCAL transform, by id (not
381
411
  // just the attached/selected one) — lets a test verify a `patchEntity3d`
382
412
  // position/rotation/scale override actually reached the live object,
@@ -485,6 +515,23 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
485
515
  let rightDownX = 0;
486
516
  let rightDownY = 0;
487
517
  let rightMoved = false;
518
+ // ADR-046 — multi-select gesture state. A left-pointerdown becomes a
519
+ // MARQUEE CANDIDATE whenever (a) ⌘/Ctrl is held — ALWAYS, regardless of
520
+ // what's under the cursor, including the ground/baseplate (see
521
+ // onPointerDown's own comment on why that case specifically matters),
522
+ // or (b) no modifier AND the down point hit nothing at all. Committed
523
+ // to an actual marquee only once the pointer moves past the drag
524
+ // threshold (see `onPointerMove`) — released without moving, it's
525
+ // either a ⌘-click TOGGLE (if it hit something) or a plain miss-click
526
+ // deselect (if not), decided in `onPointerUp`. `pendingClickHit`
527
+ // remembers what the down point hit (if anything) for that decision.
528
+ let marqueeCandidate = false;
529
+ let marqueeActive = false;
530
+ let marqueeAdditive = false; // ⌘/Ctrl held during a marquee → ADD to the existing selection instead of replacing it
531
+ let marqueeStartX = 0;
532
+ let marqueeStartY = 0;
533
+ let modifierHeldAtDown = false;
534
+ let pendingClickHit = null;
488
535
  // Entity drag — Phase 1 of real editing (translate only, ground-plane
489
536
  // constrained). Grabbing on an entity moves it; grabbing empty space/sky
490
537
  // still orbits, same convention as Unity/Blender. Whether THIS gesture is
@@ -503,33 +550,224 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
503
550
  let dragPlane = null;
504
551
  let dragGrabOffset = null; // world-space, plane-point minus object position at grab time
505
552
  /**
506
- * Deselect whatever's selected in WORLD — marker/box hidden, gizmo
507
- * detached, and (new, 2026-10-07) the host told, since a miss-click used
508
- * to deselect visually but post nothing: the host's own `lastPick` kept
509
- * the stale prior selection forever, harmless only while the Inspector's
510
- * visibility was gated on a now-removed "world mode" flag rather than on
511
- * `lastPick` itself. Also called from the HUD click listener below (cross-
512
- * layer deselect — see this file's header comment on why only one of
513
- * World/HUD should ever look selected at once).
553
+ * ADR-046 — the ONE place that changes the world selection. Takes the
554
+ * COMPLETE new selection (not a delta) and does three things: (1) syncs
555
+ * every visual (gizmo/selectionBox for the 1-entity case, `multiBoxes`
556
+ * for 2+, all hidden for 0), (2) tells the host via the new
557
+ * `selectionChanged3d` message (every count, including 0 and 1 — the
558
+ * authoritative "what's selected" signal multi-select-aware features
559
+ * read), and (3) ALSO fires the EXISTING `pickPoint3d` message every
560
+ * time, with `entityId` set only for the exactly-one case and `null`
561
+ * otherwise (0 OR 2+) — "not a single clean pick." This is what keeps
562
+ * the single-entity Scene3DInspector correctly hidden for a 2+
563
+ * selection with ZERO new host-side logic: without firing `null` for
564
+ * the 2+ case too, the host's `lastPick` would stay stale at whatever
565
+ * WAS the lone selection right before a marquee/⌘-click grew it past
566
+ * one, and the Inspector would keep showing that old entity.
567
+ */
568
+ function applySelection(objs, clickPoint) {
569
+ const next = new Set(objs);
570
+ const uniqueObjs = [...next];
571
+ // Drop any extra box no longer in the selection, OR every extra box at
572
+ // all once the count drops to ≤1 (the singular `selectionBox` owns
573
+ // that case; a leftover `multiBoxes` entry would double-highlight).
574
+ for (const [obj, box] of Array.from(multiBoxes)) {
575
+ if (!next.has(obj) || next.size < 2) {
576
+ scene?.remove(box);
577
+ box.geometry.dispose();
578
+ box.material.dispose();
579
+ multiBoxes.delete(obj);
580
+ }
581
+ }
582
+ multiSelected = next;
583
+ if (next.size === 0) {
584
+ marker.visible = false;
585
+ selectionBox.visible = false;
586
+ gizmo.detach();
587
+ }
588
+ else if (next.size === 1) {
589
+ const obj = uniqueObjs[0];
590
+ gizmo.attach(obj, camera);
591
+ selectionBox.setFromObject(obj);
592
+ selectionBox.visible = true;
593
+ // A click carries a real surface point; a programmatic 1-entity
594
+ // selection (⌘-click toggling down to one, a marquee netting
595
+ // exactly one) doesn't — the marker just hides rather than showing
596
+ // a stale or fabricated point.
597
+ if (clickPoint) {
598
+ marker.position.copy(clickPoint);
599
+ marker.visible = true;
600
+ }
601
+ else
602
+ marker.visible = false;
603
+ }
604
+ else {
605
+ selectionBox.visible = false;
606
+ marker.visible = false;
607
+ for (const obj of uniqueObjs) {
608
+ let box = multiBoxes.get(obj);
609
+ if (!box) {
610
+ box = new THREE.BoxHelper(obj, 0xffd23f);
611
+ box.renderOrder = 998;
612
+ box.material.depthTest = false;
613
+ scene?.add(box);
614
+ multiBoxes.set(obj, box);
615
+ }
616
+ box.setFromObject(obj);
617
+ }
618
+ // ADR-046 Phase 3b — the gizmo attaches to a SHARED PIVOT at the
619
+ // selection's world-space centroid, reset to identity rotation/
620
+ // scale every time (never inherits any one member's orientation —
621
+ // the group always manipulates in world axes). `gizmo.attach`
622
+ // itself handles detaching from whatever was previously attached.
623
+ const centroid = new THREE.Vector3();
624
+ for (const obj of uniqueObjs)
625
+ centroid.add(obj.getWorldPosition(new THREE.Vector3()));
626
+ centroid.divideScalar(uniqueObjs.length);
627
+ groupPivot.position.copy(centroid);
628
+ groupPivot.quaternion.identity();
629
+ groupPivot.scale.set(1, 1, 1);
630
+ gizmo.attach(groupPivot, camera);
631
+ }
632
+ const entityIds = uniqueObjs.map((o) => entityByObject.get(o)).filter((id) => !!id);
633
+ window.parent.postMessage({ type: 'umicat:editor:selectionChanged3d', entityIds }, '*');
634
+ // ALWAYS fires, not just for 0/1 — a 2+ selection has to post
635
+ // `entityId: null` too, or the host's single-entity `lastPick` would
636
+ // stay stale at whatever WAS the lone selection right before a
637
+ // marquee/⌘-click grew it past one (the Inspector would keep showing
638
+ // the old single entity instead of correctly hiding for a
639
+ // multi-selection).
640
+ {
641
+ const id = next.size === 1 ? (entityByObject.get(uniqueObjs[0]) ?? null) : null;
642
+ let p = clickPoint;
643
+ if (!p && next.size === 1)
644
+ p = uniqueObjs[0].getWorldPosition(new THREE.Vector3());
645
+ window.parent.postMessage({ type: 'umicat:editor:pickPoint3d', x: p?.x ?? 0, y: p?.y ?? 0, z: p?.z ?? 0, entityId: id }, '*');
646
+ }
647
+ }
648
+ /**
649
+ * Deselect whatever's selected in WORLD. Also called from the HUD click
650
+ * listener below (cross-layer deselect — see this file's header comment
651
+ * on why only one of World/HUD should ever look selected at once).
514
652
  */
515
653
  function clearWorldSelection() {
516
- marker.visible = false;
517
- selectionBox.visible = false;
518
- gizmo.detach();
519
- window.parent.postMessage({ type: 'umicat:editor:pickPoint3d', x: 0, y: 0, z: 0, entityId: null }, '*');
654
+ applySelection([]);
655
+ }
656
+ // ADR-046 — box-select. A plain `<div>` overlay (NOT a 3D object — this
657
+ // is pure screen-space UI, same reasoning a 2D editor's marquee would
658
+ // use), created lazily on first use and reused for the life of this
659
+ // player. `position: fixed` in viewport pixels matches `e.clientX/Y`
660
+ // directly — no coordinate conversion needed, since this editor's canvas
661
+ // already fills the viewport.
662
+ let marqueeEl = null;
663
+ function ensureMarqueeEl() {
664
+ if (marqueeEl)
665
+ return marqueeEl;
666
+ const el = document.createElement('div');
667
+ el.style.position = 'fixed';
668
+ el.style.border = '1px solid #4da3ff';
669
+ el.style.background = 'rgba(77,163,255,0.15)';
670
+ el.style.pointerEvents = 'none';
671
+ el.style.zIndex = '9999';
672
+ el.style.display = 'none';
673
+ document.body.appendChild(el);
674
+ marqueeEl = el;
675
+ return el;
676
+ }
677
+ function updateMarqueeRect(x1, y1, x2, y2) {
678
+ const el = ensureMarqueeEl();
679
+ el.style.display = 'block';
680
+ el.style.left = `${Math.min(x1, x2)}px`;
681
+ el.style.top = `${Math.min(y1, y2)}px`;
682
+ el.style.width = `${Math.abs(x2 - x1)}px`;
683
+ el.style.height = `${Math.abs(y2 - y1)}px`;
684
+ }
685
+ function hideMarqueeRect() {
686
+ if (marqueeEl)
687
+ marqueeEl.style.display = 'none';
688
+ }
689
+ /**
690
+ * ADR-046 — which entities a marquee rect nets. Tests each entity's
691
+ * WORLD-POSITION (its origin/pivot), projected to screen, for plain
692
+ * CONTAINMENT in the rect — not a full bounding-box/overlap test. This
693
+ * is a deliberate v1 simplification: a Part's pivot sitting inside the
694
+ * dragged rectangle is an unambiguous, easy-to-predict rule ("drag
695
+ * around the things you want"), whereas a full AABB-overlap test would
696
+ * also select anything merely GRAZED by the rect's edge — arguably more
697
+ * "correct" for a large or partially-covered mesh, but a materially
698
+ * bigger and more failure-prone computation (8-corner projection,
699
+ * near-plane clipping per corner) for a benefit that doesn't matter for
700
+ * the small, discrete Parts this feature is built around. Worth
701
+ * revisiting if real use shows pivot-containment missing things people
702
+ * expected to net.
703
+ */
704
+ function selectEntitiesInScreenRect(x1, y1, x2, y2) {
705
+ const left = Math.min(x1, x2);
706
+ const right = Math.max(x1, x2);
707
+ const top = Math.min(y1, y2);
708
+ const bottom = Math.max(y1, y2);
709
+ const worldPos = new THREE.Vector3();
710
+ const camSpace = new THREE.Vector3();
711
+ const hits = [];
712
+ for (const obj of objectByEntity.values()) {
713
+ obj.getWorldPosition(worldPos);
714
+ camSpace.copy(worldPos).applyMatrix4(camera.matrixWorldInverse);
715
+ if (camSpace.z > -camera.near)
716
+ continue; // behind the camera (or inside the near clip) — not actually visible, don't net it
717
+ const screen = worldToClientXY(worldPos);
718
+ if (screen.x >= left && screen.x <= right && screen.y >= top && screen.y <= bottom)
719
+ hits.push(obj);
720
+ }
721
+ return hits;
520
722
  }
521
723
  let gizmoDrag = null;
724
+ let groupDrag = null;
522
725
  const beginGizmoDrag = (hit, e) => {
523
726
  const obj = gizmo.attached;
524
727
  if (!obj)
525
728
  return false;
729
+ // ADR-046 Phase 3b — per-axis scale is REFUSED on the shared pivot.
730
+ // Scaling a rotated object along a single WORLD axis doesn't commute
731
+ // with its own (possibly different) rotation the way UNIFORM scaling
732
+ // does — the uniform "xyz" center handle stays exact regardless of
733
+ // each member's orientation, a per-axis handle would silently be
734
+ // wrong for anything not world-axis-aligned. Only the uniform handle
735
+ // is reachable for a 2+ selection; the per-axis ring/arrow handles
736
+ // simply don't begin a drag at all.
737
+ if (obj === groupPivot && hit.mode === 'scale' && hit.axis !== 'xyz')
738
+ return false;
526
739
  const worldPos = obj.getWorldPosition(new THREE.Vector3());
740
+ // Snapshots every selected real entity's WORLD-space starting
741
+ // transform, for `updateGizmoDrag` to re-derive each one's CURRENT
742
+ // transform from (its own start + this frame's pivot delta) rather
743
+ // than compounding frame-over-frame.
744
+ const beginGroupSnapshot = () => {
745
+ if (obj !== groupPivot)
746
+ return;
747
+ const members = [];
748
+ for (const m of multiSelected) {
749
+ members.push({
750
+ obj: m,
751
+ startWorldPos: m.getWorldPosition(new THREE.Vector3()),
752
+ startWorldQuat: m.getWorldQuaternion(new THREE.Quaternion()),
753
+ startLocalScale: m.scale.clone(),
754
+ parentWorldQuatInverse: m.parent ? m.parent.getWorldQuaternion(new THREE.Quaternion()).invert() : new THREE.Quaternion(),
755
+ });
756
+ }
757
+ groupDrag = {
758
+ pivotStartPos: obj.position.clone(), // groupPivot has no parent — local IS world
759
+ pivotStartQuat: obj.quaternion.clone(),
760
+ pivotStartScale: obj.scale.clone(),
761
+ members,
762
+ };
763
+ };
527
764
  if (hit.mode === 'move' && hit.axis !== 'xyz') {
528
765
  const lineDir = gizmo.axisDirectionWorld(hit.axis);
529
766
  const grab = closestPointOnLineToRay(raycaster.ray.origin, raycaster.ray.direction, worldPos, lineDir);
530
767
  if (!grab)
531
768
  return false; // camera looking straight down this axis
532
769
  gizmoDrag = { mode: 'move', axis: hit.axis, lineOrigin: worldPos.clone(), lineDir, grabOffset: grab.clone().sub(worldPos) };
770
+ beginGroupSnapshot();
533
771
  return true;
534
772
  }
535
773
  if (hit.mode === 'scale' && hit.axis !== 'xyz') {
@@ -541,6 +779,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
541
779
  if (Math.abs(startSignedDistance) < 1e-4)
542
780
  return false; // grabbed essentially at the origin — no stable ratio
543
781
  gizmoDrag = { mode: 'scale', axis: hit.axis, lineOrigin: worldPos.clone(), lineDir, startSignedDistance, startScale: obj.scale.clone() };
782
+ beginGroupSnapshot();
544
783
  return true;
545
784
  }
546
785
  if (hit.mode === 'scale' && hit.axis === 'xyz') {
@@ -549,6 +788,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
549
788
  if (startScreenDistance < 2)
550
789
  return false; // grabbed on top of the object's own screen position
551
790
  gizmoDrag = { mode: 'scale', axis: 'xyz', originScreen, startScreenDistance, startScale: obj.scale.clone() };
791
+ beginGroupSnapshot();
552
792
  return true;
553
793
  }
554
794
  if (hit.mode === 'rotate' && hit.axis !== 'xyz') {
@@ -560,6 +800,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
560
800
  const parentWorldQuatInverse = obj.parent ? obj.parent.getWorldQuaternion(new THREE.Quaternion()).invert() : new THREE.Quaternion();
561
801
  const startWorldQuaternion = obj.getWorldQuaternion(new THREE.Quaternion());
562
802
  gizmoDrag = { mode: 'rotate', axis: hit.axis, planePoint: worldPos.clone(), planeNormal, startAngle, startWorldQuaternion, parentWorldQuatInverse };
803
+ beginGroupSnapshot();
563
804
  return true;
564
805
  }
565
806
  return false;
@@ -576,6 +817,20 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
576
817
  if (obj.parent)
577
818
  obj.parent.worldToLocal(newWorldPos);
578
819
  obj.position.copy(newWorldPos);
820
+ // ADR-046 Phase 3b — propagate the SAME world-space displacement to
821
+ // every group member, each starting from ITS OWN snapshot (not
822
+ // compounding across frames). `obj` (the pivot) has no parent, so
823
+ // its local `.position` IS its world position.
824
+ if (groupDrag) {
825
+ const worldDelta = obj.position.clone().sub(groupDrag.pivotStartPos);
826
+ for (const member of groupDrag.members) {
827
+ const memberWorldPos = member.startWorldPos.clone().add(worldDelta);
828
+ if (member.obj.parent)
829
+ member.obj.parent.worldToLocal(memberWorldPos);
830
+ member.obj.position.copy(memberWorldPos);
831
+ multiBoxes.get(member.obj)?.setFromObject(member.obj);
832
+ }
833
+ }
579
834
  }
580
835
  else if (gizmoDrag.mode === 'scale' && gizmoDrag.axis !== 'xyz') {
581
836
  const grab = closestPointOnLineToRay(raycaster.ray.origin, raycaster.ray.direction, gizmoDrag.lineOrigin, gizmoDrag.lineDir);
@@ -584,6 +839,8 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
584
839
  const signedDistance = grab.clone().sub(gizmoDrag.lineOrigin).dot(gizmoDrag.lineDir);
585
840
  const ratio = THREE.MathUtils.clamp(signedDistance / gizmoDrag.startSignedDistance, 0.02, 50);
586
841
  const { axis, startScale } = gizmoDrag;
842
+ // Per-axis scale never reaches a group drag — `beginGizmoDrag`
843
+ // refuses it on the pivot — so no member-propagation needed here.
587
844
  if (axis === 'x')
588
845
  obj.scale.x = startScale.x * ratio;
589
846
  else if (axis === 'y')
@@ -595,6 +852,23 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
595
852
  const currentScreenDistance = Math.hypot(e.clientX - gizmoDrag.originScreen.x, e.clientY - gizmoDrag.originScreen.y);
596
853
  const ratio = THREE.MathUtils.clamp(currentScreenDistance / gizmoDrag.startScreenDistance, 0.02, 50);
597
854
  obj.scale.copy(gizmoDrag.startScale).multiplyScalar(ratio);
855
+ // UNIFORM scale is the one scale mode a group drag CAN reach.
856
+ // Scaling each member's own offset-from-pivot AND its own scale by
857
+ // the identical ratio is exact regardless of each member's
858
+ // individual rotation — uniform scaling commutes with rotation,
859
+ // which is exactly why per-axis scaling is refused above but this
860
+ // isn't.
861
+ if (groupDrag) {
862
+ for (const member of groupDrag.members) {
863
+ const offset = member.startWorldPos.clone().sub(groupDrag.pivotStartPos).multiplyScalar(ratio);
864
+ const memberWorldPos = groupDrag.pivotStartPos.clone().add(offset);
865
+ if (member.obj.parent)
866
+ member.obj.parent.worldToLocal(memberWorldPos);
867
+ member.obj.position.copy(memberWorldPos);
868
+ member.obj.scale.copy(member.startLocalScale).multiplyScalar(ratio);
869
+ multiBoxes.get(member.obj)?.setFromObject(member.obj);
870
+ }
871
+ }
598
872
  }
599
873
  else if (gizmoDrag.mode === 'rotate') {
600
874
  const hitPoint = raycastPlane(raycaster.ray, gizmoDrag.planePoint, gizmoDrag.planeNormal);
@@ -605,6 +879,23 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
605
879
  const deltaQuat = new THREE.Quaternion().setFromAxisAngle(gizmoDrag.planeNormal, delta);
606
880
  const newWorldQuat = deltaQuat.multiply(gizmoDrag.startWorldQuaternion.clone());
607
881
  obj.quaternion.copy(gizmoDrag.parentWorldQuatInverse.clone().multiply(newWorldQuat));
882
+ // Each member ORBITS the pivot (its offset-from-pivot rotates by
883
+ // the same delta) AND SPINS IN PLACE by that same delta — the rigid
884
+ // body behavior Roblox/Unity use for rotating a multi-selection
885
+ // together, not each member spinning around its own origin.
886
+ if (groupDrag) {
887
+ for (const member of groupDrag.members) {
888
+ const offset = member.startWorldPos.clone().sub(groupDrag.pivotStartPos);
889
+ offset.applyQuaternion(deltaQuat);
890
+ const memberWorldPos = groupDrag.pivotStartPos.clone().add(offset);
891
+ if (member.obj.parent)
892
+ member.obj.parent.worldToLocal(memberWorldPos);
893
+ member.obj.position.copy(memberWorldPos);
894
+ const memberWorldQuat = deltaQuat.clone().multiply(member.startWorldQuat);
895
+ member.obj.quaternion.copy(member.parentWorldQuatInverse.clone().multiply(memberWorldQuat));
896
+ multiBoxes.get(member.obj)?.setFromObject(member.obj);
897
+ }
898
+ }
608
899
  }
609
900
  selectionBox.setFromObject(obj);
610
901
  gizmo.update(camera);
@@ -643,7 +934,13 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
643
934
  moved = false;
644
935
  if (!scene)
645
936
  return;
646
- if (gizmo.attached) {
937
+ // ADR-046 — ⌘/Ctrl held: never starts ANY drag (gizmo, single-entity,
938
+ // OR gizmo-hit-test) — the modifier means "I'm multi-selecting," and
939
+ // deciding what that click actually DOES (toggle one entity, or start
940
+ // a marquee-ADD) has to wait for release, so a ⌘-drag that moved the
941
+ // pointer doesn't get misread as a toggle (see onPointerUp).
942
+ modifierHeldAtDown = e.metaKey || e.ctrlKey;
943
+ if (!modifierHeldAtDown && gizmo.attached) {
647
944
  raycaster.setFromCamera(ndcFromEvent(e), camera);
648
945
  const gizmoHit = gizmo.hitTest(raycaster);
649
946
  if (gizmoHit && beginGizmoDrag(gizmoHit, e)) {
@@ -667,12 +964,46 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
667
964
  }
668
965
  }
669
966
  const hit = pickEntityAt(e);
670
- // Empty space: a left-drag here is a no-op now (Roblox scheme — rotate
671
- // lives on the right button; OrbitControls' LEFT binding is null, so
672
- // there's nothing left to fall through to). Reserved for a future
673
- // marquee-select, not built yet.
674
- if (!hit)
967
+ if (modifierHeldAtDown) {
968
+ // ⌘/Ctrl held — ALWAYS a selection gesture: toggle-on-click (decided
969
+ // on release, below, if the pointer never moved) or marquee-ADD on
970
+ // drag, regardless of what's under the cursor. Deliberately NOT
971
+ // gated on `!hit` the way the non-modifier marquee below is — a
972
+ // baseplate-style scene's ground is itself a real, registered
973
+ // `Entity3D` (see `template-3d-baseplate` — the SAME plane primitive
974
+ // this fixture's own "ground" entity uses) that can cover the ENTIRE
975
+ // viewport, leaving no truly empty pixel to start a plain marquee
976
+ // from. The modifier is what makes box-select reachable on such a
977
+ // scene at all — the alternative (treating it as a no-op) would
978
+ // make Phase 3a's whole feature unreachable there.
979
+ pendingClickHit = hit;
980
+ marqueeCandidate = true;
981
+ marqueeAdditive = true;
982
+ marqueeStartX = e.clientX;
983
+ marqueeStartY = e.clientY;
984
+ try {
985
+ renderer.domElement.setPointerCapture(e.pointerId);
986
+ }
987
+ catch { /* enhancement only */ }
675
988
  return;
989
+ }
990
+ if (!hit) {
991
+ // Empty space, no modifier — might become a marquee that REPLACES
992
+ // the selection; committed only once the pointer actually moves
993
+ // (see onPointerMove). A plain miss-click (no movement) still just
994
+ // deselects, same as before marquee-select existed.
995
+ marqueeCandidate = true;
996
+ marqueeAdditive = false;
997
+ marqueeStartX = e.clientX;
998
+ marqueeStartY = e.clientY;
999
+ try {
1000
+ renderer.domElement.setPointerCapture(e.pointerId);
1001
+ }
1002
+ catch { /* enhancement only */ }
1003
+ return;
1004
+ }
1005
+ marqueeCandidate = false;
1006
+ pendingClickHit = null;
676
1007
  const objectPos = hit.entityRoot.getWorldPosition(new THREE.Vector3());
677
1008
  const plane = new THREE.Plane(new THREE.Vector3(0, 1, 0), -objectPos.y);
678
1009
  const planePoint = new THREE.Vector3();
@@ -716,6 +1047,16 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
716
1047
  return;
717
1048
  if (Math.abs(e.clientX - downX) > 4 || Math.abs(e.clientY - downY) > 4)
718
1049
  moved = true;
1050
+ if (marqueeCandidate) {
1051
+ // Not yet committed to a marquee until the pointer actually moves —
1052
+ // a plain miss-click (released with `moved` still false) stays a
1053
+ // deselect, decided in onPointerUp.
1054
+ if (!moved)
1055
+ return;
1056
+ marqueeActive = true;
1057
+ updateMarqueeRect(marqueeStartX, marqueeStartY, e.clientX, e.clientY);
1058
+ return;
1059
+ }
719
1060
  if (gizmoDrag) {
720
1061
  raycaster.setFromCamera(ndcFromEvent(e), camera);
721
1062
  updateGizmoDrag(e);
@@ -762,12 +1103,15 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
762
1103
  }
763
1104
  if (hudSelectedId)
764
1105
  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 }, '*');
1106
+ // ADR-046 — right-clicking an entity that's ALREADY part of a
1107
+ // multi-selection keeps the WHOLE selection, so the menu acts on all
1108
+ // of them (explorer-style: right-clicking one of several selected
1109
+ // items doesn't collapse the selection to one). Right-clicking
1110
+ // anything else collapses to just that one, same as a plain
1111
+ // left-click already does.
1112
+ if (!(multiSelected.size >= 2 && multiSelected.has(hit.entityRoot))) {
1113
+ applySelection([hit.entityRoot], hit.point);
1114
+ }
771
1115
  window.parent.postMessage({ type: 'umicat:editor:contextMenu3d', entityId: hit.entityId, clientX: e.clientX, clientY: e.clientY }, '*');
772
1116
  return;
773
1117
  }
@@ -782,6 +1126,34 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
782
1126
  }
783
1127
  if (gizmoDrag) {
784
1128
  const obj = gizmo.attached;
1129
+ // ADR-046 Phase 3b — the shared-pivot case posts ONE end message
1130
+ // PER group member (reusing the exact same `dragEnd3d`/
1131
+ // `rotateEnd3d`/`scaleEnd3d` message shapes a single-entity drag
1132
+ // already uses — the host's existing per-entity-id handler for
1133
+ // each needed zero changes to persist N entities instead of one).
1134
+ if (obj === groupPivot && groupDrag) {
1135
+ if (moved) {
1136
+ for (const member of groupDrag.members) {
1137
+ const entityId = entityByObject.get(member.obj);
1138
+ if (!entityId)
1139
+ continue;
1140
+ if (gizmoDrag.mode === 'move') {
1141
+ window.parent.postMessage({ type: 'umicat:editor:dragEnd3d', sceneId: opts.sceneId, entityId, position: { x: member.obj.position.x, y: member.obj.position.y, z: member.obj.position.z } }, '*');
1142
+ }
1143
+ else if (gizmoDrag.mode === 'rotate') {
1144
+ const q = member.obj.quaternion;
1145
+ window.parent.postMessage({ type: 'umicat:editor:rotateEnd3d', sceneId: opts.sceneId, entityId, rotation: [q.x, q.y, q.z, q.w] }, '*');
1146
+ }
1147
+ else if (gizmoDrag.mode === 'scale') {
1148
+ window.parent.postMessage({ type: 'umicat:editor:scaleEnd3d', sceneId: opts.sceneId, entityId, scale: { x: member.obj.scale.x, y: member.obj.scale.y, z: member.obj.scale.z } }, '*');
1149
+ }
1150
+ }
1151
+ }
1152
+ groupDrag = null;
1153
+ gizmoDrag = null;
1154
+ controls.enabled = true;
1155
+ return;
1156
+ }
785
1157
  const entityId = obj ? entityByObject.get(obj) : undefined;
786
1158
  if (moved && obj && entityId) {
787
1159
  if (gizmoDrag.mode === 'move') {
@@ -815,10 +1187,60 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
815
1187
  dragPlane = null;
816
1188
  dragGrabOffset = null;
817
1189
  controls.enabled = true;
1190
+ // ADR-046 — marquee/toggle finalize. Reachable whenever the
1191
+ // pointerdown either hit empty space (no modifier) OR had the
1192
+ // modifier held at all (see onPointerDown — both set
1193
+ // `marqueeCandidate`). Three outcomes, by what actually happened:
1194
+ // (1) it became an active drag → marquee select/add; (2) modifier
1195
+ // held, no drag → toggle whatever was under the cursor at down (can
1196
+ // be nothing, if that was empty space too); (3) no modifier, no drag
1197
+ // → plain miss-click deselect, exactly as before marquee existed.
1198
+ if (marqueeCandidate) {
1199
+ marqueeCandidate = false;
1200
+ if (marqueeActive) {
1201
+ marqueeActive = false;
1202
+ hideMarqueeRect();
1203
+ const hits = selectEntitiesInScreenRect(marqueeStartX, marqueeStartY, e.clientX, e.clientY);
1204
+ if (marqueeAdditive) {
1205
+ const next = new Set(multiSelected);
1206
+ for (const h of hits)
1207
+ next.add(h);
1208
+ applySelection([...next]);
1209
+ }
1210
+ else {
1211
+ applySelection(hits);
1212
+ }
1213
+ if (hudSelectedId)
1214
+ selectHudEntity(null);
1215
+ }
1216
+ else if (modifierHeldAtDown && pendingClickHit) {
1217
+ const obj = pendingClickHit.entityRoot;
1218
+ const next = new Set(multiSelected);
1219
+ if (next.has(obj))
1220
+ next.delete(obj);
1221
+ else
1222
+ next.add(obj);
1223
+ applySelection([...next], pendingClickHit.point);
1224
+ if (hudSelectedId)
1225
+ selectHudEntity(null);
1226
+ }
1227
+ else if (!modifierHeldAtDown && scene) {
1228
+ clearWorldSelection();
1229
+ if (hudSelectedId)
1230
+ selectHudEntity(null);
1231
+ }
1232
+ // The remaining case — modifier held, no drag, no hit (⌘-click on
1233
+ // truly empty space) — is intentionally a no-op: nothing to toggle,
1234
+ // and the modifier means "don't blow away my selection" anyway.
1235
+ modifierHeldAtDown = false;
1236
+ pendingClickHit = null;
1237
+ return;
1238
+ }
818
1239
  if (moved || !scene)
819
1240
  return;
820
- // A plain click (no drag) — the existing read-a-coordinate behavior,
821
- // plus attaching/detaching the transform gizmo to match selection.
1241
+ // A plain click (no drag, no modifier) — collapses the selection to
1242
+ // just the clicked entity (or clears it), same as every pre-multi-
1243
+ // select click already did.
822
1244
  const hit = pickEntityAt(e);
823
1245
  if (!hit) {
824
1246
  // Clicked empty space with nothing grabbed — deselect. Previously a
@@ -831,16 +1253,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
831
1253
  }
832
1254
  if (hudSelectedId)
833
1255
  selectHudEntity(null); // cross-layer deselect
834
- marker.position.copy(hit.point);
835
- marker.visible = true;
836
- // Frame the whole entity the click landed on, not just the point on its
837
- // surface — `setFromObject` walks the root's full subtree, so a
838
- // multi-mesh entity (a model with separate parts) gets one box around
839
- // all of it, matching what "entityId" actually refers to.
840
- selectionBox.setFromObject(hit.entityRoot);
841
- selectionBox.visible = true;
842
- gizmo.attach(hit.entityRoot, camera);
843
- window.parent.postMessage({ type: 'umicat:editor:pickPoint3d', x: hit.point.x, y: hit.point.y, z: hit.point.z, entityId: hit.entityId }, '*');
1256
+ applySelection([hit.entityRoot], hit.point);
844
1257
  };
845
1258
  renderer.domElement.addEventListener('pointerdown', onPointerDown);
846
1259
  renderer.domElement.addEventListener('pointermove', onPointerMove);
@@ -1091,14 +1504,26 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1091
1504
  entityByObject.delete(object);
1092
1505
  entityByObject.set(fresh, m.entityId);
1093
1506
  objectByEntity.set(m.entityId, fresh);
1094
- // Same "gizmo attachment IS the selection state" convention the
1095
- // position/rotation/scale branch above already relies on — there is
1096
- // no separate "currently selected" variable to update.
1507
+ // Same object-instance swap the position/rotation/scale branch
1508
+ // above already handles for the single-select visuals — `object`
1509
+ // itself is being replaced, so anything keyed by the OLD instance
1510
+ // (gizmo attachment, AND now `multiSelected`/`multiBoxes` — ADR-046)
1511
+ // has to move to `fresh` or it silently points at a disposed object.
1097
1512
  if (gizmo.attached === object) {
1098
1513
  gizmo.detach();
1099
1514
  gizmo.attach(fresh, camera);
1100
1515
  selectionBox.setFromObject(fresh);
1101
1516
  }
1517
+ if (multiSelected.has(object)) {
1518
+ multiSelected.delete(object);
1519
+ multiSelected.add(fresh);
1520
+ const box = multiBoxes.get(object);
1521
+ if (box) {
1522
+ multiBoxes.delete(object);
1523
+ multiBoxes.set(fresh, box);
1524
+ box.setFromObject(fresh);
1525
+ }
1526
+ }
1102
1527
  object = fresh;
1103
1528
  }
1104
1529
  done();
@@ -1358,10 +1783,13 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1358
1783
  }
1359
1784
  if (gizmoDrag && gizmo.attached === object)
1360
1785
  gizmoDrag = null;
1361
- if (gizmo.attached === object) {
1362
- gizmo.detach();
1363
- marker.visible = false;
1364
- selectionBox.visible = false;
1786
+ // ADR-046 — if the deleted entity was selected (single OR part of a
1787
+ // multi-selection), route the shrunk selection back through
1788
+ // `applySelection` rather than hand-rolling the gizmo/box cleanup here
1789
+ // — that's the one place all of it (including re-attaching the gizmo
1790
+ // if this drops a 2-selection down to 1) already lives.
1791
+ if (gizmo.attached === object || multiSelected.has(object)) {
1792
+ applySelection([...multiSelected].filter((o) => o !== object));
1365
1793
  }
1366
1794
  scene?.remove(object);
1367
1795
  disposeObjectTree(object);
@@ -1404,44 +1832,42 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1404
1832
  const target = e.target;
1405
1833
  if (target && (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable))
1406
1834
  return;
1407
- if (e.key === 'Delete' && gizmo.attached) {
1408
- const entityId = entityByObject.get(gizmo.attached);
1409
- if (entityId) {
1410
- e.preventDefault();
1835
+ // ADR-046 — these all now read `multiSelected` (the authoritative
1836
+ // selection set), not `gizmo.attached` — the gizmo is DETACHED
1837
+ // whenever 2+ entities are selected (no shared-pivot gizmo yet, Phase
1838
+ // 3b), so reading `gizmo.attached` alone would silently do nothing
1839
+ // for a multi-selection. `gizmo.attached` is always a MEMBER of
1840
+ // `multiSelected` when exactly one entity is selected (the invariant
1841
+ // `applySelection` maintains), so this is a pure generalization, not a
1842
+ // behavior change for the single-select case.
1843
+ const selectedIds = () => [...multiSelected].map((o) => entityByObject.get(o)).filter((id) => !!id);
1844
+ if (e.key === 'Delete' && multiSelected.size > 0) {
1845
+ e.preventDefault();
1846
+ for (const entityId of selectedIds())
1411
1847
  void onDeleteEntity3d({ entityId });
1412
- }
1413
1848
  }
1414
1849
  else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'z') {
1415
1850
  e.preventDefault();
1416
1851
  window.parent.postMessage({ type: 'umicat:editor:requestUndo3d' }, '*');
1417
1852
  }
1418
- else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'c' && gizmo.attached) {
1853
+ else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'c' && multiSelected.size > 0) {
1419
1854
  // ADR-045 — same "ask, don't act" shape as Undo above: the CLIPBOARD
1420
1855
  // lives on the host (Copy is a pure read of the host's own scene
1421
1856
  // 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
- }
1857
+ e.preventDefault();
1858
+ window.parent.postMessage({ type: 'umicat:editor:requestCopy3d', entityIds: selectedIds() }, '*');
1427
1859
  }
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
- }
1860
+ else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'x' && multiSelected.size > 0) {
1861
+ e.preventDefault();
1862
+ window.parent.postMessage({ type: 'umicat:editor:requestCut3d', entityIds: selectedIds() }, '*');
1434
1863
  }
1435
1864
  else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'v') {
1436
1865
  e.preventDefault();
1437
1866
  window.parent.postMessage({ type: 'umicat:editor:requestPaste3d' }, '*');
1438
1867
  }
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
- }
1868
+ else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'd' && multiSelected.size > 0) {
1869
+ e.preventDefault();
1870
+ window.parent.postMessage({ type: 'umicat:editor:requestDuplicate3d', entityIds: selectedIds() }, '*');
1445
1871
  }
1446
1872
  });
1447
1873
  // WASD/QE fly-camera + Shift speed boost — held-STATE, not a discrete
@@ -1575,6 +2001,19 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1575
2001
  selectionBox.visible = false;
1576
2002
  scene.add(selectionBox);
1577
2003
  scene.add(gizmo.root);
2004
+ // ADR-046 Phase 3b — the shared pivot itself has no visible geometry,
2005
+ // but it still needs to be IN the (fresh) scene graph for
2006
+ // `gizmo.attach(groupPivot, ...)` and any `getWorldPosition`/
2007
+ // `worldToLocal` math against it to resolve correctly.
2008
+ scene.add(groupPivot);
2009
+ // ADR-046 — a (re)load tears down the whole scene graph; any
2010
+ // multi-select boxes from a PRIOR scene were added to that scene, not
2011
+ // this one, and the objects they tracked are gone. No disposal loop
2012
+ // needed here (nothing in the new scene references them) — just drop
2013
+ // the stale bookkeeping.
2014
+ multiSelected = new Set();
2015
+ multiBoxes.clear();
2016
+ groupDrag = null;
1578
2017
  // Frame the whole scene — auto-fit, since a small template scene and a
1579
2018
  // real level's dozens of entities need wildly different orbit distances.
1580
2019
  const box = new THREE.Box3().setFromObject(scene);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.9.0",
3
+ "version": "1.11.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",