@umicat/three-sdk 0.17.2 → 0.17.3

package/dist/editor/EditorDesignPlayer3D.d.ts

@@ -16,10 +16,20 @@ export interface EditorDesignPlayer3DOptions {
  * The 3D counterpart of `@umicat/phaser-sdk`'s `EditorDesignScene` (ADR-021)
  * — renders a scene's AUTHORED data with no game code and no save, so the
  * platform's Edit tab can show a 3D game's layout the same way it already
- * does for 2D. Read-only: no drag, no gizmo, no apply-edit — the one
- * interaction is click-to-pick a world coordinate, posted to the host so a
- * person can point at a real spot instead of guessing one blind when telling
- * the AI where to place something.
+ * does for 2D.
+ *
+ * Two interactions:
+ * - **Click** an entity to select it — a bounding box frames it and a
+ *   marker reads off the exact world coordinate, posted to the host so a
+ *   person can point at a real spot instead of guessing one blind when
+ *   telling the AI where to place something.
+ * - **Drag** an entity to move it (Phase 1 of real editing, ground-plane
+ *   constrained — position only, no rotation/scale, no gizmo, no
+ *   Inspector). This function itself never writes anything — it only
+ *   moves the live THREE.Object3D and posts the final LOCAL position on
+ *   release (`umicat:editor:dragEnd3d`); the host owns turning that into a
+ *   disk write. Grabbing empty space/sky orbits instead, same convention
+ *   as Unity/Blender.
  *
  * Takes over `renderer`'s animation loop entirely for the rest of the page's
  * life — there is no scene-swap API and no teardown, matching how the

package/dist/editor/EditorDesignPlayer3D.js

@@ -5,10 +5,20 @@ import { loadScene3D } from '../SceneLoader3D.js';
  * The 3D counterpart of `@umicat/phaser-sdk`'s `EditorDesignScene` (ADR-021)
  * — renders a scene's AUTHORED data with no game code and no save, so the
  * platform's Edit tab can show a 3D game's layout the same way it already
- * does for 2D. Read-only: no drag, no gizmo, no apply-edit — the one
- * interaction is click-to-pick a world coordinate, posted to the host so a
- * person can point at a real spot instead of guessing one blind when telling
- * the AI where to place something.
+ * does for 2D.
+ *
+ * Two interactions:
+ * - **Click** an entity to select it — a bounding box frames it and a
+ *   marker reads off the exact world coordinate, posted to the host so a
+ *   person can point at a real spot instead of guessing one blind when
+ *   telling the AI where to place something.
+ * - **Drag** an entity to move it (Phase 1 of real editing, ground-plane
+ *   constrained — position only, no rotation/scale, no gizmo, no
+ *   Inspector). This function itself never writes anything — it only
+ *   moves the live THREE.Object3D and posts the final LOCAL position on
+ *   release (`umicat:editor:dragEnd3d`); the host owns turning that into a
+ *   disk write. Grabbing empty space/sky orbits instead, same convention
+ *   as Unity/Blender.
  *
  * Takes over `renderer`'s animation loop entirely for the rest of the page's
  * life — there is no scene-swap API and no teardown, matching how the
@@ -67,64 +77,143 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
     };
     resize();
     window.addEventListener('resize', resize);
+    const raycaster = new THREE.Raycaster();
+    const ndcFromEvent = (e) => {
+        const rect = renderer.domElement.getBoundingClientRect();
+        return new THREE.Vector2(((e.clientX - rect.left) / rect.width) * 2 - 1, -((e.clientY - rect.top) / rect.height) * 2 + 1);
+    };
+    // Only VISIBLE entity roots are ever raycast against. three.js's
+    // Mesh.raycast does NOT check `.visible` on its own (confirmed against the
+    // pinned three source — no such check in Raycaster.js or Object3D.raycast),
+    // and a real scene can ship an invisible collision box alongside
+    // separately-placed visible ground models — without this filter, a click
+    // that visibly lands on the rendered ground can silently return the
+    // collider's coordinates instead.
+    const pickEntityAt = (e) => {
+        raycaster.setFromCamera(ndcFromEvent(e), camera);
+        const targets = Array.from(entityByObject.keys()).filter((o) => o.visible !== false);
+        const hits = raycaster.intersectObjects(targets, true);
+        if (hits.length === 0)
+            return null;
+        let node = hits[0].object;
+        while (node) {
+            const id = entityByObject.get(node);
+            if (id)
+                return { entityId: id, entityRoot: node, point: hits[0].point };
+            node = node.parent;
+        }
+        return null;
+    };
     // Orbit-vs-click: a real drag moves the pointer more than a few px.
     let downX = 0;
     let downY = 0;
     let moved = false;
+    // Entity drag — Phase 1 of real editing (translate only, ground-plane
+    // constrained). Grabbing on an entity moves it; grabbing empty space/sky
+    // still orbits, same convention as Unity/Blender. Whether THIS gesture is
+    // a drag is decided synchronously in pointerdown (a raycast hit or not) —
+    // `OrbitControls`'s own pointerdown listener runs first (registered
+    // earlier) and always starts its internal drag bookkeeping, but its
+    // `onPointerMove`/related handlers re-check `this.enabled` on every event
+    // rather than only at attach time (confirmed against the pinned
+    // OrbitControls source), so disabling it HERE still correctly suppresses
+    // every subsequent move for this gesture; its `onPointerUp` cleanup does
+    // not check `enabled` at all, so re-enabling afterward never leaves it
+    // stuck. No drag state survives a scene reload — it's cleared on release,
+    // and a scene swap only ever happens via a full iframe reload anyway.
+    let dragEntity = null;
+    let dragEntityId = null;
+    let dragPlane = null;
+    let dragGrabOffset = null; // world-space, plane-point minus object position at grab time
     const onPointerDown = (e) => {
         downX = e.clientX;
         downY = e.clientY;
         moved = false;
+        if (!scene)
+            return;
+        const hit = pickEntityAt(e);
+        if (!hit)
+            return; // empty space — let OrbitControls own this gesture
+        const objectPos = hit.entityRoot.getWorldPosition(new THREE.Vector3());
+        const plane = new THREE.Plane(new THREE.Vector3(0, 1, 0), -objectPos.y);
+        const planePoint = new THREE.Vector3();
+        // Looking exactly parallel to the ground has no plane intersection —
+        // vanishingly rare for this camera (auto-framed, always angled down at
+        // the scene) but cheap to guard: fall through to orbit rather than
+        // start a drag from a garbage grab offset.
+        if (!raycaster.ray.intersectPlane(plane, planePoint))
+            return;
+        dragEntity = hit.entityRoot;
+        dragEntityId = hit.entityId;
+        dragPlane = plane;
+        dragGrabOffset = planePoint.sub(objectPos);
+        controls.enabled = false;
+        try {
+            renderer.domElement.setPointerCapture(e.pointerId);
+        }
+        catch {
+            // Multi-touch / an already-released pointer can throw here — never
+            // let that leave the gesture half-started (see the board-game touch
+            // lesson: an uncaught throw from setPointerCapture stranded a finger
+            // as permanently "down"). The drag still works via normal bubbling;
+            // capture is an enhancement (keeps it live if the cursor leaves the
+            // canvas mid-drag), not a requirement.
+        }
     };
     const onPointerMove = (e) => {
         if (Math.abs(e.clientX - downX) > 4 || Math.abs(e.clientY - downY) > 4)
             moved = true;
+        if (!dragEntity || !dragPlane || !dragGrabOffset || !scene)
+            return;
+        raycaster.setFromCamera(ndcFromEvent(e), camera);
+        const planePoint = new THREE.Vector3();
+        if (!raycaster.ray.intersectPlane(dragPlane, planePoint))
+            return; // looking parallel to the plane
+        const newWorldPos = planePoint.sub(dragGrabOffset);
+        if (dragEntity.parent)
+            dragEntity.parent.worldToLocal(newWorldPos);
+        dragEntity.position.copy(newWorldPos);
+        selectionBox.setFromObject(dragEntity);
     };
     const onPointerUp = (e) => {
+        try {
+            renderer.domElement.releasePointerCapture(e.pointerId);
+        }
+        catch {
+            // Already released, or never captured (e.g. this gesture never hit an
+            // entity) — nothing to do either way.
+        }
+        // A drag only really happened if the pointer actually moved — grabbing
+        // an entity and releasing without moving is a CLICK on it (case below),
+        // not a same-position no-op save.
+        if (moved && dragEntity && dragEntityId) {
+            window.parent.postMessage({
+                type: 'umicat:editor:dragEnd3d',
+                sceneId: opts.sceneId,
+                entityId: dragEntityId,
+                position: { x: dragEntity.position.x, y: dragEntity.position.y, z: dragEntity.position.z },
+            }, '*');
+        }
+        dragEntity = null;
+        dragEntityId = null;
+        dragPlane = null;
+        dragGrabOffset = null;
+        controls.enabled = true;
         if (moved || !scene)
             return;
-        const rect = renderer.domElement.getBoundingClientRect();
-        const mouse = new THREE.Vector2(((e.clientX - rect.left) / rect.width) * 2 - 1, -((e.clientY - rect.top) / rect.height) * 2 + 1);
-        const raycaster = new THREE.Raycaster();
-        raycaster.setFromCamera(mouse, camera);
-        // Only cast against VISIBLE entity roots. three.js's Mesh.raycast does
-        // NOT check `.visible` on its own (confirmed against the pinned three
-        // source — no such check in Raycaster.js or Object3D.raycast), and a
-        // real scene can ship an invisible collision box alongside separately-
-        // placed visible ground models — without this filter, a click that
-        // visibly lands on the rendered ground can silently return the
-        // collider's coordinates instead.
-        const targets = Array.from(entityByObject.keys()).filter((o) => o.visible !== false);
-        const hits = raycaster.intersectObjects(targets, true);
-        if (hits.length === 0)
+        // A plain click (no drag) — the existing read-a-coordinate behavior.
+        const hit = pickEntityAt(e);
+        if (!hit)
             return;
-        const hit = hits[0];
-        let node = hit.object;
-        let entityId = null;
-        let entityRoot = null;
-        while (node) {
-            const id = entityByObject.get(node);
-            if (id) {
-                entityId = id;
-                entityRoot = node;
-                break;
-            }
-            node = node.parent;
-        }
         marker.position.copy(hit.point);
         marker.visible = true;
         // Frame the whole entity the click landed on, not just the point on its
         // surface — `setFromObject` walks the root's full subtree, so a
         // multi-mesh entity (a model with separate parts) gets one box around
         // all of it, matching what "entityId" actually refers to.
-        if (entityRoot) {
-            selectionBox.setFromObject(entityRoot);
-            selectionBox.visible = true;
-        }
-        else {
-            selectionBox.visible = false;
-        }
-        window.parent.postMessage({ type: 'umicat:editor:pickPoint3d', x: hit.point.x, y: hit.point.y, z: hit.point.z, entityId }, '*');
+        selectionBox.setFromObject(hit.entityRoot);
+        selectionBox.visible = true;
+        window.parent.postMessage({ type: 'umicat:editor:pickPoint3d', x: hit.point.x, y: hit.point.y, z: hit.point.z, entityId: hit.entityId }, '*');
     };
     renderer.domElement.addEventListener('pointerdown', onPointerDown);
     renderer.domElement.addEventListener('pointermove', onPointerMove);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umicat/three-sdk",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "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.",
   "type": "module",
   "main": "dist/index.js",