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(ui): a button can act inside the player's tap, where WeChat requires a share
esengine61b10902fd7a
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 0fbb26880..8a65318d2 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -24,6 +24,7 @@ published separately; it ships inside the editor.### Fixed+- `createButton({ userGesture: true })` runs its click inside the host's own release event: on a WeChat phone, sharing a recording from a button was refused ("require user interaction (only in touchend event)"), because a click ran on the frame after the tap.- Mini-game exports name assets by their content, as web exports already did: a hot update to a remote texture now shows on a phone (it kept the old picture under the same URL), and a CDN can hold two versions without v1 players getting v2 files.- On a WeChat phone, a socket whose connection is refused now reports that it closed, so a development build keeps redialing the editor (and a game's socket reconnects) instead of giving up after the first refusal.- A shipping package no longer carries the development debug channel's code (13 KB on a WeChat package): only a development export that names an editor imports it, as `esengine/debug-channel`.diff --git a/examples/record-share/src/record.ts b/examples/record-share/src/record.tsindex 0bcddc07b..4eeb7d0aa 100644--- a/examples/record-share/src/record.ts+++ b/examples/record-share/src/record.ts@@ -28,13 +28,14 @@ export const recordUiSystem = defineSystem(ui.built = true;const c = themeColors();- const button = (label: string, onClick: () => void): Entity => {+ const button = (label: string, onClick: () => void, userGesture = false): Entity => {const { entity } = createButton({world, events, parent: row,node: { width: px(150), height: px(44) },states: { normal: { color: c.primary }, hover: { color: c.primary }, pressed: { color: c.primary } },text: { content: label, color: c.onPrimary, fontSize: 16 },onClick,+ userGesture,});world.insert(entity, Name, { value: `${label}Button` });return entity;@@ -50,12 +51,13 @@ export const recordUiSystem = defineSystem(.then((r) => { ui.message = `recorded ${(r.durationMs / 1000).toFixed(1)}s, ${r.highlights.length} highlight(s)`; }).catch((e: Error) => { ui.message = e.message; });});- // A share has to come from the player's tap — both hosts refuse any other.+ // A share has to come from the player's tap — both hosts refuse any other,+ // and WeChat only from inside the touch event itself.ui.share = button('Share', () => {recorder.share({ title: 'Look at this run' }).then(() => { ui.message = 'shared'; }).catch((e: Error) => { ui.message = e.message; });- });+ }, true);recorder.onFailure((e) => { ui.message = `recording stopped: ${e.message}`; });},{ name: 'RecordUiSystem' },diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex ef9bb12fe..98f22b4b9 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1717,6 +1717,7 @@ parent: number | undefinedstates: Record<string, ButtonStateVisual> | undefinedtabIndex: number | undefinedtext: string | TextInit | undefined+userGesture: boolean | undefinedworld: World```diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 2f8493a5c..beba0e414 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1717,6 +1717,7 @@ parent: number | undefinedstates: Record<string, ButtonStateVisual> | undefinedtabIndex: number | undefinedtext: string | TextInit | undefined+userGesture: boolean | undefinedworld: World```diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex d66edadf3..02989c0f8 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1712,6 +1712,7 @@ parent: number | undefinedstates: Record<string, ButtonStateVisual> | undefinedtabIndex: number | undefinedtext: string | TextInit | undefined+userGesture: boolean | undefinedworld: World```diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 35500ead1..2362ba8eb 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1712,6 +1712,7 @@ parent: number | undefinedstates: Record<string, ButtonStateVisual> | undefinedtabIndex: number | undefinedtext: string | TextInit | undefined+userGesture: boolean | undefinedworld: World```diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex b2db165d6..9fde8e114 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1712,6 +1712,7 @@ parent: number | undefinedstates: Record<string, ButtonStateVisual> | undefinedtabIndex: number | undefinedtext: string | TextInit | undefined+userGesture: boolean | undefinedworld: World```diff --git a/sdk/src/ui/input/gestureClick.ts b/sdk/src/ui/input/gestureClick.tsnew file mode 100644index 000000000..75a176d6a--- /dev/null+++ b/sdk/src/ui/input/gestureClick.ts@@ -0,0 +1,51 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file gestureClick.ts — clicks that run inside the host's own input event.+ *+ * A frame reads a release after the host has returned from it, and some calls are+ * refused outside it: WeChat shares a recording only from within `touchend`. A+ * control registered here is clicked during that event, from where its pointer+ * pressed and last hovered.+ */+import type { Entity } from '../../types';+import type { World } from '../../ecs/world';++interface Registry {+ handlers: Map<Entity, () => void>;+ fired: Set<Entity>;+}++const registries = new WeakMap<World, Registry>();++function registryOf(world: World): Registry {+ let r = registries.get(world);+ if (!r) registries.set(world, r = { handlers: new Map(), fired: new Set() });+ return r;+}++/** Run @p onClick inside the release event that clicks @p entity. */+export function onGestureClick(world: World, entity: Entity, onClick: () => void): () => void {+ const r = registryOf(world);+ r.handlers.set(entity, onClick);+ return () => {+ if (r.handlers.get(entity) === onClick) r.handlers.delete(entity);+ };+}++/** @internal Click @p entity now, if it asked for its clicks here. */+export function fireGestureClick(world: World, entity: Entity): boolean {+ const r = registries.get(world);+ const onClick = r?.handlers.get(entity);+ if (!r || !onClick) return false;+ r.fired.add(entity);+ onClick();+ return true;+}++/** @internal Whether the frame's own click for @p entity was already run during+ * its release; answers once. */+export function takeGestureFired(world: World, entity: Entity): boolean {+ const r = registries.get(world);+ return !!r?.fired.delete(entity);+}diff --git a/sdk/src/ui/input/interaction.ts b/sdk/src/ui/input/interaction.tsindex 87cdb9ad8..6e69ee3f1 100644--- a/sdk/src/ui/input/interaction.ts+++ b/sdk/src/ui/input/interaction.ts@@ -24,7 +24,9 @@ import { ensureComponent, walkParentChain } from '../util/helpers';import type { CppRegistry } from '../../wasm';import { engineApi } from '../../ecs/bridge/engineApi';import { UILayoutGeneration } from '../layout/ui-layout-generation';-import { UiPointerBook, uiPointersOf, type UiPointerSample } from './pointerBook';+import { UiPointerBook, uiPointersOf, MOUSE_POINTER, type UiPointerSample } from './pointerBook';+import { fireGestureClick } from './gestureClick';+import { inputRouter } from '../../input/inputRouter';import { SystemLabel, PluginName } from '../../ecs/systemLabels';import type { UILayoutGenerationData } from '../layout/ui-layout-generation';@@ -69,6 +71,19 @@ export class UIInteractionPlugin implements Plugin {const lastHit = new Map<number, { x: number; y: number; entity: Entity | null }>();let lastLayoutGen = -1;+ // During the host's release event, from what the last frame saw: the+ // control this pointer pressed, if it is still the one under it.+ const releaseInGesture = (pointer: number): void => {+ const held = book.releasing(pointer, lastHit.get(pointer)?.entity ?? null);+ if (held === null || !world.valid(held)) return;+ if (world.has(held, Interactable) && !(world.get(held, Interactable) as InteractableData).enabled) return;+ fireGestureClick(world, held);+ };+ inputRouter.setUIHandler({+ onTouchEnd: (id) => { releaseInGesture(id); },+ onPointerUp: (button) => { if (button === 0) releaseInGesture(MOUSE_POINTER); },+ });+app.addSystemToSchedule(Schedule.PreUpdate, defineSystem([Res(Input), Res(UICameraInfo), Res(ScreenOverlay), Res(UILayoutGeneration)],(input: InputState, camera: UICameraData, overlay: ScreenOverlayData,diff --git a/sdk/src/ui/input/pointerBook.ts b/sdk/src/ui/input/pointerBook.tsindex 471cf99dd..d0784bca5 100644--- a/sdk/src/ui/input/pointerBook.ts+++ b/sdk/src/ui/input/pointerBook.ts@@ -94,6 +94,13 @@ export class UiPointerBook {return this.pressedBy_.get(pointer) ?? null;}+ /** The control a release now would click: the one this pointer holds, if it+ * is still @p under it. */+ releasing(pointer: number, under: Entity | null): Entity | null {+ const held = this.pressedByPointer(pointer);+ return held !== null && held === under ? held : null;+ }+/*** Fold this frame's pointers in and answer what happened, in the order it* happened. `hit` is the entity under a pointer (null for none) and `alive`diff --git a/sdk/src/ui/widgets/button.ts b/sdk/src/ui/widgets/button.tsindex 8ab19e83f..ca3c92875 100644--- a/sdk/src/ui/widgets/button.ts+++ b/sdk/src/ui/widgets/button.ts@@ -19,6 +19,7 @@ import { markThemed } from '../theme/theme-style';import { spawnUIEntity, type UINodeInit, type UIVisualInit, type TextInit } from '../core/compose';import { makeWidgetInteractable } from '../input/interactable';+import { onGestureClick, takeGestureFired } from '../input/gestureClick';export type { ButtonStateVisual };@@ -49,6 +50,10 @@ export interface ButtonOptions {/** Tab order within the focus ring. Default 0 (document order). */tabIndex?: number;onClick?: (entity: Entity) => void;+ /** Run `onClick` inside the host's own release event rather than on the next+ * frame, for a call a host accepts only from a player's gesture (sharing a+ * recording on WeChat). */+ userGesture?: boolean;}export interface ButtonHandle {@@ -132,9 +137,12 @@ export function createButton(opts: ButtonOptions): ButtonHandle {}let offClick: (() => void) | undefined;+ let offGesture: (() => void) | undefined;if (opts.onClick) {const handler = opts.onClick;+ if (opts.userGesture) offGesture = onGestureClick(world, entity, () => handler(entity));offClick = events.on(entity, UIEventType.Click, () => {+ if (opts.userGesture && takeGestureFired(world, entity)) return;const interactable = world.get(entity, Interactable) as InteractableData;if (interactable.enabled) handler(entity);});@@ -152,6 +160,7 @@ export function createButton(opts: ButtonOptions): ButtonHandle {},dispose: () => {offClick?.();+ offGesture?.();if (world.valid(entity)) world.despawn(entity);},};diff --git a/sdk/tests/ui-multi-pointer.test.ts b/sdk/tests/ui-multi-pointer.test.tsindex 33a540062..aedf062a0 100644--- a/sdk/tests/ui-multi-pointer.test.ts+++ b/sdk/tests/ui-multi-pointer.test.ts@@ -100,6 +100,17 @@ describe('two fingers, two buttons', () => {});});+describe('a release inside the host event', () => {+ it('clicks the control its pointer holds while still over it, and nothing else', () => {+ const book = new UiPointerBook();+ book.step([finger(0, 10, { pressed: true })], screen, () => true);+ expect(book.releasing(0, BUTTON_A)).toBe(BUTTON_A);+ expect(book.releasing(0, BUTTON_B)).toBeNull();+ expect(book.releasing(0, null)).toBeNull();+ expect(book.releasing(1, BUTTON_A)).toBeNull();+ });+});+describe('the pointer set a frame of input makes', () => {it('is the mouse when nothing is touching the glass', () => {const input = new InputState();diff --git a/sdk/tests/ui-widgets.test.ts b/sdk/tests/ui-widgets.test.tsindex 3c51a9a08..d62634580 100644--- a/sdk/tests/ui-widgets.test.ts+++ b/sdk/tests/ui-widgets.test.ts@@ -28,6 +28,7 @@ import {type UIGearData,} from '../src/ui';import type { Entity } from '../src/types';+import { fireGestureClick } from '../src/ui/input/gestureClick';import type { World } from '../src/ecs/world';// Minimal mock world — only the surface widgets + helpers touch.@@ -205,6 +206,22 @@ describe('createButton', () => {expect(onClick).toHaveBeenCalledWith(btn);});+ it('runs a user-gesture click inside the release, and not again on the frame after', () => {+ const onClick = vi.fn();+ const { entity: btn } = createButton({+ world: world as unknown as World, events, userGesture: true,+ states: { normal: {}, hover: {}, pressed: {} }, onClick,+ });+ expect(fireGestureClick(world as unknown as World, btn)).toBe(true);+ expect(onClick).toHaveBeenCalledTimes(1);+ events.emit(btn, UIEventType.Click);+ expect(onClick).toHaveBeenCalledTimes(1);+ // A click no release reached — a key, or a tap too quick for a frame to+ // see it pressed — still runs, on the frame.+ events.emit(btn, UIEventType.Click);+ expect(onClick).toHaveBeenCalledTimes(2);+ });+it('swallows clicks while disabled', () => {const onClick = vi.fn();const { entity: btn } = createButton({diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex c546f688c..a839d9bd0 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -1114,4 +1114,6 @@ export const NOTED = {{ note: 'On a WeChat phone, a socket whose connection is refused now reports that it closed, so a development build keeps redialing the editor (and a game\'s socket reconnects) instead of giving up after the first refusal.' },'fix(export): a mini-game\'s assets are named by their content, so an update gets new URLs':{ note: 'Mini-game exports name assets by their content, as web exports already did: a hot update to a remote texture now shows on a phone (it kept the old picture under the same URL), and a CDN can hold two versions without v1 players getting v2 files.' },+ 'fix(ui): a button can act inside the player\'s tap, where WeChat requires a share':+ { note: '`createButton({ userGesture: true })` runs its click inside the host\'s own release event: on a WeChat phone, sharing a recording from a button was refused ("require user interaction (only in touchend event)"), because a click ran on the frame after the tap.' },};