@umicat/three-sdk 1.32.0 → 1.33.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.
@@ -2,6 +2,7 @@ import { UmicatCore } from '@umicat/platform-sdk/core/UmicatCore.js';
2
2
  import { DialogueModule } from '@umicat/platform-sdk/dialogue/DialogueModule.js';
3
3
  import { HudBinding3DNamespace } from './hud3d/HudDynamicBinding3D.js';
4
4
  import { setupRecordingListener } from './capture/RecordingManager.js';
5
+ import { setupScreenshotListener } from './capture/ScreenshotManager.js';
5
6
  /** Kept in sync with package.json on each publish. */
6
7
  const SDK_VERSION = '0.0.1';
7
8
  /**
@@ -38,6 +39,11 @@ export class ThreeUmicat extends UmicatCore {
38
39
  // resolves the canvas at record time, not now — there is no renderer yet
39
40
  // at init.
40
41
  setupRecordingListener();
42
+ // Screenshots, for the same reason and with the same shape. The host
43
+ // prefers its own screen capture (which also catches a DOM HUD), and
44
+ // falls back to THIS protocol when capture is unavailable or declined —
45
+ // so a game that never answers leaves that button waiting forever.
46
+ setupScreenshotListener();
41
47
  return game;
42
48
  }
43
49
  }
@@ -1,3 +1,4 @@
1
+ import { resolveCanvas } from './resolveCanvas.js';
1
2
  let mediaRecorder = null;
2
3
  let recordedChunks = [];
3
4
  /** One listener per WINDOW, whoever asks first. `ThreeUmicat.init()` installs
@@ -11,22 +12,6 @@ let recordedChunks = [];
11
12
  * no-op for the life of the process, so a suite that exercises more than one
12
13
  * scenario silently tests nothing after its first case. */
13
14
  const installedOn = new WeakSet();
14
- /** The canvas to record, resolved LAZILY — at record time, not install time.
15
- * That is what lets `ThreeUmicat.init()` install this: init runs at the top
16
- * of a game's boot, long before the renderer (and its canvas) exist. An
17
- * explicit renderer, when given, always wins.
18
- *
19
- * Picks the largest canvas when a game has more than one — a minimap or a
20
- * thumbnail baker is a canvas too, and recording one of those instead of the
21
- * game would be a silent, confusing failure. */
22
- function resolveCanvas(renderer) {
23
- if (renderer?.domElement)
24
- return renderer.domElement;
25
- const all = [...document.querySelectorAll('canvas')];
26
- if (all.length === 0)
27
- return null;
28
- return all.reduce((best, c) => (c.width * c.height > best.width * best.height ? c : best), all[0]);
29
- }
30
15
  /**
31
16
  * Sets up postMessage listeners for video recording of the renderer's
32
17
  * canvas. Same wire protocol as `@umicat/phaser-sdk`'s
@@ -9,6 +9,16 @@ import type * as THREE from 'three';
9
9
  * Parent sends: { type: 'screenshot' }
10
10
  * Game responds: { type: 'screenshot_result', dataUrl: string }
11
11
  *
12
+ * The renderer is OPTIONAL. Without one the canvas is found at capture time,
13
+ * which is what makes a single install from `ThreeUmicat.init()` cover every
14
+ * 3D game — three-sdk has no `createUmicatGame`-style wrapper, so before this
15
+ * the listener had to be wired by each game's own `main.ts` and games older
16
+ * than the template line that does it could not answer a screenshot request
17
+ * at all. That mattered more than it looks: the host falls back to this
18
+ * protocol when screen capture is unavailable or declined, so a game that
19
+ * never answers leaves the host's screenshot button waiting on a reply that
20
+ * is never coming. Calling it twice is a no-op.
21
+ *
12
22
  * Requires the renderer to have been constructed with
13
23
  * `preserveDrawingBuffer: true` — without it, `canvas.toDataURL()` on a
14
24
  * WebGL context can return a blank image depending on exactly when the
@@ -17,6 +27,6 @@ import type * as THREE from 'three';
17
27
  * option), so a game that wants captures to work must pass it when creating
18
28
  * its `THREE.WebGLRenderer`.
19
29
  */
20
- export declare function setupScreenshotListener(renderer: THREE.WebGLRenderer): void;
30
+ export declare function setupScreenshotListener(renderer?: THREE.WebGLRenderer): void;
21
31
  /** Take a screenshot programmatically. Returns a base64 PNG data URL. */
22
- export declare function takeScreenshot(renderer: THREE.WebGLRenderer): string | null;
32
+ export declare function takeScreenshot(renderer?: THREE.WebGLRenderer): string | null;
@@ -1,3 +1,12 @@
1
+ import { resolveCanvas } from './resolveCanvas.js';
2
+ /** One listener per WINDOW — same reasoning as `setupRecordingListener`'s own
3
+ * latch: `ThreeUmicat.init()` installs this for every game, and a game (or
4
+ * the 3D template) may ALSO call it explicitly with its own renderer. Two
5
+ * listeners would answer one `{type:'screenshot'}` twice, and the host
6
+ * downloads whatever arrives. Keyed on the window rather than a module-level
7
+ * flag so a test suite exercising more than one scenario still tests
8
+ * something after its first case. */
9
+ const installedOn = new WeakSet();
1
10
  /**
2
11
  * Sets up a postMessage listener that captures the renderer's canvas when the
3
12
  * parent window requests a screenshot. Same wire protocol as
@@ -8,6 +17,16 @@
8
17
  * Parent sends: { type: 'screenshot' }
9
18
  * Game responds: { type: 'screenshot_result', dataUrl: string }
10
19
  *
20
+ * The renderer is OPTIONAL. Without one the canvas is found at capture time,
21
+ * which is what makes a single install from `ThreeUmicat.init()` cover every
22
+ * 3D game — three-sdk has no `createUmicatGame`-style wrapper, so before this
23
+ * the listener had to be wired by each game's own `main.ts` and games older
24
+ * than the template line that does it could not answer a screenshot request
25
+ * at all. That mattered more than it looks: the host falls back to this
26
+ * protocol when screen capture is unavailable or declined, so a game that
27
+ * never answers leaves the host's screenshot button waiting on a reply that
28
+ * is never coming. Calling it twice is a no-op.
29
+ *
11
30
  * Requires the renderer to have been constructed with
12
31
  * `preserveDrawingBuffer: true` — without it, `canvas.toDataURL()` on a
13
32
  * WebGL context can return a blank image depending on exactly when the
@@ -17,10 +36,16 @@
17
36
  * its `THREE.WebGLRenderer`.
18
37
  */
19
38
  export function setupScreenshotListener(renderer) {
39
+ if (installedOn.has(window))
40
+ return;
41
+ installedOn.add(window);
20
42
  window.addEventListener('message', (event) => {
21
43
  if (event.data?.type === 'screenshot') {
22
44
  try {
23
- const dataUrl = renderer.domElement.toDataURL('image/png');
45
+ const canvas = resolveCanvas(renderer);
46
+ if (!canvas)
47
+ return;
48
+ const dataUrl = canvas.toDataURL('image/png');
24
49
  window.parent.postMessage({ type: 'screenshot_result', dataUrl }, '*');
25
50
  }
26
51
  catch (e) {
@@ -36,7 +61,10 @@ export function setupScreenshotListener(renderer) {
36
61
  // CSS size).
37
62
  try {
38
63
  const r = event.data.rect;
39
- const dataUrl = cropCanvasRegion(renderer.domElement, r);
64
+ const canvas = resolveCanvas(renderer);
65
+ if (!canvas)
66
+ throw new Error('no canvas to capture');
67
+ const dataUrl = cropCanvasRegion(canvas, r);
40
68
  window.parent.postMessage({ type: 'screenshot_region_result', dataUrl, requestId: event.data.requestId }, '*');
41
69
  }
42
70
  catch (e) {
@@ -79,7 +107,7 @@ function cropCanvasRegion(canvas, rect) {
79
107
  /** Take a screenshot programmatically. Returns a base64 PNG data URL. */
80
108
  export function takeScreenshot(renderer) {
81
109
  try {
82
- return renderer.domElement.toDataURL('image/png');
110
+ return resolveCanvas(renderer)?.toDataURL('image/png') ?? null;
83
111
  }
84
112
  catch (e) {
85
113
  console.error('[UmicatSDK] Screenshot failed:', e);
@@ -0,0 +1,11 @@
1
+ import type * as THREE from 'three';
2
+ /** The canvas to capture, resolved LAZILY — at capture time, not install time.
3
+ *
4
+ * That is what lets `ThreeUmicat.init()` install the capture listeners: init
5
+ * runs at the top of a game's boot, long before the renderer (and its canvas)
6
+ * exist. An explicit renderer, when given, always wins.
7
+ *
8
+ * Picks the largest canvas when a game has more than one — a minimap or a
9
+ * thumbnail baker is a canvas too, and capturing one of those instead of the
10
+ * game would be a silent, confusing failure. */
11
+ export declare function resolveCanvas(renderer?: THREE.WebGLRenderer): HTMLCanvasElement | null;
@@ -0,0 +1,17 @@
1
+ /** The canvas to capture, resolved LAZILY — at capture time, not install time.
2
+ *
3
+ * That is what lets `ThreeUmicat.init()` install the capture listeners: init
4
+ * runs at the top of a game's boot, long before the renderer (and its canvas)
5
+ * exist. An explicit renderer, when given, always wins.
6
+ *
7
+ * Picks the largest canvas when a game has more than one — a minimap or a
8
+ * thumbnail baker is a canvas too, and capturing one of those instead of the
9
+ * game would be a silent, confusing failure. */
10
+ export function resolveCanvas(renderer) {
11
+ if (renderer?.domElement)
12
+ return renderer.domElement;
13
+ const all = [...document.querySelectorAll('canvas')];
14
+ if (all.length === 0)
15
+ return null;
16
+ return all.reduce((best, c) => (c.width * c.height > best.width * best.height ? c : best), all[0]);
17
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.32.0",
3
+ "version": "1.33.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",