InputAPI reference
Class InputMap
Namespace: MicroEngine.Input
Assembly: MicroEngine.Input.dll
Guide: Input
Named actions bound to keys, gamepad buttons, stick directions and analog axes, plus any number of action sources (touch controls, custom sources). Games query actions (“jump”, “confirm”), never physical keys, so bindings and scripted input stay in one place. Every action is both digital (Down, Pressed, Released) and analog (Value, Vector): a key is 0 or 1, a stick or a virtual joystick gives the deflection beyond its dead zone. Edge states (pressed/released) are computed per fixed update, so a tap is never lost or doubled.
public sealed class InputMap : IStateHashedInheritance
Implements
Examples
// In a Game subclass: keep the defaults and add a "dash" action.protected override InputMap CreateInput() => InputMap.CreateDefault() .Bind("dash", [Key.LeftShift, Key.N], [PadButton.RightShoulder]);
// In a scene's Update:var move = Input.Vector("left", "right", "up", "down");if (Input.Pressed("confirm")) Audio.Play("select");Constructors
InputMap()
public InputMap()Fields
BindingsSlot
The slot SaveBindings and LoadBindings use unless told otherwise.
public const string BindingsSlot = "input-bindings"Field Value
Properties
Actions
The names of every bound action (including actions unbound with Unbind).
public IEnumerable<string> Actions { get; }Property Value
AxisDeadZone
Dead zone of bound triggers and other single axes (default 0.1).
public float AxisDeadZone { get; set; }Property Value
LastDevice
The device that most recently pressed an action. Touch controls use it to hide while a keyboard or gamepad plays.
public InputDevice LastDevice { get; }Property Value
Names
The engine’s own action names this map uses (menus, dialogs, on-screen controls and prompts read actions by these names). Rename them here when the game calls its actions differently; the default names are Default.
public ActionNames Names { get; set; }Property Value
PadConnected
Whether a gamepad was connected at the last sample.
public bool PadConnected { get; }Property Value
PadStyle
The family of the gamepad at the last sample (Xbox when unknown), for prompts.
public GamepadStyle PadStyle { get; }Property Value
Pointer
The pointer at the last sample: the mouse over the virtual canvas, or a finger on the screen that no on-screen control took (whichever moved last), with the wheel’s turn since the previous update.
public PointerState Pointer { get; }Property Value
Pointers
Every pointer at the last sample: the mouse while over the window, and each finger or pen on the screen that no input layer (such as the on-screen controls) took, in device and id order. Tap-to-move, drag and pinch read it.
public IReadOnlyList<PointerInfo> Pointers { get; }Property Value
Sources
The action sources read with the devices (AddSource).
public IReadOnlyList<IActionSource> Sources { get; }Property Value
StickDeadZone
Radial dead zone of the left stick, as a fraction of full deflection (default 0.2). Values beyond it are rescaled to 0..1.
public float StickDeadZone { get; set; }Property Value
StickMode
How the left stick presses direction actions: eight sectors (default) or four.
public StickDirections StickMode { get; set; }Property Value
StickThreshold
Deflection (after the dead zone) at which a stick direction counts as down (default 0.35).
public float StickThreshold { get; set; }Property Value
Methods
AddSource(IActionSource)
Adds an action source read with the devices at every sample. Its actions need no binding, but unbound names are listed in Actions only once bound.
public InputMap AddSource(IActionSource source)Parameters
source IActionSource
Returns
AnalogAxis(string, string)
-1..1 from two opposing actions, analog when a stick or virtual joystick drives them.
public float AnalogAxis(string negative, string positive)Parameters
negative string
positive string
Returns
ApplyDeadZone(Vector2, float)
Radial dead zone: inside it the stick is centred, beyond it the deflection is rescaled to 0..1.
public static Vector2 ApplyDeadZone(Vector2 stick, float deadZone)Parameters
stick Vector2
deadZone float
Returns
Axis(string, string)
-1, 0 or 1 from two opposing actions.
public int Axis(string negative, string positive)Parameters
negative string
positive string
Returns
Bind(string, params Key[])
Binds keys to action, adding to its existing bindings.
public InputMap Bind(string action, params Key[] keys)Parameters
action string
The action name (case-sensitive, not empty).
keys Key[]
Keys that press the action.
Returns
This map, for chaining.
Exceptions
action is empty.
Bind(string, Key[], PadButton[], StickDirection)
Binds keys, gamepad buttons and optionally a left-stick direction to action, adding to its existing bindings (use Unbind first to replace them).
public InputMap Bind(string action, Key[] keys, PadButton[] buttons, InputMap.StickDirection stick = StickDirection.None)Parameters
action string
The action name (case-sensitive, not empty).
keys Key[]
Keys that press the action.
buttons PadButton[]
Gamepad buttons that press the action.
stick InputMap.StickDirection
A left-stick direction that presses the action; None keeps the current one.
Returns
This map, for chaining.
Exceptions
action is empty.
Bind(string, params KeyChord[])
Binds key combinations (KeyChord: Alt+Enter, Ctrl+S) to action, adding to its existing bindings.
public InputMap Bind(string action, params KeyChord[] chords)Parameters
action string
chords KeyChord[]
Returns
Exceptions
action is empty.
BindAxis(string, PadAxis, bool)
Binds one side of an analog axis: BindAxis(“aim-right”, PadAxis.RightX, positive: true), or a trigger
(BindAxis(“fire”, PadAxis.RightTrigger)). The action is down beyond half travel and its
Value follows the axis.
public InputMap BindAxis(string action, PadAxis axis, bool positive = true)Parameters
action string
axis PadAxis
positive bool
Returns
BindFrom(string, in InputEvent, bool)
Binds the key or gamepad button of press (a key-down or button-down event, such as the one
ListenForPress hands over) to action, adding to its bindings; with
replace, the action’s keys (for a key) or buttons (for a button) are replaced.
public bool BindFrom(string action, in InputEvent press, bool replace = false)Parameters
action string
press InputEvent
replace bool
Returns
False when the event is neither a key-down nor a button-down.
BindFullscreenDefaults()
Binds Fullscreen (in Names) to F11 and Alt+Enter, the usual desktop toggle; no gamepad button has that meaning by convention, so none is bound. The engine calls this for a map that has no such action, so a game that never mentions it keeps the toggle.
public InputMap BindFullscreenDefaults()Returns
Consume(string)
Takes the action for whoever read it first in this update: from now until it is let go, it reads as up for everyone (not Down, Pressed or Released, value 0). A menu over a scene that both read “confirm” consumes it, so the scene below does not act on the same press. Does nothing when the action is not down.
public bool Consume(string action)Parameters
action string
Returns
Whether the action was down and is now consumed.
CopyBindings()
A new map with the same bindings, names and stick and axis settings, and no sampled state or action sources: the starting point of another player’s map.
public InputMap CopyBindings()Returns
CreateDefault(ActionNames?)
A conventional binding set shared by the sample games: arrows, WASD, the d-pad and the left stick move; confirm,
cancel, action and pause on keys and face buttons. names renames the engine’s actions (null
keeps Default), and the map keeps them in Names.
public static InputMap CreateDefault(ActionNames? names = null)Parameters
names ActionNames?
Returns
Directions(Vector2, float, StickDirections)
The directions a 2D input presses: none inside threshold, else by 45° or 90° sectors.
public static IReadOnlySet<InputMap.StickDirection> Directions(Vector2 v, float threshold, StickDirections mode)Parameters
v Vector2
threshold float
mode StickDirections
Returns
IReadOnlySet<InputMap.StickDirection>
Down(string)
Whether the action is held in this update. Also true for a press that started and ended within the last frame, so a quick tap is never missed. Unknown actions are never down.
public bool Down(string action)Parameters
action string
Returns
EndUpdate()
Advances edge detection. Called by the runner after each fixed update.
public void EndUpdate()ExportBindings()
Every action’s bindings as data (see InputBindingSet), in ordinal order of the names.
public InputBindingSet ExportBindings()Returns
GetBindings(string)
What the action is bound to; null for an unknown action.
public ActionBindings? GetBindings(string action)Parameters
action string
Returns
HashState(StateHasher)
Adds the sampled state to the per-step state hash: the actions down, down in the previous update, latched and forced (each in ordinal order), every action’s value, the last device, the gamepad’s connection and style, and the pointer. Bindings are configuration, not state, and are left out.
public void HashState(StateHasher hash)Parameters
hash StateHasher
ImportBindings(InputBindingSet)
Replaces the bindings of the actions this map has with those in set. Actions the set does not
mention keep theirs; actions the map does not have are ignored (a renamed or removed action does not come back),
and so are names of keys, buttons or axes this version does not know.
public int ImportBindings(InputBindingSet set)Parameters
set InputBindingSet
Returns
The number of actions whose bindings were replaced.
IsConsumed(string)
Whether Consume took the action and it has not been let go yet.
public bool IsConsumed(string action)Parameters
action string
Returns
LoadBindings(IStorage, string)
Reads bindings saved with SaveBindings and applies them (ImportBindings). Returns false and keeps the current bindings when nothing was saved or the data is unreadable (which is set aside, so the next save does not destroy it).
public bool LoadBindings(IStorage storage, string slot = "input-bindings")Parameters
storage IStorage
slot string
Returns
Pressed(string)
True during the first update after the action went down, even if it was released within the same frame.
public bool Pressed(string action)Parameters
action string
Returns
Released(string)
True during the first update after the action was let go. A tap that started and ended within one frame reports Pressed in its update and Released in the next one.
public bool Released(string action)Parameters
action string
Returns
RemoveSource(IActionSource)
Stops reading source; returns false when it was not added.
public bool RemoveSource(IActionSource source)Parameters
source IActionSource
Returns
Reset()
Clears every state, e.g. after a scene change, so held keys must be pressed again.
public void Reset()Sample(IInputSource)
Samples devices and action sources. Called by the runner before each fixed update.
public void Sample(IInputSource source)Parameters
source IInputSource
SaveBindings(IStorage, string)
Writes every action’s bindings to storage (the slot slot), for a rebinding screen.
public void SaveBindings(IStorage storage, string slot = "input-bindings")Parameters
storage IStorage
slot string
Exceptions
The storage failed.
SetForced(string, bool)
Forces an action down regardless of devices (scripted playback, tests).
public void SetForced(string action, bool down)Parameters
action string
down bool
Unbind(string)
Removes every key, chord, button, stick and axis bound to the action (the action stays, unbound), to rebind or turn it off. An action the map does not have yet becomes one with no binding, so the engine adds no default binding to it (Fullscreen).
public InputMap Unbind(string action)Parameters
action string
Returns
Exceptions
action is empty.
Value(string)
The action’s strength in 0..1: 1 for a key or button, the deflection beyond the dead zone for a stick, trigger or virtual joystick. A stick that is deflected but below StickThreshold has a value without being down.
public float Value(string action)Parameters
action string
Returns
Vector(string, string, string, string)
A 2D direction from four actions, at most 1 long: keys give unit vectors (diagonals normalised), a stick or a
virtual joystick gives its deflection. Input.Vector(“left”, “right”, “up”, “down”).
public Vector2 Vector(string left, string right, string up, string down)Parameters
left string
right string
up string
down string