@umicat/three-sdk 0.16.1 → 0.17.0

package/dist/editor/EditorDesignPlayer3D.d.ts

@@ -0,0 +1,34 @@
+import * as THREE from 'three';
+export interface EditorDesignPlayer3DOptions {
+    /**
+     * Which scene to render — a filename stem under `scenes3d/`, e.g. `"main"`
+     * for `scenes3d/main.json`. Fetched by this exact filename convention,
+     * NEVER via `manifest.scenes` — that array is scaffold data the template
+     * ships with one entry and real games never keep in sync (confirmed
+     * against a real, shipped game: its `manifest.scenes` still points at a
+     * `main.json` that does not exist, while the game's own boot code fetches
+     * `scenes3d/${level.id}.json` directly). Omit to leave the view idle — the
+     * host hasn't chosen a scene yet.
+     */
+    sceneId?: string;
+}
+/**
+ * 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.
+ *
+ * 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
+ * template's own `start()` never tears down either. The caller's own game
+ * boot must never run alongside this: `main.ts`'s `?umicatEdit=1` branch
+ * calls this and returns immediately, skipping `RAPIER.init()` and every
+ * other real-game step. `designMode: true` (passed straight through to
+ * `loadScene3D`) already skips physics and animation playback on its own, so
+ * this needs no Rapier import at all — the design view boots faster than the
+ * real game.
+ */
+export declare function runEditorDesignPlayer3D(renderer: THREE.WebGLRenderer, opts?: EditorDesignPlayer3DOptions): Promise<void>;

package/dist/editor/EditorDesignPlayer3D.js

@@ -0,0 +1,128 @@
+import * as THREE from 'three';
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+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.
+ *
+ * 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
+ * template's own `start()` never tears down either. The caller's own game
+ * boot must never run alongside this: `main.ts`'s `?umicatEdit=1` branch
+ * calls this and returns immediately, skipping `RAPIER.init()` and every
+ * other real-game step. `designMode: true` (passed straight through to
+ * `loadScene3D`) already skips physics and animation playback on its own, so
+ * this needs no Rapier import at all — the design view boots faster than the
+ * real game.
+ */
+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.
+    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;
+    let scene = null;
+    const entityByObject = new Map();
+    const resize = () => {
+        renderer.setSize(window.innerWidth, window.innerHeight);
+        camera.aspect = window.innerWidth / window.innerHeight;
+        camera.updateProjectionMatrix();
+    };
+    resize();
+    window.addEventListener('resize', resize);
+    // Orbit-vs-click: a real drag moves the pointer more than a few px.
+    let downX = 0;
+    let downY = 0;
+    let moved = false;
+    const onPointerDown = (e) => {
+        downX = e.clientX;
+        downY = e.clientY;
+        moved = false;
+    };
+    const onPointerMove = (e) => {
+        if (Math.abs(e.clientX - downX) > 4 || Math.abs(e.clientY - downY) > 4)
+            moved = true;
+    };
+    const onPointerUp = (e) => {
+        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)
+            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 }, '*');
+    };
+    renderer.domElement.addEventListener('pointerdown', onPointerDown);
+    renderer.domElement.addEventListener('pointermove', onPointerMove);
+    renderer.domElement.addEventListener('pointerup', onPointerUp);
+    // Design mode skips physics and animation entirely (loadScene3D's own
+    // designMode flag) — there are no mixers to advance and no Rapier world to
+    // step, so the loop only ever needs to render.
+    renderer.setAnimationLoop(() => {
+        controls.update();
+        if (scene)
+            renderer.render(scene, camera);
+    });
+    const sceneId = opts.sceneId;
+    if (!sceneId)
+        return; // no scene chosen yet — idle, waiting for the host
+    try {
+        const manifest = await fetch('scenes3d/manifest.json').then((r) => r.json());
+        const scene3d = await fetch(`scenes3d/${sceneId}.json`).then((r) => r.json());
+        const loaded = await loadScene3D(scene3d, manifest, { assetBase: '', designMode: true });
+        scene = loaded.scene;
+        entityByObject.clear();
+        for (const [id, obj] of loaded.entities)
+            entityByObject.set(obj, id);
+        marker.visible = false;
+        scene.add(marker);
+        // 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);
+        const size = box.getSize(new THREE.Vector3());
+        const center = box.getCenter(new THREE.Vector3());
+        const radius = Math.max(size.length() * 0.5, 0.5);
+        controls.target.copy(center);
+        camera.position.set(center.x + radius, center.y + radius * 0.8, center.z + radius);
+        camera.near = Math.max(radius / 100, 0.01);
+        camera.far = radius * 20;
+        camera.updateProjectionMatrix();
+        controls.update();
+        window.parent.postMessage({ type: 'umicat:editor:scene3dLoaded', sceneId }, '*');
+    }
+    catch (e) {
+        console.warn('[umicat/editor] 3D design player: could not load scene', sceneId, e);
+        window.parent.postMessage({ type: 'umicat:editor:scene3dLoaded', sceneId, error: true }, '*');
+    }
+}

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export { GameAudio } from './GameAudio.js';
 export type { GameAudioOptions, AudioClipSpec } from './GameAudio.js';
 export { setupScreenshotListener, takeScreenshot } from './capture/ScreenshotManager.js';
 export { setupRecordingListener } from './capture/RecordingManager.js';
+export { runEditorDesignPlayer3D } from './editor/EditorDesignPlayer3D.js';
+export type { EditorDesignPlayer3DOptions } from './editor/EditorDesignPlayer3D.js';
 export type { Attachment } from './Sockets.js';
 export type { LoadedScene3D, LoadSceneOptions } from './SceneLoader3D.js';
 export { ORIENTATION_DIMENSIONS } from '@umicat/platform-sdk/orientation.js';

package/dist/index.js

@@ -14,6 +14,7 @@ export { flashTint, updateTints, isTinted } from './Tint.js';
 export { GameAudio } from './GameAudio.js';
 export { setupScreenshotListener, takeScreenshot } from './capture/ScreenshotManager.js';
 export { setupRecordingListener } from './capture/RecordingManager.js';
+export { runEditorDesignPlayer3D } from './editor/EditorDesignPlayer3D.js';
 // Re-exported so a game imports one package for the common case. A game should
 // not have to know that identity and saves come from a different package than
 // the renderer.

package/package.json

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