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): a device in the background refuses a capture at once

esengine5489dd364cf6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 87b6cfb1a..7b5d0fce6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,7 @@ published separately; it ships inside the editor.
### Fixed
+- Capturing a development build whose tab is in the background says so at once, instead of waiting 30 seconds for a frame the browser will not draw.
- A web game opened in a background tab starts paused and reports itself hidden until it is shown; before, it counted as visible.
- The hot-update demo no longer says the remote manifest matches when it could not reach one; offline it says it keeps the local content.
- On vivo's quick game the loading notice comes down once the game starts; it could stay over the running game.
diff --git a/sdk/src/runtime/debugChannel.ts b/sdk/src/runtime/debugChannel.ts
index 77585c692..9d63898c7 100644
--- a/sdk/src/runtime/debugChannel.ts
+++ b/sdk/src/runtime/debugChannel.ts
@@ -17,6 +17,7 @@ import type { NextFrame } from '../render/frameCapture';
import { captureFrameReport, replayFrameDraw, type FrameReplayImage } from '../render/frameDebugReport';
import { log } from '../util/logger';
import { Assets } from '../asset/AssetPlugin';
+import { Lifecycle } from '../ecs/lifecycle';
import { frameStatsReport } from './frameStats';
import { worldSnapshot } from './worldSnapshot';
import { forwardConsole, type ConsoleLevel } from './consoleForward';
@@ -162,6 +163,11 @@ export function startDebugChannel(config: DebugChannelConfig): void {
}
const game = app!;
const frame = nextFrame!;
+ // A background tab gets no frames, so it would sit on this until the editor gave up.
+ const drawsFrames = !game.hasResource(Lifecycle) || game.getResource(Lifecycle).visible;
+ if ((q.kind === 'frameCapture' || q.kind === 'frameReplay') && !drawsFrames) {
+ throw new Error('the game is in the background, where it draws no frames: bring it to the front');
+ }
if (q.kind === 'frameCapture') {
reply({ t: 'reply', reqId: q.reqId, data: await captureFrameReport(game, frame) });
return;
diff --git a/sdk/tests/debug-channel.test.ts b/sdk/tests/debug-channel.test.ts
index 0345735a8..37faff56b 100644
--- a/sdk/tests/debug-channel.test.ts
+++ b/sdk/tests/debug-channel.test.ts
@@ -5,7 +5,7 @@
* printed meanwhile reaches the editor, and a question asked meanwhile is
* answered once the game starts rather than refused.
*/
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, vi } from 'vitest';
import { setPlatform } from '../src/platform/base';
import type { PlatformAdapter, PlatformSocket, PlatformSocketEvents } from '../src/platform/types';
import { startDebugChannel, attachDebugChannel, fitWithin } from '../src/runtime/debugChannel';
@@ -62,6 +62,28 @@ describe('the debug channel', () => {
});
});
+describe('a device in the background', () => {
+ it('refuses a capture at once instead of waiting for a frame it will not draw', async () => {
+ // The channel is one per process; this device needs its own.
+ vi.resetModules();
+ const base = await import('../src/platform/base');
+ const channel = await import('../src/runtime/debugChannel');
+ const { Lifecycle } = await import('../src/ecs/lifecycle');
+ const s = fakeSocket();
+ base.setPlatform({ name: 'web', now: () => performance.now(), createSocket: () => s.socket } as unknown as PlatformAdapter);
+ channel.startDebugChannel({ url: 'ws://editor:1/?token=t', project: 'Demo' });
+ s.open();
+ channel.attachDebugChannel({
+ hasResource: (r: unknown) => r === Lifecycle,
+ getResource: () => ({ visible: false }),
+ onFrameEnd: () => () => {},
+ } as unknown as App);
+ s.receive({ t: 'query', reqId: 9, kind: 'frameCapture' });
+ await flush();
+ expect(s.sent.find((m) => (m as { reqId?: number }).reqId === 9)).toMatchObject({ error: expect.stringMatching(/background/) });
+ });
+});
+
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) => {
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index a7351a5b2..709a882c6 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -1098,4 +1098,6 @@ export const NOTED = {
{ note: 'The hot-update demo no longer says the remote manifest matches when it could not reach one; offline it says it keeps the local content.' },
'fix(lifecycle): a page opened in a background tab knows it is in the background':
{ note: 'A web game opened in a background tab starts paused and reports itself hidden until it is shown; before, it counted as visible.' },
+ 'fix(debug): a device in the background refuses a capture at once':
+ { note: 'Capturing a development build whose tab is in the background says so at once, instead of waiting 30 seconds for a frame the browser will not draw.' },
};