@umicat/three-sdk 1.4.0 → 1.6.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 CHANGED
@@ -26,9 +26,14 @@ from its CDN url, no manifest entry required — and a full Roblox/Unity-style
26
26
  `umicat:editor:setGizmoMode3d`, posting `dragEnd3d`/`rotateEnd3d`/`scaleEnd3d`
27
27
  on release — plus **Delete** (`umicat:editor:deleteEntity3d`) and
28
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).
29
+ host, this player only replays a `patchEntity3d` restore)). The desktop
30
+ camera matches Roblox Studio: left-click/drag selects and manipulates
31
+ (entities, the gizmo), right-drag looks around, WASD flies, Q/E move
32
+ straight down/up, Shift speeds up — touch is untouched (still orbit/
33
+ pinch-zoom via `OrbitControls`, which mouse input no longer reaches at
34
+ all). What it still does not have: undo of entity creation/deletion,
35
+ multi-select, a local/global axis toggle (the gizmo is local-space only),
36
+ middle-mouse pan, F-to-focus, or Studio's comma/period ring-rotate.
32
37
 
33
38
  > This paragraph said "seed, not a product — no input system, no character
34
39
  > controller, no audio, and no published package" for ten minor versions after
@@ -48,14 +48,17 @@ export interface EditorDesignPlayer3DOptions {
48
48
  * THIS iframe rather than the host page — posts `requestUndo3d` asking
49
49
  * the host to do its thing. No entity-creation/deletion undo yet (only
50
50
  * transform edits on an entity that already exists).
51
- * - **HUD sub-mode** (Phase 2, 2026-10-06, read-only) — `setEditMode3d
52
- * {mode:'hud'}` covers the canvas with a neutral backdrop and mounts the
53
- * bound HUD's widgets (same pure-DOM `loadHud3DScene` Play mode uses, via
54
- * `loadHud3d{hudId,hudFile}` — the host fetches/parses the file, this only
55
- * mounts it) into `#hud`, which `hideNonCanvasStaticMarkup` below hid at
56
- * boot like every other hand-authored markup. No drag/patch/select yet —
57
- * that's a later phase; this one proves World↔HUD actually switches and
58
- * renders correctly.
51
+ * - **HUD overlay** (2026-10-07) — the bound HUD's widgets (pure-DOM, same
52
+ * `loadHud3DScene` Play mode uses, via `loadHud3d{hudId,hudFile}` — the
53
+ * host fetches/parses the file, this only mounts it) render into `#hud`
54
+ * ALWAYS ALONGSIDE the world scene, not as a separate mode — `#hud` is
55
+ * un-hidden once, permanently, right after `hideNonCanvasStaticMarkup`
56
+ * below hides it at boot like every other hand-authored markup. Click,
57
+ * create (`createHud3dEntity`), and patch (`patchHud3dEntity`) all work
58
+ * the same way they do on world entities; selecting a HUD widget clears
59
+ * any active world selection and vice versa (see `clearWorldSelection`),
60
+ * so only one of the two ever looks selected at once. `setHudVisible3d`
61
+ * is a purely cosmetic show/hide toggle for the whole HUD layer.
59
62
  *
60
63
  * Takes over `renderer`'s animation loop entirely for the rest of the page's
61
64
  * life — there is no scene-swap API and no teardown, matching how the
@@ -43,14 +43,17 @@ import { loadHud3DScene } from '../hud3d/HudRuntime3D.js';
43
43
  * THIS iframe rather than the host page — posts `requestUndo3d` asking
44
44
  * the host to do its thing. No entity-creation/deletion undo yet (only
45
45
  * transform edits on an entity that already exists).
46
- * - **HUD sub-mode** (Phase 2, 2026-10-06, read-only) — `setEditMode3d
47
- * {mode:'hud'}` covers the canvas with a neutral backdrop and mounts the
48
- * bound HUD's widgets (same pure-DOM `loadHud3DScene` Play mode uses, via
49
- * `loadHud3d{hudId,hudFile}` — the host fetches/parses the file, this only
50
- * mounts it) into `#hud`, which `hideNonCanvasStaticMarkup` below hid at
51
- * boot like every other hand-authored markup. No drag/patch/select yet —
52
- * that's a later phase; this one proves World↔HUD actually switches and
53
- * renders correctly.
46
+ * - **HUD overlay** (2026-10-07) — the bound HUD's widgets (pure-DOM, same
47
+ * `loadHud3DScene` Play mode uses, via `loadHud3d{hudId,hudFile}` — the
48
+ * host fetches/parses the file, this only mounts it) render into `#hud`
49
+ * ALWAYS ALONGSIDE the world scene, not as a separate mode — `#hud` is
50
+ * un-hidden once, permanently, right after `hideNonCanvasStaticMarkup`
51
+ * below hides it at boot like every other hand-authored markup. Click,
52
+ * create (`createHud3dEntity`), and patch (`patchHud3dEntity`) all work
53
+ * the same way they do on world entities; selecting a HUD widget clears
54
+ * any active world selection and vice versa (see `clearWorldSelection`),
55
+ * so only one of the two ever looks selected at once. `setHudVisible3d`
56
+ * is a purely cosmetic show/hide toggle for the whole HUD layer.
54
57
  *
55
58
  * Takes over `renderer`'s animation loop entirely for the rest of the page's
56
59
  * life — there is no scene-swap API and no teardown, matching how the
@@ -64,28 +67,29 @@ import { loadHud3DScene } from '../hud3d/HudRuntime3D.js';
64
67
  */
65
68
  export async function runEditorDesignPlayer3D(renderer, opts = {}) {
66
69
  hideNonCanvasStaticMarkup(renderer.domElement);
67
- // ---- HUD sub-mode (2026-10-06, HUD editing Phase 2) -----------------------
70
+ // ---- World + HUD as simultaneous layers (2026-10-07) ----------------------
68
71
  //
69
- // World↔HUD is a separate axis from this whole function's own existence —
70
- // unlike 2D's design player, which is ONE thing (world OR HUD, chosen at
71
- // iframe construction via which Scene gets launched), this player already
72
- // owns the renderer loop permanently (ADR-021, no teardown), so HUD mode is
73
- // a STATE inside it, not a new entry point. Switching needs no camera/scene
74
- // coordination at all — categorically simpler than world-mode editing —
75
- // because a HUD widget is pure DOM (see `hud3d/HudRuntime3D.ts`): HUD mode
76
- // is just "cover the canvas with a neutral backdrop and mount the same
77
- // DOM tree Play mode would show."
72
+ // World and HUD used to be mutually-exclusive editor sub-modes (a backdrop
73
+ // covered the canvas while HUD was "active"). Replaced: both are always
74
+ // visible and interactive together, Figma-layers style. This needs no new
75
+ // hit-testing code — `renderer.domElement.addEventListener('pointerdown', …)`
76
+ // below attaches directly to the canvas, and HUD widgets are plain DOM
77
+ // sitting on top of it, so ordinary browser hit-testing already gives
78
+ // "topmost element wins": a click landing on a widget never reaches the
79
+ // canvas at all, and a click on genuinely empty HUD space falls through for
80
+ // free (every widget is `position:fixed`, so the HUD root's own box
81
+ // collapses to ~zero area — there's nothing there to intercept a click
82
+ // except actual widgets). `#hud` itself (hidden by `hideNonCanvasStaticMarkup`
83
+ // above, same as every other hand-authored markup) is un-hidden once, right
84
+ // below, for the rest of the Edit session — no more toggling.
78
85
  //
79
- // `#hud` itself was just hidden by `hideNonCanvasStaticMarkup` above (it is
80
- // an existing `index.html` child with no `data-umicat-keep`, same as every
81
- // other hand-authored markup in Edit mode) — that hide is UNDONE here only
82
- // while HUD sub-mode is active, not by tagging `#hud` `data-umicat-keep` at
83
- // the top (which would make it visible in WORLD mode too, where nothing
84
- // mounts into it and it would just sit there empty — harmless, but this is
85
- // more precise: visible exactly when something is actually shown in it).
86
- let hudMode = 'world';
86
+ // The one thing that doesn't come for free: only one thing should ever
87
+ // look/act selected at a time. World's marker/selectionBox/gizmo and HUD's
88
+ // yellow outline are independent visual states that never used to coexist —
89
+ // `selectHudEntity`/the world pick handlers below now cross-clear each
90
+ // other (see `clearWorldSelection` and its two call sites).
91
+ document.getElementById('hud')?.style.setProperty('display', '');
87
92
  let hudHandle = null;
88
- let hudBackdrop = null;
89
93
  // Selection (Phase 4) — a single id, same "one thing selected at a time"
90
94
  // model world mode's marker/selectionBox/gizmo already use. No gizmo for
91
95
  // HUD widgets (there's nothing to move in 3D — repositioning is an anchor/
@@ -93,24 +97,6 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
93
97
  // selection here only needs a visual outline + telling the host what's
94
98
  // selected so the Inspector has something to show.
95
99
  let hudSelectedId = null;
96
- function ensureHudBackdrop() {
97
- if (hudBackdrop)
98
- return hudBackdrop;
99
- // Created AFTER hideNonCanvasStaticMarkup already ran once at the top of
100
- // this function — that function only hides EXISTING document.body
101
- // children at the moment it's called, so anything appended after is
102
- // simply never touched by it. No data-umicat-keep needed here either.
103
- const el = document.createElement('div');
104
- el.id = 'umicat-hud3d-editor-backdrop';
105
- // z-index 15: above the canvas (no explicit stacking, renders at the
106
- // normal in-flow level) but below `#hud` (z-index:20 in every template,
107
- // see umicat-template/index.html) — the real HUD widgets, mounted into
108
- // `#hud`, sit on TOP of this backdrop, not behind it.
109
- el.style.cssText = 'position:fixed;inset:0;z-index:15;background:#2a2d32;display:none;';
110
- document.body.appendChild(el);
111
- hudBackdrop = el;
112
- return el;
113
- }
114
100
  const HUD_OUTLINE = '2px solid #ffd23f'; // same selection-yellow world mode's BoxHelper uses
115
101
  /** Select (or clear, for `null`) a HUD entity — outline + ack to the host.
116
102
  * Re-looked-up by id on every call rather than holding an element
@@ -152,6 +138,10 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
152
138
  handle.root.addEventListener('click', (e) => {
153
139
  const target = e.target?.closest('[data-hud3d-entity-id]');
154
140
  selectHudEntity(target?.dataset.hud3dEntityId ?? null);
141
+ // Cross-layer deselect — a HUD pick and a World selection should never
142
+ // both look active at once (see this file's header comment).
143
+ if (gizmo.attached)
144
+ clearWorldSelection();
155
145
  });
156
146
  }
157
147
  function mountHud(hudScene) {
@@ -161,28 +151,104 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
161
151
  if (hudHandle)
162
152
  wireHudEditorInteractivity(hudHandle);
163
153
  }
164
- function enterHudMode(hudScene) {
165
- hudMode = 'hud';
166
- ensureHudBackdrop().style.display = 'block';
167
- const hudEl = document.getElementById('hud');
168
- if (hudEl)
169
- hudEl.style.display = '';
170
- mountHud(hudScene);
171
- }
172
- function exitHudMode() {
173
- hudMode = 'world';
174
- if (hudBackdrop)
175
- hudBackdrop.style.display = 'none';
176
- const hudEl = document.getElementById('hud');
177
- if (hudEl)
178
- hudEl.style.display = 'none';
179
- hudHandle?.destroy();
180
- hudHandle = null;
181
- hudSelectedId = null;
182
- }
183
154
  const camera = new THREE.PerspectiveCamera(50, window.innerWidth / window.innerHeight, 0.05, 2000);
184
155
  const controls = new OrbitControls(camera, renderer.domElement);
185
156
  controls.enableDamping = true;
157
+ // Desktop mouse input is owned entirely by the free-fly controller below
158
+ // (Roblox Studio's scheme: left-select/drag, right-drag-look, WASD/QE fly
159
+ // — see that block's own comment) instead of three.js's stock Unity/
160
+ // Blender-style left-drag-orbit. `controls.enabled` stays true FOREVER —
161
+ // never set false for a mouse reason — because `controls.touches` is
162
+ // deliberately left at its default (ONE: TOUCH.ROTATE, TWO:
163
+ // TOUCH.DOLLY_PAN): touch devices must keep orbiting/pinch-zooming exactly
164
+ // as before. Disabling only the three MOUSE bindings is what makes
165
+ // OrbitControls touch-only — confirmed against the pinned three@0.186.0
166
+ // source, `onMouseDown`'s button→action switch falls through to
167
+ // `default: this.state = STATE.NONE` once each mapping is null, so a
168
+ // mouse button-down is tracked (harmlessly) but never drives rotate/
169
+ // dolly/pan. Wheel is untouched on purpose — it still reaches
170
+ // OrbitControls' own (unmodified) wheel handler, which doesn't gate on
171
+ // `mouseButtons` at all; `syncOrbitTarget()` below is what makes that
172
+ // keep working as a plain forward/back dolly instead of zooming toward a
173
+ // stale point, with zero new wheel code needed.
174
+ controls.mouseButtons = { LEFT: null, MIDDLE: null, RIGHT: null };
175
+ // ---- Desktop free-fly camera (Roblox Studio scheme) ---------------------
176
+ //
177
+ // Yaw/pitch state, NOT re-derived from camera.quaternion every frame —
178
+ // storing the two angles (rather than reading them back out of the
179
+ // quaternion each update) is what avoids roll creeping in: each frame
180
+ // rebuilds the quaternion fresh from (pitch, yaw, 0) in Euler order
181
+ // 'YXZ'. That order specifically — yaw applied around WORLD Y outermost,
182
+ // pitch around the camera's OWN, already-yawed local X innermost — is the
183
+ // standard three.js FPS-camera convention (same one PointerLockControls
184
+ // uses): pitching rotates around an axis pitch itself doesn't move, so
185
+ // the camera's local X ("right") stays exactly horizontal no matter how
186
+ // far you look up/down, and roll can never accumulate since nothing ever
187
+ // writes the Euler's Z component.
188
+ let yaw = 0;
189
+ let pitch = 0;
190
+ const PITCH_LIMIT = Math.PI / 2 - 0.001; // just inside straight up/down — avoids the lookAt singularity
191
+ const flyEuler = new THREE.Euler(0, 0, 0, 'YXZ');
192
+ // How far in front of the camera OrbitControls' own `target` is kept at
193
+ // all times — a CONSTANT, seeded once from the scene's auto-frame
194
+ // distance (see the scene-load block below). Not the live distance to
195
+ // anything in the scene; purely the radius of the invisible pivot sphere
196
+ // the free-fly camera drags around with it so OrbitControls' touch/wheel
197
+ // code (which still runs `controls.update()` every frame and derives its
198
+ // own state from `camera.position`/`target`) always sees a sane,
199
+ // camera-relative target instead of a stale or distant one.
200
+ //
201
+ // This isn't just a touch nicety — confirmed against the pinned
202
+ // OrbitControls source, `update()` unconditionally ends with
203
+ // `this.object.lookAt(this.target)` on EVERY call, mouse-disabled or not.
204
+ // Without this, the render loop's own `controls.update()` call would snap
205
+ // the camera back to face a stale `target` every single frame, fighting
206
+ // whatever `applyLookDelta`/WASD just did.
207
+ let orbitDistance = 5;
208
+ // Scaled once per scene load (see below) so a tiny room and a sprawling
209
+ // level don't share one fixed speed — same "proportional to scene
210
+ // radius" convention `camera.near`/`camera.far` already use a few lines
211
+ // below in the scene-load block.
212
+ let flySpeed = 5;
213
+ const SHIFT_MULTIPLIER = 3;
214
+ const LOOK_SENSITIVITY = 0.0025; // radians per pixel of mouse movement
215
+ /**
216
+ * Keeps OrbitControls' own invariant (camera always faces `target`, at a
217
+ * sane distance) intact even though desktop input never goes through any
218
+ * OrbitControls method. Called after every desktop-driven camera change
219
+ * (a look-drag delta, a WASD/QE frame-step) — a no-op when nothing
220
+ * changed (recomputing from an unchanged camera pose reproduces the same
221
+ * target), but it's what keeps a TOUCH gesture that starts the instant
222
+ * after a desktop gesture ends from seeing a target that's still wherever
223
+ * it was left relative to the OLD camera pose.
224
+ */
225
+ function syncOrbitTarget() {
226
+ const forward = new THREE.Vector3(0, 0, -1).applyQuaternion(camera.quaternion);
227
+ controls.target.copy(camera.position).addScaledVector(forward, orbitDistance);
228
+ }
229
+ /**
230
+ * Right-drag look: rotates the camera IN PLACE (yaw/pitch only, position
231
+ * untouched) — a FREE-LOOK, not an orbit, matching Roblox Studio's actual
232
+ * behavior ("dragging the mouse moves the camera view around") rather
233
+ * than three.js's default left-drag orbit-around-target. Seeded from the
234
+ * CURRENT `yaw`/`pitch` each call — those two module-scope variables are
235
+ * the single source of truth once seeded at scene load; re-deriving them
236
+ * from `camera.quaternion` via `Euler.setFromQuaternion` on every call
237
+ * would re-introduce the float drift/roll-creep this design avoids.
238
+ */
239
+ function applyLookDelta(deltaX, deltaY) {
240
+ yaw -= deltaX * LOOK_SENSITIVITY;
241
+ pitch = THREE.MathUtils.clamp(pitch - deltaY * LOOK_SENSITIVITY, -PITCH_LIMIT, PITCH_LIMIT);
242
+ flyEuler.set(pitch, yaw, 0);
243
+ camera.quaternion.setFromEuler(flyEuler);
244
+ syncOrbitTarget();
245
+ }
246
+ // WASD/QE — held-key state, consumed every animation-loop frame with a
247
+ // real delta-time (see the render loop below) rather than acted on at
248
+ // keydown, so holding a key flies continuously instead of nudging once
249
+ // per press.
250
+ const movementKeysDown = new Set();
251
+ let shiftHeld = false;
186
252
  // A single persistent marker, repositioned per click — the exact world
187
253
  // point clicked (what "put a torch at the spot I clicked" needs), distinct
188
254
  // from the box below (which entity was hit, not just where).
@@ -327,6 +393,15 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
327
393
  scale: { x: o.scale.x, y: o.scale.y, z: o.scale.z },
328
394
  };
329
395
  };
396
+ // Test-only — the MAIN camera's current pose, for the desktop camera
397
+ // controls test suite (left-select/right-look/WASD/QE) to assert against
398
+ // without hand-deriving projection math — same posture as every other
399
+ // debug readback in this file.
400
+ globalThis.__umicatCameraPose =
401
+ () => ({
402
+ position: { x: camera.position.x, y: camera.position.y, z: camera.position.z },
403
+ quaternion: [camera.quaternion.x, camera.quaternion.y, camera.quaternion.z, camera.quaternion.w],
404
+ });
330
405
  // Only VISIBLE entity roots are ever raycast against. three.js's
331
406
  // Mesh.raycast does NOT check `.visible` on its own (confirmed against the
332
407
  // pinned three source — no such check in Raycaster.js or Object3D.raycast),
@@ -353,6 +428,12 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
353
428
  let downX = 0;
354
429
  let downY = 0;
355
430
  let moved = false;
431
+ // Right-button look-drag state — a separate gesture channel entirely from
432
+ // the left-button select/drag state above; see `applyLookDelta` and the
433
+ // `e.button === 2` branch in the pointer handlers below.
434
+ let lookDragging = false;
435
+ let lastLookX = 0;
436
+ let lastLookY = 0;
356
437
  // Entity drag — Phase 1 of real editing (translate only, ground-plane
357
438
  // constrained). Grabbing on an entity moves it; grabbing empty space/sky
358
439
  // still orbits, same convention as Unity/Blender. Whether THIS gesture is
@@ -370,6 +451,22 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
370
451
  let dragEntityId = null;
371
452
  let dragPlane = null;
372
453
  let dragGrabOffset = null; // world-space, plane-point minus object position at grab time
454
+ /**
455
+ * Deselect whatever's selected in WORLD — marker/box hidden, gizmo
456
+ * detached, and (new, 2026-10-07) the host told, since a miss-click used
457
+ * to deselect visually but post nothing: the host's own `lastPick` kept
458
+ * the stale prior selection forever, harmless only while the Inspector's
459
+ * visibility was gated on a now-removed "world mode" flag rather than on
460
+ * `lastPick` itself. Also called from the HUD click listener below (cross-
461
+ * layer deselect — see this file's header comment on why only one of
462
+ * World/HUD should ever look selected at once).
463
+ */
464
+ function clearWorldSelection() {
465
+ marker.visible = false;
466
+ selectionBox.visible = false;
467
+ gizmo.detach();
468
+ window.parent.postMessage({ type: 'umicat:editor:pickPoint3d', x: 0, y: 0, z: 0, entityId: null }, '*');
469
+ }
373
470
  let gizmoDrag = null;
374
471
  const beginGizmoDrag = (hit, e) => {
375
472
  const obj = gizmo.attached;
@@ -463,6 +560,30 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
463
560
  moved = true;
464
561
  };
465
562
  const onPointerDown = (e) => {
563
+ // Right button — camera look-drag, a separate gesture channel entirely
564
+ // from everything below. Hard-returns before touching any select/drag/
565
+ // gizmo state, so a right-click can never be misread as the start of a
566
+ // left gesture.
567
+ if (e.button === 2) {
568
+ lookDragging = true;
569
+ lastLookX = e.clientX;
570
+ lastLookY = e.clientY;
571
+ try {
572
+ renderer.domElement.setPointerCapture(e.pointerId);
573
+ }
574
+ catch {
575
+ // Same posture as every other setPointerCapture call in this file —
576
+ // capture is an enhancement (keeps the look-drag live off-canvas),
577
+ // not a requirement.
578
+ }
579
+ return;
580
+ }
581
+ // Middle button, or anything else: not ours. Left (button 0) covers
582
+ // both a real left-click AND touch's primary contact (also button 0) —
583
+ // this is how touch stays on the exact same path it's always used,
584
+ // unaffected by the Roblox-style desktop remap.
585
+ if (e.button !== 0)
586
+ return;
466
587
  downX = e.clientX;
467
588
  downY = e.clientY;
468
589
  moved = false;
@@ -472,6 +593,15 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
472
593
  raycaster.setFromCamera(ndcFromEvent(e), camera);
473
594
  const gizmoHit = gizmo.hitTest(raycaster);
474
595
  if (gizmoHit && beginGizmoDrag(gizmoHit, e)) {
596
+ // `controls.enabled` toggling is a TOUCH-only concern now — mouse
597
+ // can't reach OrbitControls regardless, since all three of its
598
+ // mouse bindings are null (see `controls.mouseButtons` above). But
599
+ // `onPointerDown`/`Move`/`Up` have no `pointerType` check and never
600
+ // have, so a touch tap/drag on a gizmo handle or entity body runs
601
+ // through this exact same code — and `controls.touches` is
602
+ // deliberately left reactive. Without this toggle, a touch-drag on
603
+ // an entity would simultaneously manipulate it AND orbit the
604
+ // camera via OrbitControls' own touch handling.
475
605
  controls.enabled = false;
476
606
  try {
477
607
  renderer.domElement.setPointerCapture(e.pointerId);
@@ -483,22 +613,25 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
483
613
  }
484
614
  }
485
615
  const hit = pickEntityAt(e);
616
+ // Empty space: a left-drag here is a no-op now (Roblox scheme — rotate
617
+ // lives on the right button; OrbitControls' LEFT binding is null, so
618
+ // there's nothing left to fall through to). Reserved for a future
619
+ // marquee-select, not built yet.
486
620
  if (!hit)
487
- return; // empty space — let OrbitControls own this gesture
621
+ return;
488
622
  const objectPos = hit.entityRoot.getWorldPosition(new THREE.Vector3());
489
623
  const plane = new THREE.Plane(new THREE.Vector3(0, 1, 0), -objectPos.y);
490
624
  const planePoint = new THREE.Vector3();
491
625
  // Looking exactly parallel to the ground has no plane intersection —
492
626
  // vanishingly rare for this camera (auto-framed, always angled down at
493
- // the scene) but cheap to guard: fall through to orbit rather than
494
- // start a drag from a garbage grab offset.
627
+ // the scene) but cheap to guard against a garbage grab offset.
495
628
  if (!raycaster.ray.intersectPlane(plane, planePoint))
496
629
  return;
497
630
  dragEntity = hit.entityRoot;
498
631
  dragEntityId = hit.entityId;
499
632
  dragPlane = plane;
500
633
  dragGrabOffset = planePoint.sub(objectPos);
501
- controls.enabled = false;
634
+ controls.enabled = false; // touch-only concern now — see the gizmo-drag site's comment above
502
635
  try {
503
636
  renderer.domElement.setPointerCapture(e.pointerId);
504
637
  }
@@ -512,6 +645,19 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
512
645
  }
513
646
  };
514
647
  const onPointerMove = (e) => {
648
+ if (lookDragging) {
649
+ applyLookDelta(e.clientX - lastLookX, e.clientY - lastLookY);
650
+ lastLookX = e.clientX;
651
+ lastLookY = e.clientY;
652
+ return;
653
+ }
654
+ // Defensive: a right-drag that started off-canvas (so this handler
655
+ // never saw its pointerdown) shouldn't be misread as a left gesture.
656
+ // `buttons` (not `button`) is the live bitmask of currently-held
657
+ // buttons — needed because a pointermove with no button transition
658
+ // reports `button === -1`.
659
+ if (e.buttons === 2)
660
+ return;
515
661
  if (Math.abs(e.clientX - downX) > 4 || Math.abs(e.clientY - downY) > 4)
516
662
  moved = true;
517
663
  if (gizmoDrag) {
@@ -532,6 +678,18 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
532
678
  selectionBox.setFromObject(dragEntity);
533
679
  };
534
680
  const onPointerUp = (e) => {
681
+ if (lookDragging && e.button === 2) {
682
+ lookDragging = false;
683
+ try {
684
+ renderer.domElement.releasePointerCapture(e.pointerId);
685
+ }
686
+ catch {
687
+ // Already released, or never captured.
688
+ }
689
+ return;
690
+ }
691
+ if (e.button !== 0)
692
+ return;
535
693
  try {
536
694
  renderer.domElement.releasePointerCapture(e.pointerId);
537
695
  }
@@ -583,11 +741,13 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
583
741
  // Clicked empty space with nothing grabbed — deselect. Previously a
584
742
  // no-op (the marker/box from a PRIOR selection just stayed on
585
743
  // screen); now load-bearing, since the gizmo also needs to disappear.
586
- marker.visible = false;
587
- selectionBox.visible = false;
588
- gizmo.detach();
744
+ clearWorldSelection();
745
+ if (hudSelectedId)
746
+ selectHudEntity(null); // cross-layer deselect
589
747
  return;
590
748
  }
749
+ if (hudSelectedId)
750
+ selectHudEntity(null); // cross-layer deselect
591
751
  marker.position.copy(hit.point);
592
752
  marker.visible = true;
593
753
  // Frame the whole entity the click landed on, not just the point on its
@@ -602,6 +762,13 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
602
762
  renderer.domElement.addEventListener('pointerdown', onPointerDown);
603
763
  renderer.domElement.addEventListener('pointermove', onPointerMove);
604
764
  renderer.domElement.addEventListener('pointerup', onPointerUp);
765
+ // Right-click is now a real camera gesture (look-drag) — the native
766
+ // context menu popping up mid-drag would be disruptive. Not strictly
767
+ // load-bearing today (OrbitControls' own `onContextMenu` already calls
768
+ // `preventDefault()` whenever `controls.enabled !== false`, and `enabled`
769
+ // stays permanently true now — see its own comment above), but this
770
+ // shouldn't be left as an implicit dependency on that internal detail.
771
+ renderer.domElement.addEventListener('contextmenu', (e) => e.preventDefault());
605
772
  /**
606
773
  * Host→iframe messages. `patchEntity3d` (0.18.0) was the first — everything
607
774
  * before it went one way: the player reported picks and drags, and the
@@ -644,30 +811,28 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
644
811
  }
645
812
  return;
646
813
  }
647
- // World/HUD toggle (HUD editing Phase 2) — see the "HUD sub-mode" block
648
- // above this function's camera setup for why this needs no camera/scene
649
- // work at all, unlike every other message here.
650
- if (data.type === 'umicat:editor:setEditMode3d') {
651
- const mode = data.mode;
652
- if (mode === 'hud')
653
- enterHudMode(null);
654
- else if (mode === 'world')
655
- exitHudMode();
814
+ // Cosmetic-only visibility toggle (the eye icon in the host toolbar) —
815
+ // independent of whether a HUD is actually mounted. World/HUD used to be
816
+ // a mutually-exclusive mode switch (`setEditMode3d`); both layers are
817
+ // always visible+interactive now (see this file's header comment), so
818
+ // this is the only thing left to toggle, and it's purely cosmetic.
819
+ if (data.type === 'umicat:editor:setHudVisible3d') {
820
+ const visible = data.visible;
821
+ const hudEl = document.getElementById('hud');
822
+ if (typeof visible === 'boolean' && hudEl)
823
+ hudEl.style.display = visible ? '' : 'none';
656
824
  return;
657
825
  }
658
826
  // The host already fetched + parsed the HUD file (it owns the binding
659
827
  // lookup and the workspace-file read, same division of labor as 2D's
660
828
  // `EditorLoadHudMessage`) — this just (re)mounts it. Used both for the
661
- // FIRST mount (host sends this once it has the bound HUD ready, shortly
662
- // after `setEditMode3d{mode:'hud'}`) and for "switch which HUD is being
663
- // edited" (HUD browser, Phase 3) without a mode change.
829
+ // active WORLD scene's bound HUD (auto-mounted as soon as the scene
830
+ // loads, host-side) and for "switch which HUD is being edited" (HUD
831
+ // browser, Phase 3) — no mode distinction between the two anymore.
664
832
  if (data.type === 'umicat:editor:loadHud3d') {
665
833
  const m = data;
666
834
  const hudFile = (typeof m.hudId === 'string' ? m.hudFile : undefined);
667
- if (hudMode !== 'hud')
668
- enterHudMode(hudFile ?? null);
669
- else
670
- mountHud(hudFile ?? null);
835
+ mountHud(hudFile ?? null);
671
836
  window.parent.postMessage({ type: 'umicat:editor:hud3dLoaded', hudId: typeof m.hudId === 'string' ? m.hudId : null, error: !hudFile }, '*');
672
837
  return;
673
838
  }
@@ -946,10 +1111,72 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
946
1111
  window.parent.postMessage({ type: 'umicat:editor:requestUndo3d' }, '*');
947
1112
  }
948
1113
  });
1114
+ // WASD/QE fly-camera + Shift speed boost — held-STATE, not a discrete
1115
+ // action, so this is a separate keydown/keyup PAIR rather than folded
1116
+ // into the action listener above (which only ever needs keydown). Same
1117
+ // focused-input guard as that listener, for the same reason it states
1118
+ // there — "costs nothing," even though nothing focusable exists in this
1119
+ // iframe today.
1120
+ const MOVEMENT_KEYS = new Set(['w', 'a', 's', 'd', 'q', 'e']);
1121
+ window.addEventListener('keydown', (e) => {
1122
+ const target = e.target;
1123
+ if (target && (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable))
1124
+ return;
1125
+ if (e.key === 'Shift') {
1126
+ shiftHeld = true;
1127
+ return;
1128
+ }
1129
+ const key = e.key.toLowerCase();
1130
+ if (MOVEMENT_KEYS.has(key))
1131
+ movementKeysDown.add(key);
1132
+ });
1133
+ window.addEventListener('keyup', (e) => {
1134
+ if (e.key === 'Shift') {
1135
+ shiftHeld = false;
1136
+ return;
1137
+ }
1138
+ movementKeysDown.delete(e.key.toLowerCase());
1139
+ });
949
1140
  // Design mode skips physics and animation entirely (loadScene3D's own
950
1141
  // designMode flag) — there are no mixers to advance and no Rapier world to
951
- // step, so the loop only ever needs to render.
1142
+ // step, so the loop only ever needs to render (plus, now, the WASD/QE
1143
+ // fly-camera frame-step below).
1144
+ const flyClock = new THREE.Clock();
952
1145
  renderer.setAnimationLoop(() => {
1146
+ // Clamped so a backgrounded tab's first frame back (an arbitrarily
1147
+ // large real-world gap) doesn't teleport the camera.
1148
+ const dt = Math.min(flyClock.getDelta(), 0.1);
1149
+ if (movementKeysDown.size > 0) {
1150
+ // Forward/right are horizontal-projected so looking down and
1151
+ // pressing W doesn't dive into the ground — Q/E (below) are the only
1152
+ // vertical axis. `right` isn't explicitly re-projected: under Euler
1153
+ // order 'YXZ', pitch rotates around the camera's own local X, which
1154
+ // pitch itself never moves, so local X stays horizontal by
1155
+ // construction — the `.y = 0; normalize()` here is cheap, defensive
1156
+ // insurance against float drift, not load-bearing math.
1157
+ const speed = flySpeed * (shiftHeld ? SHIFT_MULTIPLIER : 1) * dt;
1158
+ const forward = new THREE.Vector3(0, 0, -1).applyQuaternion(camera.quaternion);
1159
+ forward.y = 0;
1160
+ if (forward.lengthSq() > 1e-8)
1161
+ forward.normalize();
1162
+ const right = new THREE.Vector3(1, 0, 0).applyQuaternion(camera.quaternion);
1163
+ right.y = 0;
1164
+ if (right.lengthSq() > 1e-8)
1165
+ right.normalize();
1166
+ if (movementKeysDown.has('w'))
1167
+ camera.position.addScaledVector(forward, speed);
1168
+ if (movementKeysDown.has('s'))
1169
+ camera.position.addScaledVector(forward, -speed);
1170
+ if (movementKeysDown.has('d'))
1171
+ camera.position.addScaledVector(right, speed);
1172
+ if (movementKeysDown.has('a'))
1173
+ camera.position.addScaledVector(right, -speed);
1174
+ if (movementKeysDown.has('e'))
1175
+ camera.position.y += speed; // straight world-Y, independent of look direction
1176
+ if (movementKeysDown.has('q'))
1177
+ camera.position.y -= speed;
1178
+ syncOrbitTarget();
1179
+ }
953
1180
  controls.update();
954
1181
  if (!scene)
955
1182
  return;
@@ -1026,7 +1253,19 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1026
1253
  camera.near = Math.max(radius / 100, 0.01);
1027
1254
  camera.far = radius * 20;
1028
1255
  camera.updateProjectionMatrix();
1029
- controls.update();
1256
+ controls.update(); // still the simplest way to get camera.quaternion pointed at `center` — ends in object.lookAt(target)
1257
+ // Seed the free-fly controller's own state from the orientation
1258
+ // `controls.update()` just computed, instead of leaving OrbitControls
1259
+ // to keep deriving it forever (it won't — mouse can't drive it
1260
+ // anymore). `Euler.setFromQuaternion` with order 'YXZ' against a pure,
1261
+ // no-roll lookAt orientation decomposes exactly back into
1262
+ // (pitch, yaw, ~0): both constructions ultimately build "rotate to
1263
+ // face `center`, roll locked to zero, up = world Y."
1264
+ flyEuler.setFromQuaternion(camera.quaternion);
1265
+ pitch = THREE.MathUtils.clamp(flyEuler.x, -PITCH_LIMIT, PITCH_LIMIT);
1266
+ yaw = flyEuler.y;
1267
+ orbitDistance = camera.position.distanceTo(center);
1268
+ flySpeed = Math.max(radius * 0.6, 2); // proportional to scene scale, same convention camera.near/far use just above
1030
1269
  window.parent.postMessage({ type: 'umicat:editor:scene3dLoaded', sceneId }, '*');
1031
1270
  }
1032
1271
  catch (e) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.4.0",
3
+ "version": "1.6.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",