@umicat/three-sdk 0.21.0 → 0.23.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 +19 -5
- package/dist/editor/EditorDesignPlayer3D.d.ts +12 -7
- package/dist/editor/EditorDesignPlayer3D.js +322 -31
- 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
|
@@ -4,14 +4,28 @@ The three.js runtime for Umicat games, per ADR-033. Platform services come from
|
|
|
4
4
|
`@umicat/platform-sdk` untouched; what lives here is the engine layer we own.
|
|
5
5
|
|
|
6
6
|
**Status: published and in use.** `@umicat/three-sdk` is on npm; Balaboo (a
|
|
7
|
-
tower defence that ships from `woodland/`) is built on it, and
|
|
8
|
-
is
|
|
7
|
+
tower defence that ships from `woodland/`) is built on it, and every new 3D
|
|
8
|
+
project is forked from **`umicat-template`'s `template-3d` branch** — which is
|
|
9
|
+
what `gitManager.createGameFromFork` actually clones. (Not `umicat-template-3d`:
|
|
10
|
+
that was the scratch repo the template was developed in, and it has been
|
|
11
|
+
archived since 2026-09-11 precisely because two copies of a template is how
|
|
12
|
+
someone eventually edits the wrong one. This line named it for two weeks after
|
|
13
|
+
that, which is the same failure the note below describes.)
|
|
9
14
|
|
|
10
15
|
What it has: the scene3d format and loader, physics wiring, a character
|
|
11
16
|
controller and animator, an input layer that mounts on-screen controls on touch
|
|
12
|
-
devices and binds keys everywhere, bone sockets,
|
|
13
|
-
editor's screenshot/video-capture protocol
|
|
14
|
-
|
|
17
|
+
devices and binds keys everywhere, bone sockets, swappable skins and
|
|
18
|
+
attachments, hit tints, audio, the editor's screenshot/video-capture protocol,
|
|
19
|
+
and a read-and-write design view
|
|
20
|
+
(`EditorDesignPlayer3D`: click-to-pick, drag-to-move, a host→iframe patch
|
|
21
|
+
channel the platform Inspector drives, drag-and-drop model placement —
|
|
22
|
+
`umicat:editor:dropModel3d` in, `umicat:editor:modelDropped3d` out — which
|
|
23
|
+
raycasts the drop point against the ground plane and fetches the GLB straight
|
|
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). What it still does not have: undo, multi-select, or a local/
|
|
28
|
+
global axis toggle (the gizmo is local-space only).
|
|
15
29
|
|
|
16
30
|
> This paragraph said "seed, not a product — no input system, no character
|
|
17
31
|
> controller, no audio, and no published package" for ten minor versions after
|
|
@@ -23,13 +23,18 @@ 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.
|
|
33
38
|
*
|
|
34
39
|
* Takes over `renderer`'s animation loop entirely for the rest of the page's
|
|
35
40
|
* life — there is no scene-swap API and no teardown, matching how the
|
|
@@ -1,8 +1,11 @@
|
|
|
1
1
|
import * as THREE from 'three';
|
|
2
2
|
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
|
|
3
|
-
import { loadScene3D } from '../SceneLoader3D.js';
|
|
3
|
+
import { loadScene3D, loadModelAsset } from '../SceneLoader3D.js';
|
|
4
4
|
import { applySkin } from '../Skin.js';
|
|
5
5
|
import { applyAttachments } from '../Attachments.js';
|
|
6
|
+
import { singleModelManifest } from '../scene3d.js';
|
|
7
|
+
import { TransformGizmo3D } from './TransformGizmo3D.js';
|
|
8
|
+
import { closestPointOnLineToRay, raycastPlane, angleAroundAxis } from './gizmoMath.js';
|
|
6
9
|
/**
|
|
7
10
|
* The 3D counterpart of `@umicat/phaser-sdk`'s `EditorDesignScene` (ADR-021)
|
|
8
11
|
* — renders a scene's AUTHORED data with no game code and no save, so the
|
|
@@ -14,13 +17,18 @@ import { applyAttachments } from '../Attachments.js';
|
|
|
14
17
|
* marker reads off the exact world coordinate, posted to the host so a
|
|
15
18
|
* person can point at a real spot instead of guessing one blind when
|
|
16
19
|
* telling the AI where to place something.
|
|
17
|
-
* - **Drag** an entity to move it
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
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.
|
|
24
32
|
*
|
|
25
33
|
* Takes over `renderer`'s animation loop entirely for the rest of the page's
|
|
26
34
|
* life — there is no scene-swap API and no teardown, matching how the
|
|
@@ -53,6 +61,13 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
53
61
|
selectionBox.visible = false;
|
|
54
62
|
selectionBox.renderOrder = 998;
|
|
55
63
|
selectionBox.material.depthTest = false;
|
|
64
|
+
// The Move/Rotate/Scale transform gizmo — shows (and is only hit-testable)
|
|
65
|
+
// on the current mode's handles once something is selected. `gizmo.root`
|
|
66
|
+
// is added to the scene once, at scene-load time, right alongside the
|
|
67
|
+
// marker/selection box above; `gizmo.update(camera)` runs every frame (the
|
|
68
|
+
// render loop below) so it follows the selected entity and keeps a
|
|
69
|
+
// roughly constant on-screen size as the camera orbits/zooms.
|
|
70
|
+
const gizmo = new TransformGizmo3D();
|
|
56
71
|
// Orientation gizmo — a small corner compass tracking the main camera's
|
|
57
72
|
// rotation only (never its position/zoom), same convention every 3D DCC
|
|
58
73
|
// uses: X=red, Y=green, Z=blue. Rendered as a second, tiny scene into a
|
|
@@ -89,10 +104,75 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
89
104
|
resize();
|
|
90
105
|
window.addEventListener('resize', resize);
|
|
91
106
|
const raycaster = new THREE.Raycaster();
|
|
92
|
-
|
|
107
|
+
// Split out from the pointer-event version below so a host-posted
|
|
108
|
+
// `{x,y}` (no real PointerEvent exists for a drop that happened on the
|
|
109
|
+
// HOST page, over a DOM overlay sitting on top of this iframe) can go
|
|
110
|
+
// through the identical math.
|
|
111
|
+
const ndcFromClientXY = (clientX, clientY) => {
|
|
93
112
|
const rect = renderer.domElement.getBoundingClientRect();
|
|
94
|
-
return new THREE.Vector2(((
|
|
113
|
+
return new THREE.Vector2(((clientX - rect.left) / rect.width) * 2 - 1, -((clientY - rect.top) / rect.height) * 2 + 1);
|
|
95
114
|
};
|
|
115
|
+
const ndcFromEvent = (e) => ndcFromClientXY(e.clientX, e.clientY);
|
|
116
|
+
// The drag-to-move primitive (below) with no object already grabbed:
|
|
117
|
+
// raycast a screen point against a horizontal plane at `groundY` and
|
|
118
|
+
// return the world point, or null if the camera is looking edge-on to it.
|
|
119
|
+
// `clientX`/`clientY` are iframe-local — the host computes them by
|
|
120
|
+
// subtracting its own iframe's `getBoundingClientRect()` before posting,
|
|
121
|
+
// same convention the 2D editor's `computeDropWorldPos` already uses.
|
|
122
|
+
const raycastGroundPlane = (clientX, clientY, groundY) => {
|
|
123
|
+
raycaster.setFromCamera(ndcFromClientXY(clientX, clientY), camera);
|
|
124
|
+
const plane = new THREE.Plane(new THREE.Vector3(0, 1, 0), -groundY);
|
|
125
|
+
const point = new THREE.Vector3();
|
|
126
|
+
return raycaster.ray.intersectPlane(plane, point) ? point : null;
|
|
127
|
+
};
|
|
128
|
+
// The uniform-scale center handle drags by SCREEN distance from the
|
|
129
|
+
// object's projected position, not a 3D line/plane — there is no single
|
|
130
|
+
// "axis" a uniform scale runs along, but "how far did you drag the
|
|
131
|
+
// cursor away from the object" is an unambiguous 1-DOF gesture in any
|
|
132
|
+
// camera orientation.
|
|
133
|
+
const worldToClientXY = (world) => {
|
|
134
|
+
const ndc = world.clone().project(camera);
|
|
135
|
+
const rect = renderer.domElement.getBoundingClientRect();
|
|
136
|
+
return {
|
|
137
|
+
x: rect.left + (ndc.x * 0.5 + 0.5) * rect.width,
|
|
138
|
+
y: rect.top + (1 - (ndc.y * 0.5 + 0.5)) * rect.height,
|
|
139
|
+
};
|
|
140
|
+
};
|
|
141
|
+
// Test-only readback — NOT part of the host↔iframe protocol, never read by
|
|
142
|
+
// umicat-home-ui. A gizmo handle's clickable screen position depends on
|
|
143
|
+
// the live camera distance (gizmo.update's constant-apparent-size scale)
|
|
144
|
+
// and the selected object's current world transform, so a real headless
|
|
145
|
+
// test needs to ask the live scene where a handle actually is rather than
|
|
146
|
+
// precompute it blind. Mirrors the project's existing precedent of
|
|
147
|
+
// exposing small debug readbacks for verification (e.g.
|
|
148
|
+
// `renderer.info.render.frame`) rather than hand-deriving pixel math that
|
|
149
|
+
// can silently drift from the real implementation.
|
|
150
|
+
globalThis.__umicatGizmoHandleScreenXY =
|
|
151
|
+
(mode, axis) => {
|
|
152
|
+
if (!gizmo.attached)
|
|
153
|
+
return null;
|
|
154
|
+
const worldPos = gizmo.attached.getWorldPosition(new THREE.Vector3());
|
|
155
|
+
if (axis === 'xyz')
|
|
156
|
+
return worldToClientXY(worldPos); // center cube sits at the object's own position
|
|
157
|
+
const scale = gizmo.root.scale.x;
|
|
158
|
+
if (mode === 'rotate') {
|
|
159
|
+
// The ring for a given axis lies in the plane perpendicular to it —
|
|
160
|
+
// a point ON the ring is offset along one of the OTHER two local
|
|
161
|
+
// axes by the ring's radius (1, built in TransformGizmo3D.ts).
|
|
162
|
+
const other = axis === 'x' ? 'y' : 'x';
|
|
163
|
+
const dir = gizmo.axisDirectionWorld(other);
|
|
164
|
+
return worldToClientXY(worldPos.clone().addScaledVector(dir, scale * 1.0));
|
|
165
|
+
}
|
|
166
|
+
// move/scale handles run OUTWARD along their own axis — the shaft
|
|
167
|
+
// midpoint (built 0..~0.8 local units) is a safely-clickable point.
|
|
168
|
+
const dir = gizmo.axisDirectionWorld(axis);
|
|
169
|
+
return worldToClientXY(worldPos.clone().addScaledVector(dir, scale * 0.5));
|
|
170
|
+
};
|
|
171
|
+
// Test-only — the attached object's current local scale, so a test can
|
|
172
|
+
// snapshot it BEFORE a scale drag rather than assume a baseline of 1 (a
|
|
173
|
+
// dropped model's `importScale` means that's almost never true).
|
|
174
|
+
globalThis.__umicatGizmoAttachedScale =
|
|
175
|
+
() => gizmo.attached ? { x: gizmo.attached.scale.x, y: gizmo.attached.scale.y, z: gizmo.attached.scale.z } : null;
|
|
96
176
|
// Only VISIBLE entity roots are ever raycast against. three.js's
|
|
97
177
|
// Mesh.raycast does NOT check `.visible` on its own (confirmed against the
|
|
98
178
|
// pinned three source — no such check in Raycaster.js or Object3D.raycast),
|
|
@@ -136,12 +216,118 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
136
216
|
let dragEntityId = null;
|
|
137
217
|
let dragPlane = null;
|
|
138
218
|
let dragGrabOffset = null; // world-space, plane-point minus object position at grab time
|
|
219
|
+
let gizmoDrag = null;
|
|
220
|
+
const beginGizmoDrag = (hit, e) => {
|
|
221
|
+
const obj = gizmo.attached;
|
|
222
|
+
if (!obj)
|
|
223
|
+
return false;
|
|
224
|
+
const worldPos = obj.getWorldPosition(new THREE.Vector3());
|
|
225
|
+
if (hit.mode === 'move' && hit.axis !== 'xyz') {
|
|
226
|
+
const lineDir = gizmo.axisDirectionWorld(hit.axis);
|
|
227
|
+
const grab = closestPointOnLineToRay(raycaster.ray.origin, raycaster.ray.direction, worldPos, lineDir);
|
|
228
|
+
if (!grab)
|
|
229
|
+
return false; // camera looking straight down this axis
|
|
230
|
+
gizmoDrag = { mode: 'move', axis: hit.axis, lineOrigin: worldPos.clone(), lineDir, grabOffset: grab.clone().sub(worldPos) };
|
|
231
|
+
return true;
|
|
232
|
+
}
|
|
233
|
+
if (hit.mode === 'scale' && hit.axis !== 'xyz') {
|
|
234
|
+
const lineDir = gizmo.axisDirectionWorld(hit.axis);
|
|
235
|
+
const grab = closestPointOnLineToRay(raycaster.ray.origin, raycaster.ray.direction, worldPos, lineDir);
|
|
236
|
+
if (!grab)
|
|
237
|
+
return false;
|
|
238
|
+
const startSignedDistance = grab.clone().sub(worldPos).dot(lineDir);
|
|
239
|
+
if (Math.abs(startSignedDistance) < 1e-4)
|
|
240
|
+
return false; // grabbed essentially at the origin — no stable ratio
|
|
241
|
+
gizmoDrag = { mode: 'scale', axis: hit.axis, lineOrigin: worldPos.clone(), lineDir, startSignedDistance, startScale: obj.scale.clone() };
|
|
242
|
+
return true;
|
|
243
|
+
}
|
|
244
|
+
if (hit.mode === 'scale' && hit.axis === 'xyz') {
|
|
245
|
+
const originScreen = worldToClientXY(worldPos);
|
|
246
|
+
const startScreenDistance = Math.hypot(e.clientX - originScreen.x, e.clientY - originScreen.y);
|
|
247
|
+
if (startScreenDistance < 2)
|
|
248
|
+
return false; // grabbed on top of the object's own screen position
|
|
249
|
+
gizmoDrag = { mode: 'scale', axis: 'xyz', originScreen, startScreenDistance, startScale: obj.scale.clone() };
|
|
250
|
+
return true;
|
|
251
|
+
}
|
|
252
|
+
if (hit.mode === 'rotate' && hit.axis !== 'xyz') {
|
|
253
|
+
const planeNormal = gizmo.axisDirectionWorld(hit.axis);
|
|
254
|
+
const hitPoint = raycastPlane(raycaster.ray, worldPos, planeNormal);
|
|
255
|
+
if (!hitPoint)
|
|
256
|
+
return false; // camera edge-on to this ring's plane
|
|
257
|
+
const startAngle = angleAroundAxis(worldPos, planeNormal, hitPoint);
|
|
258
|
+
const parentWorldQuatInverse = obj.parent ? obj.parent.getWorldQuaternion(new THREE.Quaternion()).invert() : new THREE.Quaternion();
|
|
259
|
+
const startWorldQuaternion = obj.getWorldQuaternion(new THREE.Quaternion());
|
|
260
|
+
gizmoDrag = { mode: 'rotate', axis: hit.axis, planePoint: worldPos.clone(), planeNormal, startAngle, startWorldQuaternion, parentWorldQuatInverse };
|
|
261
|
+
return true;
|
|
262
|
+
}
|
|
263
|
+
return false;
|
|
264
|
+
};
|
|
265
|
+
const updateGizmoDrag = (e) => {
|
|
266
|
+
if (!gizmoDrag || !gizmo.attached)
|
|
267
|
+
return;
|
|
268
|
+
const obj = gizmo.attached;
|
|
269
|
+
if (gizmoDrag.mode === 'move') {
|
|
270
|
+
const grab = closestPointOnLineToRay(raycaster.ray.origin, raycaster.ray.direction, gizmoDrag.lineOrigin, gizmoDrag.lineDir);
|
|
271
|
+
if (!grab)
|
|
272
|
+
return;
|
|
273
|
+
const newWorldPos = grab.clone().sub(gizmoDrag.grabOffset);
|
|
274
|
+
if (obj.parent)
|
|
275
|
+
obj.parent.worldToLocal(newWorldPos);
|
|
276
|
+
obj.position.copy(newWorldPos);
|
|
277
|
+
}
|
|
278
|
+
else if (gizmoDrag.mode === 'scale' && gizmoDrag.axis !== 'xyz') {
|
|
279
|
+
const grab = closestPointOnLineToRay(raycaster.ray.origin, raycaster.ray.direction, gizmoDrag.lineOrigin, gizmoDrag.lineDir);
|
|
280
|
+
if (!grab)
|
|
281
|
+
return;
|
|
282
|
+
const signedDistance = grab.clone().sub(gizmoDrag.lineOrigin).dot(gizmoDrag.lineDir);
|
|
283
|
+
const ratio = THREE.MathUtils.clamp(signedDistance / gizmoDrag.startSignedDistance, 0.02, 50);
|
|
284
|
+
const { axis, startScale } = gizmoDrag;
|
|
285
|
+
if (axis === 'x')
|
|
286
|
+
obj.scale.x = startScale.x * ratio;
|
|
287
|
+
else if (axis === 'y')
|
|
288
|
+
obj.scale.y = startScale.y * ratio;
|
|
289
|
+
else
|
|
290
|
+
obj.scale.z = startScale.z * ratio;
|
|
291
|
+
}
|
|
292
|
+
else if (gizmoDrag.mode === 'scale' && gizmoDrag.axis === 'xyz') {
|
|
293
|
+
const currentScreenDistance = Math.hypot(e.clientX - gizmoDrag.originScreen.x, e.clientY - gizmoDrag.originScreen.y);
|
|
294
|
+
const ratio = THREE.MathUtils.clamp(currentScreenDistance / gizmoDrag.startScreenDistance, 0.02, 50);
|
|
295
|
+
obj.scale.copy(gizmoDrag.startScale).multiplyScalar(ratio);
|
|
296
|
+
}
|
|
297
|
+
else if (gizmoDrag.mode === 'rotate') {
|
|
298
|
+
const hitPoint = raycastPlane(raycaster.ray, gizmoDrag.planePoint, gizmoDrag.planeNormal);
|
|
299
|
+
if (!hitPoint)
|
|
300
|
+
return;
|
|
301
|
+
const currentAngle = angleAroundAxis(gizmoDrag.planePoint, gizmoDrag.planeNormal, hitPoint);
|
|
302
|
+
const delta = currentAngle - gizmoDrag.startAngle;
|
|
303
|
+
const deltaQuat = new THREE.Quaternion().setFromAxisAngle(gizmoDrag.planeNormal, delta);
|
|
304
|
+
const newWorldQuat = deltaQuat.multiply(gizmoDrag.startWorldQuaternion.clone());
|
|
305
|
+
obj.quaternion.copy(gizmoDrag.parentWorldQuatInverse.clone().multiply(newWorldQuat));
|
|
306
|
+
}
|
|
307
|
+
selectionBox.setFromObject(obj);
|
|
308
|
+
gizmo.update(camera);
|
|
309
|
+
moved = true;
|
|
310
|
+
};
|
|
139
311
|
const onPointerDown = (e) => {
|
|
140
312
|
downX = e.clientX;
|
|
141
313
|
downY = e.clientY;
|
|
142
314
|
moved = false;
|
|
143
315
|
if (!scene)
|
|
144
316
|
return;
|
|
317
|
+
if (gizmo.attached) {
|
|
318
|
+
raycaster.setFromCamera(ndcFromEvent(e), camera);
|
|
319
|
+
const gizmoHit = gizmo.hitTest(raycaster);
|
|
320
|
+
if (gizmoHit && beginGizmoDrag(gizmoHit, e)) {
|
|
321
|
+
controls.enabled = false;
|
|
322
|
+
try {
|
|
323
|
+
renderer.domElement.setPointerCapture(e.pointerId);
|
|
324
|
+
}
|
|
325
|
+
catch {
|
|
326
|
+
// See the same try/catch below — capture is an enhancement only.
|
|
327
|
+
}
|
|
328
|
+
return;
|
|
329
|
+
}
|
|
330
|
+
}
|
|
145
331
|
const hit = pickEntityAt(e);
|
|
146
332
|
if (!hit)
|
|
147
333
|
return; // empty space — let OrbitControls own this gesture
|
|
@@ -174,6 +360,11 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
174
360
|
const onPointerMove = (e) => {
|
|
175
361
|
if (Math.abs(e.clientX - downX) > 4 || Math.abs(e.clientY - downY) > 4)
|
|
176
362
|
moved = true;
|
|
363
|
+
if (gizmoDrag) {
|
|
364
|
+
raycaster.setFromCamera(ndcFromEvent(e), camera);
|
|
365
|
+
updateGizmoDrag(e);
|
|
366
|
+
return;
|
|
367
|
+
}
|
|
177
368
|
if (!dragEntity || !dragPlane || !dragGrabOffset || !scene)
|
|
178
369
|
return;
|
|
179
370
|
raycaster.setFromCamera(ndcFromEvent(e), camera);
|
|
@@ -194,6 +385,25 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
194
385
|
// Already released, or never captured (e.g. this gesture never hit an
|
|
195
386
|
// entity) — nothing to do either way.
|
|
196
387
|
}
|
|
388
|
+
if (gizmoDrag) {
|
|
389
|
+
const obj = gizmo.attached;
|
|
390
|
+
const entityId = obj ? entityByObject.get(obj) : undefined;
|
|
391
|
+
if (moved && obj && entityId) {
|
|
392
|
+
if (gizmoDrag.mode === 'move') {
|
|
393
|
+
window.parent.postMessage({ type: 'umicat:editor:dragEnd3d', sceneId: opts.sceneId, entityId, position: { x: obj.position.x, y: obj.position.y, z: obj.position.z } }, '*');
|
|
394
|
+
}
|
|
395
|
+
else if (gizmoDrag.mode === 'rotate') {
|
|
396
|
+
const q = obj.quaternion;
|
|
397
|
+
window.parent.postMessage({ type: 'umicat:editor:rotateEnd3d', sceneId: opts.sceneId, entityId, rotation: [q.x, q.y, q.z, q.w] }, '*');
|
|
398
|
+
}
|
|
399
|
+
else if (gizmoDrag.mode === 'scale') {
|
|
400
|
+
window.parent.postMessage({ type: 'umicat:editor:scaleEnd3d', sceneId: opts.sceneId, entityId, scale: { x: obj.scale.x, y: obj.scale.y, z: obj.scale.z } }, '*');
|
|
401
|
+
}
|
|
402
|
+
}
|
|
403
|
+
gizmoDrag = null;
|
|
404
|
+
controls.enabled = true;
|
|
405
|
+
return;
|
|
406
|
+
}
|
|
197
407
|
// A drag only really happened if the pointer actually moved — grabbing
|
|
198
408
|
// an entity and releasing without moving is a CLICK on it (case below),
|
|
199
409
|
// not a same-position no-op save.
|
|
@@ -212,10 +422,18 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
212
422
|
controls.enabled = true;
|
|
213
423
|
if (moved || !scene)
|
|
214
424
|
return;
|
|
215
|
-
// A plain click (no drag) — the existing read-a-coordinate behavior
|
|
425
|
+
// A plain click (no drag) — the existing read-a-coordinate behavior,
|
|
426
|
+
// plus attaching/detaching the transform gizmo to match selection.
|
|
216
427
|
const hit = pickEntityAt(e);
|
|
217
|
-
if (!hit)
|
|
428
|
+
if (!hit) {
|
|
429
|
+
// Clicked empty space with nothing grabbed — deselect. Previously a
|
|
430
|
+
// no-op (the marker/box from a PRIOR selection just stayed on
|
|
431
|
+
// screen); now load-bearing, since the gizmo also needs to disappear.
|
|
432
|
+
marker.visible = false;
|
|
433
|
+
selectionBox.visible = false;
|
|
434
|
+
gizmo.detach();
|
|
218
435
|
return;
|
|
436
|
+
}
|
|
219
437
|
marker.position.copy(hit.point);
|
|
220
438
|
marker.visible = true;
|
|
221
439
|
// Frame the whole entity the click landed on, not just the point on its
|
|
@@ -224,31 +442,30 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
224
442
|
// all of it, matching what "entityId" actually refers to.
|
|
225
443
|
selectionBox.setFromObject(hit.entityRoot);
|
|
226
444
|
selectionBox.visible = true;
|
|
445
|
+
gizmo.attach(hit.entityRoot, camera);
|
|
227
446
|
window.parent.postMessage({ type: 'umicat:editor:pickPoint3d', x: hit.point.x, y: hit.point.y, z: hit.point.z, entityId: hit.entityId }, '*');
|
|
228
447
|
};
|
|
229
448
|
renderer.domElement.addEventListener('pointerdown', onPointerDown);
|
|
230
449
|
renderer.domElement.addEventListener('pointermove', onPointerMove);
|
|
231
450
|
renderer.domElement.addEventListener('pointerup', onPointerUp);
|
|
232
451
|
/**
|
|
233
|
-
*
|
|
234
|
-
*
|
|
235
|
-
*
|
|
236
|
-
*
|
|
237
|
-
*
|
|
238
|
-
*
|
|
239
|
-
*
|
|
240
|
-
* until a rebuild. A property editor whose changes don't show is a property
|
|
241
|
-
* editor nobody trusts (a sibling 2D tool shipped exactly that bug — a new
|
|
242
|
-
* widget kind not wired into its live-patch path silently did nothing on
|
|
243
|
-
* canvas while the Inspector happily accepted the value).
|
|
452
|
+
* Host→iframe messages. `patchEntity3d` (0.18.0) was the first — everything
|
|
453
|
+
* before it went one way: the player reported picks and drags, and the
|
|
454
|
+
* host wrote them to disk, which works for a drag because the SDK itself
|
|
455
|
+
* already moved the object. A PROPERTY edited in a panel is the opposite:
|
|
456
|
+
* the host changes the file and the canvas knows nothing until a rebuild —
|
|
457
|
+
* a sibling 2D tool shipped exactly that bug once (a widget kind not wired
|
|
458
|
+
* into its live-patch path silently did nothing on canvas).
|
|
244
459
|
*
|
|
245
|
-
*
|
|
246
|
-
*
|
|
247
|
-
*
|
|
248
|
-
*
|
|
460
|
+
* `dropModel3d` (0.22.0) is the second, for the Assets-panel drag-and-drop
|
|
461
|
+
* feature: a host-side drop has no live `THREE.Object3D` yet to self-apply
|
|
462
|
+
* the way a drag does, so the host can't "just do it and tell us" — it has
|
|
463
|
+
* to ask this player to place AND load the thing.
|
|
249
464
|
*
|
|
250
|
-
*
|
|
251
|
-
*
|
|
465
|
+
* Every message gets an ack. The host writes to disk either right before
|
|
466
|
+
* (`patchEntity3d`) or right after (`dropModel3d`, once it knows this
|
|
467
|
+
* succeeded) sending — so a silent failure here always means disk and
|
|
468
|
+
* canvas disagree, and nothing else would ever say so.
|
|
252
469
|
*/
|
|
253
470
|
async function onHostMessage(event) {
|
|
254
471
|
// Source-identity, not origin: the host page and this iframe are on
|
|
@@ -257,9 +474,26 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
257
474
|
if (event.source !== window.parent)
|
|
258
475
|
return;
|
|
259
476
|
const data = event.data;
|
|
260
|
-
if (!data || typeof data !== 'object' || data.type !== '
|
|
477
|
+
if (!data || typeof data !== 'object' || typeof data.type !== 'string')
|
|
478
|
+
return;
|
|
479
|
+
if (data.type === 'umicat:editor:patchEntity3d')
|
|
480
|
+
return onPatchEntity3d(data);
|
|
481
|
+
if (data.type === 'umicat:editor:dropModel3d')
|
|
482
|
+
return onDropModel3d(data);
|
|
483
|
+
if (data.type === 'umicat:editor:setGizmoMode3d') {
|
|
484
|
+
const mode = data.mode;
|
|
485
|
+
if (mode === 'move' || mode === 'rotate' || mode === 'scale') {
|
|
486
|
+
gizmo.setMode(mode);
|
|
487
|
+
gizmo.update(camera);
|
|
488
|
+
}
|
|
261
489
|
return;
|
|
262
|
-
|
|
490
|
+
}
|
|
491
|
+
}
|
|
492
|
+
/**
|
|
493
|
+
* `patch` is an open bag deliberately: skin is the first field, and adding
|
|
494
|
+
* rotation/scale/visible later should be a new `if`, not a new message.
|
|
495
|
+
*/
|
|
496
|
+
async function onPatchEntity3d(m) {
|
|
263
497
|
const done = (error) => {
|
|
264
498
|
if (error)
|
|
265
499
|
console.warn('[umicat/editor] 3D patch failed:', m.entityId, error);
|
|
@@ -303,6 +537,61 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
303
537
|
}
|
|
304
538
|
done();
|
|
305
539
|
}
|
|
540
|
+
/**
|
|
541
|
+
* Drag a model from the Assets panel onto the canvas: raycast the drop
|
|
542
|
+
* point against the ground plane (the exact technique drag-to-move already
|
|
543
|
+
* uses, just with no object grabbed yet to anchor the plane — groundY is
|
|
544
|
+
* always 0, since no scene declares a ground height today and every
|
|
545
|
+
* shipped scene's floor sits at the origin by convention), fetch + parse
|
|
546
|
+
* the GLB from its CDN url directly (`singleModelManifest` +
|
|
547
|
+
* `loadModelAsset` — no manifest entry needed, these two exports exist
|
|
548
|
+
* specifically for a one-off model with no authored id), and register it
|
|
549
|
+
* into the SAME maps the loader populates at scene-load time so it is
|
|
550
|
+
* immediately pickable (`pickEntityAt`) and draggable (`onPointerDown`/
|
|
551
|
+
* `onPointerMove`) with zero changes to either.
|
|
552
|
+
*
|
|
553
|
+
* The host persists this to `scenes3d/<id>.json` + `manifest.json` only
|
|
554
|
+
* AFTER seeing `ok:true` here — so `sceneData`/`manifest` are updated
|
|
555
|
+
* in-place too, to keep this session's own `patchEntity3d` (re-skin,
|
|
556
|
+
* attach a prop) working on the just-dropped entity before any reload
|
|
557
|
+
* picks the disk copy back up.
|
|
558
|
+
*/
|
|
559
|
+
async function onDropModel3d(m) {
|
|
560
|
+
const done = (error, position) => {
|
|
561
|
+
if (error)
|
|
562
|
+
console.warn('[umicat/editor] 3D model drop failed:', m.entityId, error);
|
|
563
|
+
window.parent.postMessage({ type: 'umicat:editor:modelDropped3d', entityId: m.entityId, ok: !error, error, position }, '*');
|
|
564
|
+
};
|
|
565
|
+
if (!scene)
|
|
566
|
+
return done('no scene loaded yet');
|
|
567
|
+
if (objectByEntity.has(m.entityId))
|
|
568
|
+
return done(`entity '${m.entityId}' already exists in this scene`);
|
|
569
|
+
const worldPoint = raycastGroundPlane(m.x, m.y, 0);
|
|
570
|
+
if (!worldPoint)
|
|
571
|
+
return done('the drop point does not land on the ground plane (camera is looking edge-on)');
|
|
572
|
+
const modelAsset = { id: m.entityId, path: m.modelUrl, importScale: m.importScale };
|
|
573
|
+
let object;
|
|
574
|
+
try {
|
|
575
|
+
const loaded = await loadModelAsset(singleModelManifest(modelAsset), m.entityId, { assetBase: '' });
|
|
576
|
+
object = loaded.object;
|
|
577
|
+
}
|
|
578
|
+
catch (e) {
|
|
579
|
+
return done(e instanceof Error ? e.message : String(e));
|
|
580
|
+
}
|
|
581
|
+
object.position.copy(worldPoint);
|
|
582
|
+
// `Entity3D.castShadow` defaults true (scene3d.ts) — match that default
|
|
583
|
+
// for a dropped entity, same as every authored one already gets via
|
|
584
|
+
// `loadScene3D`.
|
|
585
|
+
object.traverse((n) => { n.castShadow = true; n.receiveShadow = true; });
|
|
586
|
+
scene.add(object);
|
|
587
|
+
entityByObject.set(object, m.entityId);
|
|
588
|
+
objectByEntity.set(m.entityId, object);
|
|
589
|
+
// Keep this session's own closure state consistent with what the host
|
|
590
|
+
// is about to write to disk — see the doc comment above.
|
|
591
|
+
sceneData?.entities.push({ id: m.entityId, modelAssetId: m.entityId, transform: { position: { ...worldPoint } } });
|
|
592
|
+
manifest?.models?.push(modelAsset);
|
|
593
|
+
done(undefined, { x: object.position.x, y: object.position.y, z: object.position.z });
|
|
594
|
+
}
|
|
306
595
|
window.addEventListener('message', (e) => { void onHostMessage(e); });
|
|
307
596
|
// Design mode skips physics and animation entirely (loadScene3D's own
|
|
308
597
|
// designMode flag) — there are no mixers to advance and no Rapier world to
|
|
@@ -311,6 +600,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
311
600
|
controls.update();
|
|
312
601
|
if (!scene)
|
|
313
602
|
return;
|
|
603
|
+
gizmo.update(camera);
|
|
314
604
|
renderer.setScissorTest(false);
|
|
315
605
|
renderer.render(scene, camera);
|
|
316
606
|
// Second pass: the orientation gizmo, into a small scissored corner
|
|
@@ -353,6 +643,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
353
643
|
scene.add(marker);
|
|
354
644
|
selectionBox.visible = false;
|
|
355
645
|
scene.add(selectionBox);
|
|
646
|
+
scene.add(gizmo.root);
|
|
356
647
|
// Frame the whole scene — auto-fit, since a small template scene and a
|
|
357
648
|
// real level's dozens of entities need wildly different orbit distances.
|
|
358
649
|
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.23.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",
|