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(input): a project starts with multi-touch on or off, from Project Settings
yhhe42d606a382c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 534545df5..ae379aa6e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,7 +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).+- **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; **Project Settings → Game → Runtime → Multi-touch** sets what a game starts with, and a call to `setMultiTouch` wins over it. It 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/desktop b/desktopindex af0091328..a0c86c9c1 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit af0091328c3636cac558f28272ace21fb46e531c+Subproject commit a0c86c9c14b95d618d9617dbe05661628a55c43fdiff --git a/docs/astro/src/content/docs/scripting/input.mdx b/docs/astro/src/content/docs/scripting/input.mdxindex 997e67d48..857238c76 100644--- a/docs/astro/src/content/docs/scripting/input.mdx+++ b/docs/astro/src/content/docs/scripting/input.mdx@@ -228,8 +228,10 @@ 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:+Multi-touch is on by default: every finger reaches the UI and the game. To start+a game with it off, untick **Project Settings → Game → Runtime → Multi-touch**.+A scene that only wants one finger can also turn it off while the game runs. A+call to `setMultiTouch` wins over the project setting until the game restarts:```tsconst input = app.getResource(Input);diff --git a/docs/astro/src/content/docs/zh-cn/scripting/input.mdx b/docs/astro/src/content/docs/zh-cn/scripting/input.mdxindex 69cc202a7..e9435aec7 100644--- a/docs/astro/src/content/docs/zh-cn/scripting/input.mdx+++ b/docs/astro/src/content/docs/zh-cn/scripting/input.mdx@@ -213,7 +213,8 @@ const gestureSystem = defineSystem([Res(Input), Res(Time)], (input, time) => {### 单点触控-多点触控默认开启,每根手指都会传给 UI 和游戏。只需要单指操作的场景可以把它关掉:+多点触控默认开启,每根手指都会传给 UI 和游戏。想让游戏一启动就关闭它,取消勾选 **项目设置 → 游戏 → 运行时 → 多点触控**。+只需要单指操作的场景也可以在运行中关掉;代码调用 `setMultiTouch` 之后,以代码的设置为准,直到游戏重新启动:```tsconst input = app.getResource(Input);diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 51f3161d6..9e7f1af19 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -9197,7 +9197,7 @@ textureCacheBudget: number | undefined## RuntimeConfig — const @experimental```-{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; textureCacheBudget: number; audioCacheBudget: number; retainedBudget: number; }+{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; multiTouch: boolean; textureCacheBudget: number; audioCacheBudget: number; retainedBudget: number; }```## RuntimeInitConfig — interface @experimental@@ -9230,6 +9230,7 @@ uiTheme: "light" | "dark" | undefineduiThemeOverrides: ThemeOverrides | undefinedworlds: WorldManifest[] | undefined```+multiTouch: boolean | undefined## RuntimeOnly — const @public```diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex a839440ce..30915ae92 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -9418,7 +9418,7 @@ textureCacheBudget: number | undefined## RuntimeConfig — const @experimental```-{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; textureCacheBudget: number; audioCacheBudget: number; retainedBudget: number; }+{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; multiTouch: boolean; textureCacheBudget: number; audioCacheBudget: number; retainedBudget: number; }```## RuntimeInitConfig — interface @experimental@@ -9451,6 +9451,7 @@ uiTheme: "light" | "dark" | undefineduiThemeOverrides: ThemeOverrides | undefinedworlds: WorldManifest[] | undefined```+multiTouch: boolean | undefined## RuntimeOnly — const @public```diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex b3b067208..13087635b 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -9192,7 +9192,7 @@ textureCacheBudget: number | undefined## RuntimeConfig — const @experimental```-{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; textureCacheBudget: number; audioCacheBudget: number; retainedBudget: number; }+{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; multiTouch: boolean; textureCacheBudget: number; audioCacheBudget: number; retainedBudget: number; }```## RuntimeInitConfig — interface @experimental@@ -9225,6 +9225,7 @@ uiTheme: "light" | "dark" | undefineduiThemeOverrides: ThemeOverrides | undefinedworlds: WorldManifest[] | undefined```+multiTouch: boolean | undefined## RuntimeOnly — const @public```diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex ee2f6c3ef..1562b738f 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -9488,7 +9488,7 @@ textureCacheBudget: number | undefined## RuntimeConfig — const @experimental```-{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; textureCacheBudget: number; audioCacheBudget: number; retainedBudget: number; }+{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; multiTouch: boolean; textureCacheBudget: number; audioCacheBudget: number; retainedBudget: number; }```## RuntimeInitConfig — interface @experimental@@ -9521,6 +9521,7 @@ uiTheme: "light" | "dark" | undefineduiThemeOverrides: ThemeOverrides | undefinedworlds: WorldManifest[] | undefined```+multiTouch: boolean | undefined## RuntimeOnly — const @public```diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 6886b0fd3..f3717475e 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -9199,7 +9199,7 @@ textureCacheBudget: number | undefined## RuntimeConfig — const @experimental```-{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; textureCacheBudget: number; audioCacheBudget: number; retainedBudget: number; }+{ sceneTransitionDuration: number; sceneTransitionColor: { r: number; g: number; b: number; a: number; }; defaultFontFamily: string; maxDeltaTime: number; maxFixedSteps: number; textCanvasSize: number; assetLoadTimeout: number; assetFailureCooldown: number; multiTouch: boolean; textureCacheBudget: number; audioCacheBudget: number; retainedBudget: number; }```## RuntimeInitConfig — interface @experimental@@ -9232,6 +9232,7 @@ uiTheme: "light" | "dark" | undefineduiThemeOverrides: ThemeOverrides | undefinedworlds: WorldManifest[] | undefined```+multiTouch: boolean | undefined## RuntimeOnly — const @public```diff --git a/sdk/src/defaults.ts b/sdk/src/defaults.tsindex 2fd520a61..35b6a8a89 100644--- a/sdk/src/defaults.ts+++ b/sdk/src/defaults.ts@@ -36,6 +36,8 @@ export const RuntimeConfig = {textCanvasSize: 512,assetLoadTimeout: 30000,assetFailureCooldown: 5000,+ /** Whether several fingers are handled at once, until a game says otherwise with `Input.setMultiTouch`. */+ multiTouch: true,/*** Resident GPU-texture byte budget (see setTextureBudget). Released-but-* budgeted textures stay resident as an evictable LRU cache, so re-entering@@ -75,6 +77,8 @@ export interface RuntimeBuildConfig {textureCacheBudget?: number;audioCacheBudget?: number;retainedBudget?: number;+ /** Handle several fingers at once (the default), or one at a time; `Input.setMultiTouch` changes it while the game runs. */+ multiTouch?: boolean;}/**@@ -93,6 +97,7 @@ export const RUNTIME_BUILD_DEFAULTS: Readonly<Required<RuntimeBuildConfig>> = {textureCacheBudget: 64 * 1024 * 1024,audioCacheBudget: 32 * 1024 * 1024,retainedBudget: 16 * 1024 * 1024,+ multiTouch: true,};const RUNTIME_BUILD_LIMITS = {@@ -125,6 +130,7 @@ export function parseRuntimeBuildConfig(value: unknown): RuntimeBuildConfig {if (typeof color === 'string' && /^#[0-9a-f]{6}$/i.test(color) && color.toLowerCase() !== RUNTIME_BUILD_DEFAULTS.sceneTransitionColor) {config.sceneTransitionColor = color.toLowerCase();}+ if (raw.multiTouch === false) config.multiTouch = false;const family = raw.defaultFontFamily;if (typeof family === 'string' && family.trim() !== '' && family.length <= 200 && family !== RUNTIME_BUILD_DEFAULTS.defaultFontFamily) {config.defaultFontFamily = family;@@ -144,6 +150,8 @@ export function applyBuildRuntimeConfig(app: { setMaxDeltaTime(v: number): void;if (config.textCanvasSize !== undefined) {RuntimeConfig.textCanvasSize = config.textCanvasSize;}+ // Written only when off, so absence is on: a realm booted again must not keep a false from before.+ RuntimeConfig.multiTouch = config.multiTouch ?? true;if (config.defaultFontFamily !== undefined) {RuntimeConfig.defaultFontFamily = config.defaultFontFamily;}diff --git a/sdk/src/input/input.ts b/sdk/src/input/input.tsindex c306cc5b6..57d94194a 100644--- a/sdk/src/input/input.ts+++ b/sdk/src/input/input.ts@@ -11,6 +11,7 @@ import { cancelPrimaryPointer, takePrimaryPointerCancellation } from './pointerCimport { recordTouchEnd } from './touchEdges';import { recordActionEdge, discardActionEdges, clearActionEdges, beginFixedActionEdges, endFixedActionEdges, cancelActionEdges } from './actionEdges';import type { Vec2 } from '../types';+import { RuntimeConfig } from '../defaults';/*** One active touch, in screen pixels with y growing downward.@@ -234,14 +235,16 @@ export class InputState {* 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;+ /** What the game set with {@link setMultiTouch}, or null to follow the project (RuntimeConfig.multiTouch). */+ private multiTouch_: boolean | null = null;/** 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>();+ /** On unless the project turned it off (Project Settings → Runtime) or the game did. */isMultiTouchEnabled(): boolean {- return this.multiTouch_;+ return this.multiTouch_ ?? RuntimeConfig.multiTouch;}/**@@ -251,8 +254,9 @@ export class InputState {* control they were pressing lets go without a click.*/setMultiTouch(enabled: boolean): void {- if (enabled === this.multiTouch_) return;+ const was = this.isMultiTouchEnabled();this.multiTouch_ = enabled;+ if (enabled === was) return;this.ignoredTouches_.clear();this.soleTouch_ = null;if (enabled) return;@@ -269,7 +273,7 @@ export class InputState {/** @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.isMultiTouchEnabled()) return true;if (this.soleTouch_ === null || this.soleTouch_ === id) {this.soleTouch_ = id;return true;diff --git a/sdk/tests/input-multitouch-switch.test.ts b/sdk/tests/input-multitouch-switch.test.tsindex c205c889a..c39aeaf46 100644--- a/sdk/tests/input-multitouch-switch.test.ts+++ b/sdk/tests/input-multitouch-switch.test.ts@@ -11,6 +11,7 @@ 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';+import { RuntimeConfig, applyBuildRuntimeConfig, parseRuntimeBuildConfig } from '../src/defaults';let input: InputState;let finger: ReturnType<typeof createPrimaryPointer>;@@ -29,7 +30,7 @@ beforeEach(() => {onTouchCancel: (id) => { ui.push(`cancel ${id}`); },});});-afterEach(() => unregister());+afterEach(() => { unregister(); RuntimeConfig.multiTouch = true; });const ids = () => input.getTouches().map((t) => t.id);@@ -122,3 +123,36 @@ describe('multi-touch switch', () => {expect(ids()).toEqual([5]);});});++// The project's default (Project Settings → Game → Runtime → Multi-touch).+describe('the project default', () => {+ const app = { setMaxDeltaTime() {}, setMaxFixedSteps() {} };++ it('is written only when off', () => {+ expect(parseRuntimeBuildConfig({ multiTouch: false })).toEqual({ multiTouch: false });+ expect(parseRuntimeBuildConfig({ multiTouch: true })).toEqual({});+ expect(parseRuntimeBuildConfig({ multiTouch: 'no' })).toEqual({});+ });++ it('turns multi-touch off for a game that has not said otherwise', () => {+ applyBuildRuntimeConfig(app, { multiTouch: false });+ expect(input.isMultiTouchEnabled()).toBe(false);+ finger.start(1, 10, 10);+ finger.start(2, 20, 20);+ expect(ids()).toEqual([1]);+ });++ it('gives way to the game turning it back on', () => {+ applyBuildRuntimeConfig(app, { multiTouch: false });+ input.setMultiTouch(true);+ finger.start(1, 10, 10);+ finger.start(2, 20, 20);+ expect(ids()).toEqual([1, 2]);+ });++ it('is on again for a config that does not mention it, even after one that turned it off', () => {+ applyBuildRuntimeConfig(app, { multiTouch: false });+ applyBuildRuntimeConfig(app, {});+ expect(input.isMultiTouchEnabled()).toBe(true);+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex eb3ab72b0..54ff6cf78 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): a project starts with multi-touch on or off, from Project Settings":+ { note: "Multi-touch can be turned off." },"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":