NEOLearn

Touch

Read fingers on a touch screen with the Touches resource and TouchInput messages, and how NEO's on-screen controls work on phones and tablets.

Updated October 20, 2026

On this page

Every finger on a touch screen is a touch with an id that stays the same from the moment it lands until it lifts. The Touches resource holds the fingers that are down now and those that changed this frame; TouchInput messages report each change.

The Touches resource#

src/main.rs
use neo::{input::touch::Touches, prelude::*};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Update, fingers)
        .run();
}

fn fingers(touches: Res<Touches>) {
    for touch in touches.iter_just_pressed() {
        info!("finger {} down at {}", touch.id(), touch.position());
    }
    for touch in touches.iter() {
        info!("finger {} moved {} this frame", touch.id(), touch.delta());
    }
    for touch in touches.iter_just_released() {
        info!("finger {} up after {}", touch.id(), touch.distance());
    }
    for touch in touches.iter_just_canceled() {
        info!("finger {} canceled", touch.id());
    }
}
MethodReturns
iter()The fingers that are down.
iter_just_pressed(), iter_just_released(), iter_just_canceled()The fingers that changed this frame.
get_pressed(id), get_released(id)One finger, by id.
just_pressed(id), just_released(id), just_canceled(id)Whether that finger changed this frame.
any_just_pressed(), any_just_released(), any_just_canceled()Whether any finger did.
first_pressed_position()Where the first finger that's down is.

Each Touch has id(), position(), previous_position(), start_position(), delta() (since last frame), distance() (since it landed) and force(), which is None where the screen doesn't measure pressure.

Positions are in logical pixels from the window's top-left corner, like the mouse cursor. A touch is canceled, rather than released, when the system takes it away, for example when the window loses focus.

Touch messages#

TouchInput messages carry each change in order: phase (TouchPhase::Started, Moved, Ended or Canceled), position, force, id and window.

Rust
use neo::input::touch::TouchInput;

fn log_touches(mut touches: MessageReader<TouchInput>) {
    for t in touches.read() {
        info!("{:?} finger {} at {}", t.phase, t.id, t.position);
    }
}

Touches and picking#

Picking treats each finger as its own pointer (PointerId::Touch(id)), so a tap on a UI button, sprite or mesh sends the same PointerClick as a mouse click. For buttons and draggable things, observe pointer events rather than reading touches; see Picking.

Touch controls in NEO games#

On iOS, Android and the web, NEO's input kit adds on-screen controls (neo_input_kit::touch::TouchControlsPlugin) on top of the keyboard and gamepad mapping. In a phone's or tablet's browser the page's touch pointer events become touches, so the same controls work in mobile Safari and Chrome on Android, inside an iframe too:

TouchWhat it does
Left half of the screenA move stick that appears where your thumb lands. Pushing past its ring sprints.
Right halfDrag to turn the camera.
Jump, Action, CrouchJump (vault or mantle near an obstacle), interact, and toggle crouching.
SprintSprint until you let go of the stick, like pressing in a gamepad's left stick.

Every finger counts on its own, so you can hold the stick, drag the camera and press a button at the same time. A tap that lands and lifts within one frame still presses its button, once.

The controls stay out of the screen's safe area (TouchSafeArea), hide while a menu blocks input, and add to what a paired controller does rather than replacing it. Set TouchControls::enabled to false to turn them off; TouchControls::visible says whether they show this frame. Desktop and console builds don't add them. TouchSettings holds the stick radius, the dead zone, the sprint distance and the drag sensitivity.

Switching between touch and other input#

neo_input_kit::LastInput records the kind of device the player used last (InputKind::Touch, KeyboardMouse or Gamepad) and counts the switches. The on-screen controls show only while it's Touch: a key, a mouse button, the wheel, a gamepad button or a stick pushed past half hides them, and the next finger brings them back. Phones start on touch and other platforms on the keyboard; a web build starts on touch when the browser's main pointer is coarse (a phone or tablet).

Rust
use neo::prelude::*;
use neo_input_kit::{InputKind, LastInput};

fn show_hints(last: Res<LastInput>) {
    if last.is_changed() && last.kind == InputKind::Touch {
        info!("showing touch hints");
    }
}

Camera drag#

The camera finger's movement is measured from where it was when the controls last read it (TouchControls::look_from), not from Touch::delta(). delta() repeats the last move in frames without new touch events, so a drag measured from it would turn the camera too far on a screen that sends fewer events than the game draws frames.

To check touch handling where you can't touch the screen, such as the iOS Simulator, TouchScript plays scripted touches through the same TouchInput path.

Examples: cargo run --example touch_input and touch_input_events (they need a touch screen).

Next steps#