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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
fix(debug): the debug channel holds up on a slow host with a noisy console
esengineb6b95aeba7e4
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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/desktopindex 0a456f4ae..447f7048c 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 0a456f4ae1e50e397559be04ee966cbacb709343+Subproject commit 447f7048c4fdf1c655fd6d01c7f6f33529d4782ddiff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.tsindex 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.tsindex 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.mjsindex 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.mjsindex 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))`);