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(ui): a button can act inside the player's tap, where WeChat requires a share

esengine61b10902fd7a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.ts
index 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.md
index ef9bb12fe..98f22b4b9 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1717,6 +1717,7 @@ parent: number | undefined
states: Record<string, ButtonStateVisual> | undefined
tabIndex: number | undefined
text: string | TextInit | undefined
+userGesture: boolean | undefined
world: World
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 2f8493a5c..beba0e414 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1717,6 +1717,7 @@ parent: number | undefined
states: Record<string, ButtonStateVisual> | undefined
tabIndex: number | undefined
text: string | TextInit | undefined
+userGesture: boolean | undefined
world: World
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index d66edadf3..02989c0f8 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1712,6 +1712,7 @@ parent: number | undefined
states: Record<string, ButtonStateVisual> | undefined
tabIndex: number | undefined
text: string | TextInit | undefined
+userGesture: boolean | undefined
world: World
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 35500ead1..2362ba8eb 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1712,6 +1712,7 @@ parent: number | undefined
states: Record<string, ButtonStateVisual> | undefined
tabIndex: number | undefined
text: string | TextInit | undefined
+userGesture: boolean | undefined
world: World
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index b2db165d6..9fde8e114 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1712,6 +1712,7 @@ parent: number | undefined
states: Record<string, ButtonStateVisual> | undefined
tabIndex: number | undefined
text: string | TextInit | undefined
+userGesture: boolean | undefined
world: World
```
diff --git a/sdk/src/ui/input/gestureClick.ts b/sdk/src/ui/input/gestureClick.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.mjs
index 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.' },
};