bevy/crates/bevy_input/src/touch.rs
Joona Aalto 38c3423693
Event Split: Event, EntityEvent, and BufferedEvent (#19647)
# Objective

Closes #19564.

The current `Event` trait looks like this:

```rust
pub trait Event: Send + Sync + 'static {
    type Traversal: Traversal<Self>;
    const AUTO_PROPAGATE: bool = false;
    
    fn register_component_id(world: &mut World) -> ComponentId { ... }
    fn component_id(world: &World) -> Option<ComponentId> { ... }
}
```

The `Event` trait is used by both buffered events
(`EventReader`/`EventWriter`) and observer events. If they are observer
events, they can optionally be targeted at specific `Entity`s or
`ComponentId`s, and can even be propagated to other entities.

However, there has long been a desire to split the trait semantically
for a variety of reasons, see #14843, #14272, and #16031 for discussion.
Some reasons include:

- It's very uncommon to use a single event type as both a buffered event
and targeted observer event. They are used differently and tend to have
distinct semantics.
- A common footgun is using buffered events with observers or event
readers with observer events, as there is no type-level error that
prevents this kind of misuse.
- #19440 made `Trigger::target` return an `Option<Entity>`. This
*seriously* hurts ergonomics for the general case of entity observers,
as you need to `.unwrap()` each time. If we could statically determine
whether the event is expected to have an entity target, this would be
unnecessary.

There's really two main ways that we can categorize events: push vs.
pull (i.e. "observer event" vs. "buffered event") and global vs.
targeted:

|              | Push            | Pull                        |
| ------------ | --------------- | --------------------------- |
| **Global**   | Global observer | `EventReader`/`EventWriter` |
| **Targeted** | Entity observer | -                           |

There are many ways to approach this, each with their tradeoffs.
Ultimately, we kind of want to split events both ways:

- A type-level distinction between observer events and buffered events,
to prevent people from using the wrong kind of event in APIs
- A statically designated entity target for observer events to avoid
accidentally using untargeted events for targeted APIs

This PR achieves these goals by splitting event traits into `Event`,
`EntityEvent`, and `BufferedEvent`, with `Event` being the shared trait
implemented by all events.

## `Event`, `EntityEvent`, and `BufferedEvent`

`Event` is now a very simple trait shared by all events.

```rust
pub trait Event: Send + Sync + 'static {
    // Required for observer APIs
    fn register_component_id(world: &mut World) -> ComponentId { ... }
    fn component_id(world: &World) -> Option<ComponentId> { ... }
}
```

You can call `trigger` for *any* event, and use a global observer for
listening to the event.

```rust
#[derive(Event)]
struct Speak {
    message: String,
}

// ...

app.add_observer(|trigger: On<Speak>| {
    println!("{}", trigger.message);
});

// ...

commands.trigger(Speak {
    message: "Y'all like these reworked events?".to_string(),
});
```

To allow an event to be targeted at entities and even propagated
further, you can additionally implement the `EntityEvent` trait:

```rust
pub trait EntityEvent: Event {
    type Traversal: Traversal<Self>;
    const AUTO_PROPAGATE: bool = false;
}
```

This lets you call `trigger_targets`, and to use targeted observer APIs
like `EntityCommands::observe`:

```rust
#[derive(Event, EntityEvent)]
#[entity_event(traversal = &'static ChildOf, auto_propagate)]
struct Damage {
    amount: f32,
}

// ...

let enemy = commands.spawn((Enemy, Health(100.0))).id();

// Spawn some armor as a child of the enemy entity.
// When the armor takes damage, it will bubble the event up to the enemy.
let armor_piece = commands
    .spawn((ArmorPiece, Health(25.0), ChildOf(enemy)))
    .observe(|trigger: On<Damage>, mut query: Query<&mut Health>| {
        // Note: `On::target` only exists because this is an `EntityEvent`.
        let mut health = query.get(trigger.target()).unwrap();
        health.0 -= trigger.amount();
    });

commands.trigger_targets(Damage { amount: 10.0 }, armor_piece);
```

> [!NOTE]
> You *can* still also trigger an `EntityEvent` without targets using
`trigger`. We probably *could* make this an either-or thing, but I'm not
sure that's actually desirable.

To allow an event to be used with the buffered API, you can implement
`BufferedEvent`:

```rust
pub trait BufferedEvent: Event {}
```

The event can then be used with `EventReader`/`EventWriter`:

```rust
#[derive(Event, BufferedEvent)]
struct Message(String);

fn write_hello(mut writer: EventWriter<Message>) {
    writer.write(Message("I hope these examples are alright".to_string()));
}

fn read_messages(mut reader: EventReader<Message>) {
    // Process all buffered events of type `Message`.
    for Message(message) in reader.read() {
        println!("{message}");
    }
}
```

In summary:

- Need a basic event you can trigger and observe? Derive `Event`!
- Need the event to be targeted at an entity? Derive `EntityEvent`!
- Need the event to be buffered and support the
`EventReader`/`EventWriter` API? Derive `BufferedEvent`!

## Alternatives

I'll now cover some of the alternative approaches I have considered and
briefly explored. I made this section collapsible since it ended up
being quite long :P

<details>

<summary>Expand this to see alternatives</summary>

### 1. Unified `Event` Trait

One option is not to have *three* separate traits (`Event`,
`EntityEvent`, `BufferedEvent`), and to instead just use associated
constants on `Event` to determine whether an event supports targeting
and buffering or not:

```rust
pub trait Event: Send + Sync + 'static {
    type Traversal: Traversal<Self>;
    const AUTO_PROPAGATE: bool = false;
    const TARGETED: bool = false;
    const BUFFERED: bool = false;
    
    fn register_component_id(world: &mut World) -> ComponentId { ... }
    fn component_id(world: &World) -> Option<ComponentId> { ... }
}
```

Methods can then use bounds like `where E: Event<TARGETED = true>` or
`where E: Event<BUFFERED = true>` to limit APIs to specific kinds of
events.

This would keep everything under one `Event` trait, but I don't think
it's necessarily a good idea. It makes APIs harder to read, and docs
can't easily refer to specific types of events. You can also create
weird invariants: what if you specify `TARGETED = false`, but have
`Traversal` and/or `AUTO_PROPAGATE` enabled?

### 2. `Event` and `Trigger`

Another option is to only split the traits between buffered events and
observer events, since that is the main thing people have been asking
for, and they have the largest API difference.

If we did this, I think we would need to make the terms *clearly*
separate. We can't really use `Event` and `BufferedEvent` as the names,
since it would be strange that `BufferedEvent` doesn't implement
`Event`. Something like `ObserverEvent` and `BufferedEvent` could work,
but it'd be more verbose.

For this approach, I would instead keep `Event` for the current
`EventReader`/`EventWriter` API, and call the observer event a
`Trigger`, since the "trigger" terminology is already used in the
observer context within Bevy (both as a noun and a verb). This is also
what a long [bikeshed on
Discord](https://discord.com/channels/691052431525675048/749335865876021248/1298057661878898791)
seemed to land on at the end of last year.

```rust
// For `EventReader`/`EventWriter`
pub trait Event: Send + Sync + 'static {}

// For observers
pub trait Trigger: Send + Sync + 'static {
    type Traversal: Traversal<Self>;
    const AUTO_PROPAGATE: bool = false;
    const TARGETED: bool = false;
    
    fn register_component_id(world: &mut World) -> ComponentId { ... }
    fn component_id(world: &World) -> Option<ComponentId> { ... }
}
```

The problem is that "event" is just a really good term for something
that "happens". Observers are rapidly becoming the more prominent API,
so it'd be weird to give them the `Trigger` name and leave the good
`Event` name for the less common API.

So, even though a split like this seems neat on the surface, I think it
ultimately wouldn't really work. We want to keep the `Event` name for
observer events, and there is no good alternative for the buffered
variant. (`Message` was suggested, but saying stuff like "sends a
collision message" is weird.)

### 3. `GlobalEvent` + `TargetedEvent`

What if instead of focusing on the buffered vs. observed split, we
*only* make a distinction between global and targeted events?

```rust
// A shared event trait to allow global observers to work
pub trait Event: Send + Sync + 'static {
    fn register_component_id(world: &mut World) -> ComponentId { ... }
    fn component_id(world: &World) -> Option<ComponentId> { ... }
}

// For buffered events and non-targeted observer events
pub trait GlobalEvent: Event {}

// For targeted observer events
pub trait TargetedEvent: Event {
    type Traversal: Traversal<Self>;
    const AUTO_PROPAGATE: bool = false;
}
```

This is actually the first approach I implemented, and it has the neat
characteristic that you can only use non-targeted APIs like `trigger`
with a `GlobalEvent` and targeted APIs like `trigger_targets` with a
`TargetedEvent`. You have full control over whether the entity should or
should not have a target, as they are fully distinct at the type-level.

However, there's a few problems:

- There is no type-level indication of whether a `GlobalEvent` supports
buffered events or just non-targeted observer events
- An `Event` on its own does literally nothing, it's just a shared trait
required to make global observers accept both non-targeted and targeted
events
- If an event is both a `GlobalEvent` and `TargetedEvent`, global
observers again have ambiguity on whether an event has a target or not,
undermining some of the benefits
- The names are not ideal

### 4. `Event` and `EntityEvent`

We can fix some of the problems of Alternative 3 by accepting that
targeted events can also be used in non-targeted contexts, and simply
having the `Event` and `EntityEvent` traits:

```rust
// For buffered events and non-targeted observer events
pub trait Event: Send + Sync + 'static {
    fn register_component_id(world: &mut World) -> ComponentId { ... }
    fn component_id(world: &World) -> Option<ComponentId> { ... }
}

// For targeted observer events
pub trait EntityEvent: Event {
    type Traversal: Traversal<Self>;
    const AUTO_PROPAGATE: bool = false;
}
```

This is essentially identical to this PR, just without a dedicated
`BufferedEvent`. The remaining major "problem" is that there is still
zero type-level indication of whether an `Event` event *actually*
supports the buffered API. This leads us to the solution proposed in
this PR, using `Event`, `EntityEvent`, and `BufferedEvent`.

</details>

## Conclusion

The `Event` + `EntityEvent` + `BufferedEvent` split proposed in this PR
aims to solve all the common problems with Bevy's current event model
while keeping the "weirdness" factor minimal. It splits in terms of both
the push vs. pull *and* global vs. targeted aspects, while maintaining a
shared concept for an "event".

### Why I Like This

- The term "event" remains as a single concept for all the different
kinds of events in Bevy.
- Despite all event types being "events", they use fundamentally
different APIs. Instead of assuming that you can use an event type with
any pattern (when only one is typically supported), you explicitly opt
in to each one with dedicated traits.
- Using separate traits for each type of event helps with documentation
and clearer function signatures.
- I can safely make assumptions on expected usage.
- If I see that an event is an `EntityEvent`, I can assume that I can
use `observe` on it and get targeted events.
- If I see that an event is a `BufferedEvent`, I can assume that I can
use `EventReader` to read events.
- If I see both `EntityEvent` and `BufferedEvent`, I can assume that
both APIs are supported.

In summary: This allows for a unified concept for events, while limiting
the different ways to use them with opt-in traits. No more guess-work
involved when using APIs.

### Problems?

- Because `BufferedEvent` implements `Event` (for more consistent
semantics etc.), you can still use all buffered events for non-targeted
observers. I think this is fine/good. The important part is that if you
see that an event implements `BufferedEvent`, you know that the
`EventReader`/`EventWriter` API should be supported. Whether it *also*
supports other APIs is secondary.
- I currently only support `trigger_targets` for an `EntityEvent`.
However, you can technically target components too, without targeting
any entities. I consider that such a niche and advanced use case that
it's not a huge problem to only support it for `EntityEvent`s, but we
could also split `trigger_targets` into `trigger_entities` and
`trigger_components` if we wanted to (or implement components as
entities :P).
- You can still trigger an `EntityEvent` *without* targets. I consider
this correct, since `Event` implements the non-targeted behavior, and
it'd be weird if implementing another trait *removed* behavior. However,
it does mean that global observers for entity events can technically
return `Entity::PLACEHOLDER` again (since I got rid of the
`Option<Entity>` added in #19440 for ergonomics). I think that's enough
of an edge case that it's not a huge problem, but it is worth keeping in
mind.
- ~~Deriving both `EntityEvent` and `BufferedEvent` for the same type
currently duplicates the `Event` implementation, so you instead need to
manually implement one of them.~~ Changed to always requiring `Event` to
be derived.

## Related Work

There are plans to implement multi-event support for observers,
especially for UI contexts. [Cart's
example](https://github.com/bevyengine/bevy/issues/14649#issuecomment-2960402508)
API looked like this:

```rust
// Truncated for brevity
trigger: Trigger<(
    OnAdd<Pressed>,
    OnRemove<Pressed>,
    OnAdd<InteractionDisabled>,
    OnRemove<InteractionDisabled>,
    OnInsert<Hovered>,
)>,
```

I believe this shouldn't be in conflict with this PR. If anything, this
PR might *help* achieve the multi-event pattern for entity observers
with fewer footguns: by statically enforcing that all of these events
are `EntityEvent`s in the context of `EntityCommands::observe`, we can
avoid misuse or weird cases where *some* events inside the trigger are
targeted while others are not.
2025-06-15 16:46:34 +00:00

891 lines
30 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

//! The touch input functionality.
use bevy_ecs::{
entity::Entity,
event::{BufferedEvent, Event, EventReader},
resource::Resource,
system::ResMut,
};
use bevy_math::Vec2;
use bevy_platform::collections::HashMap;
#[cfg(feature = "bevy_reflect")]
use bevy_reflect::Reflect;
#[cfg(all(feature = "serialize", feature = "bevy_reflect"))]
use bevy_reflect::{ReflectDeserialize, ReflectSerialize};
/// A touch input event.
///
/// ## Logic
///
/// Every time the user touches the screen, a new [`TouchPhase::Started`] event with an unique
/// identifier for the finger is generated. When the finger is lifted, the [`TouchPhase::Ended`]
/// event is generated with the same finger id.
///
/// After a [`TouchPhase::Started`] event has been emitted, there may be zero or more [`TouchPhase::Moved`]
/// events when the finger is moved or the touch pressure changes.
///
/// The finger id may be reused by the system after an [`TouchPhase::Ended`] event. The user
/// should assume that a new [`TouchPhase::Started`] event received with the same id has nothing
/// to do with the old finger and is a new finger.
///
/// A [`TouchPhase::Canceled`] event is emitted when the system has canceled tracking this
/// touch, such as when the window loses focus, or on iOS if the user moves the
/// device against their face.
///
/// ## Note
///
/// This event is the translated version of the `WindowEvent::Touch` from the `winit` crate.
/// It is available to the end user and can be used for game logic.
#[derive(Event, BufferedEvent, Debug, Clone, Copy, PartialEq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub struct TouchInput {
/// The phase of the touch input.
pub phase: TouchPhase,
/// The position of the finger on the touchscreen.
pub position: Vec2,
/// The window entity registering the touch.
pub window: Entity,
/// Describes how hard the screen was pressed.
///
/// May be [`None`] if the platform does not support pressure sensitivity.
/// This feature is only available on **iOS** 9.0+ and **Windows** 8+.
pub force: Option<ForceTouch>,
/// The unique identifier of the finger.
pub id: u64,
}
/// A force description of a [`Touch`] input.
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub enum ForceTouch {
/// On iOS, the force is calibrated so that the same number corresponds to
/// roughly the same amount of pressure on the screen regardless of the
/// device.
Calibrated {
/// The force of the touch, where a value of 1.0 represents the force of
/// an average touch (predetermined by the system, not user-specific).
///
/// The force reported by Apple Pencil is measured along the axis of the
/// pencil. If you want a force perpendicular to the device, you need to
/// calculate this value using the `altitude_angle` value.
force: f64,
/// The maximum possible force for a touch.
///
/// The value of this field is sufficiently high to provide a wide
/// dynamic range for values of the `force` field.
max_possible_force: f64,
/// The altitude (in radians) of the stylus.
///
/// A value of 0 radians indicates that the stylus is parallel to the
/// surface. The value of this property is Pi/2 when the stylus is
/// perpendicular to the surface.
altitude_angle: Option<f64>,
},
/// If the platform reports the force as normalized, we have no way of
/// knowing how much pressure 1.0 corresponds to we know it's the maximum
/// amount of force, but as to how much force, you might either have to
/// press really hard, or not hard at all, depending on the device.
Normalized(f64),
}
/// A phase of a [`TouchInput`].
///
/// ## Usage
///
/// It is used to describe the phase of the touch input that is currently active.
/// This includes a phase that indicates that a touch input has started or ended,
/// or that a finger has moved. There is also a canceled phase that indicates that
/// the system canceled the tracking of the finger.
#[derive(Debug, Hash, PartialEq, Eq, Clone, Copy)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, Hash, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub enum TouchPhase {
/// A finger started to touch the touchscreen.
Started,
/// A finger moved over the touchscreen.
Moved,
/// A finger stopped touching the touchscreen.
Ended,
/// The system canceled the tracking of the finger.
///
/// This occurs when the window loses focus, or on iOS if the user moves the
/// device against their face.
Canceled,
}
/// A touch input.
///
/// ## Usage
///
/// It is used to store the position and force of a touch input and also the `id` of the finger.
/// The data of the touch input comes from the [`TouchInput`] event and is being stored
/// inside of the [`Touches`] `bevy` resource.
#[derive(Debug, Clone, Copy)]
pub struct Touch {
/// The id of the touch input.
id: u64,
/// The starting position of the touch input.
start_position: Vec2,
/// The starting force of the touch input.
start_force: Option<ForceTouch>,
/// The previous position of the touch input.
previous_position: Vec2,
/// The previous force of the touch input.
previous_force: Option<ForceTouch>,
/// The current position of the touch input.
position: Vec2,
/// The current force of the touch input.
force: Option<ForceTouch>,
}
impl Touch {
/// The delta of the current `position` and the `previous_position`.
pub fn delta(&self) -> Vec2 {
self.position - self.previous_position
}
/// The distance of the `start_position` and the current `position`.
pub fn distance(&self) -> Vec2 {
self.position - self.start_position
}
/// Returns the `id` of the touch.
#[inline]
pub fn id(&self) -> u64 {
self.id
}
/// Returns the `start_position` of the touch.
#[inline]
pub fn start_position(&self) -> Vec2 {
self.start_position
}
/// Returns the `start_force` of the touch.
#[inline]
pub fn start_force(&self) -> Option<ForceTouch> {
self.start_force
}
/// Returns the `previous_position` of the touch.
#[inline]
pub fn previous_position(&self) -> Vec2 {
self.previous_position
}
/// Returns the `previous_force` of the touch.
#[inline]
pub fn previous_force(&self) -> Option<ForceTouch> {
self.previous_force
}
/// Returns the current `position` of the touch.
#[inline]
pub fn position(&self) -> Vec2 {
self.position
}
/// Returns the current `force` of the touch.
#[inline]
pub fn force(&self) -> Option<ForceTouch> {
self.force
}
}
impl From<&TouchInput> for Touch {
fn from(input: &TouchInput) -> Touch {
Touch {
id: input.id,
start_position: input.position,
start_force: input.force,
previous_position: input.position,
previous_force: input.force,
position: input.position,
force: input.force,
}
}
}
/// A collection of [`Touch`]es.
///
/// ## Usage
///
/// It is used to create a `bevy` resource that stores the data of the touches on a touchscreen
/// and can be accessed inside of a system.
///
/// ## Updating
///
/// The resource is updated inside of the [`touch_screen_input_system`].
#[derive(Debug, Clone, Default, Resource)]
pub struct Touches {
/// A collection of every [`Touch`] that is currently being pressed.
pressed: HashMap<u64, Touch>,
/// A collection of every [`Touch`] that just got pressed.
just_pressed: HashMap<u64, Touch>,
/// A collection of every [`Touch`] that just got released.
just_released: HashMap<u64, Touch>,
/// A collection of every [`Touch`] that just got canceled.
just_canceled: HashMap<u64, Touch>,
}
impl Touches {
/// An iterator visiting every pressed [`Touch`] input in arbitrary order.
pub fn iter(&self) -> impl Iterator<Item = &Touch> + '_ {
self.pressed.values()
}
/// Returns the [`Touch`] input corresponding to the `id` if it is being pressed.
pub fn get_pressed(&self, id: u64) -> Option<&Touch> {
self.pressed.get(&id)
}
/// Checks if any touch input was just pressed.
pub fn any_just_pressed(&self) -> bool {
!self.just_pressed.is_empty()
}
/// Register a release for a given touch input.
pub fn release(&mut self, id: u64) {
if let Some(touch) = self.pressed.remove(&id) {
self.just_released.insert(id, touch);
}
}
/// Registers a release for all currently pressed touch inputs.
pub fn release_all(&mut self) {
self.just_released.extend(self.pressed.drain());
}
/// Returns `true` if the input corresponding to the `id` has just been pressed.
pub fn just_pressed(&self, id: u64) -> bool {
self.just_pressed.contains_key(&id)
}
/// Clears the `just_pressed` state of the touch input and returns `true` if the touch input has just been pressed.
///
/// Future calls to [`Touches::just_pressed`] for the given touch input will return false until a new press event occurs.
pub fn clear_just_pressed(&mut self, id: u64) -> bool {
self.just_pressed.remove(&id).is_some()
}
/// An iterator visiting every just pressed [`Touch`] input in arbitrary order.
pub fn iter_just_pressed(&self) -> impl Iterator<Item = &Touch> {
self.just_pressed.values()
}
/// Returns the [`Touch`] input corresponding to the `id` if it has just been released.
pub fn get_released(&self, id: u64) -> Option<&Touch> {
self.just_released.get(&id)
}
/// Checks if any touch input was just released.
pub fn any_just_released(&self) -> bool {
!self.just_released.is_empty()
}
/// Returns `true` if the input corresponding to the `id` has just been released.
pub fn just_released(&self, id: u64) -> bool {
self.just_released.contains_key(&id)
}
/// Clears the `just_released` state of the touch input and returns `true` if the touch input has just been released.
///
/// Future calls to [`Touches::just_released`] for the given touch input will return false until a new release event occurs.
pub fn clear_just_released(&mut self, id: u64) -> bool {
self.just_released.remove(&id).is_some()
}
/// An iterator visiting every just released [`Touch`] input in arbitrary order.
pub fn iter_just_released(&self) -> impl Iterator<Item = &Touch> {
self.just_released.values()
}
/// Checks if any touch input was just canceled.
pub fn any_just_canceled(&self) -> bool {
!self.just_canceled.is_empty()
}
/// Returns `true` if the input corresponding to the `id` has just been canceled.
pub fn just_canceled(&self, id: u64) -> bool {
self.just_canceled.contains_key(&id)
}
/// Clears the `just_canceled` state of the touch input and returns `true` if the touch input has just been canceled.
///
/// Future calls to [`Touches::just_canceled`] for the given touch input will return false until a new cancel event occurs.
pub fn clear_just_canceled(&mut self, id: u64) -> bool {
self.just_canceled.remove(&id).is_some()
}
/// An iterator visiting every just canceled [`Touch`] input in arbitrary order.
pub fn iter_just_canceled(&self) -> impl Iterator<Item = &Touch> {
self.just_canceled.values()
}
/// Retrieves the position of the first currently pressed touch, if any
pub fn first_pressed_position(&self) -> Option<Vec2> {
// Looking for the position in `pressed`. If nothing is found, also look into `just_pressed`
// A touch can be in `just_pressed` but not in `pressed` if it ended in the same frame it started
self.pressed
.values()
.next()
.or_else(|| self.just_pressed.values().next())
.map(|t| t.position)
}
/// Clears `just_pressed`, `just_released`, and `just_canceled` data for every touch input.
///
/// See also [`Touches::reset_all`] for a full reset.
pub fn clear(&mut self) {
self.just_pressed.clear();
self.just_released.clear();
self.just_canceled.clear();
}
/// Clears `pressed`, `just_pressed`, `just_released`, and `just_canceled` data for every touch input.
///
/// See also [`Touches::clear`] for clearing only touches that have just been pressed, released or canceled.
pub fn reset_all(&mut self) {
self.pressed.clear();
self.just_pressed.clear();
self.just_released.clear();
self.just_canceled.clear();
}
/// Processes a [`TouchInput`] event by updating the `pressed`, `just_pressed`,
/// `just_released`, and `just_canceled` collections.
fn process_touch_event(&mut self, event: &TouchInput) {
match event.phase {
TouchPhase::Started => {
self.pressed.insert(event.id, event.into());
self.just_pressed.insert(event.id, event.into());
}
TouchPhase::Moved => {
if let Some(mut new_touch) = self.pressed.get(&event.id).cloned() {
// NOTE: This does not update the previous_force / previous_position field;
// they should be updated once per frame, not once per event
// See https://github.com/bevyengine/bevy/issues/12442
new_touch.position = event.position;
new_touch.force = event.force;
self.pressed.insert(event.id, new_touch);
}
}
TouchPhase::Ended => {
// if touch `just_released`, add related event to it
// the event position info is inside `pressed`, so use it unless not found
if let Some((_, v)) = self.pressed.remove_entry(&event.id) {
self.just_released.insert(event.id, v);
} else {
self.just_released.insert(event.id, event.into());
}
}
TouchPhase::Canceled => {
// if touch `just_canceled`, add related event to it
// the event position info is inside `pressed`, so use it unless not found
if let Some((_, v)) = self.pressed.remove_entry(&event.id) {
self.just_canceled.insert(event.id, v);
} else {
self.just_canceled.insert(event.id, event.into());
}
}
};
}
}
/// Updates the [`Touches`] resource with the latest [`TouchInput`] events.
///
/// This is not clearing the `pressed` collection, because it could incorrectly mark a touch input
/// as not pressed even though it is pressed. This could happen if the touch input is not moving
/// for a single frame and would therefore be marked as not pressed, because this function is
/// called on every single frame no matter if there was an event or not.
///
/// ## Differences
///
/// The main difference between the [`TouchInput`] event and the [`Touches`] resource is that
/// the latter has convenient functions like [`Touches::just_pressed`] and [`Touches::just_released`].
pub fn touch_screen_input_system(
mut touch_state: ResMut<Touches>,
mut touch_input_events: EventReader<TouchInput>,
) {
if !touch_state.just_pressed.is_empty() {
touch_state.just_pressed.clear();
}
if !touch_state.just_released.is_empty() {
touch_state.just_released.clear();
}
if !touch_state.just_canceled.is_empty() {
touch_state.just_canceled.clear();
}
if !touch_input_events.is_empty() {
for touch in touch_state.pressed.values_mut() {
touch.previous_position = touch.position;
touch.previous_force = touch.force;
}
for event in touch_input_events.read() {
touch_state.process_touch_event(event);
}
}
}
#[cfg(test)]
mod test {
use super::Touches;
#[test]
fn touch_update() {
use crate::{touch::Touch, Touches};
use bevy_math::Vec2;
let mut touches = Touches::default();
let touch_event = Touch {
id: 4,
start_position: Vec2::ZERO,
start_force: None,
previous_position: Vec2::ZERO,
previous_force: None,
position: Vec2::ZERO,
force: None,
};
// Add a touch to `just_pressed`, 'just_released', and 'just canceled'
touches.just_pressed.insert(4, touch_event);
touches.just_released.insert(4, touch_event);
touches.just_canceled.insert(4, touch_event);
clear_all(&mut touches);
// Verify that all the `just_x` maps are cleared
assert!(touches.just_pressed.is_empty());
assert!(touches.just_released.is_empty());
assert!(touches.just_canceled.is_empty());
}
#[test]
fn touch_process() {
use crate::{touch::TouchPhase, TouchInput, Touches};
use bevy_ecs::entity::Entity;
use bevy_math::Vec2;
let mut touches = Touches::default();
// Test adding a `TouchPhase::Started`
let touch_event = TouchInput {
phase: TouchPhase::Started,
position: Vec2::splat(4.0),
window: Entity::PLACEHOLDER,
force: None,
id: 4,
};
clear_all(&mut touches);
touches.process_touch_event(&touch_event);
assert!(touches.pressed.get(&touch_event.id).is_some());
assert!(touches.just_pressed.get(&touch_event.id).is_some());
// Test adding a `TouchPhase::Moved`
let moved_touch_event = TouchInput {
phase: TouchPhase::Moved,
position: Vec2::splat(5.0),
window: Entity::PLACEHOLDER,
force: None,
id: touch_event.id,
};
clear_all(&mut touches);
touches.process_touch_event(&moved_touch_event);
assert_eq!(
touches
.pressed
.get(&moved_touch_event.id)
.expect("Missing from pressed after move.")
.previous_position,
touch_event.position
);
// Test cancelling an event
let cancel_touch_event = TouchInput {
phase: TouchPhase::Canceled,
position: Vec2::ONE,
window: Entity::PLACEHOLDER,
force: None,
id: touch_event.id,
};
clear_all(&mut touches);
touches.process_touch_event(&cancel_touch_event);
assert!(touches.just_canceled.get(&touch_event.id).is_some());
assert!(touches.pressed.get(&touch_event.id).is_none());
// Test ending an event
let end_touch_event = TouchInput {
phase: TouchPhase::Ended,
position: Vec2::splat(4.0),
window: Entity::PLACEHOLDER,
force: None,
id: touch_event.id,
};
clear_all(&mut touches);
touches.process_touch_event(&touch_event);
touches.process_touch_event(&moved_touch_event);
touches.process_touch_event(&end_touch_event);
assert!(touches.just_released.get(&touch_event.id).is_some());
assert!(touches.pressed.get(&touch_event.id).is_none());
let touch = touches.just_released.get(&touch_event.id).unwrap();
// Make sure the position is updated from TouchPhase::Moved and TouchPhase::Ended
assert_ne!(touch.previous_position, touch.position);
}
// See https://github.com/bevyengine/bevy/issues/12442
#[test]
fn touch_process_multi_event() {
use crate::{touch::TouchPhase, TouchInput, Touches};
use bevy_ecs::entity::Entity;
use bevy_math::Vec2;
let mut touches = Touches::default();
let started_touch_event = TouchInput {
phase: TouchPhase::Started,
position: Vec2::splat(4.0),
window: Entity::PLACEHOLDER,
force: None,
id: 4,
};
let moved_touch_event1 = TouchInput {
phase: TouchPhase::Moved,
position: Vec2::splat(5.0),
window: Entity::PLACEHOLDER,
force: None,
id: started_touch_event.id,
};
let moved_touch_event2 = TouchInput {
phase: TouchPhase::Moved,
position: Vec2::splat(6.0),
window: Entity::PLACEHOLDER,
force: None,
id: started_touch_event.id,
};
// tick 1: touch is started during frame
for touch in touches.pressed.values_mut() {
// update ONCE, at start of frame
touch.previous_position = touch.position;
}
touches.process_touch_event(&started_touch_event);
touches.process_touch_event(&moved_touch_event1);
touches.process_touch_event(&moved_touch_event2);
{
let touch = touches.get_pressed(started_touch_event.id).unwrap();
assert_eq!(touch.previous_position, started_touch_event.position);
assert_eq!(touch.position, moved_touch_event2.position);
}
// tick 2: touch was started before frame
for touch in touches.pressed.values_mut() {
touch.previous_position = touch.position;
}
touches.process_touch_event(&moved_touch_event1);
touches.process_touch_event(&moved_touch_event2);
touches.process_touch_event(&moved_touch_event1);
{
let touch = touches.get_pressed(started_touch_event.id).unwrap();
assert_eq!(touch.previous_position, moved_touch_event2.position);
assert_eq!(touch.position, moved_touch_event1.position);
}
}
#[test]
fn touch_pressed() {
use crate::{touch::TouchPhase, TouchInput, Touches};
use bevy_ecs::entity::Entity;
use bevy_math::Vec2;
let mut touches = Touches::default();
let touch_event = TouchInput {
phase: TouchPhase::Started,
position: Vec2::splat(4.0),
window: Entity::PLACEHOLDER,
force: None,
id: 4,
};
// Register the touch and test that it was registered correctly
touches.process_touch_event(&touch_event);
assert!(touches.get_pressed(touch_event.id).is_some());
assert!(touches.just_pressed(touch_event.id));
assert_eq!(touches.iter().count(), 1);
touches.clear_just_pressed(touch_event.id);
assert!(!touches.just_pressed(touch_event.id));
}
#[test]
fn touch_released() {
use crate::{touch::TouchPhase, TouchInput, Touches};
use bevy_ecs::entity::Entity;
use bevy_math::Vec2;
let mut touches = Touches::default();
let touch_event = TouchInput {
phase: TouchPhase::Ended,
position: Vec2::splat(4.0),
window: Entity::PLACEHOLDER,
force: None,
id: 4,
};
// Register the touch and test that it was registered correctly
touches.process_touch_event(&touch_event);
assert!(touches.get_released(touch_event.id).is_some());
assert!(touches.just_released(touch_event.id));
assert_eq!(touches.iter_just_released().count(), 1);
touches.clear_just_released(touch_event.id);
assert!(!touches.just_released(touch_event.id));
}
#[test]
fn touch_canceled() {
use crate::{touch::TouchPhase, TouchInput, Touches};
use bevy_ecs::entity::Entity;
use bevy_math::Vec2;
let mut touches = Touches::default();
let touch_event = TouchInput {
phase: TouchPhase::Canceled,
position: Vec2::splat(4.0),
window: Entity::PLACEHOLDER,
force: None,
id: 4,
};
// Register the touch and test that it was registered correctly
touches.process_touch_event(&touch_event);
assert!(touches.just_canceled(touch_event.id));
assert_eq!(touches.iter_just_canceled().count(), 1);
touches.clear_just_canceled(touch_event.id);
assert!(!touches.just_canceled(touch_event.id));
}
#[test]
fn release_touch() {
use crate::{touch::TouchPhase, TouchInput, Touches};
use bevy_ecs::entity::Entity;
use bevy_math::Vec2;
let mut touches = Touches::default();
let touch_event = TouchInput {
phase: TouchPhase::Started,
position: Vec2::splat(4.0),
window: Entity::PLACEHOLDER,
force: None,
id: 4,
};
// Register the touch and test that it was registered correctly
touches.process_touch_event(&touch_event);
assert!(touches.get_pressed(touch_event.id).is_some());
touches.release(touch_event.id);
assert!(touches.get_pressed(touch_event.id).is_none());
assert!(touches.just_released(touch_event.id));
}
#[test]
fn release_all_touches() {
use crate::{touch::TouchPhase, TouchInput, Touches};
use bevy_ecs::entity::Entity;
use bevy_math::Vec2;
let mut touches = Touches::default();
let touch_pressed_event = TouchInput {
phase: TouchPhase::Started,
position: Vec2::splat(4.0),
window: Entity::PLACEHOLDER,
force: None,
id: 4,
};
let touch_moved_event = TouchInput {
phase: TouchPhase::Moved,
position: Vec2::splat(4.0),
window: Entity::PLACEHOLDER,
force: None,
id: 4,
};
touches.process_touch_event(&touch_pressed_event);
touches.process_touch_event(&touch_moved_event);
assert!(touches.get_pressed(touch_pressed_event.id).is_some());
assert!(touches.get_pressed(touch_moved_event.id).is_some());
touches.release_all();
assert!(touches.get_pressed(touch_pressed_event.id).is_none());
assert!(touches.just_released(touch_pressed_event.id));
assert!(touches.get_pressed(touch_moved_event.id).is_none());
assert!(touches.just_released(touch_moved_event.id));
}
#[test]
fn clear_touches() {
use crate::{touch::TouchPhase, TouchInput, Touches};
use bevy_ecs::entity::Entity;
use bevy_math::Vec2;
let mut touches = Touches::default();
let touch_press_event = TouchInput {
phase: TouchPhase::Started,
position: Vec2::splat(4.0),
window: Entity::PLACEHOLDER,
force: None,
id: 4,
};
let touch_canceled_event = TouchInput {
phase: TouchPhase::Canceled,
position: Vec2::splat(4.0),
window: Entity::PLACEHOLDER,
force: None,
id: 5,
};
let touch_released_event = TouchInput {
phase: TouchPhase::Ended,
position: Vec2::splat(4.0),
window: Entity::PLACEHOLDER,
force: None,
id: 6,
};
// Register the touches and test that it was registered correctly
touches.process_touch_event(&touch_press_event);
touches.process_touch_event(&touch_canceled_event);
touches.process_touch_event(&touch_released_event);
assert!(touches.get_pressed(touch_press_event.id).is_some());
assert!(touches.just_pressed(touch_press_event.id));
assert!(touches.just_canceled(touch_canceled_event.id));
assert!(touches.just_released(touch_released_event.id));
touches.clear();
assert!(touches.get_pressed(touch_press_event.id).is_some());
assert!(!touches.just_pressed(touch_press_event.id));
assert!(!touches.just_canceled(touch_canceled_event.id));
assert!(!touches.just_released(touch_released_event.id));
}
#[test]
fn reset_all_touches() {
use crate::{touch::TouchPhase, TouchInput, Touches};
use bevy_ecs::entity::Entity;
use bevy_math::Vec2;
let mut touches = Touches::default();
let touch_press_event = TouchInput {
phase: TouchPhase::Started,
position: Vec2::splat(4.0),
window: Entity::PLACEHOLDER,
force: None,
id: 4,
};
let touch_canceled_event = TouchInput {
phase: TouchPhase::Canceled,
position: Vec2::splat(4.0),
window: Entity::PLACEHOLDER,
force: None,
id: 5,
};
let touch_released_event = TouchInput {
phase: TouchPhase::Ended,
position: Vec2::splat(4.0),
window: Entity::PLACEHOLDER,
force: None,
id: 6,
};
// Register the touches and test that it was registered correctly
touches.process_touch_event(&touch_press_event);
touches.process_touch_event(&touch_canceled_event);
touches.process_touch_event(&touch_released_event);
assert!(touches.get_pressed(touch_press_event.id).is_some());
assert!(touches.just_pressed(touch_press_event.id));
assert!(touches.just_canceled(touch_canceled_event.id));
assert!(touches.just_released(touch_released_event.id));
touches.reset_all();
assert!(touches.get_pressed(touch_press_event.id).is_none());
assert!(!touches.just_pressed(touch_press_event.id));
assert!(!touches.just_canceled(touch_canceled_event.id));
assert!(!touches.just_released(touch_released_event.id));
}
fn clear_all(touch_state: &mut Touches) {
touch_state.just_pressed.clear();
touch_state.just_released.clear();
touch_state.just_canceled.clear();
}
}