InputAPI reference
Namespace MicroEngine.Input
Input: device events with ids (keys, text, pointers and touches, wheel, gamepads), players and device pairing, input layers, and actions over them: bindings and their persistence, analog values, on-screen controls, prompts, custom sources.
Guide: Input
Classes
The bindings of one action as data, by name (keys, buttons and axes are their enum names), so saved bindings stay valid when the engine adds keys. Part of InputBindingSet.
What an action is bound to, for display or a rebinding screen (GetBindings).
The action names the engine’s own parts read: the widget tree’s focus and confirm (UiRoot), the default
on-screen controls and prompts. They are defaults the game may rename: build the
map with CreateDefault or set Names, and every engine
part follows.
Tells the player which control presses an action on the device they are using, so dialogues, tutorials, help screens and hints never name a key the player does not have. The text follows the active device (the one that last pressed an action, touch while the on-screen controls are shown), the action’s current bindings (remapping included) and the touch layout, and changes as soon as the player switches device: read it every frame, or when Version changes. Games get one in Prompts.
A base for input backends of platforms whose system reports input as it happens or as per-frame state: a backend
emits events (Emit) while it processes the system’s, and the engine drains them
(Drain). It also answers the polled questions (IInputSource) from the same events, for
code that reads a platform’s Input directly; there a press shorter than a frame reads as held until the next
BeginFrame.
The built-in look, shaped by TouchStyle. Idle controls are an outlined shape at the style’s opacity; a pressed one is filled, outlined thicker and drawn slightly smaller (pressed in), so the press reads by shape as well as colour, even at low opacity. A dark halo keeps outlines legible on light scenes. A d-pad lights the arrows it presses and marks where the thumb is; a joystick shows its base, its dead zone, the knob at the thumb’s deflection and an arrow on the rim whose opacity follows the intensity. Images replace fills and outlines.
Where the virtual canvas goes in a window: the shared letterbox rule of every backend.
Every action’s bindings as data, for a rebinding screen to save and load: through SaveBindings
and LoadBindings (the platform’s storage), or as a value a game keeps in its own save
(SaveStore.Save(“bindings”, map.ExportBindings()); the classes have public properties).
A connected device as its backend describes it.
The state of every device, derived from the events no input layer took: which keys and buttons are held, where the axes, the pointers and the wheel are, and which devices are connected. A press that started and ended between two updates still reads as held until an update has sampled it (EndSample): taps expire by updates, never by drawn frames. Players read it through views limited to their devices (View).
The orders of the engine’s own layers. Higher orders see events first; gameplay is below every layer.
The input layers in routing order: highest order first, layers of equal order in the order they were added.
Events no layer takes become the polled state actions read (InputDevices) and the frame’s
Events.
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.
The engine’s input: the devices and their events, the routing through input layers, the players and their action maps, and the text channel. Each frame the events of the platform’s input backend (and those sent with Send) are routed through Layers; what no layer takes becomes the devices’ polled state and Events. Each update samples every player’s map from the devices they hear.
A key pressed while a modifier is held: new KeyChord(Key.Enter, Key.LeftAlt, Key.RightAlt) is Alt+Enter with
either Alt key. The chord is down while Key and any one of Modifiers are down.
The physical position of each Key as a USB HID keyboard usage (page 7), the code SDL calls a scancode: backends that report HID usages map them with one table.
A clipboard that only remembers its text: the headless platform’s, and a stand-in where there is no system clipboard.
Shapes built from IOverlayCanvas triangles and rectangles, which never overlap, so translucent colours stay even.
One local player: an action map of their own (Map) read from the devices paired with them.
The local players. With no setup there is one player who owns every device, so a single-player game never deals
with players at all (Game.Input is player 1’s map). For local multiplayer, pair devices explicitly: a
device paired with a player is heard only by that player, and once player 1 has a device of their own they stop
hearing the devices nobody was given.
The text channel, separate from actions: while it is on, characters typed (and the text an input method is composing) arrive here instead of as keys to remember. Turn it on for name entry, chat or a console; on phones it shows the on-screen keyboard. A layer above gameplay (a text field) may take text events itself.
A button that presses an action (and optionally more, as one key may: Also = [“confirm”] on a jump button).
One on-screen control of a TouchLayout. Positions and sizes are density-independent pixels (dp, 1/160 inch), so a control keeps its physical size on any screen; the layout shrinks everything when a screen is too small.
A d-pad: discrete directions with no analog value, for games where a precise press matters more than a smooth one (platformers, grid movement, menus). The thumb anywhere around its centre presses the direction it points to.
A game’s on-screen controls: which controls, where, and how they look and feel. The same layout is used on phones
(SDL), in mobile browsers and in tests; games return theirs from Game.CreateTouchLayout.
An analog joystick: a 2D value with intensity (Vector) and, beyond Threshold, the four direction actions as well, so digital code keeps working.
How touch controls look: shape, colours of each state, outline, press feedback and optional images. Only the drawing changes: hit areas, finger tracking and actions stay those of the layout, so a restyled control behaves exactly as before. Colours left null follow Tint and PressedTint. Set one style for every control kind (ButtonStyle, DPadStyle, StickStyle) or for one control (Style).
On-screen controls at run time: hit testing, finger tracking, d-pad and joystick values, tap latching, haptics and drawing. It is an IActionSource (read by InputMap with the keyboard and gamepad), an ITouchOverlay (drawn by the backend over the game) and an input layer (IInputLayer, at TouchControls): a finger that lands on a control is the control’s, every other finger goes on to gameplay as a pointer. Each finger belongs to the control it started on until it lifts, so two thumbs work independently and a thumb that slides a little stays on its control.
Structs
How to show one action to the player on one device: “Z” on a keyboard, “A” on an Xbox pad,
“×” on a PlayStation pad, the button’s own label on a touch screen. Text is what to print;
Kind and the other members let a game draw a glyph instead (a key cap, a coloured pad button).
Identifies one input device for as long as it is connected: a keyboard, a mouse, a touch screen, one gamepad. Ids are chosen by whoever reports the device (a backend’s own ids are positive; the engine’s polled sources and touch screen use negative ones) and are never reused while the game runs.
One thing that happened on an input device, in the order it happened, with the time it happened on the host’s monotonic clock. Backends deliver them (IInputBackend); the engine routes them through the input layers (UI, on-screen controls, then gameplay) and derives the polled state actions read from those no layer took. Build one with the static methods (KeyDown, PointerDown…).
A pointer the game can read: the mouse while it is over the window, or a finger or pen on the screen.
The mouse (or another pointer) over the game’s virtual canvas.
One event of the frame and where it went (Routed).
Everything a skin needs to draw one control as it is this frame, in screen pixels.
One change of one finger, in the touch screen’s pixels (Size).
Interfaces
A source of actions rather than of keys: on-screen touch controls, a network peer, an accessibility switch or an AI. Added with AddSource, it is read every step together with the keyboard and gamepad, so a game cannot tell which produced an action.
The system clipboard’s text: a platform capability (Game.TryGetCapability). Text fields copy, cut and paste
through it (MicroEngine.UI.TextField); a game may use it for its own “copy the seed” or “paste a code” buttons.
Gamepad vibration, a capability of input backends whose pads can rumble.
The input part of a platform: the devices and what happens on them, delivered as events. A capability of hosts with input (TryGetCapability``1); the engine drains it once per frame, at the start of the frame’s input phase.
One stage of input routing: user interface, on-screen controls, a debug console, a rebinding screen. Events reach the layers from the highest order down (InputLayers); a layer that returns true takes the event, and nothing below it (other layers, the actions of gameplay) sees it.
The raw device state a backend reports once per polled frame.
The labels the player’s keyboard layout prints on keys: “Q” for A on AZERTY. A capability of input backends that know the layout (TryGetCapability``1).
Primitive drawing in screen pixels, implemented by each backend for ITouchOverlay.
Turns the system’s text input on and off: the on-screen keyboard on phones, input methods (IME) on desktops. A capability of input backends that deliver Text.
Something drawn over the game on the touch screen, such as VirtualControls.
A screen that may be touched, a capability a backend offers (TryGetCapability``1): its drawable size, the
area free of notches, rounded corners and system bars, its density, the touches since the last frame, and a layer
drawn over the game for on-screen controls. Coordinates are drawable pixels with the origin at the top left.
SDL reports phones and touch screens, the browser host reports Pointer Events, the headless platform lets tests
touch it (HeadlessTouchScreen).
Draws touch controls. The engine calls it for each shown control with its state; a game may replace the whole look (Skin) and still delegate kinds it does not change to Instance.
Enums
The kind of an input device.
The button names of a gamepad family, for prompts: PadButton uses Xbox names, which PlayStation pads show as shapes and Nintendo pads with A/B and X/Y swapped.
The kind of device that last pressed an action (see LastDevice).
What an InputEvent reports.
The direction of the left stick an action is bound to (None, Left, Right, Up,
Down). The action is down when the stick points that way beyond StickThreshold, and its
Value is the deflection along that direction.
Physical keys, named by their position on a US keyboard (a scancode, not a character): A is the key
left of S whatever the layout prints on it, so WASD movement stays in place on AZERTY or Dvorak. Ask
IKeyLabels (or ActionPrompts) for the label the player’s layout shows. Backends map their own
codes onto these; the set covers a full-size keyboard.
Analog gamepad axes. Sticks are -1..1 (right and down positive), triggers 0..1.
Gamepad buttons by position, using Xbox names (A is the bottom face button on every pad); backends map their own codes. GamepadStyle says what the pad prints there.
Pointer buttons. A finger or pen tip is Primary.
What kind of pointer moved or pressed: the mouse, a finger on a touch screen or a pen.
What an ActionPrompt shows: a key, a gamepad control, an on-screen control, or a plain label.
How a 2D stick turns into the four direction actions.
Where a virtual joystick’s base is.
Which corner or edge of the safe area a touch control is placed from.
How a touch button drives its action.
What happened to a finger in a TouchEvent: it touched the screen (Began), moved (Moved),
was lifted (Ended), or the system took it away, for example when the game left the screen (Canceled).
The outline of a drawn touch control.
When on-screen controls are drawn.