@umicat/three-sdk 1.10.0 → 1.12.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,69 @@ 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;
699
729
  const worldPos = obj.getWorldPosition(new THREE.Vector3());
730
+ // Snapshots every selected real entity's WORLD-space starting
731
+ // transform, for `updateGizmoDrag` to re-derive each one's CURRENT
732
+ // transform from (its own start + this frame's pivot delta) rather
733
+ // than compounding frame-over-frame. `worldAxisDir`, when given (a
734
+ // per-axis scale drag only — move/rotate pass nothing), is what each
735
+ // member's `nearestLocalAxisIndex` is computed against.
736
+ const AXIS_UNIT_VECTORS = [new THREE.Vector3(1, 0, 0), new THREE.Vector3(0, 1, 0), new THREE.Vector3(0, 0, 1)];
737
+ const beginGroupSnapshot = (worldAxisDir) => {
738
+ if (obj !== groupPivot)
739
+ return;
740
+ const members = [];
741
+ for (const m of multiSelected) {
742
+ const worldQuat = m.getWorldQuaternion(new THREE.Quaternion());
743
+ let nearestLocalAxisIndex = 0;
744
+ if (worldAxisDir) {
745
+ // ADR-046 Phase 3b.1 — "scale this member along whichever of
746
+ // ITS OWN local axes best matches the dragged world axis," the
747
+ // same nearest-matching-axis approximation real DCCs use for a
748
+ // multi-object per-axis scale when members aren't all
749
+ // world-axis-aligned: a literal world-space stretch of an
750
+ // arbitrarily rotated rigid box would require shear, which a
751
+ // Part-style position+scale (no shear component) can't store,
752
+ // so SOME approximation is unavoidable — this is the simplest
753
+ // one (snap to the best-aligned axis), not a continuous
754
+ // decomposition that would blend as rotation increases.
755
+ let best = -Infinity;
756
+ for (let i = 0; i < 3; i++) {
757
+ const score = Math.abs(AXIS_UNIT_VECTORS[i].clone().applyQuaternion(worldQuat).dot(worldAxisDir));
758
+ if (score > best) {
759
+ best = score;
760
+ nearestLocalAxisIndex = i;
761
+ }
762
+ }
763
+ }
764
+ members.push({
765
+ obj: m,
766
+ startWorldPos: m.getWorldPosition(new THREE.Vector3()),
767
+ startWorldQuat: worldQuat,
768
+ startLocalScale: m.scale.clone(),
769
+ parentWorldQuatInverse: m.parent ? m.parent.getWorldQuaternion(new THREE.Quaternion()).invert() : new THREE.Quaternion(),
770
+ nearestLocalAxisIndex,
771
+ });
772
+ }
773
+ groupDrag = {
774
+ pivotStartPos: obj.position.clone(), // groupPivot has no parent — local IS world
775
+ pivotStartQuat: obj.quaternion.clone(),
776
+ pivotStartScale: obj.scale.clone(),
777
+ members,
778
+ };
779
+ };
700
780
  if (hit.mode === 'move' && hit.axis !== 'xyz') {
701
781
  const lineDir = gizmo.axisDirectionWorld(hit.axis);
702
782
  const grab = closestPointOnLineToRay(raycaster.ray.origin, raycaster.ray.direction, worldPos, lineDir);
703
783
  if (!grab)
704
784
  return false; // camera looking straight down this axis
705
785
  gizmoDrag = { mode: 'move', axis: hit.axis, lineOrigin: worldPos.clone(), lineDir, grabOffset: grab.clone().sub(worldPos) };
786
+ beginGroupSnapshot();
706
787
  return true;
707
788
  }
708
789
  if (hit.mode === 'scale' && hit.axis !== 'xyz') {
@@ -714,6 +795,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
714
795
  if (Math.abs(startSignedDistance) < 1e-4)
715
796
  return false; // grabbed essentially at the origin — no stable ratio
716
797
  gizmoDrag = { mode: 'scale', axis: hit.axis, lineOrigin: worldPos.clone(), lineDir, startSignedDistance, startScale: obj.scale.clone() };
798
+ beginGroupSnapshot(lineDir);
717
799
  return true;
718
800
  }
719
801
  if (hit.mode === 'scale' && hit.axis === 'xyz') {
@@ -722,6 +804,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
722
804
  if (startScreenDistance < 2)
723
805
  return false; // grabbed on top of the object's own screen position
724
806
  gizmoDrag = { mode: 'scale', axis: 'xyz', originScreen, startScreenDistance, startScale: obj.scale.clone() };
807
+ beginGroupSnapshot();
725
808
  return true;
726
809
  }
727
810
  if (hit.mode === 'rotate' && hit.axis !== 'xyz') {
@@ -733,6 +816,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
733
816
  const parentWorldQuatInverse = obj.parent ? obj.parent.getWorldQuaternion(new THREE.Quaternion()).invert() : new THREE.Quaternion();
734
817
  const startWorldQuaternion = obj.getWorldQuaternion(new THREE.Quaternion());
735
818
  gizmoDrag = { mode: 'rotate', axis: hit.axis, planePoint: worldPos.clone(), planeNormal, startAngle, startWorldQuaternion, parentWorldQuatInverse };
819
+ beginGroupSnapshot();
736
820
  return true;
737
821
  }
738
822
  return false;
@@ -749,6 +833,20 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
749
833
  if (obj.parent)
750
834
  obj.parent.worldToLocal(newWorldPos);
751
835
  obj.position.copy(newWorldPos);
836
+ // ADR-046 Phase 3b — propagate the SAME world-space displacement to
837
+ // every group member, each starting from ITS OWN snapshot (not
838
+ // compounding across frames). `obj` (the pivot) has no parent, so
839
+ // its local `.position` IS its world position.
840
+ if (groupDrag) {
841
+ const worldDelta = obj.position.clone().sub(groupDrag.pivotStartPos);
842
+ for (const member of groupDrag.members) {
843
+ const memberWorldPos = member.startWorldPos.clone().add(worldDelta);
844
+ if (member.obj.parent)
845
+ member.obj.parent.worldToLocal(memberWorldPos);
846
+ member.obj.position.copy(memberWorldPos);
847
+ multiBoxes.get(member.obj)?.setFromObject(member.obj);
848
+ }
849
+ }
752
850
  }
753
851
  else if (gizmoDrag.mode === 'scale' && gizmoDrag.axis !== 'xyz') {
754
852
  const grab = closestPointOnLineToRay(raycaster.ray.origin, raycaster.ray.direction, gizmoDrag.lineOrigin, gizmoDrag.lineDir);
@@ -763,11 +861,51 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
763
861
  obj.scale.y = startScale.y * ratio;
764
862
  else
765
863
  obj.scale.z = startScale.z * ratio;
864
+ // ADR-046 Phase 3b.1 — group members: scale each member's own
865
+ // NEAREST local axis (picked once at drag-begin, per
866
+ // `nearestLocalAxisIndex`) by the ratio, and scale only the
867
+ // component of its pivot-offset PARALLEL to the dragged world
868
+ // axis (the position math is unambiguous regardless of rotation —
869
+ // only "which of the member's own scale components" needed the
870
+ // nearest-axis approximation).
871
+ if (groupDrag) {
872
+ const worldAxisDir = gizmoDrag.lineDir;
873
+ for (const member of groupDrag.members) {
874
+ const offset = member.startWorldPos.clone().sub(groupDrag.pivotStartPos);
875
+ const along = offset.dot(worldAxisDir);
876
+ const parallel = worldAxisDir.clone().multiplyScalar(along);
877
+ const perp = offset.clone().sub(parallel);
878
+ const memberWorldPos = groupDrag.pivotStartPos.clone().add(perp).add(parallel.multiplyScalar(ratio));
879
+ if (member.obj.parent)
880
+ member.obj.parent.worldToLocal(memberWorldPos);
881
+ member.obj.position.copy(memberWorldPos);
882
+ const i = member.nearestLocalAxisIndex;
883
+ member.obj.scale.setComponent(i, member.startLocalScale.getComponent(i) * ratio);
884
+ multiBoxes.get(member.obj)?.setFromObject(member.obj);
885
+ }
886
+ }
766
887
  }
767
888
  else if (gizmoDrag.mode === 'scale' && gizmoDrag.axis === 'xyz') {
768
889
  const currentScreenDistance = Math.hypot(e.clientX - gizmoDrag.originScreen.x, e.clientY - gizmoDrag.originScreen.y);
769
890
  const ratio = THREE.MathUtils.clamp(currentScreenDistance / gizmoDrag.startScreenDistance, 0.02, 50);
770
891
  obj.scale.copy(gizmoDrag.startScale).multiplyScalar(ratio);
892
+ // UNIFORM scale is the one scale mode a group drag CAN reach.
893
+ // Scaling each member's own offset-from-pivot AND its own scale by
894
+ // the identical ratio is exact regardless of each member's
895
+ // individual rotation — uniform scaling commutes with rotation,
896
+ // which is exactly why per-axis scaling is refused above but this
897
+ // isn't.
898
+ if (groupDrag) {
899
+ for (const member of groupDrag.members) {
900
+ const offset = member.startWorldPos.clone().sub(groupDrag.pivotStartPos).multiplyScalar(ratio);
901
+ const memberWorldPos = groupDrag.pivotStartPos.clone().add(offset);
902
+ if (member.obj.parent)
903
+ member.obj.parent.worldToLocal(memberWorldPos);
904
+ member.obj.position.copy(memberWorldPos);
905
+ member.obj.scale.copy(member.startLocalScale).multiplyScalar(ratio);
906
+ multiBoxes.get(member.obj)?.setFromObject(member.obj);
907
+ }
908
+ }
771
909
  }
772
910
  else if (gizmoDrag.mode === 'rotate') {
773
911
  const hitPoint = raycastPlane(raycaster.ray, gizmoDrag.planePoint, gizmoDrag.planeNormal);
@@ -778,6 +916,23 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
778
916
  const deltaQuat = new THREE.Quaternion().setFromAxisAngle(gizmoDrag.planeNormal, delta);
779
917
  const newWorldQuat = deltaQuat.multiply(gizmoDrag.startWorldQuaternion.clone());
780
918
  obj.quaternion.copy(gizmoDrag.parentWorldQuatInverse.clone().multiply(newWorldQuat));
919
+ // Each member ORBITS the pivot (its offset-from-pivot rotates by
920
+ // the same delta) AND SPINS IN PLACE by that same delta — the rigid
921
+ // body behavior Roblox/Unity use for rotating a multi-selection
922
+ // together, not each member spinning around its own origin.
923
+ if (groupDrag) {
924
+ for (const member of groupDrag.members) {
925
+ const offset = member.startWorldPos.clone().sub(groupDrag.pivotStartPos);
926
+ offset.applyQuaternion(deltaQuat);
927
+ const memberWorldPos = groupDrag.pivotStartPos.clone().add(offset);
928
+ if (member.obj.parent)
929
+ member.obj.parent.worldToLocal(memberWorldPos);
930
+ member.obj.position.copy(memberWorldPos);
931
+ const memberWorldQuat = deltaQuat.clone().multiply(member.startWorldQuat);
932
+ member.obj.quaternion.copy(member.parentWorldQuatInverse.clone().multiply(memberWorldQuat));
933
+ multiBoxes.get(member.obj)?.setFromObject(member.obj);
934
+ }
935
+ }
781
936
  }
782
937
  selectionBox.setFromObject(obj);
783
938
  gizmo.update(camera);
@@ -1008,6 +1163,53 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1008
1163
  }
1009
1164
  if (gizmoDrag) {
1010
1165
  const obj = gizmo.attached;
1166
+ // ADR-046 Phase 3b — the shared-pivot case posts ONE end message
1167
+ // PER group member (reusing the exact same `dragEnd3d`/
1168
+ // `rotateEnd3d`/`scaleEnd3d` message shapes a single-entity drag
1169
+ // already uses — the host's existing per-entity-id handler for
1170
+ // each needed zero changes to persist N entities instead of one).
1171
+ if (obj === groupPivot && groupDrag) {
1172
+ if (moved) {
1173
+ for (const member of groupDrag.members) {
1174
+ const entityId = entityByObject.get(member.obj);
1175
+ if (!entityId)
1176
+ continue;
1177
+ if (gizmoDrag.mode === 'move') {
1178
+ 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 } }, '*');
1179
+ }
1180
+ else if (gizmoDrag.mode === 'rotate') {
1181
+ const q = member.obj.quaternion;
1182
+ window.parent.postMessage({ type: 'umicat:editor:rotateEnd3d', sceneId: opts.sceneId, entityId, rotation: [q.x, q.y, q.z, q.w] }, '*');
1183
+ }
1184
+ else if (gizmoDrag.mode === 'scale') {
1185
+ 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 } }, '*');
1186
+ }
1187
+ }
1188
+ }
1189
+ // ADR-046 Phase 3b.1 — the pivot's rotation/scale are reset back
1190
+ // to identity/1 the instant the drag ends, not just when the
1191
+ // SELECTION changes. A rotate drag necessarily leaves the pivot
1192
+ // itself rotated (that's how its delta is computed), and a scale
1193
+ // drag leaves it scaled — if either stuck around into the NEXT
1194
+ // gesture, `axisDirectionWorld('x')` (used both for rendering the
1195
+ // handles AND for Phase 3b.1's own nearest-matching-axis per-axis
1196
+ // scale math) would resolve against the PIVOT's stale leftover
1197
+ // rotation instead of true world space, corrupting an
1198
+ // immediately-following per-axis scale with no visible symptom
1199
+ // beyond "the wrong member axis changed" — exactly the bug this
1200
+ // reset fixes. The pivot's POSITION is never reset here — move/
1201
+ // rotate/scale all keep it exactly at the true centroid
1202
+ // throughout (rotating and uniform-scaling around the centroid
1203
+ // can't move it; a translate moves it by the same amount the
1204
+ // members moved, which IS the new centroid).
1205
+ groupPivot.quaternion.identity();
1206
+ groupPivot.scale.set(1, 1, 1);
1207
+ gizmo.update(camera);
1208
+ groupDrag = null;
1209
+ gizmoDrag = null;
1210
+ controls.enabled = true;
1211
+ return;
1212
+ }
1011
1213
  const entityId = obj ? entityByObject.get(obj) : undefined;
1012
1214
  if (moved && obj && entityId) {
1013
1215
  if (gizmoDrag.mode === 'move') {
@@ -1855,6 +2057,11 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1855
2057
  selectionBox.visible = false;
1856
2058
  scene.add(selectionBox);
1857
2059
  scene.add(gizmo.root);
2060
+ // ADR-046 Phase 3b — the shared pivot itself has no visible geometry,
2061
+ // but it still needs to be IN the (fresh) scene graph for
2062
+ // `gizmo.attach(groupPivot, ...)` and any `getWorldPosition`/
2063
+ // `worldToLocal` math against it to resolve correctly.
2064
+ scene.add(groupPivot);
1858
2065
  // ADR-046 — a (re)load tears down the whole scene graph; any
1859
2066
  // multi-select boxes from a PRIOR scene were added to that scene, not
1860
2067
  // this one, and the objects they tracked are gone. No disposal loop
@@ -1862,6 +2069,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1862
2069
  // the stale bookkeeping.
1863
2070
  multiSelected = new Set();
1864
2071
  multiBoxes.clear();
2072
+ groupDrag = null;
1865
2073
  // Frame the whole scene — auto-fit, since a small template scene and a
1866
2074
  // real level's dozens of entities need wildly different orbit distances.
1867
2075
  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.12.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",