ControlMap
Unified mapping from remote-button and controller input to named actions/axes - the one class a game needs to learn to support both input sources. Exposed as Game.controls; see Game.enableControllerInput().
Constructor
new ControlMap(
registry: BGE.Controller.ControllerRegistry,
): ControlMapParameters
registry(BGE.Controller.ControllerRegistry)
Instance Methods
bindAction(
name: string,
remoteButton?: string,
controllerButton?: string,
playerIndex?: integer,
label?: string,
): void
Binds a logical action name to a remote button and/or a specific player's named controller button - either source fires the action. A controller button name is whatever the browser page sends (see controller-web/index.html) - any name works, including one a custom controller page invents for its own control, with no engine change.
Parameters
name(string) — the logical action name, e.g. "jump"remoteButton(string, optional, default: "invalid") — a remote button name (see BGE.GameInput.isButton)controllerButton(string, optional, default: "invalid") — a controller button nameplayerIndex(integer, optional, default: 0) — which controller's button this binds tolabel(string, optional, default: "invalid") — shown to the player on the controller page for this control
Returns
void
bindAxis(
name: string,
stick?: string,
playerIndex?: integer,
label?: string,
): void
Binds a logical axis name to a player's named controller stick. getAxis() falls back to the remote d-pad whenever that stick reads neutral, so a game written against this axis works with just a remote connected. A d-pad-only controller page sends its d-pad as just another named stick (snapped to -1/0/1 per axis) - no separate binding call needed.
Parameters
name(string) — the logical axis name, e.g. "move"stick(string, optional, default: "\"1\"") — the stick's name, as sent in the message'ssticksmapplayerIndex(integer, optional, default: 0) — which controller's stick this binds tolabel(string, optional, default: "invalid") — shown to the player on the controller page for this control
Returns
void
hasBindings(): boolean
Returns
boolean
hasAxisBinding(name: string): boolean
Parameters
name(string) — a name previously passed to bindAxis()
Returns
boolean
beginFrame(): void
Starts a new frame: clears the one-shot press/release flags so they only read true on the frame their event arrived. held is a snapshot of "currently down", not a transient, so it is left alone here and only changes when a later onInput() says otherwise. Called once per frame by Game - a game does not call this directly.
Returns
void
onInput(input: BGE.GameInput): void
Feeds one GameInput event (remote or controller-originated) through every action binding, updating whichever actions it matches. Called once per input event by Game - a game does not call this directly.
Several events for the same binding can arrive in one frame (Game feeds a press and then a held event for the same button), so press/release accumulate across the frame rather than overwriting each other.
Parameters
input(BGE.GameInput)
Returns
void
isActionPressed(name: string): boolean
A binding's playerIndex is fixed at bindAction() time, so reading an action never needs it - the name alone identifies the binding.
Parameters
name(string)
Returns
boolean
isActionHeld(name: string): boolean
Parameters
name(string)
Returns
boolean
isActionReleased(name: string): boolean
Parameters
name(string)
Returns
boolean
getActionHeldTimeMs(name: string): integer
Parameters
name(string)
Returns
integer
getAxis(name: string): BGE.Math.Vector
Parameters
name(string) — a name previously passed to bindAxis()
Returns
BGE.Math.Vector
getCustomPayload(playerIndex?: integer): object
controller page, {} if none sent yet - an escape hatch for a custom on-screen control that isn't button/stick shaped (a slider, etc.)
Parameters
playerIndex(integer, optional, default: 0)
Returns
object
getLabels(): object
Sent to a connecting browser page once (see Game.enableControllerInput()) so a generic controller page can show meaningful text instead of raw names.
Returns
object