@umicat/three-sdk 0.14.0 → 0.16.0

package/README.md

@@ -9,8 +9,9 @@ is what new 3D projects start from.
 
 What it has: the scene3d format and loader, physics wiring, a character
 controller and animator, an input layer that mounts on-screen controls on touch
-devices and binds keys everywhere, bone sockets, hit tints, and audio. What it
-still does not have: an editor.
+devices and binds keys everywhere, bone sockets, hit tints, audio, and the
+editor's screenshot/video-capture protocol. What it still does not have: an
+editor.
 
 > This paragraph said "seed, not a product — no input system, no character
 > controller, no audio, and no published package" for ten minor versions after
@@ -23,7 +24,7 @@ still does not have: an editor.
         │
 @umicat/three-sdk       ThreeUmicat · scene3d · loadScene3D · physics · Input3D
                         CharacterController3D · CharacterAnimator · GameAudio
-                        sockets · tints
+                        sockets · tints · setupScreenshotListener/setupRecordingListener
         ▲
    your game            gameplay
 ```

package/dist/GameAudio.js

@@ -230,6 +230,19 @@ export class GameAudio {
         const ctx = this.ctx;
         if (this.muted)
             return;
+        // The music may still be waiting for a gesture even though the context is
+        // not. `start()` is the only other place that starts it, and it early-exits
+        // when the context is ALREADY running — which is what happens in a
+        // cross-origin iframe, where the context comes up running and the first
+        // `play()` therefore never takes the unlock path. Measured: a game
+        // embedded that way had a live context, decoded buffers, working effects
+        // and no music at all, because `startMusic()` had never been reached.
+        //
+        // `play()` is the right place for the second attempt: it is called from
+        // inside a real gesture (a button, a move), which is exactly the
+        // permission an element needs, and `startMusic` is idempotent.
+        if (this.ready && this.musicName && !this.musicEl)
+            this.startMusic();
         if (!this.ready || !ctx || !this.master) {
             // Not "drop it": this is the unlocking gesture, and the sound it asked
             // for is the one the player is waiting to hear. `start()` plays it.

package/dist/capture/RecordingManager.d.ts

@@ -0,0 +1,19 @@
+import type * as THREE from 'three';
+/**
+ * Sets up postMessage listeners for video recording of the renderer's
+ * canvas. Same wire protocol as `@umicat/phaser-sdk`'s
+ * `recording/RecordingManager.ts` — the host doesn't need to know which
+ * engine is running.
+ *
+ * Parent sends: 'startRecording'
+ * Game responds: { type: 'recordingStarted' }
+ *
+ * Parent sends: 'stopRecording'
+ * Game responds: { type: 'recordingComplete', data: string (base64 data URL), mimeType: string }
+ *
+ * `canvas.captureStream()` samples the compositor's output directly, so
+ * unlike {@link "./ScreenshotManager.js".takeScreenshot}, it works whether
+ * or not the renderer was constructed with `preserveDrawingBuffer` — but the
+ * template sets it anyway, for the screenshot path.
+ */
+export declare function setupRecordingListener(renderer: THREE.WebGLRenderer): void;

package/dist/capture/RecordingManager.js

@@ -0,0 +1,67 @@
+let mediaRecorder = null;
+let recordedChunks = [];
+/**
+ * Sets up postMessage listeners for video recording of the renderer's
+ * canvas. Same wire protocol as `@umicat/phaser-sdk`'s
+ * `recording/RecordingManager.ts` — the host doesn't need to know which
+ * engine is running.
+ *
+ * Parent sends: 'startRecording'
+ * Game responds: { type: 'recordingStarted' }
+ *
+ * Parent sends: 'stopRecording'
+ * Game responds: { type: 'recordingComplete', data: string (base64 data URL), mimeType: string }
+ *
+ * `canvas.captureStream()` samples the compositor's output directly, so
+ * unlike {@link "./ScreenshotManager.js".takeScreenshot}, it works whether
+ * or not the renderer was constructed with `preserveDrawingBuffer` — but the
+ * template sets it anyway, for the screenshot path.
+ */
+export function setupRecordingListener(renderer) {
+    window.addEventListener('message', (event) => {
+        if (event.data === 'startRecording') {
+            try {
+                const canvas = renderer.domElement;
+                if (!canvas)
+                    return;
+                recordedChunks = [];
+                const stream = canvas.captureStream(30);
+                // Pick best available codec.
+                const mimeType = MediaRecorder.isTypeSupported('video/webm;codecs=vp9')
+                    ? 'video/webm;codecs=vp9'
+                    : 'video/webm';
+                mediaRecorder = new MediaRecorder(stream, {
+                    mimeType,
+                    videoBitsPerSecond: 1500000, // 1.5 Mbps
+                });
+                mediaRecorder.ondataavailable = (e) => {
+                    if (e.data.size > 0)
+                        recordedChunks.push(e.data);
+                };
+                mediaRecorder.onstop = () => {
+                    const blob = new Blob(recordedChunks, { type: 'video/webm' });
+                    const reader = new FileReader();
+                    reader.onloadend = () => {
+                        window.parent.postMessage({
+                            type: 'recordingComplete',
+                            data: reader.result,
+                            mimeType: 'video/webm',
+                        }, '*');
+                    };
+                    reader.readAsDataURL(blob);
+                };
+                mediaRecorder.start(1000); // collect data every 1 second
+                window.parent.postMessage({ type: 'recordingStarted' }, '*');
+            }
+            catch (e) {
+                console.error('[UmicatSDK] Recording failed to start:', e);
+                window.parent.postMessage({ type: 'recordingError', error: String(e) }, '*');
+            }
+        }
+        if (event.data === 'stopRecording') {
+            if (mediaRecorder && mediaRecorder.state !== 'inactive') {
+                mediaRecorder.stop();
+            }
+        }
+    });
+}

package/dist/capture/ScreenshotManager.d.ts

@@ -0,0 +1,22 @@
+import type * as THREE from 'three';
+/**
+ * Sets up a postMessage listener that captures the renderer's canvas when the
+ * parent window requests a screenshot. Same wire protocol as
+ * `@umicat/phaser-sdk`'s `screenshot/ScreenshotManager.ts` — the host
+ * (umicat-home-ui) speaks one protocol to both engines and never needs to
+ * know which one is running.
+ *
+ * Parent sends: { type: 'screenshot' }
+ * Game responds: { type: 'screenshot_result', dataUrl: string }
+ *
+ * Requires the renderer to have been constructed with
+ * `preserveDrawingBuffer: true` — without it, `canvas.toDataURL()` on a
+ * WebGL context can return a blank image depending on exactly when the
+ * browser clears the drawing buffer after compositing. This is NOT
+ * something the SDK can fix after the fact (it's a renderer-construction-time
+ * option), so a game that wants captures to work must pass it when creating
+ * its `THREE.WebGLRenderer`.
+ */
+export declare function setupScreenshotListener(renderer: THREE.WebGLRenderer): void;
+/** Take a screenshot programmatically. Returns a base64 PNG data URL. */
+export declare function takeScreenshot(renderer: THREE.WebGLRenderer): string | null;

package/dist/capture/ScreenshotManager.js

@@ -0,0 +1,88 @@
+/**
+ * Sets up a postMessage listener that captures the renderer's canvas when the
+ * parent window requests a screenshot. Same wire protocol as
+ * `@umicat/phaser-sdk`'s `screenshot/ScreenshotManager.ts` — the host
+ * (umicat-home-ui) speaks one protocol to both engines and never needs to
+ * know which one is running.
+ *
+ * Parent sends: { type: 'screenshot' }
+ * Game responds: { type: 'screenshot_result', dataUrl: string }
+ *
+ * Requires the renderer to have been constructed with
+ * `preserveDrawingBuffer: true` — without it, `canvas.toDataURL()` on a
+ * WebGL context can return a blank image depending on exactly when the
+ * browser clears the drawing buffer after compositing. This is NOT
+ * something the SDK can fix after the fact (it's a renderer-construction-time
+ * option), so a game that wants captures to work must pass it when creating
+ * its `THREE.WebGLRenderer`.
+ */
+export function setupScreenshotListener(renderer) {
+    window.addEventListener('message', (event) => {
+        if (event.data?.type === 'screenshot') {
+            try {
+                const dataUrl = renderer.domElement.toDataURL('image/png');
+                window.parent.postMessage({ type: 'screenshot_result', dataUrl }, '*');
+            }
+            catch (e) {
+                console.error('[UmicatSDK] Screenshot failed:', e);
+            }
+        }
+        else if (event.data?.type === 'screenshotRegion') {
+            // Marquee-to-chat: the host drew a selection rect over the iframe (in
+            // iframe-relative CSS px); crop the canvas to it here, where the
+            // canvas's on-screen position + intrinsic resolution are known
+            // (handles devicePixelRatio scaling — a 3D game always runs 'resize'
+            // scale mode, never letterboxed, but pixel ratio still differs from
+            // CSS size).
+            try {
+                const r = event.data.rect;
+                const dataUrl = cropCanvasRegion(renderer.domElement, r);
+                window.parent.postMessage({ type: 'screenshot_region_result', dataUrl, requestId: event.data.requestId }, '*');
+            }
+            catch (e) {
+                console.error('[UmicatSDK] Region screenshot failed:', e);
+                window.parent.postMessage({ type: 'screenshot_region_result', dataUrl: null, requestId: event.data?.requestId }, '*');
+            }
+        }
+    });
+}
+/**
+ * Crop the canvas to a rect given in iframe-relative CSS pixels (the host's
+ * marquee). Maps display px → intrinsic canvas px via the canvas's bounding
+ * rect + resolution, clamps to bounds. Same math as phaser-sdk's
+ * `cropCanvasRegion` — deliberately engine-agnostic, it only looks at the
+ * canvas element.
+ */
+function cropCanvasRegion(canvas, rect) {
+    const cr = canvas.getBoundingClientRect();
+    if (cr.width <= 0 || cr.height <= 0)
+        return null;
+    const scale = canvas.width / cr.width; // intrinsic px per displayed px
+    let sx = Math.round((rect.x - cr.x) * scale);
+    let sy = Math.round((rect.y - cr.y) * scale);
+    let sw = Math.round(rect.width * scale);
+    let sh = Math.round(rect.height * scale);
+    // Clamp to the canvas (the marquee can run past the edges).
+    sx = Math.max(0, Math.min(sx, canvas.width - 1));
+    sy = Math.max(0, Math.min(sy, canvas.height - 1));
+    sw = Math.max(1, Math.min(sw, canvas.width - sx));
+    sh = Math.max(1, Math.min(sh, canvas.height - sy));
+    const out = document.createElement('canvas');
+    out.width = sw;
+    out.height = sh;
+    const ctx = out.getContext('2d');
+    if (!ctx)
+        return null;
+    ctx.drawImage(canvas, sx, sy, sw, sh, 0, 0, sw, sh);
+    return out.toDataURL('image/png');
+}
+/** Take a screenshot programmatically. Returns a base64 PNG data URL. */
+export function takeScreenshot(renderer) {
+    try {
+        return renderer.domElement.toDataURL('image/png');
+    }
+    catch (e) {
+        console.error('[UmicatSDK] Screenshot failed:', e);
+        return null;
+    }
+}

package/dist/index.d.ts

@@ -12,6 +12,8 @@ export { attachToSocket, findBone, boneNames } from './Sockets.js';
 export { flashTint, updateTints, isTinted } from './Tint.js';
 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 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

@@ -12,6 +12,8 @@ export { Input3D } from './Input3D.js';
 export { attachToSocket, findBone, boneNames } from './Sockets.js';
 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';
 // 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/dist/scene3d.d.ts

@@ -176,6 +176,14 @@ export interface Manifest3D {
 /** Identity quaternion, spelled out so callers don't have to remember the order. */
 export declare const IDENTITY_QUAT: Quat;
 export declare function vec3(x?: number, y?: number, z?: number): Vec3;
+/**
+ * Wrap a single model as a `Manifest3D` so `loadModelAsset` can load it
+ * without a caller hand-rolling the boilerplate every time. `scenes`/
+ * `initialScene` are unused by `loadModelAsset` (only `loadScene3D` reads
+ * them) — left empty rather than optional so the type stays exactly
+ * `Manifest3D`, not a new shape callers have to learn.
+ */
+export declare function singleModelManifest(model: ModelAsset3D): Manifest3D;
 /**
  * Validate a scene enough to fail loudly at author time rather than as a blank
  * screen at play time. Returns the problems; empty means usable.

package/dist/scene3d.js

@@ -26,6 +26,16 @@
 /** Identity quaternion, spelled out so callers don't have to remember the order. */
 export const IDENTITY_QUAT = [0, 0, 0, 1];
 export function vec3(x = 0, y = 0, z = 0) { return { x, y, z }; }
+/**
+ * Wrap a single model as a `Manifest3D` so `loadModelAsset` can load it
+ * without a caller hand-rolling the boilerplate every time. `scenes`/
+ * `initialScene` are unused by `loadModelAsset` (only `loadScene3D` reads
+ * them) — left empty rather than optional so the type stays exactly
+ * `Manifest3D`, not a new shape callers have to learn.
+ */
+export function singleModelManifest(model) {
+    return { schemaVersion: 1, initialScene: '', scenes: [], models: [model] };
+}
 /**
  * Validate a scene enough to fail loudly at author time rather than as a blank
  * screen at play time. Returns the problems; empty means usable.

package/package.json

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