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): the vocabulary a game declares is frozen; the raw frame state is beta
esengine9c6320ffc6b3
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 5ca21cc05..7030fe89d 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -1,13 +1,37 @@{"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.","counts": {- "public": 74,- "beta": 24,- "experimental": 1527,+ "public": 94,+ "beta": 27,+ "experimental": 1504,"deprecated": 3},"total": 1625,"public": [+ {+ "name": "ActionDef",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "ActionType",+ "kind": "type",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "AddedWrapper","kind": "interface",@@ -32,6 +56,42 @@"minigame"]},+ {+ "name": "Axis1D",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "Axis2D",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "Binding",+ "kind": "type",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "BuiltinComponentDef","kind": "interface",@@ -44,6 +104,18 @@"minigame"]},+ {+ "name": "Button",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "ChangedWrapper","kind": "interface",@@ -296,6 +368,30 @@"minigame"]},+ {+ "name": "GamepadAxis",+ "kind": "enum",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "GamepadButton",+ "kind": "enum",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "GetWorld","kind": "function",@@ -320,6 +416,30 @@"minigame"]},+ {+ "name": "GpAxis",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "GpButton",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "InferParam","kind": "type",@@ -344,6 +464,90 @@"minigame"]},+ {+ "name": "InputMap",+ "kind": "class",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "InputMapAsset",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "Key",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "Keys1D",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "Keys2D",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "ListenOptions",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "MouseButton",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "Mut","kind": "function",@@ -632,6 +836,18 @@"minigame"]},+ {+ "name": "Stick",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "SystemDef","kind": "interface",@@ -776,6 +992,18 @@"minigame"]},+ {+ "name": "Virtual",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "World","kind": "class",@@ -848,6 +1076,18 @@"minigame"]},+ {+ "name": "defineInputMap",+ "kind": "function",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "defineResource","kind": "function",@@ -922,6 +1162,30 @@"minigame"]},+ {+ "name": "Input",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "InputState",+ "kind": "class",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "MaterialGraph","kind": "interface",@@ -1026,6 +1290,18 @@"minigame"]},+ {+ "name": "TouchPoint",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "addNode","kind": "function",diff --git a/examples/input-actions/src/actions.ts b/examples/input-actions/src/actions.tsindex 6ddd42d1d..71b446cc4 100644--- a/examples/input-actions/src/actions.ts+++ b/examples/input-actions/src/actions.ts@@ -2,10 +2,14 @@// of physical keys, so keyboard, gamepad and rebound inputs all flow through// one place. defineInputMap registers the per-frame evaluation system itself.import {- defineInputMap, Axis2D, Button, Keys2D, Stick, Key, GpButton, GamepadButton,+ defineInputMap, Axis1D, Axis2D, Button, Keys1D, Keys2D, Stick, Key,+ GpAxis, GpButton, GamepadAxis, GamepadButton,} from 'esengine';import type { Binding } from 'esengine';+// No mouse button here on purpose: the HUD's own buttons are clicks, and Fire+// reads the raw button rather than asking whether the pointer is over UI. A mouse+// binding is reachable through the rebind below, which is where it belongs.export const DEFAULT_FIRE: Binding[] = [Key('Space'), GpButton(GamepadButton.South)];export const Actions = defineInputMap({@@ -15,6 +19,12 @@ export const Actions = defineInputMap({Stick('left'),),Fire: Button(...DEFAULT_FIRE),+ // The keyboard and gamepad equivalent of the pinch gesture. GpAxis inverts+ // the raw stick Y, which points down, so pushing up grows the ship.+ Zoom: Axis1D(+ Keys1D('BracketLeft', 'BracketRight'),+ GpAxis(GamepadAxis.RightY, 0, -1),+ ),});/** Storage key for user rebinds (Actions.save / Actions.load). */diff --git a/examples/input-actions/src/systems/hud.ts b/examples/input-actions/src/systems/hud.tsindex b94df4394..3101f262e 100644--- a/examples/input-actions/src/systems/hud.ts+++ b/examples/input-actions/src/systems/hud.ts@@ -31,8 +31,11 @@ function startRebind(): void {Actions.cancelListen();return;}- status = 'Press any key or gamepad button... (click again to cancel)';- void Actions.rebind('Fire', { keyboard: true, gamepad: true }).then((binding) => {+ status = 'Press any key, mouse button or gamepad button... (click again to cancel)';+ // Mouse is safe to include here: this runs in Update, and the scan runs next+ // frame's PreUpdate — after Last cleared this frame's press edges, so the click+ // that opened the rebind is not the one captured.+ void Actions.rebind('Fire', { keyboard: true, mouse: true, gamepad: true }).then((binding) => {if (binding) {Actions.save(BINDINGS_KEY);status = `Fire is now ${formatBinding(binding)} (saved)`;diff --git a/examples/input-actions/src/systems/ship.ts b/examples/input-actions/src/systems/ship.tsindex 13029536e..c71c825df 100644--- a/examples/input-actions/src/systems/ship.ts+++ b/examples/input-actions/src/systems/ship.ts@@ -27,6 +27,13 @@ export const shipSystem = defineSystem(transform.position.x = clamp(x, -HALF_W, HALF_W);transform.position.y = clamp(y, -HALF_H, HALF_H);++ // Zoom is the keyboard/gamepad twin of the pinch gesture, so both write+ // the same scale rather than each keeping its own.+ const zoom = Actions.value('Zoom');+ if (zoom !== 0) {+ gestureState.scale = clamp(gestureState.scale + zoom * time.delta, 0.5, 2.5);+ }transform.scale = { x: gestureState.scale, y: gestureState.scale, z: 1 };if (Actions.pressed('Fire')) {diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex c2bd92e73..81878406a 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 74 public · 17 beta · 1412 experimental · 3 deprecated+Symbols: 94 public · 20 beta · 1389 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -54,13 +54,13 @@ static new (): AchievementsAPIstatic prototype: AchievementsAPI```-## ActionDef — interface @experimental+## ActionDef — interface @public```bindings: Binding[]type: ActionType```-## ActionType — type @experimental+## ActionType — type @public```'button' | 'axis' | 'axis2d'```@@ -941,12 +941,12 @@ name: stringtype: "audio"```-## Axis1D — const @experimental+## Axis1D — const @public```(...bindings: Binding[]) => ActionDef```-## Axis2D — const @experimental+## Axis2D — const @public```(...bindings: Binding[]) => ActionDef```@@ -1034,7 +1034,7 @@ p2y: number(payload: Uint8Array) => void```-## Binding — type @experimental+## Binding — type @public```| { kind: 'key'; code: string }| { kind: 'mouse'; button: number }@@ -1257,7 +1257,7 @@ trigger: stringFilterEffectDef | ReverbEffectDef | CompressorEffectDef```-## Button — const @experimental+## Button — const @public```(...bindings: Binding[]) => ActionDef```@@ -2937,7 +2937,7 @@ static prototype: GameSocketPlatformSocketOptions```-## GamepadAxis — enum @experimental+## GamepadAxis — enum @public```LeftX = 0LeftY = 1@@ -2945,7 +2945,7 @@ RightX = 2RightY = 3```-## GamepadButton — enum @experimental+## GamepadButton — enum @public```Back = 8DpadDown = 13@@ -3035,12 +3035,12 @@ static prototype: GestureDetector@internal _type: "get_world"```-## GpAxis — const @experimental+## GpAxis — const @public```(axis: number, pad?: number, scale?: number) => Binding```-## GpButton — const @experimental+## GpButton — const @public```(button: number, pad?: number) => Binding```@@ -3209,7 +3209,7 @@ P extends QueryDescriptor<infer C> ? QueryInstance<C> :}```-## Input — const @experimental+## Input — const @beta```ResourceDef<InputState>```@@ -3228,13 +3228,13 @@ onTouchStart: ((id: number, x: number, y: number) => boolean | void) | undefinedonWheel: ((deltaX: number, deltaY: number, mods: Modifiers) => boolean | void) | undefined```-## InputMap — class @experimental+## InputMap — class @public```+@internal evaluate: (input: InputState) => voidactions: () => string[]axis2d: (name: string) => Vec2cancelListen: () => voiddown: (name: string) => boolean-evaluate: (input: InputState) => voidgetBindings: (name: string) => Binding[]isListening: () => booleanlistenForBinding: (opts?: ListenOptions) => Promise<Binding | null>@@ -3252,7 +3252,7 @@ static new (actions: Record<string, ActionDef>): InputMapstatic prototype: InputMap```-## InputMapAsset — interface @experimental+## InputMapAsset — interface @public```actions: Record<string, ActionDef>version: number@@ -3286,7 +3286,7 @@ static new (): InputRouterstatic prototype: InputRouter```-## InputState — class @experimental+## InputState — class @beta```beginFixedStep: () => voidclearFrameState: () => void@@ -3398,7 +3398,7 @@ data: T(typeof JustifyContent)[keyof typeof JustifyContent]```-## Key — const @experimental+## Key — const @public```(code: string) => Binding```@@ -3412,12 +3412,12 @@ time: numbervalue: number```-## Keys1D — const @experimental+## Keys1D — const @public```(neg: string, pos: string) => Binding```-## Keys2D — const @experimental+## Keys2D — const @public```(up: string, down: string, left: string, right: string) => Binding```@@ -3656,7 +3656,7 @@ viewportSize: Vec2world: World```-## ListenOptions — interface @experimental+## ListenOptions — interface @public```gamepad: boolean | undefinedkeyboard: boolean | undefined@@ -4099,7 +4099,7 @@ shift: booleanComponentDef<MotorJointData>```-## MouseButton — const @experimental+## MouseButton — const @public```(button: number) => Binding```@@ -6612,7 +6612,7 @@ Running = "running"Success = "success"```-## Stick — const @experimental+## Stick — const @public```(stick: "left" | "right", pad?: number) => Binding```@@ -7505,7 +7505,7 @@ tabIndex: number | undefinedworld: World```-## TouchPoint — interface @experimental+## TouchPoint — interface @beta```id: numberx: number@@ -8228,7 +8228,7 @@ x: numbery: number```-## Virtual — const @experimental+## Virtual — const @public```(id: string) => Binding```@@ -9039,7 +9039,7 @@ PluralSelector<T>(name: string): EventDef<T>```-## defineInputMap — function @experimental+## defineInputMap — function @public```(actions: Record<string, ActionDef>): InputMap```diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex cf16459fa..d00ddcf2c 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 74 public · 22 beta · 1431 experimental · 3 deprecated+Symbols: 94 public · 25 beta · 1408 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -54,13 +54,13 @@ static new (): AchievementsAPIstatic prototype: AchievementsAPI```-## ActionDef — interface @experimental+## ActionDef — interface @public```bindings: Binding[]type: ActionType```-## ActionType — type @experimental+## ActionType — type @public```'button' | 'axis' | 'axis2d'```@@ -941,12 +941,12 @@ name: stringtype: "audio"```-## Axis1D — const @experimental+## Axis1D — const @public```(...bindings: Binding[]) => ActionDef```-## Axis2D — const @experimental+## Axis2D — const @public```(...bindings: Binding[]) => ActionDef```@@ -1034,7 +1034,7 @@ p2y: number(payload: Uint8Array) => void```-## Binding — type @experimental+## Binding — type @public```| { kind: 'key'; code: string }| { kind: 'mouse'; button: number }@@ -1257,7 +1257,7 @@ trigger: stringFilterEffectDef | ReverbEffectDef | CompressorEffectDef```-## Button — const @experimental+## Button — const @public```(...bindings: Binding[]) => ActionDef```@@ -2945,7 +2945,7 @@ static prototype: GameSocketPlatformSocketOptions```-## GamepadAxis — enum @experimental+## GamepadAxis — enum @public```LeftX = 0LeftY = 1@@ -2953,7 +2953,7 @@ RightX = 2RightY = 3```-## GamepadButton — enum @experimental+## GamepadButton — enum @public```Back = 8DpadDown = 13@@ -3043,12 +3043,12 @@ static prototype: GestureDetector@internal _type: "get_world"```-## GpAxis — const @experimental+## GpAxis — const @public```(axis: number, pad?: number, scale?: number) => Binding```-## GpButton — const @experimental+## GpButton — const @public```(button: number, pad?: number) => Binding```@@ -3217,7 +3217,7 @@ P extends QueryDescriptor<infer C> ? QueryInstance<C> :}```-## Input — const @experimental+## Input — const @beta```ResourceDef<InputState>```@@ -3236,13 +3236,13 @@ onTouchStart: ((id: number, x: number, y: number) => boolean | void) | undefinedonWheel: ((deltaX: number, deltaY: number, mods: Modifiers) => boolean | void) | undefined```-## InputMap — class @experimental+## InputMap — class @public```+@internal evaluate: (input: InputState) => voidactions: () => string[]axis2d: (name: string) => Vec2cancelListen: () => voiddown: (name: string) => boolean-evaluate: (input: InputState) => voidgetBindings: (name: string) => Binding[]isListening: () => booleanlistenForBinding: (opts?: ListenOptions) => Promise<Binding | null>@@ -3260,7 +3260,7 @@ static new (actions: Record<string, ActionDef>): InputMapstatic prototype: InputMap```-## InputMapAsset — interface @experimental+## InputMapAsset — interface @public```actions: Record<string, ActionDef>version: number@@ -3294,7 +3294,7 @@ static new (): InputRouterstatic prototype: InputRouter```-## InputState — class @experimental+## InputState — class @beta```beginFixedStep: () => voidclearFrameState: () => void@@ -3406,7 +3406,7 @@ data: T(typeof JustifyContent)[keyof typeof JustifyContent]```-## Key — const @experimental+## Key — const @public```(code: string) => Binding```@@ -3420,12 +3420,12 @@ time: numbervalue: number```-## Keys1D — const @experimental+## Keys1D — const @public```(neg: string, pos: string) => Binding```-## Keys2D — const @experimental+## Keys2D — const @public```(up: string, down: string, left: string, right: string) => Binding```@@ -3664,7 +3664,7 @@ viewportSize: Vec2world: World```-## ListenOptions — interface @experimental+## ListenOptions — interface @public```gamepad: boolean | undefinedkeyboard: boolean | undefined@@ -4112,7 +4112,7 @@ shift: booleanComponentDef<MotorJointData>```-## MouseButton — const @experimental+## MouseButton — const @public```(button: number) => Binding```@@ -6805,7 +6805,7 @@ Running = "running"Success = "success"```-## Stick — const @experimental+## Stick — const @public```(stick: "left" | "right", pad?: number) => Binding```@@ -7698,7 +7698,7 @@ tabIndex: number | undefinedworld: World```-## TouchPoint — interface @experimental+## TouchPoint — interface @beta```id: numberx: number@@ -8421,7 +8421,7 @@ x: numbery: number```-## Virtual — const @experimental+## Virtual — const @public```(id: string) => Binding```@@ -9272,7 +9272,7 @@ PluralSelector<T>(name: string): EventDef<T>```-## defineInputMap — function @experimental+## defineInputMap — function @public```(actions: Record<string, ActionDef>): InputMap```diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex e5bf4927a..fbbbecec2 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 74 public · 19 beta · 1411 experimental · 3 deprecated+Symbols: 94 public · 22 beta · 1388 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -49,13 +49,13 @@ static new (): AchievementsAPIstatic prototype: AchievementsAPI```-## ActionDef — interface @experimental+## ActionDef — interface @public```bindings: Binding[]type: ActionType```-## ActionType — type @experimental+## ActionType — type @public```'button' | 'axis' | 'axis2d'```@@ -936,12 +936,12 @@ name: stringtype: "audio"```-## Axis1D — const @experimental+## Axis1D — const @public```(...bindings: Binding[]) => ActionDef```-## Axis2D — const @experimental+## Axis2D — const @public```(...bindings: Binding[]) => ActionDef```@@ -1029,7 +1029,7 @@ p2y: number(payload: Uint8Array) => void```-## Binding — type @experimental+## Binding — type @public```| { kind: 'key'; code: string }| { kind: 'mouse'; button: number }@@ -1252,7 +1252,7 @@ trigger: stringFilterEffectDef | ReverbEffectDef | CompressorEffectDef```-## Button — const @experimental+## Button — const @public```(...bindings: Binding[]) => ActionDef```@@ -2932,7 +2932,7 @@ static prototype: GameSocketPlatformSocketOptions```-## GamepadAxis — enum @experimental+## GamepadAxis — enum @public```LeftX = 0LeftY = 1@@ -2940,7 +2940,7 @@ RightX = 2RightY = 3```-## GamepadButton — enum @experimental+## GamepadButton — enum @public```Back = 8DpadDown = 13@@ -3030,12 +3030,12 @@ static prototype: GestureDetector@internal _type: "get_world"```-## GpAxis — const @experimental+## GpAxis — const @public```(axis: number, pad?: number, scale?: number) => Binding```-## GpButton — const @experimental+## GpButton — const @public```(button: number, pad?: number) => Binding```@@ -3204,7 +3204,7 @@ P extends QueryDescriptor<infer C> ? QueryInstance<C> :}```-## Input — const @experimental+## Input — const @beta```ResourceDef<InputState>```@@ -3223,13 +3223,13 @@ onTouchStart: ((id: number, x: number, y: number) => boolean | void) | undefinedonWheel: ((deltaX: number, deltaY: number, mods: Modifiers) => boolean | void) | undefined```-## InputMap — class @experimental+## InputMap — class @public```+@internal evaluate: (input: InputState) => voidactions: () => string[]axis2d: (name: string) => Vec2cancelListen: () => voiddown: (name: string) => boolean-evaluate: (input: InputState) => voidgetBindings: (name: string) => Binding[]isListening: () => booleanlistenForBinding: (opts?: ListenOptions) => Promise<Binding | null>@@ -3247,7 +3247,7 @@ static new (actions: Record<string, ActionDef>): InputMapstatic prototype: InputMap```-## InputMapAsset — interface @experimental+## InputMapAsset — interface @public```actions: Record<string, ActionDef>version: number@@ -3281,7 +3281,7 @@ static new (): InputRouterstatic prototype: InputRouter```-## InputState — class @experimental+## InputState — class @beta```beginFixedStep: () => voidclearFrameState: () => void@@ -3393,7 +3393,7 @@ data: T(typeof JustifyContent)[keyof typeof JustifyContent]```-## Key — const @experimental+## Key — const @public```(code: string) => Binding```@@ -3407,12 +3407,12 @@ time: numbervalue: number```-## Keys1D — const @experimental+## Keys1D — const @public```(neg: string, pos: string) => Binding```-## Keys2D — const @experimental+## Keys2D — const @public```(up: string, down: string, left: string, right: string) => Binding```@@ -3651,7 +3651,7 @@ viewportSize: Vec2world: World```-## ListenOptions — interface @experimental+## ListenOptions — interface @public```gamepad: boolean | undefinedkeyboard: boolean | undefined@@ -4094,7 +4094,7 @@ shift: booleanComponentDef<MotorJointData>```-## MouseButton — const @experimental+## MouseButton — const @public```(button: number) => Binding```@@ -6607,7 +6607,7 @@ Running = "running"Success = "success"```-## Stick — const @experimental+## Stick — const @public```(stick: "left" | "right", pad?: number) => Binding```@@ -7500,7 +7500,7 @@ tabIndex: number | undefinedworld: World```-## TouchPoint — interface @experimental+## TouchPoint — interface @beta```id: numberx: number@@ -8223,7 +8223,7 @@ x: numbery: number```-## Virtual — const @experimental+## Virtual — const @public```(id: string) => Binding```@@ -9034,7 +9034,7 @@ PluralSelector<T>(name: string): EventDef<T>```-## defineInputMap — function @experimental+## defineInputMap — function @public```(actions: Record<string, ActionDef>): InputMap```diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 7afbedc7b..f2c59c039 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 74 public · 17 beta · 1432 experimental · 3 deprecated+Symbols: 94 public · 20 beta · 1409 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -49,13 +49,13 @@ static new (): AchievementsAPIstatic prototype: AchievementsAPI```-## ActionDef — interface @experimental+## ActionDef — interface @public```bindings: Binding[]type: ActionType```-## ActionType — type @experimental+## ActionType — type @public```'button' | 'axis' | 'axis2d'```@@ -936,12 +936,12 @@ name: stringtype: "audio"```-## Axis1D — const @experimental+## Axis1D — const @public```(...bindings: Binding[]) => ActionDef```-## Axis2D — const @experimental+## Axis2D — const @public```(...bindings: Binding[]) => ActionDef```@@ -1029,7 +1029,7 @@ p2y: number(payload: Uint8Array) => void```-## Binding — type @experimental+## Binding — type @public```| { kind: 'key'; code: string }| { kind: 'mouse'; button: number }@@ -1252,7 +1252,7 @@ trigger: stringFilterEffectDef | ReverbEffectDef | CompressorEffectDef```-## Button — const @experimental+## Button — const @public```(...bindings: Binding[]) => ActionDef```@@ -2932,7 +2932,7 @@ static prototype: GameSocketPlatformSocketOptions```-## GamepadAxis — enum @experimental+## GamepadAxis — enum @public```LeftX = 0LeftY = 1@@ -2940,7 +2940,7 @@ RightX = 2RightY = 3```-## GamepadButton — enum @experimental+## GamepadButton — enum @public```Back = 8DpadDown = 13@@ -3030,12 +3030,12 @@ static prototype: GestureDetector@internal _type: "get_world"```-## GpAxis — const @experimental+## GpAxis — const @public```(axis: number, pad?: number, scale?: number) => Binding```-## GpButton — const @experimental+## GpButton — const @public```(button: number, pad?: number) => Binding```@@ -3204,7 +3204,7 @@ P extends QueryDescriptor<infer C> ? QueryInstance<C> :}```-## Input — const @experimental+## Input — const @beta```ResourceDef<InputState>```@@ -3223,13 +3223,13 @@ onTouchStart: ((id: number, x: number, y: number) => boolean | void) | undefinedonWheel: ((deltaX: number, deltaY: number, mods: Modifiers) => boolean | void) | undefined```-## InputMap — class @experimental+## InputMap — class @public```+@internal evaluate: (input: InputState) => voidactions: () => string[]axis2d: (name: string) => Vec2cancelListen: () => voiddown: (name: string) => boolean-evaluate: (input: InputState) => voidgetBindings: (name: string) => Binding[]isListening: () => booleanlistenForBinding: (opts?: ListenOptions) => Promise<Binding | null>@@ -3247,7 +3247,7 @@ static new (actions: Record<string, ActionDef>): InputMapstatic prototype: InputMap```-## InputMapAsset — interface @experimental+## InputMapAsset — interface @public```actions: Record<string, ActionDef>version: number@@ -3281,7 +3281,7 @@ static new (): InputRouterstatic prototype: InputRouter```-## InputState — class @experimental+## InputState — class @beta```beginFixedStep: () => voidclearFrameState: () => void@@ -3393,7 +3393,7 @@ data: T(typeof JustifyContent)[keyof typeof JustifyContent]```-## Key — const @experimental+## Key — const @public```(code: string) => Binding```@@ -3407,12 +3407,12 @@ time: numbervalue: number```-## Keys1D — const @experimental+## Keys1D — const @public```(neg: string, pos: string) => Binding```-## Keys2D — const @experimental+## Keys2D — const @public```(up: string, down: string, left: string, right: string) => Binding```@@ -3651,7 +3651,7 @@ viewportSize: Vec2world: World```-## ListenOptions — interface @experimental+## ListenOptions — interface @public```gamepad: boolean | undefinedkeyboard: boolean | undefined@@ -4339,7 +4339,7 @@ shift: booleanComponentDef<MotorJointData>```-## MouseButton — const @experimental+## MouseButton — const @public```(button: number) => Binding```@@ -6852,7 +6852,7 @@ Running = "running"Success = "success"```-## Stick — const @experimental+## Stick — const @public```(stick: "left" | "right", pad?: number) => Binding```@@ -7745,7 +7745,7 @@ tabIndex: number | undefinedworld: World```-## TouchPoint — interface @experimental+## TouchPoint — interface @beta```id: numberx: number@@ -8468,7 +8468,7 @@ x: numbery: number```-## Virtual — const @experimental+## Virtual — const @public```(id: string) => Binding```@@ -9284,7 +9284,7 @@ PluralSelector<T>(name: string): EventDef<T>```-## defineInputMap — function @experimental+## defineInputMap — function @public```(actions: Record<string, ActionDef>): InputMap```diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 73203a790..bf6a7065c 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 74 public · 17 beta · 1422 experimental · 3 deprecated+Symbols: 94 public · 20 beta · 1399 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -49,13 +49,13 @@ static new (): AchievementsAPIstatic prototype: AchievementsAPI```-## ActionDef — interface @experimental+## ActionDef — interface @public```bindings: Binding[]type: ActionType```-## ActionType — type @experimental+## ActionType — type @public```'button' | 'axis' | 'axis2d'```@@ -936,12 +936,12 @@ name: stringtype: "audio"```-## Axis1D — const @experimental+## Axis1D — const @public```(...bindings: Binding[]) => ActionDef```-## Axis2D — const @experimental+## Axis2D — const @public```(...bindings: Binding[]) => ActionDef```@@ -1029,7 +1029,7 @@ p2y: number(payload: Uint8Array) => void```-## Binding — type @experimental+## Binding — type @public```| { kind: 'key'; code: string }| { kind: 'mouse'; button: number }@@ -1252,7 +1252,7 @@ trigger: stringFilterEffectDef | ReverbEffectDef | CompressorEffectDef```-## Button — const @experimental+## Button — const @public```(...bindings: Binding[]) => ActionDef```@@ -2932,7 +2932,7 @@ static prototype: GameSocketPlatformSocketOptions```-## GamepadAxis — enum @experimental+## GamepadAxis — enum @public```LeftX = 0LeftY = 1@@ -2940,7 +2940,7 @@ RightX = 2RightY = 3```-## GamepadButton — enum @experimental+## GamepadButton — enum @public```Back = 8DpadDown = 13@@ -3030,12 +3030,12 @@ static prototype: GestureDetector@internal _type: "get_world"```-## GpAxis — const @experimental+## GpAxis — const @public```(axis: number, pad?: number, scale?: number) => Binding```-## GpButton — const @experimental+## GpButton — const @public```(button: number, pad?: number) => Binding```@@ -3211,7 +3211,7 @@ P extends QueryDescriptor<infer C> ? QueryInstance<C> :}```-## Input — const @experimental+## Input — const @beta```ResourceDef<InputState>```@@ -3230,13 +3230,13 @@ onTouchStart: ((id: number, x: number, y: number) => boolean | void) | undefinedonWheel: ((deltaX: number, deltaY: number, mods: Modifiers) => boolean | void) | undefined```-## InputMap — class @experimental+## InputMap — class @public```+@internal evaluate: (input: InputState) => voidactions: () => string[]axis2d: (name: string) => Vec2cancelListen: () => voiddown: (name: string) => boolean-evaluate: (input: InputState) => voidgetBindings: (name: string) => Binding[]isListening: () => booleanlistenForBinding: (opts?: ListenOptions) => Promise<Binding | null>@@ -3254,7 +3254,7 @@ static new (actions: Record<string, ActionDef>): InputMapstatic prototype: InputMap```-## InputMapAsset — interface @experimental+## InputMapAsset — interface @public```actions: Record<string, ActionDef>version: number@@ -3288,7 +3288,7 @@ static new (): InputRouterstatic prototype: InputRouter```-## InputState — class @experimental+## InputState — class @beta```beginFixedStep: () => voidclearFrameState: () => void@@ -3400,7 +3400,7 @@ data: T(typeof JustifyContent)[keyof typeof JustifyContent]```-## Key — const @experimental+## Key — const @public```(code: string) => Binding```@@ -3414,12 +3414,12 @@ time: numbervalue: number```-## Keys1D — const @experimental+## Keys1D — const @public```(neg: string, pos: string) => Binding```-## Keys2D — const @experimental+## Keys2D — const @public```(up: string, down: string, left: string, right: string) => Binding```@@ -3658,7 +3658,7 @@ viewportSize: Vec2world: World```-## ListenOptions — interface @experimental+## ListenOptions — interface @public```gamepad: boolean | undefinedkeyboard: boolean | undefined@@ -4101,7 +4101,7 @@ shift: booleanComponentDef<MotorJointData>```-## MouseButton — const @experimental+## MouseButton — const @public```(button: number) => Binding```@@ -6614,7 +6614,7 @@ Running = "running"Success = "success"```-## Stick — const @experimental+## Stick — const @public```(stick: "left" | "right", pad?: number) => Binding```@@ -7507,7 +7507,7 @@ tabIndex: number | undefinedworld: World```-## TouchPoint — interface @experimental+## TouchPoint — interface @beta```id: numberx: number@@ -8230,7 +8230,7 @@ x: numbery: number```-## Virtual — const @experimental+## Virtual — const @public```(id: string) => Binding```@@ -9061,7 +9061,7 @@ PluralSelector<T>(name: string): EventDef<T>```-## defineInputMap — function @experimental+## defineInputMap — function @public```(actions: Record<string, ActionDef>): InputMap```diff --git a/sdk/src/input/input.ts b/sdk/src/input/input.tsindex f97756672..eef3d6346 100644--- a/sdk/src/input/input.ts+++ b/sdk/src/input/input.ts@@ -8,6 +8,11 @@ import type { GamepadSnapshot, InputEventCallbacks } from '../platform/types';import { inputRouter } from './inputRouter';import type { Vec2 } from '../types';+/**+ * One active touch, in screen pixels with y growing downward.+ *+ * @beta+ */export interface TouchPoint {id: number;x: number;@@ -18,6 +23,8 @@ export interface TouchPoint {* Standard-mapping gamepad buttons (W3C "standard gamepad"). Positional names* (SDL / Steam Input convention) avoid device assumptions; Xbox / PlayStation* face labels are noted for reference.+ *+ * @public*/export enum GamepadButton {South = 0, // A (Xbox) · Cross (PS)@@ -39,7 +46,8 @@ export enum GamepadButton {Guide = 16, // Xbox · PS · Home}-/** Standard-mapping gamepad axes (signed, [-1,1]). */+/** Standard-mapping gamepad axes (signed, [-1,1]).+ * @public */export enum GamepadAxis {LeftX = 0,LeftY = 1,@@ -57,6 +65,15 @@ interface PadState {const ZERO_VIRTUAL: Vec2 = { x: 0, y: 0 };+/**+ * This frame's raw input — the layer under {@link defineInputMap}'s named actions.+ *+ * `@beta`: per-frame touch state is reachable only as the raw `touches` /+ * `touchesStarted` / `touchesEnded` maps, so freezing it freezes two gaps in that+ * representation — no accessor for started/ended, and no write door at all.+ *+ * @beta+ */export class InputState {keysDown = new Set<string>();keysPressed = new Set<string>();@@ -308,6 +325,12 @@ export class InputState {}}+/**+ * This frame's raw input, as a resource. The input plugin writes it before any+ * game system runs, and clears the per-frame edges after the last one.+ *+ * @beta+ */export const Input = defineResource<InputState>(new InputState(), 'Input');/**diff --git a/sdk/src/input/inputMap.ts b/sdk/src/input/inputMap.tsindex b86fbd6c3..198509e5a 100644--- a/sdk/src/input/inputMap.ts+++ b/sdk/src/input/inputMap.ts@@ -21,6 +21,13 @@ import { Storage } from '../util/storage';// Binding model (plain, serializable — also the rebind / persistence format)// =============================================================================+/**+ * One physical source for an action. Plain serializable data on purpose: this is+ * also the rebind and persistence format, so what a player remaps is the same+ * shape a `.inputmap` asset ships.+ *+ * @public+ */export type Binding =| { kind: 'key'; code: string }| { kind: 'mouse'; button: number }@@ -31,15 +38,33 @@ export type Binding =| { kind: 'stick'; stick: 'left' | 'right'; pad?: number }| { kind: 'virtual'; id: string };+/**+ * How an action's bindings combine: a digital `button`, a signed 1D `axis`, or a+ * 2D `axis2d`. It decides which query answers — `pressed`/`down` for a button,+ * `value` for an axis, `axis2d` for the last.+ *+ * @public+ */export type ActionType = 'button' | 'axis' | 'axis2d';+/**+ * A named action: what kind of value it produces and every source that feeds it.+ * Bindings are alternatives, not a chord — whichever is strongest this frame wins.+ *+ * @public+ */export interface ActionDef {type: ActionType;bindings: Binding[];}-/** The serialized form of a whole map — the content of an `.inputmap` asset.- * Data-driven input: author/ship this JSON, then {@link loadInputMapAsset}. */+/**+ * The serialized form of a whole map — the content of an `.inputmap` asset.+ * Data-driven input: author/ship this JSON, then {@link loadInputMapAsset}.+ * `version` is the asset format's, so an older file stays readable.+ *+ * @public+ */export interface InputMapAsset {version: number;actions: Record<string, ActionDef>;@@ -48,27 +73,50 @@ export interface InputMapAsset {const INPUT_MAP_ASSET_VERSION = 1;// — Binding constructors (Capitalized, matching the engine DSL: Query/Mut/With) —+/** A keyboard key, by `KeyboardEvent.code` — physical position, not the character+ * it types, so WASD stays WASD on AZERTY.+ * @public */export const Key = (code: string): Binding => ({ kind: 'key', code });+/** A mouse button, by the DOM numbering (0 = left, 1 = middle, 2 = right).+ * @public */export const MouseButton = (button: number): Binding => ({ kind: 'mouse', button });+/** A gamepad button — see {@link GamepadButton}. `pad` defaults to the first one.+ * @public */export const GpButton = (button: number, pad?: number): Binding => ({ kind: 'gpButton', button, pad });+/** A gamepad axis — see {@link GamepadAxis}. `scale` multiplies the reading, so+ * `-1` inverts a stick axis that points the other way.+ * @public */export const GpAxis = (axis: number, pad?: number, scale?: number): Binding => ({ kind: 'gpAxis', axis, pad, scale });-/** Two keys → a signed 1D axis (neg = -1, pos = +1). */+/** Two keys → a signed 1D axis (neg = -1, pos = +1).+ * @public */export const Keys1D = (neg: string, pos: string): Binding => ({ kind: 'keys1d', neg, pos });-/** Four keys → a 2D axis (up = +y, right = +x). */+/** Four keys → a 2D axis (up = +y, right = +x).+ * @public */export const Keys2D = (up: string, down: string, left: string, right: string): Binding =>({ kind: 'keys2d', up, down, left, right });-/** A gamepad stick → a 2D axis (up = +y; the raw Y axis is inverted to match Keys2D). */+/** A gamepad stick → a 2D axis (up = +y; the raw Y axis is inverted to match Keys2D).+ * @public */export const Stick = (stick: 'left' | 'right', pad?: number): Binding => ({ kind: 'stick', stick, pad });/*** A named value the game writes itself (`Input.setVirtual`) — an on-screen* stick or button, which is the only input a touch device has. Works as a* scalar or a 2D source, so one kind covers both.+ *+ * @public*/export const Virtual = (id: string): Binding => ({ kind: 'virtual', id });// — Action constructors —+/** A digital action, read with `pressed`/`down`/`released`. An analog source+ * counts as down past half its range.+ * @public */export const Button = (...bindings: Binding[]): ActionDef => ({ type: 'button', bindings });+/** A signed 1D action in [-1, 1], read with `value`.+ * @public */export const Axis1D = (...bindings: Binding[]): ActionDef => ({ type: 'axis', bindings });+/** A 2D action, read with `axis2d`. Diagonals are not normalised — the vector is+ * what the sources produced.+ * @public */export const Axis2D = (...bindings: Binding[]): ActionDef => ({ type: 'axis2d', bindings });// =============================================================================@@ -127,8 +175,12 @@ const clamp = (v: number, lo: number, hi: number): number => (v < lo ? lo : v >// InputMap// =============================================================================-/** Which device families an interactive rebind listens to. Mouse is OFF by- * default (so the click that started the rebind isn't captured). */+/**+ * Which device families an interactive rebind listens to. Mouse is OFF by default+ * (so the click that started the rebind isn't captured).+ *+ * @public+ */export interface ListenOptions {keyboard?: boolean;mouse?: boolean;@@ -140,6 +192,13 @@ interface PendingListen {opts: ListenOptions;}+/**+ * A live set of named actions, as {@link defineInputMap} answers it. Query it by+ * name from a system; the map recomputes itself once per frame, so every read+ * within a frame sees the same values.+ *+ * @public+ */export class InputMap {private readonly defs_ = new Map<string, ActionDef>();private readonly state_ = new Map<string, ActionState>();@@ -152,8 +211,8 @@ export class InputMap {}}- /** Recompute every action from the current raw input. Called once per frame by- * the registered evaluation system; edges (pressed/released) diff vs last frame. */+ /** @internal Recompute every action from the current raw input. Called once per+ * frame by the registered evaluation system; edges diff against last frame. */evaluate(input: InputState): void {if (this.pendingListen_) this.scanForRebind_(input);for (const [name, def] of this.defs_) {@@ -299,6 +358,8 @@ export class InputMap {* Jump: Button(Key('Space'), GpButton(GamepadButton.South)),* });* // in a system: if (Game.pressed('Jump')) ...; const dir = Game.axis2d('Move');+ *+ * @public*/export function defineInputMap(actions: Record<string, ActionDef>): InputMap {const map = new InputMap(actions);@@ -313,7 +374,8 @@ export function defineInputMap(actions: Record<string, ActionDef>): InputMap {/*** Build a live InputMap from a loaded `.inputmap` asset (data-driven input —* fetch / import the JSON, then call this). Registers the evaluation system, same- * as {@link defineInputMap}.+ * as {@link defineInputMap}. Not frozen: no project we certify releases against+ * loads a map from an asset, so nothing holds this signature up.*/export function loadInputMapAsset(asset: InputMapAsset): InputMap {return defineInputMap(asset.actions);diff --git a/sdk/tests/input-vocabulary.test.ts b/sdk/tests/input-vocabulary.test.tsnew file mode 100644index 000000000..0348878f5--- /dev/null+++ b/sdk/tests/input-vocabulary.test.ts@@ -0,0 +1,204 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file input-vocabulary.test.ts — the frozen half of the input surface.+ *+ * The action/binding vocabulary is what freezes in 0.50; the raw per-frame state+ * stays @beta. So what is pinned here is the part a game DECLARES: that each+ * binding kind reads the source it names, that the three action types answer+ * through the three different queries, and that a map round-trips through the+ * asset shape — the claims a rebind UI and a shipped `.inputmap` both rest on.+ */+import { describe, it, expect } from 'vitest';+import {+ defineInputMap, InputMap, InputState, GamepadAxis, GamepadButton,+ Key, MouseButton, GpButton, GpAxis, Keys1D, Keys2D, Stick, Virtual,+ Button, Axis1D, Axis2D,+} from '../src/core';+import type { ActionDef, ActionType, Binding, InputMapAsset, ListenOptions } from '../src/core';++/** A pad reporting one axis and one button, as the platform would. */+function padded(input: InputState, axes: number[], buttons: number[] = []) {+ input.updateGamepads([{ index: 0, connected: true, axes, buttons }]);+}++describe('binding vocabulary', () => {+ it('every constructor answers the Binding kind it is named for', () => {+ const bindings: Binding[] = [+ Key('KeyW'), MouseButton(0), GpButton(GamepadButton.South), GpAxis(GamepadAxis.LeftX),+ Keys1D('KeyA', 'KeyD'), Keys2D('KeyW', 'KeyS', 'KeyA', 'KeyD'), Stick('left'), Virtual('pad'),+ ];+ expect(bindings.map((b) => b.kind)).toEqual([+ 'key', 'mouse', 'gpButton', 'gpAxis', 'keys1d', 'keys2d', 'stick', 'virtual',+ ]);+ });++ it('a key binding is a physical code, not the character it types', () => {+ const map = defineInputMap({ Fire: Button(Key('KeyZ')) });+ const input = new InputState();+ input.noteKeyDown('KeyY');+ map.evaluate(input);+ expect(map.down('Fire')).toBe(false);+ input.noteKeyDown('KeyZ');+ map.evaluate(input);+ expect(map.down('Fire')).toBe(true);+ });++ it('a mouse binding reads the DOM button numbering', () => {+ const map = defineInputMap({ Fire: Button(MouseButton(2)) });+ const input = new InputState();+ input.noteMouseDown(0);+ map.evaluate(input);+ expect(map.down('Fire')).toBe(false);+ input.noteMouseDown(2);+ map.evaluate(input);+ expect(map.down('Fire')).toBe(true);+ });++ it('Keys1D is a signed axis and both keys cancel', () => {+ const map = defineInputMap({ Throttle: Axis1D(Keys1D('KeyA', 'KeyD')) });+ const input = new InputState();+ input.noteKeyDown('KeyD');+ map.evaluate(input);+ expect(map.value('Throttle')).toBe(1);+ input.noteKeyDown('KeyA');+ map.evaluate(input);+ expect(map.value('Throttle')).toBe(0);+ });++ it('Keys2D puts up at +y, so screen coordinates do not leak into gameplay', () => {+ const map = defineInputMap({ Move: Axis2D(Keys2D('KeyW', 'KeyS', 'KeyA', 'KeyD')) });+ const input = new InputState();+ input.noteKeyDown('KeyW');+ input.noteKeyDown('KeyD');+ map.evaluate(input);+ const move = map.axis2d('Move');+ expect(move.y).toBeGreaterThan(0);+ expect(move.x).toBeGreaterThan(0);+ });++ it('GpAxis scale inverts a reading, which is why a stick can point up', () => {+ const map = defineInputMap({+ Raw: Axis1D(GpAxis(GamepadAxis.RightY)),+ Inverted: Axis1D(GpAxis(GamepadAxis.RightY, 0, -1)),+ });+ const input = new InputState();+ padded(input, [0, 0, 0, 1]);+ map.evaluate(input);+ expect(map.value('Raw')).toBeCloseTo(1, 5);+ expect(map.value('Inverted')).toBeCloseTo(-1, 5);+ });++ it('Stick answers +y for up, matching Keys2D rather than the raw axis', () => {+ const map = defineInputMap({ Move: Axis2D(Stick('left')) });+ const input = new InputState();+ // Raw stick Y grows downward; the binding is what flips it.+ padded(input, [0, -1, 0, 0]);+ map.evaluate(input);+ expect(map.axis2d('Move').y).toBeGreaterThan(0);+ });++ it('Virtual reads what the game wrote, so a touch stick needs no new kind', () => {+ const map = defineInputMap({ Move: Axis2D(Virtual('stick')) });+ const input = new InputState();+ input.setVirtual('stick', 0.5, 0.25);+ map.evaluate(input);+ expect(map.axis2d('Move')).toEqual({ x: 0.5, y: 0.25 });+ });+});++describe('action vocabulary', () => {+ it('the three action types carry the three ActionType values', () => {+ const button: ActionDef = Button(Key('Space'));+ const axis: ActionDef = Axis1D(Keys1D('KeyA', 'KeyD'));+ const axis2d: ActionDef = Axis2D(Stick('left'));+ const types: ActionType[] = [button.type, axis.type, axis2d.type];+ expect(types).toEqual(['button', 'axis', 'axis2d']);+ });++ it('bindings are alternatives, so either source drives the action', () => {+ const map = defineInputMap({+ Fire: Button(Key('Space'), GpButton(GamepadButton.South)),+ });+ const input = new InputState();+ padded(input, [], [1]);+ map.evaluate(input);+ expect(map.down('Fire')).toBe(true);++ const keyboard = new InputState();+ keyboard.noteKeyDown('Space');+ map.evaluate(keyboard);+ expect(map.down('Fire')).toBe(true);+ });++ it('pressed and released are edges, down is the level', () => {+ const map = defineInputMap({ Fire: Button(Key('Space')) });+ const held = new InputState();+ held.noteKeyDown('Space');++ map.evaluate(held);+ expect([map.pressed('Fire'), map.down('Fire'), map.released('Fire')]).toEqual([true, true, false]);+ map.evaluate(held);+ expect([map.pressed('Fire'), map.down('Fire'), map.released('Fire')]).toEqual([false, true, false]);+ map.evaluate(new InputState());+ expect([map.pressed('Fire'), map.down('Fire'), map.released('Fire')]).toEqual([false, false, true]);+ });++ it('an analog source counts as down past half its range', () => {+ const map = defineInputMap({ Fire: Button(GpButton(GamepadButton.RightTrigger)) });+ const input = new InputState();+ padded(input, [], [0, 0, 0, 0, 0, 0, 0, 0.3]);+ map.evaluate(input);+ expect(map.down('Fire')).toBe(false);+ padded(input, [], [0, 0, 0, 0, 0, 0, 0, 0.8]);+ map.evaluate(input);+ expect(map.down('Fire')).toBe(true);+ });+});++describe('input map vocabulary', () => {+ it('defineInputMap answers an InputMap listing what it was given', () => {+ const map: InputMap = defineInputMap({ Move: Axis2D(Stick('left')), Fire: Button(Key('Space')) });+ expect(map.actions().sort()).toEqual(['Fire', 'Move']);+ });++ it('a map round-trips through the asset shape it ships as', () => {+ const map = defineInputMap({ Fire: Button(Key('Space'), MouseButton(0)) });+ const asset: InputMapAsset = map.toAsset();+ expect(asset.actions.Fire.type).toBe('button');+ expect(asset.actions.Fire.bindings.map((b) => b.kind)).toEqual(['key', 'mouse']);+ });++ it('setBindings replaces what a rebind persists, and toJSON is bindings only', () => {+ const map = defineInputMap({ Fire: Button(Key('Space')) });+ map.setBindings('Fire', [Key('KeyF')]);+ expect(map.getBindings('Fire')).toEqual([Key('KeyF')]);+ expect(map.toJSON()).toEqual({ Fire: [Key('KeyF')] });+ });++ it('a listen captures the next press and ignores a device it was not asked for', async () => {+ const map = defineInputMap({ Fire: Button(Key('Space')) });+ const opts: ListenOptions = { keyboard: false, mouse: true };+ const pending = map.rebind('Fire', opts);+ expect(map.isListening()).toBe(true);++ const keyOnly = new InputState();+ keyOnly.noteKeyDown('KeyQ');+ map.evaluate(keyOnly);+ expect(map.isListening()).toBe(true);++ const clicked = new InputState();+ clicked.noteMouseDown(1);+ map.evaluate(clicked);+ expect(await pending).toEqual(MouseButton(1));+ expect(map.getBindings('Fire')).toEqual([MouseButton(1)]);+ });++ it('cancelListen resolves with null rather than leaving a promise hanging', async () => {+ const map = defineInputMap({ Fire: Button(Key('Space')) });+ const pending = map.listenForBinding();+ map.cancelListen();+ expect(await pending).toBeNull();+ expect(map.isListening()).toBe(false);+ });+});diff --git a/tools/check-freeze-bar.mjs b/tools/check-freeze-bar.mjsindex 8d818a14b..52109de2c 100644--- a/tools/check-freeze-bar.mjs+++ b/tools/check-freeze-bar.mjs@@ -37,7 +37,13 @@ import { GOLDEN, projectDir } from './goldenProjects.mjs';* every frame. The criterion is blind to them, not unmet by them.*/const RECEIVED = 'received from a declared parameter, never imported — golden projects run it, no import list names it';+const HANDED_BACK = 'answered by a frozen factory, never imported — a game names the factory, not this';export const EXEMPT = {+ InputMap: HANDED_BACK,+ // Same blindness, from the other direction: the map's rebind scan builds one+ // when a player binds a mouse button, so a certified game runs it without any+ // import list ever naming it.+ MouseButton: 'built by InputMap\'s rebind scan on the game\'s behalf — run by a golden project, named by none',// Same shape of blindness: the engine maintains this one from Parent, so a// game reads it and every golden project's layout walks it every frame, but// nothing imports the name.