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): 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.json
index 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.ts
index 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.ts
index 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.ts
index 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.md
index 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 (): AchievementsAPI
static 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: string
type: "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: string
FilterEffectDef | ReverbEffectDef | CompressorEffectDef
```
-## Button — const @experimental
+## Button — const @public
```
(...bindings: Binding[]) => ActionDef
```
@@ -2937,7 +2937,7 @@ static prototype: GameSocket
PlatformSocketOptions
```
-## GamepadAxis — enum @experimental
+## GamepadAxis — enum @public
```
LeftX = 0
LeftY = 1
@@ -2945,7 +2945,7 @@ RightX = 2
RightY = 3
```
-## GamepadButton — enum @experimental
+## GamepadButton — enum @public
```
Back = 8
DpadDown = 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) | undefined
onWheel: ((deltaX: number, deltaY: number, mods: Modifiers) => boolean | void) | undefined
```
-## InputMap — class @experimental
+## InputMap — class @public
```
+@internal evaluate: (input: InputState) => void
actions: () => string[]
axis2d: (name: string) => Vec2
cancelListen: () => void
down: (name: string) => boolean
-evaluate: (input: InputState) => void
getBindings: (name: string) => Binding[]
isListening: () => boolean
listenForBinding: (opts?: ListenOptions) => Promise<Binding | null>
@@ -3252,7 +3252,7 @@ static new (actions: Record<string, ActionDef>): InputMap
static prototype: InputMap
```
-## InputMapAsset — interface @experimental
+## InputMapAsset — interface @public
```
actions: Record<string, ActionDef>
version: number
@@ -3286,7 +3286,7 @@ static new (): InputRouter
static prototype: InputRouter
```
-## InputState — class @experimental
+## InputState — class @beta
```
beginFixedStep: () => void
clearFrameState: () => 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: number
value: 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: Vec2
world: World
```
-## ListenOptions — interface @experimental
+## ListenOptions — interface @public
```
gamepad: boolean | undefined
keyboard: boolean | undefined
@@ -4099,7 +4099,7 @@ shift: boolean
ComponentDef<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 | undefined
world: World
```
-## TouchPoint — interface @experimental
+## TouchPoint — interface @beta
```
id: number
x: number
@@ -8228,7 +8228,7 @@ x: number
y: 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.md
index 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 (): AchievementsAPI
static 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: string
type: "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: string
FilterEffectDef | ReverbEffectDef | CompressorEffectDef
```
-## Button — const @experimental
+## Button — const @public
```
(...bindings: Binding[]) => ActionDef
```
@@ -2945,7 +2945,7 @@ static prototype: GameSocket
PlatformSocketOptions
```
-## GamepadAxis — enum @experimental
+## GamepadAxis — enum @public
```
LeftX = 0
LeftY = 1
@@ -2953,7 +2953,7 @@ RightX = 2
RightY = 3
```
-## GamepadButton — enum @experimental
+## GamepadButton — enum @public
```
Back = 8
DpadDown = 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) | undefined
onWheel: ((deltaX: number, deltaY: number, mods: Modifiers) => boolean | void) | undefined
```
-## InputMap — class @experimental
+## InputMap — class @public
```
+@internal evaluate: (input: InputState) => void
actions: () => string[]
axis2d: (name: string) => Vec2
cancelListen: () => void
down: (name: string) => boolean
-evaluate: (input: InputState) => void
getBindings: (name: string) => Binding[]
isListening: () => boolean
listenForBinding: (opts?: ListenOptions) => Promise<Binding | null>
@@ -3260,7 +3260,7 @@ static new (actions: Record<string, ActionDef>): InputMap
static prototype: InputMap
```
-## InputMapAsset — interface @experimental
+## InputMapAsset — interface @public
```
actions: Record<string, ActionDef>
version: number
@@ -3294,7 +3294,7 @@ static new (): InputRouter
static prototype: InputRouter
```
-## InputState — class @experimental
+## InputState — class @beta
```
beginFixedStep: () => void
clearFrameState: () => 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: number
value: 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: Vec2
world: World
```
-## ListenOptions — interface @experimental
+## ListenOptions — interface @public
```
gamepad: boolean | undefined
keyboard: boolean | undefined
@@ -4112,7 +4112,7 @@ shift: boolean
ComponentDef<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 | undefined
world: World
```
-## TouchPoint — interface @experimental
+## TouchPoint — interface @beta
```
id: number
x: number
@@ -8421,7 +8421,7 @@ x: number
y: 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.md
index 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 (): AchievementsAPI
static 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: string
type: "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: string
FilterEffectDef | ReverbEffectDef | CompressorEffectDef
```
-## Button — const @experimental
+## Button — const @public
```
(...bindings: Binding[]) => ActionDef
```
@@ -2932,7 +2932,7 @@ static prototype: GameSocket
PlatformSocketOptions
```
-## GamepadAxis — enum @experimental
+## GamepadAxis — enum @public
```
LeftX = 0
LeftY = 1
@@ -2940,7 +2940,7 @@ RightX = 2
RightY = 3
```
-## GamepadButton — enum @experimental
+## GamepadButton — enum @public
```
Back = 8
DpadDown = 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) | undefined
onWheel: ((deltaX: number, deltaY: number, mods: Modifiers) => boolean | void) | undefined
```
-## InputMap — class @experimental
+## InputMap — class @public
```
+@internal evaluate: (input: InputState) => void
actions: () => string[]
axis2d: (name: string) => Vec2
cancelListen: () => void
down: (name: string) => boolean
-evaluate: (input: InputState) => void
getBindings: (name: string) => Binding[]
isListening: () => boolean
listenForBinding: (opts?: ListenOptions) => Promise<Binding | null>
@@ -3247,7 +3247,7 @@ static new (actions: Record<string, ActionDef>): InputMap
static prototype: InputMap
```
-## InputMapAsset — interface @experimental
+## InputMapAsset — interface @public
```
actions: Record<string, ActionDef>
version: number
@@ -3281,7 +3281,7 @@ static new (): InputRouter
static prototype: InputRouter
```
-## InputState — class @experimental
+## InputState — class @beta
```
beginFixedStep: () => void
clearFrameState: () => 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: number
value: 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: Vec2
world: World
```
-## ListenOptions — interface @experimental
+## ListenOptions — interface @public
```
gamepad: boolean | undefined
keyboard: boolean | undefined
@@ -4094,7 +4094,7 @@ shift: boolean
ComponentDef<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 | undefined
world: World
```
-## TouchPoint — interface @experimental
+## TouchPoint — interface @beta
```
id: number
x: number
@@ -8223,7 +8223,7 @@ x: number
y: 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.md
index 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 (): AchievementsAPI
static 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: string
type: "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: string
FilterEffectDef | ReverbEffectDef | CompressorEffectDef
```
-## Button — const @experimental
+## Button — const @public
```
(...bindings: Binding[]) => ActionDef
```
@@ -2932,7 +2932,7 @@ static prototype: GameSocket
PlatformSocketOptions
```
-## GamepadAxis — enum @experimental
+## GamepadAxis — enum @public
```
LeftX = 0
LeftY = 1
@@ -2940,7 +2940,7 @@ RightX = 2
RightY = 3
```
-## GamepadButton — enum @experimental
+## GamepadButton — enum @public
```
Back = 8
DpadDown = 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) | undefined
onWheel: ((deltaX: number, deltaY: number, mods: Modifiers) => boolean | void) | undefined
```
-## InputMap — class @experimental
+## InputMap — class @public
```
+@internal evaluate: (input: InputState) => void
actions: () => string[]
axis2d: (name: string) => Vec2
cancelListen: () => void
down: (name: string) => boolean
-evaluate: (input: InputState) => void
getBindings: (name: string) => Binding[]
isListening: () => boolean
listenForBinding: (opts?: ListenOptions) => Promise<Binding | null>
@@ -3247,7 +3247,7 @@ static new (actions: Record<string, ActionDef>): InputMap
static prototype: InputMap
```
-## InputMapAsset — interface @experimental
+## InputMapAsset — interface @public
```
actions: Record<string, ActionDef>
version: number
@@ -3281,7 +3281,7 @@ static new (): InputRouter
static prototype: InputRouter
```
-## InputState — class @experimental
+## InputState — class @beta
```
beginFixedStep: () => void
clearFrameState: () => 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: number
value: 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: Vec2
world: World
```
-## ListenOptions — interface @experimental
+## ListenOptions — interface @public
```
gamepad: boolean | undefined
keyboard: boolean | undefined
@@ -4339,7 +4339,7 @@ shift: boolean
ComponentDef<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 | undefined
world: World
```
-## TouchPoint — interface @experimental
+## TouchPoint — interface @beta
```
id: number
x: number
@@ -8468,7 +8468,7 @@ x: number
y: 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.md
index 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 (): AchievementsAPI
static 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: string
type: "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: string
FilterEffectDef | ReverbEffectDef | CompressorEffectDef
```
-## Button — const @experimental
+## Button — const @public
```
(...bindings: Binding[]) => ActionDef
```
@@ -2932,7 +2932,7 @@ static prototype: GameSocket
PlatformSocketOptions
```
-## GamepadAxis — enum @experimental
+## GamepadAxis — enum @public
```
LeftX = 0
LeftY = 1
@@ -2940,7 +2940,7 @@ RightX = 2
RightY = 3
```
-## GamepadButton — enum @experimental
+## GamepadButton — enum @public
```
Back = 8
DpadDown = 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) | undefined
onWheel: ((deltaX: number, deltaY: number, mods: Modifiers) => boolean | void) | undefined
```
-## InputMap — class @experimental
+## InputMap — class @public
```
+@internal evaluate: (input: InputState) => void
actions: () => string[]
axis2d: (name: string) => Vec2
cancelListen: () => void
down: (name: string) => boolean
-evaluate: (input: InputState) => void
getBindings: (name: string) => Binding[]
isListening: () => boolean
listenForBinding: (opts?: ListenOptions) => Promise<Binding | null>
@@ -3254,7 +3254,7 @@ static new (actions: Record<string, ActionDef>): InputMap
static prototype: InputMap
```
-## InputMapAsset — interface @experimental
+## InputMapAsset — interface @public
```
actions: Record<string, ActionDef>
version: number
@@ -3288,7 +3288,7 @@ static new (): InputRouter
static prototype: InputRouter
```
-## InputState — class @experimental
+## InputState — class @beta
```
beginFixedStep: () => void
clearFrameState: () => 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: number
value: 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: Vec2
world: World
```
-## ListenOptions — interface @experimental
+## ListenOptions — interface @public
```
gamepad: boolean | undefined
keyboard: boolean | undefined
@@ -4101,7 +4101,7 @@ shift: boolean
ComponentDef<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 | undefined
world: World
```
-## TouchPoint — interface @experimental
+## TouchPoint — interface @beta
```
id: number
x: number
@@ -8230,7 +8230,7 @@ x: number
y: 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.mjs
index 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.