Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(debug): the debug channel holds up on a slow host with a noisy console

esengineb6b95aeba7e4
diff --git a/CHANGELOG.md b/CHANGELOG.md
index efc8634c9..3a06d28e0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,8 @@ published separately; it ships inside the editor.
### Fixed
+- Games on vivo's quick game run past their first frame: the frame loop now hands requestAnimationFrame a handler the runtime accepts.
+- The debug channel works on vivo's quick game: logs arrive in batches, and a replay is sent at the size the Frame Debugger shows instead of the whole screen.
- A native build loads a remote group's textures from the CDN — they never loaded before — and after a hot update, from its disk cache when offline.
- A WeChat development build connects to the editor from WeChat DevTools (the domain check is turned off for that build only), and frame replays come back from a mini-game.
- Hot update works on mini-games: the update is fetched from the CDN, verified, applied and cached, and after a restart without a network the game starts on it with its updated art.
diff --git a/desktop b/desktop
index 0a456f4ae..447f7048c 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 0a456f4ae1e50e397559be04ee966cbacb709343
+Subproject commit 447f7048c4fdf1c655fd6d01c7f6f33529d4782d
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 67936d68f..31f2246bc 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -2726,15 +2726,15 @@ url: string
## DebugChannelMessage — type @experimental
```
| { t: 'hello'; v: number; platform: string; title: string; project: string | null; revision: string | null }
- | { t: 'reply'; reqId: number; data: unknown; pixels?: boolean }
+ | { t: 'reply'; reqId: number; data: unknown; pixels?: number }
| { t: 'reply'; reqId: number; error: string }
- | { t: 'log'; level: ConsoleLevel; line: string }
+ | { t: 'logs'; entries: Array<{ level: ConsoleLevel; line: string }> }
```
## DebugChannelQuery — type @experimental
```
| { t: 'query'; reqId: number; kind: 'frameCapture' }
- | { t: 'query'; reqId: number; kind: 'frameReplay'; drawIndex: number }
+ | { t: 'query'; reqId: number; kind: 'frameReplay'; drawIndex: number; maxSide?: number }
| { t: 'query'; reqId: number; kind: 'stats' }
| { t: 'query'; reqId: number; kind: 'snapshot'; selectedId: number | null; withTree: boolean }
| ({ t: 'query'; reqId: number; kind: 'control' } & DebugControl)
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 8a107952c..6bc3ea798 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -2734,15 +2734,15 @@ url: string
## DebugChannelMessage — type @experimental
```
| { t: 'hello'; v: number; platform: string; title: string; project: string | null; revision: string | null }
- | { t: 'reply'; reqId: number; data: unknown; pixels?: boolean }
+ | { t: 'reply'; reqId: number; data: unknown; pixels?: number }
| { t: 'reply'; reqId: number; error: string }
- | { t: 'log'; level: ConsoleLevel; line: string }
+ | { t: 'logs'; entries: Array<{ level: ConsoleLevel; line: string }> }
```
## DebugChannelQuery — type @experimental
```
| { t: 'query'; reqId: number; kind: 'frameCapture' }
- | { t: 'query'; reqId: number; kind: 'frameReplay'; drawIndex: number }
+ | { t: 'query'; reqId: number; kind: 'frameReplay'; drawIndex: number; maxSide?: number }
| { t: 'query'; reqId: number; kind: 'stats' }
| { t: 'query'; reqId: number; kind: 'snapshot'; selectedId: number | null; withTree: boolean }
| ({ t: 'query'; reqId: number; kind: 'control' } & DebugControl)
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 525c17c06..7e02bafe1 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -2721,15 +2721,15 @@ url: string
## DebugChannelMessage — type @experimental
```
| { t: 'hello'; v: number; platform: string; title: string; project: string | null; revision: string | null }
- | { t: 'reply'; reqId: number; data: unknown; pixels?: boolean }
+ | { t: 'reply'; reqId: number; data: unknown; pixels?: number }
| { t: 'reply'; reqId: number; error: string }
- | { t: 'log'; level: ConsoleLevel; line: string }
+ | { t: 'logs'; entries: Array<{ level: ConsoleLevel; line: string }> }
```
## DebugChannelQuery — type @experimental
```
| { t: 'query'; reqId: number; kind: 'frameCapture' }
- | { t: 'query'; reqId: number; kind: 'frameReplay'; drawIndex: number }
+ | { t: 'query'; reqId: number; kind: 'frameReplay'; drawIndex: number; maxSide?: number }
| { t: 'query'; reqId: number; kind: 'stats' }
| { t: 'query'; reqId: number; kind: 'snapshot'; selectedId: number | null; withTree: boolean }
| ({ t: 'query'; reqId: number; kind: 'control' } & DebugControl)
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 1cc0527d2..d0d562b74 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -2721,15 +2721,15 @@ url: string
## DebugChannelMessage — type @experimental
```
| { t: 'hello'; v: number; platform: string; title: string; project: string | null; revision: string | null }
- | { t: 'reply'; reqId: number; data: unknown; pixels?: boolean }
+ | { t: 'reply'; reqId: number; data: unknown; pixels?: number }
| { t: 'reply'; reqId: number; error: string }
- | { t: 'log'; level: ConsoleLevel; line: string }
+ | { t: 'logs'; entries: Array<{ level: ConsoleLevel; line: string }> }
```
## DebugChannelQuery — type @experimental
```
| { t: 'query'; reqId: number; kind: 'frameCapture' }
- | { t: 'query'; reqId: number; kind: 'frameReplay'; drawIndex: number }
+ | { t: 'query'; reqId: number; kind: 'frameReplay'; drawIndex: number; maxSide?: number }
| { t: 'query'; reqId: number; kind: 'stats' }
| { t: 'query'; reqId: number; kind: 'snapshot'; selectedId: number | null; withTree: boolean }
| ({ t: 'query'; reqId: number; kind: 'control' } & DebugControl)
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index f42e78257..6b02cd75f 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -2721,15 +2721,15 @@ url: string
## DebugChannelMessage — type @experimental
```
| { t: 'hello'; v: number; platform: string; title: string; project: string | null; revision: string | null }
- | { t: 'reply'; reqId: number; data: unknown; pixels?: boolean }
+ | { t: 'reply'; reqId: number; data: unknown; pixels?: number }
| { t: 'reply'; reqId: number; error: string }
- | { t: 'log'; level: ConsoleLevel; line: string }
+ | { t: 'logs'; entries: Array<{ level: ConsoleLevel; line: string }> }
```
## DebugChannelQuery — type @experimental
```
| { t: 'query'; reqId: number; kind: 'frameCapture' }
- | { t: 'query'; reqId: number; kind: 'frameReplay'; drawIndex: number }
+ | { t: 'query'; reqId: number; kind: 'frameReplay'; drawIndex: number; maxSide?: number }
| { t: 'query'; reqId: number; kind: 'stats' }
| { t: 'query'; reqId: number; kind: 'snapshot'; selectedId: number | null; withTree: boolean }
| ({ t: 'query'; reqId: number; kind: 'control' } & DebugControl)
diff --git a/sdk/src/runtime/debugChannel.ts b/sdk/src/runtime/debugChannel.ts
index 5dc852056..77585c692 100644
--- a/sdk/src/runtime/debugChannel.ts
+++ b/sdk/src/runtime/debugChannel.ts
@@ -14,7 +14,7 @@ import type { App } from '../app/app';
import { getPlatform, platformNow } from '../platform/base';
import type { PlatformSocket } from '../platform/types';
import type { NextFrame } from '../render/frameCapture';
-import { captureFrameReport, replayFrameDraw } from '../render/frameDebugReport';
+import { captureFrameReport, replayFrameDraw, type FrameReplayImage } from '../render/frameDebugReport';
import { log } from '../util/logger';
import { Assets } from '../asset/AssetPlugin';
import { frameStatsReport } from './frameStats';
@@ -43,26 +43,45 @@ export interface DebugControl {
export type DebugChannelQuery =
| { t: 'query'; reqId: number; kind: 'frameCapture' }
- | { t: 'query'; reqId: number; kind: 'frameReplay'; drawIndex: number }
+ | { t: 'query'; reqId: number; kind: 'frameReplay'; drawIndex: number; maxSide?: number }
| { t: 'query'; reqId: number; kind: 'stats' }
| { t: 'query'; reqId: number; kind: 'snapshot'; selectedId: number | null; withTree: boolean }
| ({ t: 'query'; reqId: number; kind: 'control' } & DebugControl);
/**
- * What a device sends. A replay's pixels follow their `reply` as the very next
- * frame, binary, rather than inside it: a 1080p pass is 8MB of RGBA, and text
- * would add a third to every byte of it.
+ * What a device sends. A replay's pixels follow their `reply` as binary frames,
+ * `pixels` of them: text would add a third to every byte, and a mini-game host's
+ * socket drops a frame the size of a whole screen. Lines go in batches, since a
+ * host that traces its own every call prints thousands a second.
*/
export type DebugChannelMessage =
| { t: 'hello'; v: number; platform: string; title: string; project: string | null; revision: string | null }
- | { t: 'reply'; reqId: number; data: unknown; pixels?: boolean }
+ | { t: 'reply'; reqId: number; data: unknown; pixels?: number }
| { t: 'reply'; reqId: number; error: string }
- | { t: 'log'; level: ConsoleLevel; line: string };
+ | { t: 'logs'; entries: Array<{ level: ConsoleLevel; line: string }> };
const RECONNECT_MS = 3000;
const START_WAIT_MS = 20_000;
-/** Lines kept while no editor listens; the oldest go first, and how many is said. */
-const LOG_BACKLOG = 200;
+/** Lines held for the editor; past this the oldest go first, and how many is said. */
+const LOG_BACKLOG = 500;
+const LOG_FLUSH_MS = 100;
+const PIXEL_CHUNK = 256 * 1024;
+
+/** @p image scaled (nearest) so its longer side is at most @p maxSide; the full
+ * size rides along so a reader can say what it is looking at. */
+export function fitWithin(image: FrameReplayImage, maxSide?: number): FrameReplayImage & { fullWidth: number; fullHeight: number } {
+ const { width: w, height: h } = image;
+ const scale = maxSide && maxSide > 0 ? Math.min(1, maxSide / Math.max(w, h)) : 1;
+ if (scale === 1) return { ...image, fullWidth: w, fullHeight: h };
+ const sw = Math.max(1, Math.round(w * scale)), sh = Math.max(1, Math.round(h * scale));
+ const src = new Uint32Array(image.pixels.buffer, image.pixels.byteOffset, w * h);
+ const out = new Uint32Array(sw * sh);
+ for (let y = 0; y < sh; y++) {
+ const row = Math.min(h - 1, Math.floor(y / scale)) * w;
+ for (let x = 0; x < sw; x++) out[y * sw + x] = src[row + Math.min(w - 1, Math.floor(x / scale))];
+ }
+ return { ...image, width: sw, height: sh, pixels: new Uint8ClampedArray(out.buffer), fullWidth: w, fullHeight: h };
+}
/** Resolves once @p app has finished a frame and the task that drew it has run. */
function appFrame(app: App): NextFrame {
@@ -108,23 +127,23 @@ export function startDebugChannel(config: DebugChannelConfig): void {
const backlog: Array<{ level: ConsoleLevel; line: string }> = [];
let dropped = 0;
+ let flushTimer: ReturnType<typeof setTimeout> | null = null;
const send = (m: DebugChannelMessage): void => {
if (socket?.readyState === 'open') socket.send(JSON.stringify(m));
};
+ const flushBacklog = (): void => {
+ flushTimer = null;
+ if (socket?.readyState !== 'open' || (backlog.length === 0 && dropped === 0)) return;
+ const entries = backlog.splice(0, backlog.length);
+ if (dropped > 0) entries.unshift({ level: 'warn', line: `[debug] ${dropped} line(s) are not shown: more were printed than the channel holds` });
+ dropped = 0;
+ send({ t: 'logs', entries });
+ };
forwardConsole((level, line) => timed(() => {
- if (socket?.readyState === 'open') {
- send({ t: 'log', level, line });
- return;
- }
if (backlog.length >= LOG_BACKLOG) { backlog.shift(); dropped++; }
backlog.push({ level, line });
+ if (flushTimer === null && socket?.readyState === 'open') flushTimer = setTimeout(flushBacklog, LOG_FLUSH_MS);
}));
- const flushBacklog = (): void => {
- if (dropped > 0) send({ t: 'log', level: 'warn', line: `[debug] ${dropped} earlier line(s) are not shown: the editor was not listening yet` });
- for (const e of backlog) send({ t: 'log', ...e });
- backlog.length = 0;
- dropped = 0;
- };
const hello = (): void => {
const assets = app?.hasResource(Assets) ? app.getResource(Assets) : null;
send({
@@ -173,16 +192,21 @@ export function startDebugChannel(config: DebugChannelConfig): void {
reply({ t: 'reply', reqId: q.reqId, data: { paused: game.isPaused(), fps: Math.round(game.getTargetFrameRate()) } });
return;
}
- const image = await replayFrameDraw(game, q.drawIndex, frame);
- if (!image) {
+ const full = await replayFrameDraw(game, q.drawIndex, frame);
+ if (!full) {
reply({ t: 'reply', reqId: q.reqId, data: null });
return;
}
+ // A mini-game's socket moved a full-screen replay at ~180KB/s (55 s);
+ // the editor asks for what it will show.
+ const image = timed(() => fitWithin(full, q.maxSide));
const { pixels, ...rest } = image;
- reply({ t: 'reply', reqId: q.reqId, data: rest, pixels: true });
- socket?.send(pixels.buffer.byteLength === pixels.byteLength
- ? pixels.buffer as ArrayBuffer
- : pixels.slice().buffer as ArrayBuffer);
+ const chunks = Math.max(1, Math.ceil(pixels.byteLength / PIXEL_CHUNK));
+ reply({ t: 'reply', reqId: q.reqId, data: rest, pixels: chunks });
+ for (let i = 0; i < chunks; i++) {
+ const part = pixels.subarray(i * PIXEL_CHUNK, Math.min(pixels.byteLength, (i + 1) * PIXEL_CHUNK));
+ socket?.send(part.slice().buffer as ArrayBuffer);
+ }
} catch (e) {
reply({ t: 'reply', reqId: q.reqId, error: e instanceof Error ? e.message : String(e) });
}
@@ -216,6 +240,7 @@ export function startDebugChannel(config: DebugChannelConfig): void {
app = game;
nextFrame = appFrame(game);
hello();
+ flushBacklog();
started();
},
};
diff --git a/sdk/tests/debug-channel.test.ts b/sdk/tests/debug-channel.test.ts
index 37fca5fbb..0345735a8 100644
--- a/sdk/tests/debug-channel.test.ts
+++ b/sdk/tests/debug-channel.test.ts
@@ -8,7 +8,7 @@
import { describe, it, expect } from 'vitest';
import { setPlatform } from '../src/platform/base';
import type { PlatformAdapter, PlatformSocket, PlatformSocketEvents } from '../src/platform/types';
-import { startDebugChannel, attachDebugChannel } from '../src/runtime/debugChannel';
+import { startDebugChannel, attachDebugChannel, fitWithin } from '../src/runtime/debugChannel';
import type { App } from '../src/app/app';
function fakeSocket() {
@@ -38,7 +38,8 @@ describe('the debug channel', () => {
console.log('booting the engine');
s.open();
- const logged = s.sent.filter((m) => (m as { t: string }).t === 'log').map((m) => (m as { line: string }).line);
+ const logged = s.sent.filter((m) => (m as { t: string }).t === 'logs')
+ .flatMap((m) => (m as { entries: Array<{ line: string }> }).entries.map((e) => e.line));
expect(logged).toContain('booting the engine');
expect(s.sent[0]).toMatchObject({ t: 'hello', project: 'Demo', revision: null });
@@ -60,3 +61,28 @@ describe('the debug channel', () => {
expect(s.sent.find((m) => (m as { reqId?: number }).reqId === 7)).toEqual({ t: 'reply', reqId: 7, data: { paused: true, fps: 0 } });
});
});
+
+describe('a replay sent from a device', () => {
+ // A mini-game socket moved a 2340x1080 replay in 55 s; the editor asks for what it shows.
+ const image = (w: number, h: number) => {
+ const pixels = new Uint8ClampedArray(w * h * 4);
+ for (let i = 0; i < w * h; i++) pixels.set([i % 256, (i >> 8) % 256, 7, 255], i * 4);
+ return { width: w, height: h, pixels, matchesCapture: true };
+ };
+
+ it('is scaled so its longer side fits, and says how big the whole one is', () => {
+ const out = fitWithin(image(2340, 1080), 800);
+ expect([out.width, out.height, out.fullWidth, out.fullHeight]).toEqual([800, 369, 2340, 1080]);
+ expect(out.pixels.byteLength).toBe(800 * 369 * 4);
+ // Nearest sampling: output column x reads source column floor(x / scale).
+ const col = Math.floor(799 / (800 / 2340));
+ const src = Array.from(image(2340, 1080).pixels.subarray(col * 4, (col + 1) * 4));
+ expect(Array.from(out.pixels.subarray((800 - 1) * 4, 800 * 4))).toEqual(src);
+ });
+
+ it('is sent as it is when it already fits, or when no limit is asked', () => {
+ const small = image(640, 360);
+ expect(fitWithin(small, 800).pixels).toBe(small.pixels);
+ expect(fitWithin(image(2340, 1080)).width).toBe(2340);
+ });
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 3b08b04e9..a0b698e69 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -1082,4 +1082,10 @@ export const NOTED = {
{ note: 'Hot update works on mini-games: the update is fetched from the CDN, verified, applied and cached, and after a restart without a network the game starts on it with its updated art.' },
'fix(native): a CDN texture loads on a native build, and from the cache when offline':
{ note: 'A native build loads a remote group\'s textures from the CDN — they never loaded before — and after a hot update, from its disk cache when offline.' },
+ 'fix(app): the frame loop runs on vivo\'s quick game, not just its first frame':
+ { note: 'Games on vivo\'s quick game run past their first frame: the frame loop now hands requestAnimationFrame a handler the runtime accepts.' },
+ 'fix(debug): the debug channel holds up on a slow host with a noisy console':
+ { note: 'The debug channel works on vivo\'s quick game: logs arrive in batches, and a replay is sent at the size the Frame Debugger shows instead of the whole screen.' },
+ 'fix(frame-debugger): a device\'s replay is asked for at the size the panel shows':
+ { note: 'The debug channel works on vivo\'s quick game: logs arrive in batches, and a replay is sent at the size the Frame Debugger shows instead of the whole screen.' },
};
diff --git a/tools/verify-remote-capture.mjs b/tools/verify-remote-capture.mjs
index 4244c2635..fd98595b2 100644
--- a/tools/verify-remote-capture.mjs
+++ b/tools/verify-remote-capture.mjs
@@ -122,6 +122,10 @@ try {
const now = server.targets().find((t) => t.id === target.id);
check(now?.project === 'Input Actions' && typeof now?.revision === 'string',
`the build said which project and content it is (${now?.project}, ${now?.revision})`);
+ // Lines travel in batches, behind whatever answer is on the socket.
+ for (const until = Date.now() + 5000; Date.now() < until && !lines.some((l) => /EstellaContext initialized/.test(l.line));) {
+ await new Promise((r) => setTimeout(r, 100));
+ }
check(lines.some((l) => /EstellaContext initialized/.test(l.line)),
`what the device printed before it connected reached the editor (${lines.length} line(s))`);