Input
Look up the device, trigger, seat, and action model, the value conversions a binding supports, and the tick policies.
Byte Engine records physical input as device-trigger values in one input
collector. Input sinks resolve those values into actions such as Move,
Lookaround, RightHand, View, or Exit, and your application listens for
action events instead of checking raw keys and buttons. This page defines the
pieces of that model. To declare actions, read their events, and give each
consumer its own sink, follow Respond to input.
Device classes
A device class describes the input layout for a category of hardware.
The standard setup registers classes such as Mouse, Keyboard, and Gamepad.
Each class has triggers:
Mouse.Position,Mouse.Movement,Mouse.LeftButton,Mouse.ScrollKeyboard.W,Keyboard.Space,Keyboard.Backspace,Keyboard.CharacterGamepad.LeftStick,Gamepad.RightStick,Gamepad.X,Gamepad.RightTrigger
Each device class declares its named inputs and the value type that each input produces.
Devices
A device is a concrete instance of a class. One keyboard and two gamepads are three devices, even though the gamepads share one device class.
The default graphics setup creates one mouse, one keyboard, and one gamepad device after registering the standard classes.
Custom integrations can register their own classes and create devices directly through InputCollector.
Seats
A seat identifies the player or user context associated with input.
The current default window integration uses SeatHandle::stub() until platform seats are wired through end to end.
Seats let the same type of physical input belong to different users. Input state is stored by seat, device, and trigger, so local multiplayer, split-screen, remote control, or editor/game focus can be represented without changing the action model.
Triggers
A trigger is a named value on a device class. It can be boolean, float, unicode, vector, quaternion, color, or another supported input value type.
Window events are translated into trigger records.
For example, a key press becomes a boolean value for Keyboard.W, mouse motion becomes a Vector2 value for Mouse.Movement, and typed text becomes a unicode value for Keyboard.Character.
The collector queues records until the sinks pull them. When the tick ends, it keeps the latest value for each seat, device, and trigger.
Actions
An action represents input that your application understands. It has:
- an output type
- one or more trigger bindings
- optional value mappings
- a tick policy
For movement, keyboard keys can map to direction vectors, and the resolved action value can be a single Vector3.
For lookaround, mouse position and a gamepad stick can both contribute to the same direction-like action.
Actions are created on the application's world. A Name attached in the same
creation chain lets inspection tools find the action by name.
Value mapping
Bindings can map a trigger value into the action's output type.
Byte Engine doesn't support a general cast between every input value type. The following table lists the conversions that action bindings support:
| Trigger value | Supported action values | Conversion |
|---|---|---|
| Boolean | Boolean, Float, Vector2, Vector3 | A Boolean value passes through unchanged. For a Float action, the binding supplies the scalar value used while the trigger is active. For a Vector2 or Vector3 action, Byte Engine adds the mapped direction from each active Boolean binding, then normalizes the result. |
| Unicode | Unicode | The character passes through unchanged. |
| Float | Boolean, Float | 0.0 becomes false, and any other value becomes true. A Float value passes through unchanged. |
| Integer | None | Action bindings don't convert integer trigger values. |
| Vector2 | Vector2, Vector3 | A Vector2 value passes through unchanged. A Vector3 action can use Function::Sphere to map the two components to a 3D direction and apply the binding's mapped Vector3 transformation. |
| Vector3 | Vector2, Vector3 | Converting to Vector2 keeps x and y and drops z. A Vector3 value passes through unchanged. |
| Quaternion | None | Action bindings don't convert quaternion trigger values. |
| RGBA | None | Action bindings don't convert color trigger values. |
These rules apply when a sink resolves device triggers through action
bindings. An ActionEvent published directly, for example by the inspector,
must carry a value whose type already matches the action type.
For movement, boolean key triggers can map to direction vectors. When multiple movement keys are active, the input resolver combines the active mappings and normalizes the result. This is why diagonal keyboard movement can be represented as one stable movement vector instead of separate key checks.
For lookaround, Function::Sphere can map a 2D input into a 3D direction.
Your application receives a direction-like action value without needing to know
whether it came from mouse position or a stick.
Tick policy
Actions can emit with different policies:
OnChange: emit when input changesWhileActive: emit every frame while the resolved value is non-defaultAlways: emit every frame after the action has a known value
A repeating policy emits at most once per tick for each device: the record that
changes the value is that tick's emission, and later ticks repeat the held value.
Movement usually uses WhileActive so holding a key or stick keeps producing movement events.
Discrete actions such as fire, view toggle, or exit usually use the default change-based behavior.