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
feat(ui): a HUD can clear the host's own menu, not just the notch
esengineba4467510616
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6f53787ed..53545912c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -21,6 +21,15 @@ published separately; it ships inside the editor.header at 13px read as bold body text rather than as a title. Window titles now have astep of their own, which is what every editor this size gives them.+### Added++- **A UI node can keep clear of WeChat's capsule menu, which the safe area does not cover.**+ `SafeArea.avoidHostMenu` pushes the top inset past the host's own overlay. Measured on the+ iPhone 12 the simulator offers, the capsule's bottom edge is 29px *inside* the safe area —+ so a HUD that respects the safe area still sits under it, which is what the space-shooter+ example's lives counter did. No engine offers this: every game converts the rect to layout+ units by hand, which is the arithmetic the safe area already does here.+### Fixed- **A WeChat mini-game boots again.** Its package had no platform in it: the SDK entrydiff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.jsonindex f9c89dae9..5dc7638a7 100644--- a/docs/astro/src/data/components.generated.json+++ b/docs/astro/src/data/components.generated.json@@ -3652,6 +3652,11 @@"key": "applyRight","type": "boolean","default": "true"+ },+ {+ "key": "avoidHostMenu",+ "type": "boolean",+ "default": "false"}]},diff --git a/sdk/src/ui/layout/safe-area.ts b/sdk/src/ui/layout/safe-area.tsindex 719b5578f..ef60da74c 100644--- a/sdk/src/ui/layout/safe-area.ts+++ b/sdk/src/ui/layout/safe-area.ts@@ -22,6 +22,12 @@ export interface SafeAreaData {applyBottom: boolean;applyLeft: boolean;applyRight: boolean;+ /**+ * Also clear the host's own overlay — WeChat's capsule menu, which sits+ * INSIDE the safe area: measured on an iPhone 12, its bottom is 29px below+ * `safeArea.top`, so a node that respects the safe area is still under it.+ */+ avoidHostMenu: boolean;}export const SafeArea = defineComponent<SafeAreaData>('SafeArea', {@@ -29,6 +35,7 @@ export const SafeArea = defineComponent<SafeAreaData>('SafeArea', {applyBottom: true,applyLeft: true,applyRight: true,+ avoidHostMenu: false,});export interface SafeAreaInsets {@@ -41,10 +48,24 @@ export interface SafeAreaInsets {interface WxGlobal {wx?: {getSystemInfoSync?(): { safeArea: { top: number; bottom: number; left: number; right: number }; screenWidth: number; screenHeight: number } | undefined;+ getMenuButtonBoundingClientRect?(): { top: number; bottom: number; left: number; right: number } | undefined;onWindowResize?(cb: () => void): void;};}+/**+ * How far down the host's own overlay reaches, in the CSS pixels the safe area+ * is given in — zero where there is none. No engine offers this: every game+ * converts the rect to layout units by hand, which is the arithmetic the safe+ * area already goes through here.+ */+function hostMenuBottom(): number {+ if (!isWeChat()) return 0;+ const g = globalThis as unknown as WxGlobal;+ const rect = g.wx?.getMenuButtonBoundingClientRect?.();+ return rect && rect.bottom > 0 ? rect.bottom : 0;+}+function getWeChatSafeAreaInsets(): SafeAreaInsets {const g = globalThis as unknown as WxGlobal;const info = g.wx?.getSystemInfoSync?.();@@ -105,6 +126,7 @@ export class SafeAreaPlugin implements Plugin {// only real after the first layout, and a plugin that built before that// would hold zeros for the life of the game.let cachedInsets: SafeAreaInsets = { top: 0, bottom: 0, left: 0, right: 0 };+ let cachedMenuBottom = 0;let stale = true;let prevScreenH = 0;let prevLayoutH = 0;@@ -135,6 +157,7 @@ export class SafeAreaPlugin implements Plugin {if (stale) {stale = false;cachedInsets = getSafeAreaInsets();+ cachedMenuBottom = hostMenuBottom();}const dpr = platformDevicePixelRatio();@@ -146,7 +169,12 @@ export class SafeAreaPlugin implements Plugin {const sa = world.get(entity, SafeArea) as SafeAreaData;const node = world.get(entity, UINode) as UINodeData;- const top = sa.applyTop ? cachedInsets.top * insetScale : 0;+ // The overlay sits inside the safe area, so this is a floor+ // on the top inset rather than something added to it.+ const topPx = sa.avoidHostMenu+ ? Math.max(cachedInsets.top, cachedMenuBottom)+ : cachedInsets.top;+ const top = sa.applyTop ? topPx * insetScale : 0;const bottom = sa.applyBottom ? cachedInsets.bottom * insetScale : 0;const left = sa.applyLeft ? cachedInsets.left * insetScale : 0;const right = sa.applyRight ? cachedInsets.right * insetScale : 0;diff --git a/sdk/tests/safe-area-host-menu.test.ts b/sdk/tests/safe-area-host-menu.test.tsnew file mode 100644index 000000000..7377fbf69--- /dev/null+++ b/sdk/tests/safe-area-host-menu.test.ts@@ -0,0 +1,93 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file A WeChat package's HUD has a second thing to clear.+ *+ * The capsule menu sits INSIDE the safe area: measured on the iPhone 12 the+ * simulator offers, `safeArea.top` is 47 and the capsule's bottom is 76, so a+ * node that respects the safe area is still under the capsule for 29 of its 32+ * pixels — which is what the space-shooter example's lives counter did.+ */+import { describe, it, expect, beforeEach, afterEach } from 'vitest';+import { App } from '../src/app/app';+import { safeAreaPlugin, SafeArea } from '../src/ui/layout/safe-area';+import { uiLayoutPlugin } from '../src/ui/layout/layout';+import { ScreenLayout } from '../src/ui/core/screen-layout';+import { UINode } from '../src/ui/core/ui-node';+import type { UINodeData } from '../src/ui/core/ui-node';+import { createMockModule } from './mocks/wasm';+import { setPlatform } from '../src/platform/base';+import { webAdapter } from '../src/platform/web';+import { MiniGamePlatformAdapter } from '../src/platform/minigame/adapter';+import { wechatProfile } from '../src/platform/wechat/profile';++/** The numbers the WeChat simulator reports for an iPhone 12/13. */+const SCREEN = { width: 390, height: 844 };+const SAFE_AREA = { top: 47, bottom: 810, left: 0, right: 390 };+const CAPSULE = { top: 44, bottom: 76, left: 292, right: 380 };++interface FakeWx {+ getSystemInfoSync(): unknown;+ getMenuButtonBoundingClientRect(): unknown;+ onWindowResize(cb: () => void): void;+}++let savedWx: unknown;++function installFakeWx(capsule: typeof CAPSULE | null): void {+ const wx: FakeWx = {+ getSystemInfoSync: () => ({+ safeArea: SAFE_AREA, screenWidth: SCREEN.width, screenHeight: SCREEN.height, pixelRatio: 3,+ }),+ getMenuButtonBoundingClientRect: () => capsule ?? { top: 0, bottom: 0, left: 0, right: 0 },+ onWindowResize: () => {},+ };+ (globalThis as unknown as { wx?: unknown }).wx = wx;+ setPlatform(new MiniGamePlatformAdapter(wechatProfile));+}++beforeEach(() => { savedWx = (globalThis as unknown as { wx?: unknown }).wx; });+afterEach(() => {+ (globalThis as unknown as { wx?: unknown }).wx = savedWx;+ setPlatform(webAdapter);+});++/** One tick with a screen box whose scale is 1, so insets read as CSS pixels. */+async function insetTopOf(avoidHostMenu: boolean): Promise<number> {+ const module = createMockModule();+ const app = App.new();+ app.connectCpp(module.getRegistry(), module);+ app.insertResource(ScreenLayout, {+ ...ScreenLayout._default,+ valid: true, scale: 1,+ left: 0, bottom: 0, right: SCREEN.width, top: SCREEN.height,+ viewportW: SCREEN.width, viewportH: SCREEN.height,+ });+ app.addPlugin(uiLayoutPlugin);+ app.addPlugin(safeAreaPlugin);++ const e = app.world.spawn();+ app.world.insert(e, UINode, { ...UINode._default } as UINodeData);+ app.world.insert(e, SafeArea, {+ applyTop: true, applyBottom: true, applyLeft: true, applyRight: true, avoidHostMenu,+ });+ await app.tick(1 / 60);+ return (app.world.get(e, UINode) as UINodeData).insetTop.value;+}++describe('a node that must clear the host menu', () => {+ it('stops at the safe area when it does not ask to', async () => {+ installFakeWx(CAPSULE);+ expect(await insetTopOf(false)).toBe(SAFE_AREA.top);+ });++ it('clears the capsule when it does', async () => {+ installFakeWx(CAPSULE);+ expect(await insetTopOf(true)).toBe(CAPSULE.bottom);+ });++ it('is the safe area again on a host with no capsule to clear', async () => {+ installFakeWx(null);+ expect(await insetTopOf(true)).toBe(SAFE_AREA.top);+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex e5cbbf8a5..38da1b80f 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -684,4 +684,6 @@ export const NOTED = {{ note: 'A mini-game export no longer fails on a project whose sprites are atlased.' },'fix(wechat): the package installs its platform by calling for it':{ note: 'A WeChat mini-game boots again.' },+ 'feat(ui): a HUD can clear the host\'s own menu, not just the notch':+ { note: 'A UI node can keep clear of WeChat\'s capsule menu, which the safe area does not cover.' },};