Function pointer_events

pub fn pointer_events(
    input_events: EventReader<'_, '_, PointerInput>,
    pointers: Query<'_, '_, &PointerLocation>,
    pointer_map: Res<'_, PointerMap>,
    hover_map: Res<'_, HoverMap>,
    previous_hover_map: Res<'_, PreviousHoverMap>,
    pointer_state: ResMut<'_, PointerState>,
    commands: Commands<'_, '_>,
    event_writers: PickingEventWriters<'_>,
)

Dispatches interaction events to the target entities.

Within a single frame, events are dispatched in the following order:

• Out → DragLeave.
• DragEnter → Over.
• Any number of any of the following:
  • For each movement: DragStart → Drag → DragOver → Move.
  • For each button press: Down or Click → Up → DragDrop → DragEnd → DragLeave.
  • For each pointer cancellation: Cancel.

Additionally, across multiple frames, the following are also strictly ordered by the interaction state machine:

• When a pointer moves over the target: Over, Move, Out.
• When a pointer presses buttons on the target: Down, Click, Up.
• When a pointer drags the target: DragStart, Drag, DragEnd.
• When a pointer drags something over the target: DragEnter, DragOver, DragDrop, DragLeave.
• When a pointer is canceled: No other events will follow the Cancel event for that pointer.

Two events – Over and Out – are driven only by the HoverMap. The rest rely on additional data from the PointerInput event stream. To receive these events for a custom pointer, you must add PointerInput events.

When the pointer goes from hovering entity A to entity B, entity A will receive Out and then entity B will receive Over. No entity will ever receive both an Over and and a Out event during the same frame.

When we account for event bubbling, this is no longer true. When focus shifts between children, parent entities may receive redundant Out → Over pairs. In the context of UI, this is especially problematic. Additional hierarchy-aware events will be added in a future release.

Both Click and Up target the entity hovered in the previous frame, rather than the current frame. This is because touch pointers hover nothing on the frame they are released. The end effect is that these two events can be received sequentally after an Out event (but always on the same frame as the Out event).

Note: Though it is common for the PointerInput stream may contain multiple pointer movements and presses each frame, the hover state is determined only by the pointer’s final position. Since the hover state ultimately determines which entities receive events, this may mean that an entity can receive events from before or after it was actually hovered.