Byte Engine Docs

Respond to input

Turn keys, buttons, and sticks into the actions your application understands.

Define input as application actions so your gameplay code responds to intent instead of specific devices.

This keeps your application code focused on intent. Keyboard.W, Keyboard.S, Gamepad.LeftStick, and a VR controller axis can all contribute to the same movement action without changing the movement system.

This page shows how to declare actions, read their events, and give each consumer its own sink. The model behind them, such as device classes, triggers, the value conversions a binding supports, and tick policies, is in the input reference.

Build actions

Follow this flow:

  1. Register device classes and triggers.
  2. Create concrete devices for those classes.
  3. Create application actions with trigger bindings.
  4. Translate platform events into trigger records on the collector.
  5. Let every sink pull, then end the collector's tick.
  6. Listen for action events in application or engine systems.

Most headed applications use setup_default_input for the first two steps and process_default_window_input for platform window events. That default path installs the standard mouse, keyboard, and gamepad names used by action bindings.

Publish a value when a button is released

A binding can publish one source's value when another source records a release (false). For example, a mouse click can publish the current cursor position. The application receives the position in one action without maintaining a separate cursor action or cached position.

The trigger must be boolean and belong to the value source's device class. The sink samples the latest recorded value from the same seat and device at each release by default. Choose TriggerMode::Press with trigger_on to sample on press instead. Movement alone doesn't emit this binding. If no value has been recorded yet, the trigger produces no event. Records are processed in queue order, so multiple clicks in one update retain their own positions. Actions containing these bindings bypass their tick policy to avoid repeating a captured value on later ticks.

Follow a drag

Use one action to receive the position at press, each movement while held, and release:

let drag = Action::new(
    &[ActionBindingDescription::new("Mouse.Position").dragged_by("Mouse.LeftButton")],
    Types::Vector2,
);

Read ActionEvent::phase() to handle ActionPhase::Started, Updated, and Ended. Each event carries the current position in value(). Store the start position in your application if you need a displacement or selection rectangle. Drags start immediately on press and bypass tick policy, so an idle pointer does not repeat drag events. The position must have a recorded value when the button is pressed. Moving after a press without a sample doesn't begin a drag.

With several sinks, check ResolvedAction::phase and return Capture::Captured for a start inside your target. The sink then captures that drag's movement and release even outside the target. Keep pulling that sink until release or cancellation. A passed start can reach the next sink.

Call InputSink::cancel_action, cancel_seat, or cancel_device when focus changes or a device disconnects. A cancelled drag emits ActionPhase::Cancelled with its last position. Discard the operation instead of committing it. The button needs a fresh press to start another drag. Cancellation events are delivered through the action event channel.

Read actions

Create a listener from the input event channel, then filter it by action handle. Read the filtered stream in your application tick loop or in the system that owns the input-driven behavior.

This is the same message pattern used elsewhere in the engine. Sinks publish action events, and gameplay/application code consumes the actions it understands. Raw devices stay behind the collector.

Trigger actions from the inspector

An inspector-triggered action must be created through GraphicsApplication::world and have a Name so tools can find its target through the entity query endpoint.

The message endpoint accepts a TriggerAction message containing the target and a value that matches the action's type. The inspector publishes the canonical ActionEvent directly to the same channel used by physical input. The message-type endpoint describes the supported value variants and their payload shapes.

Give each consumer its own sink

Input arrives in two steps. Every source event ends up in one InputCollector: window keys and buttons, pointer motion, gamepad controls, and replayed samples all become control records there. Then every distinct consumer, such as a UI, gameplay, or a debug overlay, owns an InputSink that declares its actions and pulls them from the collector once per tick.

Register controls on the collector and create devices with collector.create_device(&class). Take one SinkHandle per sink with collector.add_sink(). Each sink retains its action values, so pulling needs no frame allocator.

Pull sinks in priority order. A record is dropped once every sink has pulled past it:

let mut collector = InputCollector::new();
let mut ui = InputSink::new(collector.add_sink(), ui_channel).with_declarations(ui_actions.listener());
let mut game = InputSink::new(collector.add_sink(), game_channel).with_declarations(game_actions.listener());

// Each tick, after recording window input into `collector`:
ui.pull(&mut collector, |action| Capture::when(ui_handles(action)));
game.pull(&mut collector, |action| { play(action); Capture::Passed });

Use InputCollector::new_in and InputSink::new_in to choose the allocator for retained input storage. The new constructors use Rust's global allocator. A collector and its sinks can use different allocators.

let storage = bumpalo::Bump::new();
let mut collector = InputCollector::new_in(&storage);
let mut ui = InputSink::new_in(collector.add_sink(), ui_channel, &storage);

Keep the allocator alive for the input objects' lifetime. The queue reuses its capacity and retains control state. Reset an arena after dropping those objects. The allocator covers registered names, buffers, bindings, and action values. Channels and action factories keep their own allocation policies.

A sink's consumer answers Capture::Captured for an action it handled. The record behind that action stops there, so no later sink turns the same input into another action. Capture::Passed lets the input continue down the chain. Each sink also publishes its actions to its own channel, so systems that only observe actions can keep using listeners.

Sinks don't share actions. Give each one its own action factory, and bind the same control in as many sinks as you need: only the sink that captures it decides what the input means this tick.

Use InputSink::capture_pending for a context that must swallow input it has no action for, such as a modal dialog over a scene.

Decide with the value, not with layout

Bind the value your decision needs, instead of querying the UI mid-tick. A binding that publishes the cursor position when a button is released gives the sink the exact click position:

ActionBindingDescription::new("Mouse.Position").triggered_by("Mouse.LeftButton")

Clicks default to release. To capture the position on press, choose the phase:

ActionBindingDescription::new("Mouse.Position")
    .triggered_by("Mouse.LeftButton")
    .trigger_on(TriggerMode::Press)

While deciding capture, ask the UI engine what's under the pointer with Engine::hit. The query takes normalized window coordinates, answers from the last evaluated frame's clipped rectangles, and neither allocates nor runs layout.

Set decorative and full-screen transparent containers to Container::hit_testable(false) so uncovered areas pass through. Their children can remain interactive. The retained query uses rectangular bounds. It doesn't perform alpha or rounded-corner hit testing.

Subscribe to app.messages().channel::<ghi::window::Event>() before creating a window. In the ordinary tick_with callback, take the Event::Window values, record their event with process_default_window_input into your own InputCollector, then pull your sinks. Each window event carries the WindowId of the window it targets, so an app with several windows can route input per window. The function returns true when focus loss, minimizing, closing, or resizing discarded the seat, so cancel your sinks' held actions on that tick. Omit setup_default_input when the app owns this pipeline, so the application's own sink doesn't publish competing actions. Window close and renderer lifecycle handling still belong to the graphics application.

Handle holds, impulses, and cancellation

Capturing a press claims its control until it's released, so a drag keeps working when the pointer leaves the surface that started it, and the release reaches the sink that owns the drag. A control another sink captured contributes nothing to this sink's actions, so its held keys can't join your movement vector. Repeated down records from platform key repeat are still one hold.

Mark custom impulse controls with TriggerDescription::transient(). Standard mouse movement, scroll, and keyboard character controls already use this flag. An impulse never claims a control and never repeats through a tick policy.

Call InputSink::cancel_action when a sink's consumer loses focus while holding an action, or InputSink::cancel_device when a device is suspended. The action publishes its neutral value with ActionEvent::is_cancelled and stops repeating. Cancellation needs no access to the collector. The interrupted press stays captured until release, so a later sink needs a fresh press. End the interaction on a cancelled action instead of treating it as a successful release.

Call InputCollector::reset_seat when a window loses focus, so a release the platform never delivers can't keep a control captured.

Keep the application's sink instead

GraphicsApplication owns one collector and one sink for the actions declared through its world. That sink pulls before your tick callback and captures nothing, which is all a single-consumer application needs. It's what setup_default_input and the standard tick_with loop install. Read its events from app.world().channel::<ActionEvent>().

Choose one of the two paths per application. The application's sink pulls its whole collector before your callback runs, so a sink placed beside it can't capture anything from it.

Practical guidance

Name actions after intent, not hardware. Use Move, Lookaround, Fire, or Confirm rather than WKey or LeftMouseButton.

Put hardware names in bindings. That's where Keyboard.W, Mouse.LeftButton, and Gamepad.X belong.

Choose the output type that downstream code wants to read. Movement code usually wants a vector. Text input wants unicode and editing actions. Buttons and toggles usually want booleans.

Use seats even when there is only one player. The default seat keeps the API shape consistent, and code written against seats is easier to extend later.

Keep action payloads small. Input is hot-path code, so prefer compact values and local state over allocating per-binding structures in the app loop.

Rust API

On this page