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.

feat(ui): a HUD can clear the host's own menu, not just the notch

esengineba4467510616
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 a
step 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 entry
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index 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.ts
index 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.ts
new file mode 100644
index 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.mjs
index 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.' },
};