@umicat/three-sdk 1.10.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.
@@ -285,6 +285,15 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
285
285
  // render loop below) so it follows the selected entity and keeps a
286
286
  // roughly constant on-screen size as the camera orbits/zooms.
287
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();
288
297
  // Orientation gizmo — a small corner compass tracking the main camera's
289
298
  // rotation only (never its position/zoom), same convention every 3D DCC
290
299
  // uses: X=red, Y=green, Z=blue. Rendered as a second, tiny scene into a
@@ -390,6 +399,14 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
390
399
  // dropped model's `importScale` means that's almost never true).
391
400
  globalThis.__umicatGizmoAttachedScale =
392
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;
393
410
  // Test-only — an arbitrary entity's current LOCAL transform, by id (not
394
411
  // just the attached/selected one) — lets a test verify a `patchEntity3d`
395
412
  // position/rotation/scale override actually reached the live object,
@@ -585,7 +602,6 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
585
602
  marker.visible = false;
586
603
  }
587
604
  else {
588
- gizmo.detach();
589
605
  selectionBox.visible = false;
590
606
  marker.visible = false;
591
607
  for (const obj of uniqueObjs) {
@@ -599,6 +615,19 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
599
615
  }
600
616
  box.setFromObject(obj);
601
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);
602
631
  }
603
632
  const entityIds = uniqueObjs.map((o) => entityByObject.get(o)).filter((id) => !!id);
604
633
  window.parent.postMessage({ type: 'umicat:editor:selectionChanged3d', entityIds }, '*');
@@ -692,17 +721,53 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
692
721
  return hits;
693
722
  }
694
723
  let gizmoDrag = null;
724
+ let groupDrag = null;
695
725
  const beginGizmoDrag = (hit, e) => {
696
726
  const obj = gizmo.attached;
697
727
  if (!obj)
698
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;
699
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
+ };
700
764
  if (hit.mode === 'move' && hit.axis !== 'xyz') {
701
765
  const lineDir = gizmo.axisDirectionWorld(hit.axis);
702
766
  const grab = closestPointOnLineToRay(raycaster.ray.origin, raycaster.ray.direction, worldPos, lineDir);
703
767
  if (!grab)
704
768
  return false; // camera looking straight down this axis
705
769
  gizmoDrag = { mode: 'move', axis: hit.axis, lineOrigin: worldPos.clone(), lineDir, grabOffset: grab.clone().sub(worldPos) };
770
+ beginGroupSnapshot();
706
771
  return true;
707
772
  }
708
773
  if (hit.mode === 'scale' && hit.axis !== 'xyz') {
@@ -714,6 +779,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
714
779
  if (Math.abs(startSignedDistance) < 1e-4)
715
780
  return false; // grabbed essentially at the origin — no stable ratio
716
781
  gizmoDrag = { mode: 'scale', axis: hit.axis, lineOrigin: worldPos.clone(), lineDir, startSignedDistance, startScale: obj.scale.clone() };
782
+ beginGroupSnapshot();
717
783
  return true;
718
784
  }
719
785
  if (hit.mode === 'scale' && hit.axis === 'xyz') {
@@ -722,6 +788,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
722
788
  if (startScreenDistance < 2)
723
789
  return false; // grabbed on top of the object's own screen position
724
790
  gizmoDrag = { mode: 'scale', axis: 'xyz', originScreen, startScreenDistance, startScale: obj.scale.clone() };
791
+ beginGroupSnapshot();
725
792
  return true;
726
793
  }
727
794
  if (hit.mode === 'rotate' && hit.axis !== 'xyz') {
@@ -733,6 +800,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
733
800
  const parentWorldQuatInverse = obj.parent ? obj.parent.getWorldQuaternion(new THREE.Quaternion()).invert() : new THREE.Quaternion();
734
801
  const startWorldQuaternion = obj.getWorldQuaternion(new THREE.Quaternion());
735
802
  gizmoDrag = { mode: 'rotate', axis: hit.axis, planePoint: worldPos.clone(), planeNormal, startAngle, startWorldQuaternion, parentWorldQuatInverse };
803
+ beginGroupSnapshot();
736
804
  return true;
737
805
  }
738
806
  return false;
@@ -749,6 +817,20 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
749
817
  if (obj.parent)
750
818
  obj.parent.worldToLocal(newWorldPos);
751
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
+ }
752
834
  }
753
835
  else if (gizmoDrag.mode === 'scale' && gizmoDrag.axis !== 'xyz') {
754
836
  const grab = closestPointOnLineToRay(raycaster.ray.origin, raycaster.ray.direction, gizmoDrag.lineOrigin, gizmoDrag.lineDir);
@@ -757,6 +839,8 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
757
839
  const signedDistance = grab.clone().sub(gizmoDrag.lineOrigin).dot(gizmoDrag.lineDir);
758
840
  const ratio = THREE.MathUtils.clamp(signedDistance / gizmoDrag.startSignedDistance, 0.02, 50);
759
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.
760
844
  if (axis === 'x')
761
845
  obj.scale.x = startScale.x * ratio;
762
846
  else if (axis === 'y')
@@ -768,6 +852,23 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
768
852
  const currentScreenDistance = Math.hypot(e.clientX - gizmoDrag.originScreen.x, e.clientY - gizmoDrag.originScreen.y);
769
853
  const ratio = THREE.MathUtils.clamp(currentScreenDistance / gizmoDrag.startScreenDistance, 0.02, 50);
770
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
+ }
771
872
  }
772
873
  else if (gizmoDrag.mode === 'rotate') {
773
874
  const hitPoint = raycastPlane(raycaster.ray, gizmoDrag.planePoint, gizmoDrag.planeNormal);
@@ -778,6 +879,23 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
778
879
  const deltaQuat = new THREE.Quaternion().setFromAxisAngle(gizmoDrag.planeNormal, delta);
779
880
  const newWorldQuat = deltaQuat.multiply(gizmoDrag.startWorldQuaternion.clone());
780
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
+ }
781
899
  }
782
900
  selectionBox.setFromObject(obj);
783
901
  gizmo.update(camera);
@@ -1008,6 +1126,34 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1008
1126
  }
1009
1127
  if (gizmoDrag) {
1010
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
+ }
1011
1157
  const entityId = obj ? entityByObject.get(obj) : undefined;
1012
1158
  if (moved && obj && entityId) {
1013
1159
  if (gizmoDrag.mode === 'move') {
@@ -1855,6 +2001,11 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1855
2001
  selectionBox.visible = false;
1856
2002
  scene.add(selectionBox);
1857
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);
1858
2009
  // ADR-046 — a (re)load tears down the whole scene graph; any
1859
2010
  // multi-select boxes from a PRIOR scene were added to that scene, not
1860
2011
  // this one, and the objects they tracked are gone. No disposal loop
@@ -1862,6 +2013,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1862
2013
  // the stale bookkeeping.
1863
2014
  multiSelected = new Set();
1864
2015
  multiBoxes.clear();
2016
+ groupDrag = null;
1865
2017
  // Frame the whole scene — auto-fit, since a small template scene and a
1866
2018
  // real level's dozens of entities need wildly different orbit distances.
1867
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.10.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",