@umicat/three-sdk 1.11.0 → 1.13.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.
@@ -0,0 +1,19 @@
1
+ import type { ThreeUmicat } from './ThreeUmicat.js';
2
+ /** The size a game should render at: the upper panel when folded, else the window. */
3
+ export declare function viewportSize(umicat: ThreeUmicat): {
4
+ width: number;
5
+ height: number;
6
+ };
7
+ /**
8
+ * Starts keeping the page laid out for the fold. Call once, after `init`.
9
+ *
10
+ * Publishes the geometry as CSS custom properties on `<html>` so a game's own
11
+ * DOM/HUD can use it without reading the SDK:
12
+ *
13
+ * --umicat-top-height, --umicat-bottom-top, --umicat-bottom-height,
14
+ * --umicat-fold-top, --umicat-fold-height
15
+ *
16
+ * All in CSS pixels; all `0` when there is no fold, so a stylesheet that uses
17
+ * them is correct on a flat screen too.
18
+ */
19
+ export declare function installDualScreen(umicat: ThreeUmicat): () => void;
@@ -0,0 +1,99 @@
1
+ // Laying a 3D game across a folded device, NDS-style: the world above the
2
+ // crease, the controls below it.
3
+ //
4
+ // **The split is owned by two different parties, and that is not a design
5
+ // choice — it is where the code already lives.**
6
+ //
7
+ // • The SDK owns the touch-control layer (`Input3D` builds it), so moving the
8
+ // controls into the lower panel works on every 3D game that exists, with no
9
+ // game-side change at all.
10
+ //
11
+ // • The GAME owns its renderer and canvas — three-sdk has no central wrapper
12
+ // the way the Phaser SDK does, so every `main.ts` calls
13
+ // `renderer.setSize(window.innerWidth, window.innerHeight)` itself. The SDK
14
+ // cannot resize a renderer it was never handed. So a game that wants its
15
+ // world in the UPPER panel asks for the size instead of reading the window:
16
+ //
17
+ // const { width, height } = viewportSize(umicat);
18
+ // renderer.setSize(width, height, false);
19
+ // camera.aspect = width / height;
20
+ //
21
+ // `viewportSize` is the whole window when there is no fold, so that line is
22
+ // correct everywhere and the game never branches.
23
+ //
24
+ // A game that does NOT adopt `viewportSize` still gets the controls moved down,
25
+ // which is the half that matters for reach; its world simply still spans the
26
+ // crease. That is a worse picture, not a broken one, and it degrades without
27
+ // anybody having to ship anything.
28
+ const TOUCH_ROOT = '[data-umicat-touch]';
29
+ /** The size a game should render at: the upper panel when folded, else the window. */
30
+ export function viewportSize(umicat) {
31
+ const { dualScreen, top } = umicat.fold.layout;
32
+ if (dualScreen && top)
33
+ return { width: top.width, height: top.height };
34
+ return { width: window.innerWidth, height: window.innerHeight };
35
+ }
36
+ /**
37
+ * Starts keeping the page laid out for the fold. Call once, after `init`.
38
+ *
39
+ * Publishes the geometry as CSS custom properties on `<html>` so a game's own
40
+ * DOM/HUD can use it without reading the SDK:
41
+ *
42
+ * --umicat-top-height, --umicat-bottom-top, --umicat-bottom-height,
43
+ * --umicat-fold-top, --umicat-fold-height
44
+ *
45
+ * All in CSS pixels; all `0` when there is no fold, so a stylesheet that uses
46
+ * them is correct on a flat screen too.
47
+ */
48
+ export function installDualScreen(umicat) {
49
+ return umicat.fold.subscribe((layout) => {
50
+ publishVariables(layout);
51
+ placeControls(layout);
52
+ // The game sizes its own renderer off a resize listener. Folding is a size
53
+ // change as far as it is concerned, but no window resize accompanies it —
54
+ // the window is exactly as big as it was, the usable part of it is not.
55
+ window.dispatchEvent(new Event('resize'));
56
+ });
57
+ }
58
+ function publishVariables(layout) {
59
+ const root = document.documentElement;
60
+ const px = (n) => `${Math.round(n ?? 0)}px`;
61
+ const on = layout.dualScreen;
62
+ root.style.setProperty('--umicat-top-height', px(on ? layout.top?.height : 0));
63
+ root.style.setProperty('--umicat-bottom-top', px(on ? layout.bottom?.y : 0));
64
+ root.style.setProperty('--umicat-bottom-height', px(on ? layout.bottom?.height : 0));
65
+ root.style.setProperty('--umicat-fold-top', px(on ? layout.division?.y : 0));
66
+ root.style.setProperty('--umicat-fold-height', px(on ? layout.division?.height : 0));
67
+ // A stylesheet cannot ask the SDK a question, so the state is an attribute.
68
+ if (on)
69
+ root.dataset.umicatDualScreen = '';
70
+ else
71
+ delete root.dataset.umicatDualScreen;
72
+ }
73
+ /**
74
+ * Moves the SDK's touch layer into the lower panel.
75
+ *
76
+ * It is `position:fixed; inset:0` normally — the full window, with the stick
77
+ * and buttons pinned near the bottom corners, which is where thumbs are on a
78
+ * flat phone. Folded, thumbs are on the lower half and the upper half is
79
+ * propped away from them, so "near the bottom of the window" is the wrong place
80
+ * twice over: too far to reach, and sitting on top of the world.
81
+ *
82
+ * Done by moving the LAYER rather than each control, so every control the SDK
83
+ * places — and any it grows later — follows for free.
84
+ */
85
+ function placeControls(layout) {
86
+ const root = document.querySelector(TOUCH_ROOT);
87
+ if (!root)
88
+ return; // desktop: the SDK mounts no touch layer at all
89
+ if (layout.dualScreen && layout.bottom) {
90
+ Object.assign(root.style, {
91
+ top: `${layout.bottom.y}px`,
92
+ bottom: '0px',
93
+ inset: '',
94
+ });
95
+ }
96
+ else {
97
+ Object.assign(root.style, { inset: '0', top: '', bottom: '' });
98
+ }
99
+ }
@@ -726,32 +726,48 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
726
726
  const obj = gizmo.attached;
727
727
  if (!obj)
728
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;
739
729
  const worldPos = obj.getWorldPosition(new THREE.Vector3());
740
730
  // Snapshots every selected real entity's WORLD-space starting
741
731
  // transform, for `updateGizmoDrag` to re-derive each one's CURRENT
742
732
  // transform from (its own start + this frame's pivot delta) rather
743
- // than compounding frame-over-frame.
744
- const beginGroupSnapshot = () => {
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) => {
745
738
  if (obj !== groupPivot)
746
739
  return;
747
740
  const members = [];
748
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
+ }
749
764
  members.push({
750
765
  obj: m,
751
766
  startWorldPos: m.getWorldPosition(new THREE.Vector3()),
752
- startWorldQuat: m.getWorldQuaternion(new THREE.Quaternion()),
767
+ startWorldQuat: worldQuat,
753
768
  startLocalScale: m.scale.clone(),
754
769
  parentWorldQuatInverse: m.parent ? m.parent.getWorldQuaternion(new THREE.Quaternion()).invert() : new THREE.Quaternion(),
770
+ nearestLocalAxisIndex,
755
771
  });
756
772
  }
757
773
  groupDrag = {
@@ -779,7 +795,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
779
795
  if (Math.abs(startSignedDistance) < 1e-4)
780
796
  return false; // grabbed essentially at the origin — no stable ratio
781
797
  gizmoDrag = { mode: 'scale', axis: hit.axis, lineOrigin: worldPos.clone(), lineDir, startSignedDistance, startScale: obj.scale.clone() };
782
- beginGroupSnapshot();
798
+ beginGroupSnapshot(lineDir);
783
799
  return true;
784
800
  }
785
801
  if (hit.mode === 'scale' && hit.axis === 'xyz') {
@@ -839,14 +855,35 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
839
855
  const signedDistance = grab.clone().sub(gizmoDrag.lineOrigin).dot(gizmoDrag.lineDir);
840
856
  const ratio = THREE.MathUtils.clamp(signedDistance / gizmoDrag.startSignedDistance, 0.02, 50);
841
857
  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.
844
858
  if (axis === 'x')
845
859
  obj.scale.x = startScale.x * ratio;
846
860
  else if (axis === 'y')
847
861
  obj.scale.y = startScale.y * ratio;
848
862
  else
849
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
+ }
850
887
  }
851
888
  else if (gizmoDrag.mode === 'scale' && gizmoDrag.axis === 'xyz') {
852
889
  const currentScreenDistance = Math.hypot(e.clientX - gizmoDrag.originScreen.x, e.clientY - gizmoDrag.originScreen.y);
@@ -1149,6 +1186,25 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1149
1186
  }
1150
1187
  }
1151
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);
1152
1208
  groupDrag = null;
1153
1209
  gizmoDrag = null;
1154
1210
  controls.enabled = true;
package/dist/index.d.ts CHANGED
@@ -27,6 +27,8 @@ export { resolveAnchor3D } from './hud3d/anchor3d.js';
27
27
  export { setHudBinding3D, getHudBinding3D } from './hud3d/HudDynamicBinding3D.js';
28
28
  export type { Attachment } from './Sockets.js';
29
29
  export type { LoadedScene3D, LoadSceneOptions } from './SceneLoader3D.js';
30
+ export { installDualScreen, viewportSize } from './DualScreen3D.js';
31
+ export type { FoldLayout, FoldRect } from '@umicat/platform-sdk/fold/FoldModule.js';
30
32
  export { ORIENTATION_DIMENSIONS } from '@umicat/platform-sdk/orientation.js';
31
33
  export type { Orientation } from '@umicat/platform-sdk/orientation.js';
32
34
  export { RpcError } from '@umicat/platform-sdk/core/Transport.js';
package/dist/index.js CHANGED
@@ -24,5 +24,6 @@ export { setHudBinding3D, getHudBinding3D } from './hud3d/HudDynamicBinding3D.js
24
24
  // Re-exported so a game imports one package for the common case. A game should
25
25
  // not have to know that identity and saves come from a different package than
26
26
  // the renderer.
27
+ export { installDualScreen, viewportSize } from './DualScreen3D.js';
27
28
  export { ORIENTATION_DIMENSIONS } from '@umicat/platform-sdk/orientation.js';
28
29
  export { RpcError } from '@umicat/platform-sdk/core/Transport.js';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.11.0",
3
+ "version": "1.13.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",
@@ -19,7 +19,7 @@
19
19
  "dependencies": {
20
20
  "@dimforge/rapier3d-compat": "^0.14.0",
21
21
  "three": "0.186.0",
22
- "@umicat/platform-sdk": "^0.2.0"
22
+ "@umicat/platform-sdk": "^0.3.0"
23
23
  },
24
24
  "devDependencies": {
25
25
  "@types/three": "^0.185.4",