@umicat/three-sdk 0.17.1 → 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
@@ -25,10 +35,39 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
     const camera = new THREE.PerspectiveCamera(50, window.innerWidth / window.innerHeight, 0.05, 2000);
     const controls = new OrbitControls(camera, renderer.domElement);
     controls.enableDamping = true;
-    // A single persistent marker, repositioned per click.
+    // A single persistent marker, repositioned per click — the exact world
+    // point clicked (what "put a torch at the spot I clicked" needs), distinct
+    // from the box below (which entity was hit, not just where).
     const marker = new THREE.Mesh(new THREE.SphereGeometry(0.12, 16, 12), new THREE.MeshBasicMaterial({ color: '#ff3b6b', depthTest: false }));
     marker.visible = false;
     marker.renderOrder = 999;
+    // Selection box — Unity/Blender-style "frame the object you clicked", not
+    // just a point on its surface. `BoxHelper.setFromObject` (three.js core,
+    // no custom geometry math needed) recomputes a world-space AABB wireframe
+    // from scratch each call, so retargeting it to a different entity per
+    // click is just calling it again — it does not need to track a moving
+    // object (this scene never animates in design mode).
+    const selectionBox = new THREE.BoxHelper(new THREE.Object3D(), 0xffd23f);
+    selectionBox.visible = false;
+    selectionBox.renderOrder = 998;
+    selectionBox.material.depthTest = false;
+    // Orientation gizmo — a small corner compass tracking the main camera's
+    // rotation only (never its position/zoom), same convention every 3D DCC
+    // uses: X=red, Y=green, Z=blue. Rendered as a second, tiny scene into a
+    // scissored corner viewport each frame (see the render loop below) — the
+    // simplest way to get a HUD-anchored 3D readout without a second canvas.
+    const GIZMO_SIZE = 84;
+    const GIZMO_MARGIN = 14;
+    const gizmoScene = new THREE.Scene();
+    const gizmoCamera = new THREE.OrthographicCamera(-1.6, 1.6, 1.6, -1.6, 0.1, 10);
+    const AXES = [
+        [new THREE.Vector3(1, 0, 0), 0xff4d4d], // X — red
+        [new THREE.Vector3(0, 1, 0), 0x4dff88], // Y — green
+        [new THREE.Vector3(0, 0, 1), 0x4d9fff], // Z — blue
+    ];
+    for (const [dir, color] of AXES) {
+        gizmoScene.add(new THREE.ArrowHelper(dir, new THREE.Vector3(0, 0, 0), 1, color, 0.35, 0.22));
+    }
     let scene = null;
     const entityByObject = new Map();
     const resize = () => {
@@ -38,51 +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;
-        while (node) {
-            const id = entityByObject.get(node);
-            if (id) {
-                entityId = id;
-                break;
-            }
-            node = node.parent;
-        }
         marker.position.copy(hit.point);
         marker.visible = true;
-        window.parent.postMessage({ type: 'umicat:editor:pickPoint3d', x: hit.point.x, y: hit.point.y, z: hit.point.z, entityId }, '*');
+        // 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.
+        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);
@@ -92,8 +223,30 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
     // step, so the loop only ever needs to render.
     renderer.setAnimationLoop(() => {
         controls.update();
-        if (scene)
-            renderer.render(scene, camera);
+        if (!scene)
+            return;
+        renderer.setScissorTest(false);
+        renderer.render(scene, camera);
+        // Second pass: the orientation gizmo, into a small scissored corner
+        // viewport. Its camera copies the MAIN camera's rotation only (not
+        // position/zoom) so it reads as "which way am I looking", exactly what
+        // orbiting the main view is meant to answer. three.js viewport Y is
+        // bottom-up, so "top-right on screen" is `height - size - margin`.
+        const w = renderer.domElement.clientWidth;
+        const h = renderer.domElement.clientHeight;
+        gizmoCamera.position.set(0, 0, 4).applyQuaternion(camera.quaternion);
+        gizmoCamera.up.copy(camera.up);
+        gizmoCamera.lookAt(0, 0, 0);
+        const gx = w - GIZMO_SIZE - GIZMO_MARGIN;
+        const gy = h - GIZMO_SIZE - GIZMO_MARGIN;
+        renderer.setScissorTest(true);
+        renderer.setScissor(gx, gy, GIZMO_SIZE, GIZMO_SIZE);
+        renderer.setViewport(gx, gy, GIZMO_SIZE, GIZMO_SIZE);
+        // render()'s own autoClear respects the scissor rect just set, so this
+        // only wipes the corner box, not the scene pass above.
+        renderer.render(gizmoScene, gizmoCamera);
+        renderer.setScissorTest(false);
+        renderer.setViewport(0, 0, w, h);
     });
     const sceneId = opts.sceneId;
     if (!sceneId)
@@ -108,6 +261,8 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
             entityByObject.set(obj, id);
         marker.visible = false;
         scene.add(marker);
+        selectionBox.visible = false;
+        scene.add(selectionBox);
         // Frame the whole scene — auto-fit, since a small template scene and a
         // real level's dozens of entities need wildly different orbit distances.
         const box = new THREE.Box3().setFromObject(scene);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umicat/three-sdk",
-  "version": "0.17.1",
+  "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",