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(input): multi-touch can be turned off, one finger at a time reaching the UI and the game

yhh19dd97d8a34c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9e1dc63e3..534545df5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@ published separately; it ships inside the editor.
### Added
+- **Multi-touch can be turned off.** `Input.setMultiTouch(false)` handles one finger at a time: the first to go down until it lifts, with any finger pressed meanwhile ignored by the UI and the game alike, so it cannot press a button or move a joystick under the first. Turning it off with several fingers down keeps the first and cancels the rest. `isMultiTouchEnabled()` reads it; it is on by default, and works the same on the web, mini-games and native apps (#117).
- **A Spine skeleton can be part of a UI.** A `SpineAnimation` under a Canvas paints by its place in the Canvas tree, between the controls around it, and takes the UI tree's opacity, hidden state and masks. Under a screen-space Canvas it is drawn with the UI in the screen overlay instead of by the cameras, where before it showed up in the world at the Canvas' pixel coordinates and never in the UI (#116). A non-zero `layer` still holds it over or under the whole UI, and a skeleton outside any Canvas is unchanged. DragonBones armatures under a screen Canvas are drawn in the overlay too.
- **A grip is edited where it is held.** Select an object with a `GripProfile` and its Details section edits the grip while a character in the scene holds it in the edit viewport, without Play: pick the character (it is given a `GripHolder`), create and pick the two palm anchors, see each palm drawn where it goes, switch the leading hand, and change every finger joint by joint in degrees, starting from a grip pose. Anchors are placed once and mirrored in the object's own plane for the other hand (`GripProfile.hand`, `mirror`); fingers said joint by joint (`GripFinger.bend`, `fan`, kept in `mainFingers`/`supportFingers`) are measured on the hand's own axes, so they mirror and fit any rig. The preview is the viewport's Preview FX and gives the bones back when it is turned off.
diff --git a/docs/astro/src/content/docs/scripting/input.mdx b/docs/astro/src/content/docs/scripting/input.mdx
index e0ad17c97..997e67d48 100644
--- a/docs/astro/src/content/docs/scripting/input.mdx
+++ b/docs/astro/src/content/docs/scripting/input.mdx
@@ -226,6 +226,26 @@ A tap is a touch under 0.3 s with less than 10 px of travel; a swipe needs ≥ 5
at ≥ 200 px/s; pinch reports the frame-to-frame scale of a two-finger spread with
its center point.
+### One finger at a time
+
+Multi-touch is on by default: every finger reaches the UI and the game. A scene
+that only wants one finger can turn it off:
+
+```ts
+const input = app.getResource(Input);
+input.setMultiTouch(false); // one finger at a time
+input.setMultiTouch(true); // every finger again
+input.isMultiTouchEnabled(); // which mode is on
+```
+
+When it is off, the first finger to go down is handled until it lifts. A finger
+pressed during that time is ignored until it lifts, by the UI as well as the
+game, so a second finger cannot press a button or move a joystick while the
+first is down. If several fingers are down when you turn it off, the first one
+to go down is kept. The others are cancelled: they end with no release edge,
+and a button they were pressing lets go without a click. The setting applies on
+every platform: the web, mini-games and native apps.
+
## Input routing (layers)
Before a raw platform event lands in the `Input` resource, it passes through the
diff --git a/docs/astro/src/content/docs/zh-cn/scripting/input.mdx b/docs/astro/src/content/docs/zh-cn/scripting/input.mdx
index 85fd47f5b..69cc202a7 100644
--- a/docs/astro/src/content/docs/zh-cn/scripting/input.mdx
+++ b/docs/astro/src/content/docs/zh-cn/scripting/input.mdx
@@ -211,6 +211,22 @@ const gestureSystem = defineSystem([Res(Input), Res(Time)], (input, time) => {
点按 = 0.3 s 内、移动小于 10 px;滑动需 ≥ 50 px 且 ≥ 200 px/s;捏合报告双指
间距逐帧的缩放系数及中心点。
+### 单点触控
+
+多点触控默认开启,每根手指都会传给 UI 和游戏。只需要单指操作的场景可以把它关掉:
+
+```ts
+const input = app.getResource(Input);
+input.setMultiTouch(false); // 一次只处理一根手指
+input.setMultiTouch(true); // 恢复处理所有手指
+input.isMultiTouchEnabled(); // 当前是哪种模式
+```
+
+关闭后,只处理第一根按下的手指,直到它抬起。期间按下的其他手指在抬起前都会被忽略,UI 和游戏都收不到,
+所以第二根手指既按不了按钮,也推不动摇杆。如果关闭时已经有多根手指按着,会保留最早按下的那根,
+其余的按取消处理:不产生抬起事件,正被它们按着的按钮会松开,也不会触发点击。
+这个设置在所有平台上都生效:网页、小游戏和原生应用。
+
## 输入路由(分层)
原始平台事件在落进 `Input` 资源之前,会先经过 **`InputRouter`**——一条三层的
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 66ed57296..51f3161d6 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5508,7 +5508,10 @@ isMouseButtonPressed: (button: number) => boolean
isMouseButtonReleased: (button: number) => boolean
isPointerOverUI: () => boolean
isTouchActive: (id: number) => boolean
+@internal admitTouch: (id: number) => boolean
keysDown: Set<string>
+@internal forgetTouches: () => void
+@internal touchIgnored: (id: number, retiring?: boolean) => boolean
keysPressed: Set<string>
keysPressedFixed: Set<string>
keysReleased: Set<string>
@@ -5540,6 +5543,7 @@ touchesStarted: Map<number, TouchPoint>
updateGamepads: (snapshots: GamepadSnapshot[]) => void
static new (): InputState
static prototype: InputState
+isMultiTouchEnabled: () => boolean
```
## InstantiatePrefabOptions — interface @experimental
@@ -5565,6 +5569,7 @@ BuiltinComponentDef<InteractableData>
## InteractableData — interface @experimental
```
blockRaycast: boolean
+setMultiTouch: (enabled: boolean) => void
enabled: boolean
raycastTarget: boolean
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index c27ce7f3a..a839440ce 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -5516,7 +5516,10 @@ isMouseButtonPressed: (button: number) => boolean
isMouseButtonReleased: (button: number) => boolean
isPointerOverUI: () => boolean
isTouchActive: (id: number) => boolean
+@internal admitTouch: (id: number) => boolean
keysDown: Set<string>
+@internal forgetTouches: () => void
+@internal touchIgnored: (id: number, retiring?: boolean) => boolean
keysPressed: Set<string>
keysPressedFixed: Set<string>
keysReleased: Set<string>
@@ -5548,6 +5551,7 @@ touchesStarted: Map<number, TouchPoint>
updateGamepads: (snapshots: GamepadSnapshot[]) => void
static new (): InputState
static prototype: InputState
+isMultiTouchEnabled: () => boolean
```
## InstantiatePrefabOptions — interface @experimental
@@ -5573,6 +5577,7 @@ BuiltinComponentDef<InteractableData>
## InteractableData — interface @experimental
```
blockRaycast: boolean
+setMultiTouch: (enabled: boolean) => void
enabled: boolean
raycastTarget: boolean
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 15d96e10c..b3b067208 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -5503,7 +5503,10 @@ isMouseButtonPressed: (button: number) => boolean
isMouseButtonReleased: (button: number) => boolean
isPointerOverUI: () => boolean
isTouchActive: (id: number) => boolean
+@internal admitTouch: (id: number) => boolean
keysDown: Set<string>
+@internal forgetTouches: () => void
+@internal touchIgnored: (id: number, retiring?: boolean) => boolean
keysPressed: Set<string>
keysPressedFixed: Set<string>
keysReleased: Set<string>
@@ -5535,6 +5538,7 @@ touchesStarted: Map<number, TouchPoint>
updateGamepads: (snapshots: GamepadSnapshot[]) => void
static new (): InputState
static prototype: InputState
+isMultiTouchEnabled: () => boolean
```
## InstantiatePrefabOptions — interface @experimental
@@ -5560,6 +5564,7 @@ BuiltinComponentDef<InteractableData>
## InteractableData — interface @experimental
```
blockRaycast: boolean
+setMultiTouch: (enabled: boolean) => void
enabled: boolean
raycastTarget: boolean
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 80e5d86df..ee2f6c3ef 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -5503,7 +5503,10 @@ isMouseButtonPressed: (button: number) => boolean
isMouseButtonReleased: (button: number) => boolean
isPointerOverUI: () => boolean
isTouchActive: (id: number) => boolean
+@internal admitTouch: (id: number) => boolean
keysDown: Set<string>
+@internal forgetTouches: () => void
+@internal touchIgnored: (id: number, retiring?: boolean) => boolean
keysPressed: Set<string>
keysPressedFixed: Set<string>
keysReleased: Set<string>
@@ -5535,6 +5538,7 @@ touchesStarted: Map<number, TouchPoint>
updateGamepads: (snapshots: GamepadSnapshot[]) => void
static new (): InputState
static prototype: InputState
+isMultiTouchEnabled: () => boolean
```
## InstantiatePrefabOptions — interface @experimental
@@ -5560,6 +5564,7 @@ BuiltinComponentDef<InteractableData>
## InteractableData — interface @experimental
```
blockRaycast: boolean
+setMultiTouch: (enabled: boolean) => void
enabled: boolean
raycastTarget: boolean
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 3b51c3935..6886b0fd3 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -5510,7 +5510,10 @@ isMouseButtonPressed: (button: number) => boolean
isMouseButtonReleased: (button: number) => boolean
isPointerOverUI: () => boolean
isTouchActive: (id: number) => boolean
+@internal admitTouch: (id: number) => boolean
keysDown: Set<string>
+@internal forgetTouches: () => void
+@internal touchIgnored: (id: number, retiring?: boolean) => boolean
keysPressed: Set<string>
keysPressedFixed: Set<string>
keysReleased: Set<string>
@@ -5542,6 +5545,7 @@ touchesStarted: Map<number, TouchPoint>
updateGamepads: (snapshots: GamepadSnapshot[]) => void
static new (): InputState
static prototype: InputState
+isMultiTouchEnabled: () => boolean
```
## InstantiatePrefabOptions — interface @experimental
@@ -5567,6 +5571,7 @@ BuiltinComponentDef<InteractableData>
## InteractableData — interface @experimental
```
blockRaycast: boolean
+setMultiTouch: (enabled: boolean) => void
enabled: boolean
raycastTarget: boolean
```
diff --git a/sdk/src/input/input.ts b/sdk/src/input/input.ts
index 83a819140..c306cc5b6 100644
--- a/sdk/src/input/input.ts
+++ b/sdk/src/input/input.ts
@@ -226,6 +226,74 @@ export class InputState {
this.touchesEnded.set(id, point);
}
+ // — Multi-touch —
+ /**
+ * Whether several fingers are handled at once. On (the default), every touch
+ * reaches the UI and the game. Off, one finger at a time does: the first to
+ * go down is the touch until it lifts, and a finger pressed meanwhile is
+ * ignored for its whole life, by the UI and the game alike, so a second
+ * finger cannot press a button or move a joystick under the first.
+ */
+ private multiTouch_ = true;
+ /** Single-touch mode: the finger being handled, or null when none is down. */
+ private soleTouch_: number | null = null;
+ /** Single-touch mode: fingers ignored until they lift. */
+ private ignoredTouches_ = new Set<number>();
+
+ isMultiTouchEnabled(): boolean {
+ return this.multiTouch_;
+ }
+
+ /**
+ * Handle several fingers at once, or one. Turning it off while several are
+ * down keeps the first that went down and cancels the rest, as the platform
+ * cancelling them would: their touches end with no release edge, and a UI
+ * control they were pressing lets go without a click.
+ */
+ setMultiTouch(enabled: boolean): void {
+ if (enabled === this.multiTouch_) return;
+ this.multiTouch_ = enabled;
+ this.ignoredTouches_.clear();
+ this.soleTouch_ = null;
+ if (enabled) return;
+ const down = [...this.touches.keys()];
+ this.soleTouch_ = down[0] ?? null;
+ for (const id of down.slice(1)) {
+ inputRouter.dispatchTouchCancel(id);
+ this.touches.delete(id);
+ this.touchesStarted.delete(id);
+ this.touchesEnded.delete(id);
+ this.ignoredTouches_.add(id);
+ }
+ }
+
+ /** @internal Whether a finger going down is handled; records it as the one in single-touch mode. */
+ admitTouch(id: number): boolean {
+ if (this.multiTouch_) return true;
+ if (this.soleTouch_ === null || this.soleTouch_ === id) {
+ this.soleTouch_ = id;
+ return true;
+ }
+ this.ignoredTouches_.add(id);
+ return false;
+ }
+
+ /** @internal Whether a finger's move, lift or cancel is ignored; a lift or cancel also retires it. */
+ touchIgnored(id: number, retiring = false): boolean {
+ if (this.ignoredTouches_.has(id)) {
+ if (retiring) this.ignoredTouches_.delete(id);
+ return true;
+ }
+ if (retiring && this.soleTouch_ === id) this.soleTouch_ = null;
+ return false;
+ }
+
+ /** @internal Every finger is gone (focus lost, the app hidden). */
+ forgetTouches(): void {
+ this.soleTouch_ = null;
+ this.ignoredTouches_.clear();
+ }
+
// — Virtual (an on-screen control, or anything else that decides to be input) —
/**
* Named 2D values a game writes itself — an on-screen control, the only
@@ -510,6 +578,8 @@ export function inputEventCallbacks(state: InputState): InputEventCallbacks {
},
onTouchStart(id, x, y) {
if (executionOwners.has(state)) return;
+ // Before the UI: with multi-touch off, a second finger presses nothing.
+ if (!state.admitTouch(id)) return;
if (inputRouter.dispatchTouchStart(id, x, y)) return;
const point = { id, x, y };
state.touches.set(id, point);
@@ -517,6 +587,7 @@ export function inputEventCallbacks(state: InputState): InputEventCallbacks {
},
onTouchMove(id, x, y) {
if (executionOwners.has(state)) return;
+ if (state.touchIgnored(id)) return;
if (inputRouter.dispatchTouchMove(id, x, y)) return;
const existing = state.touches.get(id);
if (existing) {
@@ -526,10 +597,12 @@ export function inputEventCallbacks(state: InputState): InputEventCallbacks {
},
onTouchEnd(id) {
if (executionOwners.has(state)) return;
+ if (state.touchIgnored(id, true)) return;
finishTouch(id, inputRouter.dispatchTouchEnd(id));
},
onTouchCancel(id, primary) {
if (executionOwners.has(state)) return;
+ if (state.touchIgnored(id, true)) return;
inputRouter.dispatchTouchCancel(id);
state.touches.delete(id);
state.touchesStarted.delete(id);
@@ -549,6 +622,7 @@ export function inputEventCallbacks(state: InputState): InputEventCallbacks {
state.keysDown.clear();
state.mouseButtons.clear();
state.touches.clear();
+ state.forgetTouches();
state.cancelVirtualSources();
state.clearFrameState();
cancelActionEdges(state);
diff --git a/sdk/tests/input-multitouch-switch.test.ts b/sdk/tests/input-multitouch-switch.test.ts
new file mode 100644
index 000000000..c205c889a
--- /dev/null
+++ b/sdk/tests/input-multitouch-switch.test.ts
@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Turning multi-touch off: one finger at a time reaches the UI and the
+ * game (esengine/estella#117). Driven through the one funnel every
+ * platform's touches arrive by (inputEventCallbacks), with the platform's
+ * own primary-pointer synthesis in front, so what is tested is what a
+ * phone sends.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { InputState, inputEventCallbacks } from '../src/input/input';
+import { inputRouter } from '../src/input/inputRouter';
+import { createPrimaryPointer } from '../src/platform/primaryPointer';
+
+let input: InputState;
+let finger: ReturnType<typeof createPrimaryPointer>;
+let ui: string[];
+let unregister: () => void;
+
+beforeEach(() => {
+ input = new InputState();
+ finger = createPrimaryPointer(inputEventCallbacks(input));
+ ui = [];
+ // A UI that sees every touch and claims none: what reaches it is recorded.
+ unregister = inputRouter.setUIHandler({
+ onTouchStart: (id) => { ui.push(`start ${id}`); },
+ onTouchMove: (id) => { ui.push(`move ${id}`); },
+ onTouchEnd: (id) => { ui.push(`end ${id}`); },
+ onTouchCancel: (id) => { ui.push(`cancel ${id}`); },
+ });
+});
+afterEach(() => unregister());
+
+const ids = () => input.getTouches().map((t) => t.id);
+
+describe('multi-touch switch', () => {
+ it('is on by default, and every finger is handled', () => {
+ expect(input.isMultiTouchEnabled()).toBe(true);
+ finger.start(1, 10, 10);
+ finger.start(2, 20, 20);
+ expect(ids()).toEqual([1, 2]);
+ expect(ui).toEqual(['start 1', 'start 2']);
+ });
+
+ it('off, a second finger reaches neither the game nor the UI for its whole life', () => {
+ input.setMultiTouch(false);
+ finger.start(1, 10, 10);
+ finger.start(2, 20, 20);
+ finger.move(2, 25, 25);
+ finger.end(2);
+ expect(ids()).toEqual([1]);
+ expect(input.getTouchesStarted().map((t) => t.id)).toEqual([1]);
+ expect(input.getTouchesEnded()).toEqual([]);
+ expect(ui).toEqual(['start 1']);
+ });
+
+ it('off, the next finger is handled once the first has lifted', () => {
+ input.setMultiTouch(false);
+ finger.start(1, 10, 10);
+ finger.end(1);
+ finger.start(2, 20, 20);
+ expect(ids()).toEqual([2]);
+ });
+
+ it('off, a finger pressed under the first stays ignored after the first lifts', () => {
+ input.setMultiTouch(false);
+ finger.start(1, 10, 10);
+ finger.start(2, 20, 20);
+ finger.end(1);
+ finger.move(2, 30, 30);
+ expect(ids()).toEqual([]);
+ finger.end(2);
+ finger.start(3, 40, 40);
+ expect(ids()).toEqual([3]);
+ });
+
+ it('a cancelled first finger frees the slot', () => {
+ input.setMultiTouch(false);
+ finger.start(1, 10, 10);
+ finger.cancel(1);
+ finger.start(2, 20, 20);
+ expect(ids()).toEqual([2]);
+ });
+
+ it('turned off with several fingers down keeps the first and cancels the rest', () => {
+ finger.start(1, 10, 10);
+ finger.start(2, 20, 20);
+ finger.start(3, 30, 30);
+ ui.length = 0;
+ input.setMultiTouch(false);
+ expect(ids()).toEqual([1]);
+ expect(ui).toEqual(['cancel 2', 'cancel 3']);
+ // They end with no release edge, and their later events are ignored.
+ finger.move(2, 99, 99);
+ finger.end(3);
+ expect(input.getTouchesEnded()).toEqual([]);
+ expect(ui).toEqual(['cancel 2', 'cancel 3']);
+ });
+
+ it('turned back on, every finger is handled again', () => {
+ input.setMultiTouch(false);
+ finger.start(1, 10, 10);
+ input.setMultiTouch(true);
+ finger.start(2, 20, 20);
+ expect(ids()).toEqual([1, 2]);
+ });
+
+ it('the mouse pointer a phone synthesises still follows only the first finger', () => {
+ input.setMultiTouch(false);
+ finger.start(1, 10, 10);
+ finger.start(2, 50, 50);
+ expect(input.isMouseButtonDown(0)).toBe(true);
+ expect(input.getMousePosition()).toEqual({ x: 10, y: 10 });
+ });
+
+ it('losing focus forgets every finger, in single-touch mode too', () => {
+ input.setMultiTouch(false);
+ finger.start(1, 10, 10);
+ finger.start(2, 20, 20);
+ inputEventCallbacks(input).onInputCancel?.();
+ finger.start(5, 0, 0);
+ expect(ids()).toEqual([5]);
+ });
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 7ae56eb87..eb3ab72b0 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ "feat(input): multi-touch can be turned off, one finger at a time reaching the UI and the game":
+ { note: "Multi-touch can be turned off." },
"feat(ui): a Spine skeleton in a Canvas paints by its place in the tree, with the UI's opacity, visibility and masks":
{ note: "A Spine skeleton can be part of a UI." },
"fix(export): an Android package carries its Spine runtimes on every architecture, not the first only":