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(lifecycle): a page opened in a background tab knows it is in the background

esengine24435ab25ccf
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4935ad48a..87b6cfb1a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,7 @@ published separately; it ships inside the editor.
### Fixed
+- 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.
- A quick tap on a slow frame still clicks a button: a finger that landed and lifted between two frames was seen only lifting, so the button never saw a press.
diff --git a/sdk/src/ecs/lifecycle.ts b/sdk/src/ecs/lifecycle.ts
index 7462d8139..cb5bfc5b3 100644
--- a/sdk/src/ecs/lifecycle.ts
+++ b/sdk/src/ecs/lifecycle.ts
@@ -167,6 +167,9 @@ function setupWebLifecycle_(manager: LifecycleManager, app: AppLike): () => void
document.addEventListener('visibilitychange', onVisibilityChange);
window.addEventListener('focus', onFocus);
window.addEventListener('blur', onBlur);
+ // No event reports the state a page is born in: one opened in a background tab
+ // would otherwise count as visible until it had been shown and hidden again.
+ if (document.hidden) onVisibilityChange();
return (): void => {
document.removeEventListener('visibilitychange', onVisibilityChange);
diff --git a/sdk/tests/web-lifecycle-hidden-start.test.ts b/sdk/tests/web-lifecycle-hidden-start.test.ts
new file mode 100644
index 000000000..8dcd2ed41
--- /dev/null
+++ b/sdk/tests/web-lifecycle-hidden-start.test.ts
@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file A page that starts in a background tab knows it is in the background:
+ * the browser sends no visibilitychange for the state a page is born in.
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import { App } from '../src/app/app';
+import { Lifecycle, LifecyclePlugin } from '../src/ecs/lifecycle';
+import { setPlatform } from '../src/platform/base';
+import { webAdapter } from '../src/platform/web';
+
+const setHidden = (v: boolean) => Object.defineProperty(document, 'hidden', { configurable: true, get: () => v });
+
+afterEach(() => { delete (document as { hidden?: boolean }).hidden; });
+
+describe('a page started in a background tab', () => {
+ it('is not visible and is paused until it is shown', () => {
+ setPlatform(webAdapter);
+ setHidden(true);
+ const app = App.new();
+ app.addPlugin(new LifecyclePlugin());
+ expect(app.getResource(Lifecycle).visible).toBe(false);
+ expect(app.isPaused()).toBe(true);
+
+ setHidden(false);
+ document.dispatchEvent(new Event('visibilitychange'));
+ expect(app.getResource(Lifecycle).visible).toBe(true);
+ expect(app.isPaused()).toBe(false);
+ });
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 6f3d8723f..a7351a5b2 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -1096,4 +1096,6 @@ export const NOTED = {
{ note: 'On vivo\'s quick game the loading notice comes down once the game starts; it could stay over the running game.' },
'fix(examples): the hot-update demo says when it could not reach the update endpoint':
{ 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.' },
};