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:
- Register device classes and triggers.
- Create concrete devices for those classes.
- Create application actions with trigger bindings.
- Translate platform events into trigger records on the collector.
- Let every sink pull, then end the collector's tick.
- 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.