@umicat/three-sdk 0.22.0 → 0.24.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.
- package/README.md +9 -3
- package/dist/editor/EditorDesignPlayer3D.d.ts +25 -7
- package/dist/editor/EditorDesignPlayer3D.js +386 -11
- package/dist/editor/TransformGizmo3D.d.ts +50 -0
- package/dist/editor/TransformGizmo3D.js +162 -0
- package/dist/editor/gizmoMath.d.ts +36 -0
- package/dist/editor/gizmoMath.js +60 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -18,11 +18,17 @@ devices and binds keys everywhere, bone sockets, swappable skins and
|
|
|
18
18
|
attachments, hit tints, audio, the editor's screenshot/video-capture protocol,
|
|
19
19
|
and a read-and-write design view
|
|
20
20
|
(`EditorDesignPlayer3D`: click-to-pick, drag-to-move, a host→iframe patch
|
|
21
|
-
channel the platform Inspector drives,
|
|
21
|
+
channel the platform Inspector drives, drag-and-drop model placement —
|
|
22
22
|
`umicat:editor:dropModel3d` in, `umicat:editor:modelDropped3d` out — which
|
|
23
23
|
raycasts the drop point against the ground plane and fetches the GLB straight
|
|
24
|
-
from its CDN url, no manifest entry required
|
|
25
|
-
|
|
24
|
+
from its CDN url, no manifest entry required — and a full Roblox/Unity-style
|
|
25
|
+
3-axis **Move/Rotate/Scale gizmo** on the selected entity, mode switched via
|
|
26
|
+
`umicat:editor:setGizmoMode3d`, posting `dragEnd3d`/`rotateEnd3d`/`scaleEnd3d`
|
|
27
|
+
on release — plus **Delete** (`umicat:editor:deleteEntity3d`) and
|
|
28
|
+
**transform-only undo** (Ctrl/Cmd+Z; the undo stack itself lives on the
|
|
29
|
+
host, this player only replays a `patchEntity3d` restore)). What it still
|
|
30
|
+
does not have: undo of entity creation/deletion, multi-select, or a local/
|
|
31
|
+
global axis toggle (the gizmo is local-space only).
|
|
26
32
|
|
|
27
33
|
> This paragraph said "seed, not a product — no input system, no character
|
|
28
34
|
> controller, no audio, and no published package" for ten minor versions after
|
|
@@ -23,13 +23,31 @@ export interface EditorDesignPlayer3DOptions {
|
|
|
23
23
|
* marker reads off the exact world coordinate, posted to the host so a
|
|
24
24
|
* person can point at a real spot instead of guessing one blind when
|
|
25
25
|
* telling the AI where to place something.
|
|
26
|
-
* - **Drag** an entity to move it
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
26
|
+
* - **Drag** an entity's body directly to move it on the ground plane
|
|
27
|
+
* (Phase 1 of real editing — unchanged by the gizmo below). Grabbing
|
|
28
|
+
* empty space/sky orbits instead, same convention as Unity/Blender.
|
|
29
|
+
* - **Drag a gizmo handle** (Phase 2) — a Roblox/Unity-style 3-axis
|
|
30
|
+
* Move/Rotate/Scale gizmo appears on the selected entity. Dragging an
|
|
31
|
+
* arrow moves it along that axis (any direction, not just the ground
|
|
32
|
+
* plane); dragging a ring rotates it around that axis; dragging a scale
|
|
33
|
+
* handle (or the center cube, uniformly) resizes it. Mode switches via
|
|
34
|
+
* `umicat:editor:setGizmoMode3d`. This function itself never writes
|
|
35
|
+
* anything — it only moves/rotates/scales the live `THREE.Object3D` and
|
|
36
|
+
* posts the final LOCAL transform on release (`dragEnd3d` / `rotateEnd3d`
|
|
37
|
+
* / `scaleEnd3d`); the host owns turning that into a disk write.
|
|
38
|
+
* - **Delete** (0.24.0) — select an entity, press Delete, it's gone from
|
|
39
|
+
* the live scene immediately (`umicat:editor:deleteEntity3d` in /
|
|
40
|
+
* `entityDeleted3d` out — same ack shape as everything else here). The
|
|
41
|
+
* host owns removing it from disk once it sees `ok:true`.
|
|
42
|
+
* - **Undo** (0.24.0, transform-only) — Ctrl/Cmd+Z restores an entity's
|
|
43
|
+
* PRIOR position/rotation/scale. The undo stack itself lives on the host
|
|
44
|
+
* (see `umicat-home-ui`'s `useScene3DDesignView` CLAUDE.md note) — this
|
|
45
|
+
* player only ever receives an ordinary `patchEntity3d` with the restored
|
|
46
|
+
* value (its `patch` bag grew `position`/`rotation`/`scale` fields for
|
|
47
|
+
* exactly this), or — when the keypress happens while focus is inside
|
|
48
|
+
* THIS iframe rather than the host page — posts `requestUndo3d` asking
|
|
49
|
+
* the host to do its thing. No entity-creation/deletion undo yet (only
|
|
50
|
+
* transform edits on an entity that already exists).
|
|
33
51
|
*
|
|
34
52
|
* Takes over `renderer`'s animation loop entirely for the rest of the page's
|
|
35
53
|
* life — there is no scene-swap API and no teardown, matching how the
|
|
@@ -4,6 +4,8 @@ import { loadScene3D, loadModelAsset } from '../SceneLoader3D.js';
|
|
|
4
4
|
import { applySkin } from '../Skin.js';
|
|
5
5
|
import { applyAttachments } from '../Attachments.js';
|
|
6
6
|
import { singleModelManifest } from '../scene3d.js';
|
|
7
|
+
import { TransformGizmo3D } from './TransformGizmo3D.js';
|
|
8
|
+
import { closestPointOnLineToRay, raycastPlane, angleAroundAxis } from './gizmoMath.js';
|
|
7
9
|
/**
|
|
8
10
|
* The 3D counterpart of `@umicat/phaser-sdk`'s `EditorDesignScene` (ADR-021)
|
|
9
11
|
* — renders a scene's AUTHORED data with no game code and no save, so the
|
|
@@ -15,13 +17,31 @@ import { singleModelManifest } from '../scene3d.js';
|
|
|
15
17
|
* marker reads off the exact world coordinate, posted to the host so a
|
|
16
18
|
* person can point at a real spot instead of guessing one blind when
|
|
17
19
|
* telling the AI where to place something.
|
|
18
|
-
* - **Drag** an entity to move it
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
20
|
+
* - **Drag** an entity's body directly to move it on the ground plane
|
|
21
|
+
* (Phase 1 of real editing — unchanged by the gizmo below). Grabbing
|
|
22
|
+
* empty space/sky orbits instead, same convention as Unity/Blender.
|
|
23
|
+
* - **Drag a gizmo handle** (Phase 2) — a Roblox/Unity-style 3-axis
|
|
24
|
+
* Move/Rotate/Scale gizmo appears on the selected entity. Dragging an
|
|
25
|
+
* arrow moves it along that axis (any direction, not just the ground
|
|
26
|
+
* plane); dragging a ring rotates it around that axis; dragging a scale
|
|
27
|
+
* handle (or the center cube, uniformly) resizes it. Mode switches via
|
|
28
|
+
* `umicat:editor:setGizmoMode3d`. This function itself never writes
|
|
29
|
+
* anything — it only moves/rotates/scales the live `THREE.Object3D` and
|
|
30
|
+
* posts the final LOCAL transform on release (`dragEnd3d` / `rotateEnd3d`
|
|
31
|
+
* / `scaleEnd3d`); the host owns turning that into a disk write.
|
|
32
|
+
* - **Delete** (0.24.0) — select an entity, press Delete, it's gone from
|
|
33
|
+
* the live scene immediately (`umicat:editor:deleteEntity3d` in /
|
|
34
|
+
* `entityDeleted3d` out — same ack shape as everything else here). The
|
|
35
|
+
* host owns removing it from disk once it sees `ok:true`.
|
|
36
|
+
* - **Undo** (0.24.0, transform-only) — Ctrl/Cmd+Z restores an entity's
|
|
37
|
+
* PRIOR position/rotation/scale. The undo stack itself lives on the host
|
|
38
|
+
* (see `umicat-home-ui`'s `useScene3DDesignView` CLAUDE.md note) — this
|
|
39
|
+
* player only ever receives an ordinary `patchEntity3d` with the restored
|
|
40
|
+
* value (its `patch` bag grew `position`/`rotation`/`scale` fields for
|
|
41
|
+
* exactly this), or — when the keypress happens while focus is inside
|
|
42
|
+
* THIS iframe rather than the host page — posts `requestUndo3d` asking
|
|
43
|
+
* the host to do its thing. No entity-creation/deletion undo yet (only
|
|
44
|
+
* transform edits on an entity that already exists).
|
|
25
45
|
*
|
|
26
46
|
* Takes over `renderer`'s animation loop entirely for the rest of the page's
|
|
27
47
|
* life — there is no scene-swap API and no teardown, matching how the
|
|
@@ -54,6 +74,13 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
54
74
|
selectionBox.visible = false;
|
|
55
75
|
selectionBox.renderOrder = 998;
|
|
56
76
|
selectionBox.material.depthTest = false;
|
|
77
|
+
// The Move/Rotate/Scale transform gizmo — shows (and is only hit-testable)
|
|
78
|
+
// on the current mode's handles once something is selected. `gizmo.root`
|
|
79
|
+
// is added to the scene once, at scene-load time, right alongside the
|
|
80
|
+
// marker/selection box above; `gizmo.update(camera)` runs every frame (the
|
|
81
|
+
// render loop below) so it follows the selected entity and keeps a
|
|
82
|
+
// roughly constant on-screen size as the camera orbits/zooms.
|
|
83
|
+
const gizmo = new TransformGizmo3D();
|
|
57
84
|
// Orientation gizmo — a small corner compass tracking the main camera's
|
|
58
85
|
// rotation only (never its position/zoom), same convention every 3D DCC
|
|
59
86
|
// uses: X=red, Y=green, Z=blue. Rendered as a second, tiny scene into a
|
|
@@ -111,6 +138,70 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
111
138
|
const point = new THREE.Vector3();
|
|
112
139
|
return raycaster.ray.intersectPlane(plane, point) ? point : null;
|
|
113
140
|
};
|
|
141
|
+
// The uniform-scale center handle drags by SCREEN distance from the
|
|
142
|
+
// object's projected position, not a 3D line/plane — there is no single
|
|
143
|
+
// "axis" a uniform scale runs along, but "how far did you drag the
|
|
144
|
+
// cursor away from the object" is an unambiguous 1-DOF gesture in any
|
|
145
|
+
// camera orientation.
|
|
146
|
+
const worldToClientXY = (world) => {
|
|
147
|
+
const ndc = world.clone().project(camera);
|
|
148
|
+
const rect = renderer.domElement.getBoundingClientRect();
|
|
149
|
+
return {
|
|
150
|
+
x: rect.left + (ndc.x * 0.5 + 0.5) * rect.width,
|
|
151
|
+
y: rect.top + (1 - (ndc.y * 0.5 + 0.5)) * rect.height,
|
|
152
|
+
};
|
|
153
|
+
};
|
|
154
|
+
// Test-only readback — NOT part of the host↔iframe protocol, never read by
|
|
155
|
+
// umicat-home-ui. A gizmo handle's clickable screen position depends on
|
|
156
|
+
// the live camera distance (gizmo.update's constant-apparent-size scale)
|
|
157
|
+
// and the selected object's current world transform, so a real headless
|
|
158
|
+
// test needs to ask the live scene where a handle actually is rather than
|
|
159
|
+
// precompute it blind. Mirrors the project's existing precedent of
|
|
160
|
+
// exposing small debug readbacks for verification (e.g.
|
|
161
|
+
// `renderer.info.render.frame`) rather than hand-deriving pixel math that
|
|
162
|
+
// can silently drift from the real implementation.
|
|
163
|
+
globalThis.__umicatGizmoHandleScreenXY =
|
|
164
|
+
(mode, axis) => {
|
|
165
|
+
if (!gizmo.attached)
|
|
166
|
+
return null;
|
|
167
|
+
const worldPos = gizmo.attached.getWorldPosition(new THREE.Vector3());
|
|
168
|
+
if (axis === 'xyz')
|
|
169
|
+
return worldToClientXY(worldPos); // center cube sits at the object's own position
|
|
170
|
+
const scale = gizmo.root.scale.x;
|
|
171
|
+
if (mode === 'rotate') {
|
|
172
|
+
// The ring for a given axis lies in the plane perpendicular to it —
|
|
173
|
+
// a point ON the ring is offset along one of the OTHER two local
|
|
174
|
+
// axes by the ring's radius (1, built in TransformGizmo3D.ts).
|
|
175
|
+
const other = axis === 'x' ? 'y' : 'x';
|
|
176
|
+
const dir = gizmo.axisDirectionWorld(other);
|
|
177
|
+
return worldToClientXY(worldPos.clone().addScaledVector(dir, scale * 1.0));
|
|
178
|
+
}
|
|
179
|
+
// move/scale handles run OUTWARD along their own axis — the shaft
|
|
180
|
+
// midpoint (built 0..~0.8 local units) is a safely-clickable point.
|
|
181
|
+
const dir = gizmo.axisDirectionWorld(axis);
|
|
182
|
+
return worldToClientXY(worldPos.clone().addScaledVector(dir, scale * 0.5));
|
|
183
|
+
};
|
|
184
|
+
// Test-only — the attached object's current local scale, so a test can
|
|
185
|
+
// snapshot it BEFORE a scale drag rather than assume a baseline of 1 (a
|
|
186
|
+
// dropped model's `importScale` means that's almost never true).
|
|
187
|
+
globalThis.__umicatGizmoAttachedScale =
|
|
188
|
+
() => gizmo.attached ? { x: gizmo.attached.scale.x, y: gizmo.attached.scale.y, z: gizmo.attached.scale.z } : null;
|
|
189
|
+
// Test-only — an arbitrary entity's current LOCAL transform, by id (not
|
|
190
|
+
// just the attached/selected one) — lets a test verify a `patchEntity3d`
|
|
191
|
+
// position/rotation/scale override actually reached the live object,
|
|
192
|
+
// and that a deleted entity is genuinely gone from `objectByEntity`
|
|
193
|
+
// rather than just visually hidden.
|
|
194
|
+
globalThis.__umicatEntityTransform =
|
|
195
|
+
(entityId) => {
|
|
196
|
+
const o = objectByEntity.get(entityId);
|
|
197
|
+
if (!o)
|
|
198
|
+
return null;
|
|
199
|
+
return {
|
|
200
|
+
position: { x: o.position.x, y: o.position.y, z: o.position.z },
|
|
201
|
+
rotation: [o.quaternion.x, o.quaternion.y, o.quaternion.z, o.quaternion.w],
|
|
202
|
+
scale: { x: o.scale.x, y: o.scale.y, z: o.scale.z },
|
|
203
|
+
};
|
|
204
|
+
};
|
|
114
205
|
// Only VISIBLE entity roots are ever raycast against. three.js's
|
|
115
206
|
// Mesh.raycast does NOT check `.visible` on its own (confirmed against the
|
|
116
207
|
// pinned three source — no such check in Raycaster.js or Object3D.raycast),
|
|
@@ -154,12 +245,118 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
154
245
|
let dragEntityId = null;
|
|
155
246
|
let dragPlane = null;
|
|
156
247
|
let dragGrabOffset = null; // world-space, plane-point minus object position at grab time
|
|
248
|
+
let gizmoDrag = null;
|
|
249
|
+
const beginGizmoDrag = (hit, e) => {
|
|
250
|
+
const obj = gizmo.attached;
|
|
251
|
+
if (!obj)
|
|
252
|
+
return false;
|
|
253
|
+
const worldPos = obj.getWorldPosition(new THREE.Vector3());
|
|
254
|
+
if (hit.mode === 'move' && hit.axis !== 'xyz') {
|
|
255
|
+
const lineDir = gizmo.axisDirectionWorld(hit.axis);
|
|
256
|
+
const grab = closestPointOnLineToRay(raycaster.ray.origin, raycaster.ray.direction, worldPos, lineDir);
|
|
257
|
+
if (!grab)
|
|
258
|
+
return false; // camera looking straight down this axis
|
|
259
|
+
gizmoDrag = { mode: 'move', axis: hit.axis, lineOrigin: worldPos.clone(), lineDir, grabOffset: grab.clone().sub(worldPos) };
|
|
260
|
+
return true;
|
|
261
|
+
}
|
|
262
|
+
if (hit.mode === 'scale' && hit.axis !== 'xyz') {
|
|
263
|
+
const lineDir = gizmo.axisDirectionWorld(hit.axis);
|
|
264
|
+
const grab = closestPointOnLineToRay(raycaster.ray.origin, raycaster.ray.direction, worldPos, lineDir);
|
|
265
|
+
if (!grab)
|
|
266
|
+
return false;
|
|
267
|
+
const startSignedDistance = grab.clone().sub(worldPos).dot(lineDir);
|
|
268
|
+
if (Math.abs(startSignedDistance) < 1e-4)
|
|
269
|
+
return false; // grabbed essentially at the origin — no stable ratio
|
|
270
|
+
gizmoDrag = { mode: 'scale', axis: hit.axis, lineOrigin: worldPos.clone(), lineDir, startSignedDistance, startScale: obj.scale.clone() };
|
|
271
|
+
return true;
|
|
272
|
+
}
|
|
273
|
+
if (hit.mode === 'scale' && hit.axis === 'xyz') {
|
|
274
|
+
const originScreen = worldToClientXY(worldPos);
|
|
275
|
+
const startScreenDistance = Math.hypot(e.clientX - originScreen.x, e.clientY - originScreen.y);
|
|
276
|
+
if (startScreenDistance < 2)
|
|
277
|
+
return false; // grabbed on top of the object's own screen position
|
|
278
|
+
gizmoDrag = { mode: 'scale', axis: 'xyz', originScreen, startScreenDistance, startScale: obj.scale.clone() };
|
|
279
|
+
return true;
|
|
280
|
+
}
|
|
281
|
+
if (hit.mode === 'rotate' && hit.axis !== 'xyz') {
|
|
282
|
+
const planeNormal = gizmo.axisDirectionWorld(hit.axis);
|
|
283
|
+
const hitPoint = raycastPlane(raycaster.ray, worldPos, planeNormal);
|
|
284
|
+
if (!hitPoint)
|
|
285
|
+
return false; // camera edge-on to this ring's plane
|
|
286
|
+
const startAngle = angleAroundAxis(worldPos, planeNormal, hitPoint);
|
|
287
|
+
const parentWorldQuatInverse = obj.parent ? obj.parent.getWorldQuaternion(new THREE.Quaternion()).invert() : new THREE.Quaternion();
|
|
288
|
+
const startWorldQuaternion = obj.getWorldQuaternion(new THREE.Quaternion());
|
|
289
|
+
gizmoDrag = { mode: 'rotate', axis: hit.axis, planePoint: worldPos.clone(), planeNormal, startAngle, startWorldQuaternion, parentWorldQuatInverse };
|
|
290
|
+
return true;
|
|
291
|
+
}
|
|
292
|
+
return false;
|
|
293
|
+
};
|
|
294
|
+
const updateGizmoDrag = (e) => {
|
|
295
|
+
if (!gizmoDrag || !gizmo.attached)
|
|
296
|
+
return;
|
|
297
|
+
const obj = gizmo.attached;
|
|
298
|
+
if (gizmoDrag.mode === 'move') {
|
|
299
|
+
const grab = closestPointOnLineToRay(raycaster.ray.origin, raycaster.ray.direction, gizmoDrag.lineOrigin, gizmoDrag.lineDir);
|
|
300
|
+
if (!grab)
|
|
301
|
+
return;
|
|
302
|
+
const newWorldPos = grab.clone().sub(gizmoDrag.grabOffset);
|
|
303
|
+
if (obj.parent)
|
|
304
|
+
obj.parent.worldToLocal(newWorldPos);
|
|
305
|
+
obj.position.copy(newWorldPos);
|
|
306
|
+
}
|
|
307
|
+
else if (gizmoDrag.mode === 'scale' && gizmoDrag.axis !== 'xyz') {
|
|
308
|
+
const grab = closestPointOnLineToRay(raycaster.ray.origin, raycaster.ray.direction, gizmoDrag.lineOrigin, gizmoDrag.lineDir);
|
|
309
|
+
if (!grab)
|
|
310
|
+
return;
|
|
311
|
+
const signedDistance = grab.clone().sub(gizmoDrag.lineOrigin).dot(gizmoDrag.lineDir);
|
|
312
|
+
const ratio = THREE.MathUtils.clamp(signedDistance / gizmoDrag.startSignedDistance, 0.02, 50);
|
|
313
|
+
const { axis, startScale } = gizmoDrag;
|
|
314
|
+
if (axis === 'x')
|
|
315
|
+
obj.scale.x = startScale.x * ratio;
|
|
316
|
+
else if (axis === 'y')
|
|
317
|
+
obj.scale.y = startScale.y * ratio;
|
|
318
|
+
else
|
|
319
|
+
obj.scale.z = startScale.z * ratio;
|
|
320
|
+
}
|
|
321
|
+
else if (gizmoDrag.mode === 'scale' && gizmoDrag.axis === 'xyz') {
|
|
322
|
+
const currentScreenDistance = Math.hypot(e.clientX - gizmoDrag.originScreen.x, e.clientY - gizmoDrag.originScreen.y);
|
|
323
|
+
const ratio = THREE.MathUtils.clamp(currentScreenDistance / gizmoDrag.startScreenDistance, 0.02, 50);
|
|
324
|
+
obj.scale.copy(gizmoDrag.startScale).multiplyScalar(ratio);
|
|
325
|
+
}
|
|
326
|
+
else if (gizmoDrag.mode === 'rotate') {
|
|
327
|
+
const hitPoint = raycastPlane(raycaster.ray, gizmoDrag.planePoint, gizmoDrag.planeNormal);
|
|
328
|
+
if (!hitPoint)
|
|
329
|
+
return;
|
|
330
|
+
const currentAngle = angleAroundAxis(gizmoDrag.planePoint, gizmoDrag.planeNormal, hitPoint);
|
|
331
|
+
const delta = currentAngle - gizmoDrag.startAngle;
|
|
332
|
+
const deltaQuat = new THREE.Quaternion().setFromAxisAngle(gizmoDrag.planeNormal, delta);
|
|
333
|
+
const newWorldQuat = deltaQuat.multiply(gizmoDrag.startWorldQuaternion.clone());
|
|
334
|
+
obj.quaternion.copy(gizmoDrag.parentWorldQuatInverse.clone().multiply(newWorldQuat));
|
|
335
|
+
}
|
|
336
|
+
selectionBox.setFromObject(obj);
|
|
337
|
+
gizmo.update(camera);
|
|
338
|
+
moved = true;
|
|
339
|
+
};
|
|
157
340
|
const onPointerDown = (e) => {
|
|
158
341
|
downX = e.clientX;
|
|
159
342
|
downY = e.clientY;
|
|
160
343
|
moved = false;
|
|
161
344
|
if (!scene)
|
|
162
345
|
return;
|
|
346
|
+
if (gizmo.attached) {
|
|
347
|
+
raycaster.setFromCamera(ndcFromEvent(e), camera);
|
|
348
|
+
const gizmoHit = gizmo.hitTest(raycaster);
|
|
349
|
+
if (gizmoHit && beginGizmoDrag(gizmoHit, e)) {
|
|
350
|
+
controls.enabled = false;
|
|
351
|
+
try {
|
|
352
|
+
renderer.domElement.setPointerCapture(e.pointerId);
|
|
353
|
+
}
|
|
354
|
+
catch {
|
|
355
|
+
// See the same try/catch below — capture is an enhancement only.
|
|
356
|
+
}
|
|
357
|
+
return;
|
|
358
|
+
}
|
|
359
|
+
}
|
|
163
360
|
const hit = pickEntityAt(e);
|
|
164
361
|
if (!hit)
|
|
165
362
|
return; // empty space — let OrbitControls own this gesture
|
|
@@ -192,6 +389,11 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
192
389
|
const onPointerMove = (e) => {
|
|
193
390
|
if (Math.abs(e.clientX - downX) > 4 || Math.abs(e.clientY - downY) > 4)
|
|
194
391
|
moved = true;
|
|
392
|
+
if (gizmoDrag) {
|
|
393
|
+
raycaster.setFromCamera(ndcFromEvent(e), camera);
|
|
394
|
+
updateGizmoDrag(e);
|
|
395
|
+
return;
|
|
396
|
+
}
|
|
195
397
|
if (!dragEntity || !dragPlane || !dragGrabOffset || !scene)
|
|
196
398
|
return;
|
|
197
399
|
raycaster.setFromCamera(ndcFromEvent(e), camera);
|
|
@@ -212,6 +414,25 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
212
414
|
// Already released, or never captured (e.g. this gesture never hit an
|
|
213
415
|
// entity) — nothing to do either way.
|
|
214
416
|
}
|
|
417
|
+
if (gizmoDrag) {
|
|
418
|
+
const obj = gizmo.attached;
|
|
419
|
+
const entityId = obj ? entityByObject.get(obj) : undefined;
|
|
420
|
+
if (moved && obj && entityId) {
|
|
421
|
+
if (gizmoDrag.mode === 'move') {
|
|
422
|
+
window.parent.postMessage({ type: 'umicat:editor:dragEnd3d', sceneId: opts.sceneId, entityId, position: { x: obj.position.x, y: obj.position.y, z: obj.position.z } }, '*');
|
|
423
|
+
}
|
|
424
|
+
else if (gizmoDrag.mode === 'rotate') {
|
|
425
|
+
const q = obj.quaternion;
|
|
426
|
+
window.parent.postMessage({ type: 'umicat:editor:rotateEnd3d', sceneId: opts.sceneId, entityId, rotation: [q.x, q.y, q.z, q.w] }, '*');
|
|
427
|
+
}
|
|
428
|
+
else if (gizmoDrag.mode === 'scale') {
|
|
429
|
+
window.parent.postMessage({ type: 'umicat:editor:scaleEnd3d', sceneId: opts.sceneId, entityId, scale: { x: obj.scale.x, y: obj.scale.y, z: obj.scale.z } }, '*');
|
|
430
|
+
}
|
|
431
|
+
}
|
|
432
|
+
gizmoDrag = null;
|
|
433
|
+
controls.enabled = true;
|
|
434
|
+
return;
|
|
435
|
+
}
|
|
215
436
|
// A drag only really happened if the pointer actually moved — grabbing
|
|
216
437
|
// an entity and releasing without moving is a CLICK on it (case below),
|
|
217
438
|
// not a same-position no-op save.
|
|
@@ -230,10 +451,18 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
230
451
|
controls.enabled = true;
|
|
231
452
|
if (moved || !scene)
|
|
232
453
|
return;
|
|
233
|
-
// A plain click (no drag) — the existing read-a-coordinate behavior
|
|
454
|
+
// A plain click (no drag) — the existing read-a-coordinate behavior,
|
|
455
|
+
// plus attaching/detaching the transform gizmo to match selection.
|
|
234
456
|
const hit = pickEntityAt(e);
|
|
235
|
-
if (!hit)
|
|
457
|
+
if (!hit) {
|
|
458
|
+
// Clicked empty space with nothing grabbed — deselect. Previously a
|
|
459
|
+
// no-op (the marker/box from a PRIOR selection just stayed on
|
|
460
|
+
// screen); now load-bearing, since the gizmo also needs to disappear.
|
|
461
|
+
marker.visible = false;
|
|
462
|
+
selectionBox.visible = false;
|
|
463
|
+
gizmo.detach();
|
|
236
464
|
return;
|
|
465
|
+
}
|
|
237
466
|
marker.position.copy(hit.point);
|
|
238
467
|
marker.visible = true;
|
|
239
468
|
// Frame the whole entity the click landed on, not just the point on its
|
|
@@ -242,6 +471,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
242
471
|
// all of it, matching what "entityId" actually refers to.
|
|
243
472
|
selectionBox.setFromObject(hit.entityRoot);
|
|
244
473
|
selectionBox.visible = true;
|
|
474
|
+
gizmo.attach(hit.entityRoot, camera);
|
|
245
475
|
window.parent.postMessage({ type: 'umicat:editor:pickPoint3d', x: hit.point.x, y: hit.point.y, z: hit.point.z, entityId: hit.entityId }, '*');
|
|
246
476
|
};
|
|
247
477
|
renderer.domElement.addEventListener('pointerdown', onPointerDown);
|
|
@@ -279,10 +509,21 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
279
509
|
return onPatchEntity3d(data);
|
|
280
510
|
if (data.type === 'umicat:editor:dropModel3d')
|
|
281
511
|
return onDropModel3d(data);
|
|
512
|
+
if (data.type === 'umicat:editor:deleteEntity3d')
|
|
513
|
+
return onDeleteEntity3d(data);
|
|
514
|
+
if (data.type === 'umicat:editor:setGizmoMode3d') {
|
|
515
|
+
const mode = data.mode;
|
|
516
|
+
if (mode === 'move' || mode === 'rotate' || mode === 'scale') {
|
|
517
|
+
gizmo.setMode(mode);
|
|
518
|
+
gizmo.update(camera);
|
|
519
|
+
}
|
|
520
|
+
return;
|
|
521
|
+
}
|
|
282
522
|
}
|
|
283
523
|
/**
|
|
284
|
-
* `patch` is an open bag deliberately: skin
|
|
285
|
-
* rotation/scale
|
|
524
|
+
* `patch` is an open bag deliberately: skin was the first field, and each
|
|
525
|
+
* one after it (attachments, now position/rotation/scale) is a new `if`,
|
|
526
|
+
* not a new message.
|
|
286
527
|
*/
|
|
287
528
|
async function onPatchEntity3d(m) {
|
|
288
529
|
const done = (error) => {
|
|
@@ -293,6 +534,22 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
293
534
|
const object = objectByEntity.get(m.entityId);
|
|
294
535
|
if (!object)
|
|
295
536
|
return done(`no entity '${m.entityId}' in the scene being shown`);
|
|
537
|
+
if (m.patch?.position !== undefined) {
|
|
538
|
+
object.position.set(m.patch.position.x, m.patch.position.y, m.patch.position.z);
|
|
539
|
+
}
|
|
540
|
+
if (m.patch?.rotation !== undefined) {
|
|
541
|
+
const [rx, ry, rz, rw] = m.patch.rotation;
|
|
542
|
+
object.quaternion.set(rx, ry, rz, rw);
|
|
543
|
+
}
|
|
544
|
+
if (m.patch?.scale !== undefined) {
|
|
545
|
+
object.scale.set(m.patch.scale.x, m.patch.scale.y, m.patch.scale.z);
|
|
546
|
+
}
|
|
547
|
+
if ((m.patch?.position || m.patch?.rotation || m.patch?.scale) && gizmo.attached === object) {
|
|
548
|
+
// The gizmo itself re-syncs every frame via the render loop's
|
|
549
|
+
// `gizmo.update(camera)` call — only the selection box needs an
|
|
550
|
+
// explicit refresh here, same as a live drag already does.
|
|
551
|
+
selectionBox.setFromObject(object);
|
|
552
|
+
}
|
|
296
553
|
if (m.patch?.attachments !== undefined) {
|
|
297
554
|
const authored = sceneData?.entities.find((e) => e.id === m.entityId);
|
|
298
555
|
const asset = manifest?.models?.find((x) => x.id === authored?.modelAssetId);
|
|
@@ -383,7 +640,123 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
383
640
|
manifest?.models?.push(modelAsset);
|
|
384
641
|
done(undefined, { x: object.position.x, y: object.position.y, z: object.position.z });
|
|
385
642
|
}
|
|
643
|
+
/**
|
|
644
|
+
* Frees a subtree's GPU resources the same way the whole-scene `dispose()`
|
|
645
|
+
* in `SceneLoader3D.ts` does (geometry + material + every texture field a
|
|
646
|
+
* material holds, deduped against double-freeing a texture two materials
|
|
647
|
+
* share) — just scoped to one entity instead of the whole scene, since
|
|
648
|
+
* removing ONE entity must not touch anything a sibling is still using.
|
|
649
|
+
*/
|
|
650
|
+
function disposeObjectTree(root) {
|
|
651
|
+
const disposedTextures = new Set();
|
|
652
|
+
const disposeMaterial = (mat) => {
|
|
653
|
+
for (const value of Object.values(mat)) {
|
|
654
|
+
if (value instanceof THREE.Texture && !disposedTextures.has(value)) {
|
|
655
|
+
disposedTextures.add(value);
|
|
656
|
+
value.dispose();
|
|
657
|
+
}
|
|
658
|
+
}
|
|
659
|
+
mat.dispose();
|
|
660
|
+
};
|
|
661
|
+
root.traverse((o) => {
|
|
662
|
+
const mesh = o;
|
|
663
|
+
if (mesh.geometry)
|
|
664
|
+
mesh.geometry.dispose();
|
|
665
|
+
const mat = mesh.material;
|
|
666
|
+
if (Array.isArray(mat))
|
|
667
|
+
mat.forEach(disposeMaterial);
|
|
668
|
+
else if (mat)
|
|
669
|
+
disposeMaterial(mat);
|
|
670
|
+
});
|
|
671
|
+
}
|
|
672
|
+
/**
|
|
673
|
+
* Removes an entity from the live scene AND this session's own closure
|
|
674
|
+
* state — the exact reverse of `onDropModel3d`'s registration step, so an
|
|
675
|
+
* entity that was dropped and then deleted in the same session leaves
|
|
676
|
+
* nothing dangling behind it (not in `entityByObject`/`objectByEntity`,
|
|
677
|
+
* not in `sceneData.entities`, not selected/gizmo'd/mid-drag). Returns an
|
|
678
|
+
* error string on failure, undefined on success — same convention as
|
|
679
|
+
* `onPatchEntity3d`'s inner checks, just returned instead of routed
|
|
680
|
+
* through a `done()` closure, since this is also called directly from the
|
|
681
|
+
* in-iframe Delete-key handler below (no message/ack involved there).
|
|
682
|
+
*
|
|
683
|
+
* Deliberately does NOT touch `manifest.models` — the model ASSET
|
|
684
|
+
* definition is not necessarily entity-specific (an authored scene
|
|
685
|
+
* routinely has several entities sharing one model), so there is no safe
|
|
686
|
+
* way to tell from here whether deleting this placement should also
|
|
687
|
+
* delete the asset entry. An unreferenced manifest entry left behind is
|
|
688
|
+
* harmless — same as any other unused asset reference.
|
|
689
|
+
*/
|
|
690
|
+
function deleteEntityLive(entityId) {
|
|
691
|
+
const object = objectByEntity.get(entityId);
|
|
692
|
+
if (!object)
|
|
693
|
+
return `no entity '${entityId}' in the scene being shown`;
|
|
694
|
+
if (dragEntity === object) {
|
|
695
|
+
dragEntity = null;
|
|
696
|
+
dragEntityId = null;
|
|
697
|
+
dragPlane = null;
|
|
698
|
+
dragGrabOffset = null;
|
|
699
|
+
}
|
|
700
|
+
if (gizmoDrag && gizmo.attached === object)
|
|
701
|
+
gizmoDrag = null;
|
|
702
|
+
if (gizmo.attached === object) {
|
|
703
|
+
gizmo.detach();
|
|
704
|
+
marker.visible = false;
|
|
705
|
+
selectionBox.visible = false;
|
|
706
|
+
}
|
|
707
|
+
scene?.remove(object);
|
|
708
|
+
disposeObjectTree(object);
|
|
709
|
+
entityByObject.delete(object);
|
|
710
|
+
objectByEntity.delete(entityId);
|
|
711
|
+
worn.delete(entityId);
|
|
712
|
+
if (sceneData) {
|
|
713
|
+
const idx = sceneData.entities.findIndex((e) => e.id === entityId);
|
|
714
|
+
if (idx >= 0)
|
|
715
|
+
sceneData.entities.splice(idx, 1);
|
|
716
|
+
}
|
|
717
|
+
return undefined;
|
|
718
|
+
}
|
|
719
|
+
async function onDeleteEntity3d(m) {
|
|
720
|
+
const error = deleteEntityLive(m.entityId);
|
|
721
|
+
if (error)
|
|
722
|
+
console.warn('[umicat/editor] 3D entity delete failed:', m.entityId, error);
|
|
723
|
+
window.parent.postMessage({ type: 'umicat:editor:entityDeleted3d', entityId: m.entityId, ok: !error, error }, '*');
|
|
724
|
+
}
|
|
386
725
|
window.addEventListener('message', (e) => { void onHostMessage(e); });
|
|
726
|
+
/**
|
|
727
|
+
* In-iframe keyboard shortcuts — Delete/Backspace and Ctrl/Cmd+Z only work
|
|
728
|
+
* from the HOST page's own keydown listener while focus is still on the
|
|
729
|
+
* host (chat, panels); clicking the canvas moves focus INTO this iframe's
|
|
730
|
+
* browsing context, after which the host's `window.addEventListener`
|
|
731
|
+
* never fires again until focus returns. Exactly the same gap
|
|
732
|
+
* `@umicat/phaser-sdk`'s 2D editor overlay already solves for Cmd+S/Z/Y —
|
|
733
|
+
* this is the 3D counterpart.
|
|
734
|
+
*
|
|
735
|
+
* Delete acts immediately and locally (this player already owns the live
|
|
736
|
+
* scene graph — there is nothing to ask the host's permission for, same
|
|
737
|
+
* as a drag self-applying before telling the host). Undo does NOT: the
|
|
738
|
+
* undo STACK lives on the host (it is what decided there was something to
|
|
739
|
+
* undo in the first place), so this only asks — `requestUndo3d`, no
|
|
740
|
+
* payload — and the host answers with an ordinary `patchEntity3d` restoring
|
|
741
|
+
* the prior value, the exact same inbound message a host-initiated undo
|
|
742
|
+
* uses.
|
|
743
|
+
*/
|
|
744
|
+
window.addEventListener('keydown', (e) => {
|
|
745
|
+
const target = e.target;
|
|
746
|
+
if (target && (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable))
|
|
747
|
+
return;
|
|
748
|
+
if (e.key === 'Delete' && gizmo.attached) {
|
|
749
|
+
const entityId = entityByObject.get(gizmo.attached);
|
|
750
|
+
if (entityId) {
|
|
751
|
+
e.preventDefault();
|
|
752
|
+
void onDeleteEntity3d({ entityId });
|
|
753
|
+
}
|
|
754
|
+
}
|
|
755
|
+
else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'z') {
|
|
756
|
+
e.preventDefault();
|
|
757
|
+
window.parent.postMessage({ type: 'umicat:editor:requestUndo3d' }, '*');
|
|
758
|
+
}
|
|
759
|
+
});
|
|
387
760
|
// Design mode skips physics and animation entirely (loadScene3D's own
|
|
388
761
|
// designMode flag) — there are no mixers to advance and no Rapier world to
|
|
389
762
|
// step, so the loop only ever needs to render.
|
|
@@ -391,6 +764,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
391
764
|
controls.update();
|
|
392
765
|
if (!scene)
|
|
393
766
|
return;
|
|
767
|
+
gizmo.update(camera);
|
|
394
768
|
renderer.setScissorTest(false);
|
|
395
769
|
renderer.render(scene, camera);
|
|
396
770
|
// Second pass: the orientation gizmo, into a small scissored corner
|
|
@@ -433,6 +807,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
433
807
|
scene.add(marker);
|
|
434
808
|
selectionBox.visible = false;
|
|
435
809
|
scene.add(selectionBox);
|
|
810
|
+
scene.add(gizmo.root);
|
|
436
811
|
// Frame the whole scene — auto-fit, since a small template scene and a
|
|
437
812
|
// real level's dozens of entities need wildly different orbit distances.
|
|
438
813
|
const box = new THREE.Box3().setFromObject(scene);
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import * as THREE from 'three';
|
|
2
|
+
export type GizmoMode = 'move' | 'rotate' | 'scale';
|
|
3
|
+
export type GizmoAxis = 'x' | 'y' | 'z' | 'xyz';
|
|
4
|
+
export interface GizmoHit {
|
|
5
|
+
mode: GizmoMode;
|
|
6
|
+
axis: GizmoAxis;
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* Builds and owns the three mode-specific handle groups (move/rotate/scale)
|
|
10
|
+
* plus hit-testing and per-frame follow/sizing. Everything else — what a
|
|
11
|
+
* drag on a given handle actually DOES to the attached object — is the
|
|
12
|
+
* caller's job (`EditorDesignPlayer3D.ts`): this class only answers "is the
|
|
13
|
+
* gizmo showing, and which handle did this ray hit."
|
|
14
|
+
*
|
|
15
|
+
* The whole gizmo is LOCAL-space: `root`'s orientation tracks the attached
|
|
16
|
+
* object's world rotation, not the world axes. There's no local/global
|
|
17
|
+
* toggle (v1) — this is also the only sane default for scale, since scale
|
|
18
|
+
* is always local to an object regardless of any toggle, so move/rotate
|
|
19
|
+
* sharing that frame keeps all three modes visually and mathematically
|
|
20
|
+
* consistent with each other.
|
|
21
|
+
*/
|
|
22
|
+
export declare class TransformGizmo3D {
|
|
23
|
+
readonly root: THREE.Group<THREE.Object3DEventMap>;
|
|
24
|
+
mode: GizmoMode;
|
|
25
|
+
private target;
|
|
26
|
+
private readonly moveGroup;
|
|
27
|
+
private readonly rotateGroup;
|
|
28
|
+
private readonly scaleGroup;
|
|
29
|
+
private readonly pickableByMode;
|
|
30
|
+
private readonly hitByMesh;
|
|
31
|
+
constructor();
|
|
32
|
+
get attached(): THREE.Object3D | null;
|
|
33
|
+
setMode(mode: GizmoMode): void;
|
|
34
|
+
attach(object: THREE.Object3D, camera: THREE.Camera): void;
|
|
35
|
+
detach(): void;
|
|
36
|
+
private refreshVisibility;
|
|
37
|
+
/** Keep the gizmo glued to its target's world transform and sized roughly
|
|
38
|
+
* constant on screen regardless of camera distance — call every frame
|
|
39
|
+
* (cheap: a handful of vector ops), not just while dragging, since
|
|
40
|
+
* orbiting the camera changes both of those every frame too. */
|
|
41
|
+
update(camera: THREE.Camera): void;
|
|
42
|
+
/** World-space direction of a given LOCAL axis letter, honoring the
|
|
43
|
+
* gizmo's current (target-local) orientation. */
|
|
44
|
+
axisDirectionWorld(axis: 'x' | 'y' | 'z'): THREE.Vector3;
|
|
45
|
+
/** Only the active mode's own handles are ever candidates — sidesteps
|
|
46
|
+
* relying on `.visible` during raycasting, which (confirmed against the
|
|
47
|
+
* pinned three.js version used elsewhere in this file) is NOT checked
|
|
48
|
+
* automatically by `Raycaster.intersectObjects`. */
|
|
49
|
+
hitTest(raycaster: THREE.Raycaster): GizmoHit | null;
|
|
50
|
+
}
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
import * as THREE from 'three';
|
|
2
|
+
const AXIS_COLOR = { x: 0xff4d4d, y: 0x53e06a, z: 0x4d9fff };
|
|
3
|
+
function axisMaterial(axis, doubleSide = false) {
|
|
4
|
+
return new THREE.MeshBasicMaterial({
|
|
5
|
+
color: AXIS_COLOR[axis],
|
|
6
|
+
depthTest: false,
|
|
7
|
+
side: doubleSide ? THREE.DoubleSide : THREE.FrontSide,
|
|
8
|
+
});
|
|
9
|
+
}
|
|
10
|
+
/** The move/scale handles are built pointing along local +Y, then rotated
|
|
11
|
+
* into place — avoids writing three near-identical geometry builders. */
|
|
12
|
+
function orientAlongAxis(obj, axis) {
|
|
13
|
+
if (axis === 'x')
|
|
14
|
+
obj.rotation.z = -Math.PI / 2;
|
|
15
|
+
else if (axis === 'z')
|
|
16
|
+
obj.rotation.x = Math.PI / 2;
|
|
17
|
+
}
|
|
18
|
+
function buildMoveArrow(axis) {
|
|
19
|
+
const group = new THREE.Group();
|
|
20
|
+
const material = axisMaterial(axis);
|
|
21
|
+
const shaft = new THREE.Mesh(new THREE.CylinderGeometry(0.025, 0.025, 0.8, 8), material);
|
|
22
|
+
shaft.position.y = 0.4;
|
|
23
|
+
const head = new THREE.Mesh(new THREE.ConeGeometry(0.08, 0.22, 10), material);
|
|
24
|
+
head.position.y = 0.91;
|
|
25
|
+
group.add(shaft, head);
|
|
26
|
+
group.renderOrder = 1000;
|
|
27
|
+
orientAlongAxis(group, axis);
|
|
28
|
+
return { group, meshes: [shaft, head] };
|
|
29
|
+
}
|
|
30
|
+
function buildScaleHandle(axis) {
|
|
31
|
+
const group = new THREE.Group();
|
|
32
|
+
const material = axisMaterial(axis);
|
|
33
|
+
const shaft = new THREE.Mesh(new THREE.CylinderGeometry(0.02, 0.02, 0.7, 8), material);
|
|
34
|
+
shaft.position.y = 0.35;
|
|
35
|
+
const cap = new THREE.Mesh(new THREE.BoxGeometry(0.12, 0.12, 0.12), material);
|
|
36
|
+
cap.position.y = 0.76;
|
|
37
|
+
group.add(shaft, cap);
|
|
38
|
+
group.renderOrder = 1000;
|
|
39
|
+
orientAlongAxis(group, axis);
|
|
40
|
+
return { group, meshes: [shaft, cap] };
|
|
41
|
+
}
|
|
42
|
+
/** TorusGeometry is built in the XY plane (its ring normal is +Z) — rotated
|
|
43
|
+
* here so the final ring normal IS the requested axis, i.e. dragging around
|
|
44
|
+
* the ring rotates the object around that axis, matching the arrows'
|
|
45
|
+
* "this handle controls this axis" convention. */
|
|
46
|
+
function buildRotateRing(axis) {
|
|
47
|
+
const mesh = new THREE.Mesh(new THREE.TorusGeometry(1, 0.03, 8, 48), axisMaterial(axis, true));
|
|
48
|
+
mesh.renderOrder = 1000;
|
|
49
|
+
if (axis === 'x')
|
|
50
|
+
mesh.rotation.y = Math.PI / 2;
|
|
51
|
+
else if (axis === 'y')
|
|
52
|
+
mesh.rotation.x = Math.PI / 2;
|
|
53
|
+
return { mesh };
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Builds and owns the three mode-specific handle groups (move/rotate/scale)
|
|
57
|
+
* plus hit-testing and per-frame follow/sizing. Everything else — what a
|
|
58
|
+
* drag on a given handle actually DOES to the attached object — is the
|
|
59
|
+
* caller's job (`EditorDesignPlayer3D.ts`): this class only answers "is the
|
|
60
|
+
* gizmo showing, and which handle did this ray hit."
|
|
61
|
+
*
|
|
62
|
+
* The whole gizmo is LOCAL-space: `root`'s orientation tracks the attached
|
|
63
|
+
* object's world rotation, not the world axes. There's no local/global
|
|
64
|
+
* toggle (v1) — this is also the only sane default for scale, since scale
|
|
65
|
+
* is always local to an object regardless of any toggle, so move/rotate
|
|
66
|
+
* sharing that frame keeps all three modes visually and mathematically
|
|
67
|
+
* consistent with each other.
|
|
68
|
+
*/
|
|
69
|
+
export class TransformGizmo3D {
|
|
70
|
+
constructor() {
|
|
71
|
+
this.root = new THREE.Group();
|
|
72
|
+
this.mode = 'move';
|
|
73
|
+
this.target = null;
|
|
74
|
+
this.moveGroup = new THREE.Group();
|
|
75
|
+
this.rotateGroup = new THREE.Group();
|
|
76
|
+
this.scaleGroup = new THREE.Group();
|
|
77
|
+
this.pickableByMode = { move: [], rotate: [], scale: [] };
|
|
78
|
+
this.hitByMesh = new Map();
|
|
79
|
+
for (const axis of ['x', 'y', 'z']) {
|
|
80
|
+
const move = buildMoveArrow(axis);
|
|
81
|
+
this.moveGroup.add(move.group);
|
|
82
|
+
for (const m of move.meshes) {
|
|
83
|
+
this.hitByMesh.set(m, { mode: 'move', axis });
|
|
84
|
+
this.pickableByMode.move.push(m);
|
|
85
|
+
}
|
|
86
|
+
const rotate = buildRotateRing(axis);
|
|
87
|
+
this.rotateGroup.add(rotate.mesh);
|
|
88
|
+
this.hitByMesh.set(rotate.mesh, { mode: 'rotate', axis });
|
|
89
|
+
this.pickableByMode.rotate.push(rotate.mesh);
|
|
90
|
+
const scale = buildScaleHandle(axis);
|
|
91
|
+
this.scaleGroup.add(scale.group);
|
|
92
|
+
for (const m of scale.meshes) {
|
|
93
|
+
this.hitByMesh.set(m, { mode: 'scale', axis });
|
|
94
|
+
this.pickableByMode.scale.push(m);
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
// Uniform-scale center handle — scales all three axes together.
|
|
98
|
+
const center = new THREE.Mesh(new THREE.BoxGeometry(0.14, 0.14, 0.14), new THREE.MeshBasicMaterial({ color: 0xe8e8e8, depthTest: false }));
|
|
99
|
+
center.renderOrder = 1000;
|
|
100
|
+
this.scaleGroup.add(center);
|
|
101
|
+
this.hitByMesh.set(center, { mode: 'scale', axis: 'xyz' });
|
|
102
|
+
this.pickableByMode.scale.push(center);
|
|
103
|
+
this.moveGroup.visible = false;
|
|
104
|
+
this.rotateGroup.visible = false;
|
|
105
|
+
this.scaleGroup.visible = false;
|
|
106
|
+
this.root.add(this.moveGroup, this.rotateGroup, this.scaleGroup);
|
|
107
|
+
}
|
|
108
|
+
get attached() {
|
|
109
|
+
return this.target;
|
|
110
|
+
}
|
|
111
|
+
setMode(mode) {
|
|
112
|
+
this.mode = mode;
|
|
113
|
+
this.refreshVisibility();
|
|
114
|
+
}
|
|
115
|
+
attach(object, camera) {
|
|
116
|
+
this.target = object;
|
|
117
|
+
this.refreshVisibility();
|
|
118
|
+
this.update(camera);
|
|
119
|
+
}
|
|
120
|
+
detach() {
|
|
121
|
+
this.target = null;
|
|
122
|
+
this.refreshVisibility();
|
|
123
|
+
}
|
|
124
|
+
refreshVisibility() {
|
|
125
|
+
const show = this.target !== null;
|
|
126
|
+
this.moveGroup.visible = show && this.mode === 'move';
|
|
127
|
+
this.rotateGroup.visible = show && this.mode === 'rotate';
|
|
128
|
+
this.scaleGroup.visible = show && this.mode === 'scale';
|
|
129
|
+
}
|
|
130
|
+
/** Keep the gizmo glued to its target's world transform and sized roughly
|
|
131
|
+
* constant on screen regardless of camera distance — call every frame
|
|
132
|
+
* (cheap: a handful of vector ops), not just while dragging, since
|
|
133
|
+
* orbiting the camera changes both of those every frame too. */
|
|
134
|
+
update(camera) {
|
|
135
|
+
if (!this.target)
|
|
136
|
+
return;
|
|
137
|
+
const pos = this.target.getWorldPosition(new THREE.Vector3());
|
|
138
|
+
this.root.position.copy(pos);
|
|
139
|
+
this.root.quaternion.copy(this.target.getWorldQuaternion(new THREE.Quaternion()));
|
|
140
|
+
const dist = camera.position.distanceTo(pos);
|
|
141
|
+
this.root.scale.setScalar(Math.max(dist * 0.15, 0.001));
|
|
142
|
+
}
|
|
143
|
+
/** World-space direction of a given LOCAL axis letter, honoring the
|
|
144
|
+
* gizmo's current (target-local) orientation. */
|
|
145
|
+
axisDirectionWorld(axis) {
|
|
146
|
+
const dir = axis === 'x' ? new THREE.Vector3(1, 0, 0) : axis === 'y' ? new THREE.Vector3(0, 1, 0) : new THREE.Vector3(0, 0, 1);
|
|
147
|
+
return dir.applyQuaternion(this.root.quaternion).normalize();
|
|
148
|
+
}
|
|
149
|
+
/** Only the active mode's own handles are ever candidates — sidesteps
|
|
150
|
+
* relying on `.visible` during raycasting, which (confirmed against the
|
|
151
|
+
* pinned three.js version used elsewhere in this file) is NOT checked
|
|
152
|
+
* automatically by `Raycaster.intersectObjects`. */
|
|
153
|
+
hitTest(raycaster) {
|
|
154
|
+
if (!this.target)
|
|
155
|
+
return null;
|
|
156
|
+
const meshes = this.pickableByMode[this.mode];
|
|
157
|
+
const hits = raycaster.intersectObjects(meshes, false);
|
|
158
|
+
if (hits.length === 0)
|
|
159
|
+
return null;
|
|
160
|
+
return this.hitByMesh.get(hits[0].object) ?? null;
|
|
161
|
+
}
|
|
162
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import * as THREE from 'three';
|
|
2
|
+
/**
|
|
3
|
+
* The point on a 3D line closest to a ray — the primitive single-axis
|
|
4
|
+
* move/scale handles are built on. A ray dragged across the screen rarely
|
|
5
|
+
* ever actually INTERSECTS the axis line (that only happens by chance), so
|
|
6
|
+
* "where does the cursor's ray cross the axis" is the wrong question; "what
|
|
7
|
+
* point on the axis is the cursor closest to pointing at" is the one that
|
|
8
|
+
* gives a stable, predictable 1-DOF drag.
|
|
9
|
+
*
|
|
10
|
+
* Standard closest-point-between-two-lines algebra (e.g. Ericson,
|
|
11
|
+
* *Real-Time Collision Detection* §5.1.9), solved for the axis line's own
|
|
12
|
+
* parameter only — the ray's parameter is never needed by a caller. Returns
|
|
13
|
+
* null when the ray runs parallel to the axis (dragging while looking
|
|
14
|
+
* straight down the handle you're dragging) — there is no stable answer
|
|
15
|
+
* there, and the caller should just hold the previous frame's point rather
|
|
16
|
+
* than snap somewhere arbitrary.
|
|
17
|
+
*/
|
|
18
|
+
export declare function closestPointOnLineToRay(rayOrigin: THREE.Vector3, rayDir: THREE.Vector3, // must be normalized
|
|
19
|
+
lineOrigin: THREE.Vector3, lineDir: THREE.Vector3): THREE.Vector3 | null;
|
|
20
|
+
/**
|
|
21
|
+
* Where a ray crosses an arbitrary plane (point + normal) — the rotate
|
|
22
|
+
* handles' equivalent of `raycastGroundPlane`, generalized to any axis
|
|
23
|
+
* rather than hardcoded to a horizontal Y=0 ground.
|
|
24
|
+
*/
|
|
25
|
+
export declare function raycastPlane(ray: THREE.Ray, planePoint: THREE.Vector3, planeNormal: THREE.Vector3): THREE.Vector3 | null;
|
|
26
|
+
/**
|
|
27
|
+
* The angle of `point` around `axis` through `center`, in a stable
|
|
28
|
+
* reference frame built FROM the axis alone — so two calls with the SAME
|
|
29
|
+
* axis always agree on what angle zero means, and a rotate drag's angle
|
|
30
|
+
* *delta* (this frame's angle minus last frame's) is the thing actually
|
|
31
|
+
* applied. `point` need not lie exactly in the axis's plane (it won't,
|
|
32
|
+
* exactly, once float error creeps in) — the component along `axis` is
|
|
33
|
+
* discarded before reading the angle off the remainder.
|
|
34
|
+
*/
|
|
35
|
+
export declare function angleAroundAxis(center: THREE.Vector3, axis: THREE.Vector3, // must be normalized
|
|
36
|
+
point: THREE.Vector3): number;
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import * as THREE from 'three';
|
|
2
|
+
/**
|
|
3
|
+
* The point on a 3D line closest to a ray — the primitive single-axis
|
|
4
|
+
* move/scale handles are built on. A ray dragged across the screen rarely
|
|
5
|
+
* ever actually INTERSECTS the axis line (that only happens by chance), so
|
|
6
|
+
* "where does the cursor's ray cross the axis" is the wrong question; "what
|
|
7
|
+
* point on the axis is the cursor closest to pointing at" is the one that
|
|
8
|
+
* gives a stable, predictable 1-DOF drag.
|
|
9
|
+
*
|
|
10
|
+
* Standard closest-point-between-two-lines algebra (e.g. Ericson,
|
|
11
|
+
* *Real-Time Collision Detection* §5.1.9), solved for the axis line's own
|
|
12
|
+
* parameter only — the ray's parameter is never needed by a caller. Returns
|
|
13
|
+
* null when the ray runs parallel to the axis (dragging while looking
|
|
14
|
+
* straight down the handle you're dragging) — there is no stable answer
|
|
15
|
+
* there, and the caller should just hold the previous frame's point rather
|
|
16
|
+
* than snap somewhere arbitrary.
|
|
17
|
+
*/
|
|
18
|
+
export function closestPointOnLineToRay(rayOrigin, rayDir, // must be normalized
|
|
19
|
+
lineOrigin, lineDir) {
|
|
20
|
+
const r = new THREE.Vector3().subVectors(rayOrigin, lineOrigin);
|
|
21
|
+
const b = rayDir.dot(lineDir);
|
|
22
|
+
const f1 = rayDir.dot(r);
|
|
23
|
+
const f2 = lineDir.dot(r);
|
|
24
|
+
const denom = b * b - 1;
|
|
25
|
+
if (Math.abs(denom) < 1e-6)
|
|
26
|
+
return null; // ray ‖ axis
|
|
27
|
+
const s = (b * f1 - f2) / denom;
|
|
28
|
+
return lineOrigin.clone().addScaledVector(lineDir, s);
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Where a ray crosses an arbitrary plane (point + normal) — the rotate
|
|
32
|
+
* handles' equivalent of `raycastGroundPlane`, generalized to any axis
|
|
33
|
+
* rather than hardcoded to a horizontal Y=0 ground.
|
|
34
|
+
*/
|
|
35
|
+
export function raycastPlane(ray, planePoint, planeNormal) {
|
|
36
|
+
const plane = new THREE.Plane().setFromNormalAndCoplanarPoint(planeNormal, planePoint);
|
|
37
|
+
const point = new THREE.Vector3();
|
|
38
|
+
return ray.intersectPlane(plane, point) ? point : null;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* The angle of `point` around `axis` through `center`, in a stable
|
|
42
|
+
* reference frame built FROM the axis alone — so two calls with the SAME
|
|
43
|
+
* axis always agree on what angle zero means, and a rotate drag's angle
|
|
44
|
+
* *delta* (this frame's angle minus last frame's) is the thing actually
|
|
45
|
+
* applied. `point` need not lie exactly in the axis's plane (it won't,
|
|
46
|
+
* exactly, once float error creeps in) — the component along `axis` is
|
|
47
|
+
* discarded before reading the angle off the remainder.
|
|
48
|
+
*/
|
|
49
|
+
export function angleAroundAxis(center, axis, // must be normalized
|
|
50
|
+
point) {
|
|
51
|
+
// Any vector not parallel to `axis` works as a seed; Y unless the axis
|
|
52
|
+
// basically IS Y, in which case X is never parallel to it.
|
|
53
|
+
const seed = Math.abs(axis.y) < 0.99 ? new THREE.Vector3(0, 1, 0) : new THREE.Vector3(1, 0, 0);
|
|
54
|
+
const u = new THREE.Vector3().crossVectors(seed, axis).normalize();
|
|
55
|
+
const w = new THREE.Vector3().crossVectors(axis, u).normalize();
|
|
56
|
+
const rel = new THREE.Vector3().subVectors(point, center);
|
|
57
|
+
const onAxis = axis.clone().multiplyScalar(rel.dot(axis));
|
|
58
|
+
const inPlane = rel.clone().sub(onAxis);
|
|
59
|
+
return Math.atan2(inPlane.dot(w), inPlane.dot(u));
|
|
60
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@umicat/three-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.24.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",
|