Struct collider::Collider

pub struct Collider<I: Interactivity = DefaultInteractivity> { /* fields omitted */ }

A structure that tracks hitboxes and returns collide/separate events.

Collider manages events using a "simulation time" that the user updates as necessary. This time starts at 0.0.

Methods

impl<I: Interactivity> Collider<I>

fn new(cell_width: f64, padding: f64) -> Collider<I>

Constructs a new Collider instance.

To reduce the number of overlaps that are tested, hitboxes are placed in a fixed grid structure behind the scenes. cell_width is the width of the cells in this grid. If your projct uses a similar grid, then it is usually a good choice to use the same cell width as that grid. Otherwise, a good choice is to use a width that is slightly larger than most of the hitboxes.

Collider generates both Collide and Separate events. However, due to numerical error, it is important that two hitboxes be a certain small distance apart from each other after a collision before they are considered separated. Otherwise false separation events may occur if, for example, a sprite runs into a wall and stops, still touching the wall. padding is used to describe what this minimum separation distance is. This should typically be something that is not visible to the user, perhaps a fraction of a "pixel." Another restriction introduced by padding is that hitboxes are not allowed to have a width or height smaller than padding.

fn time(&self) -> f64

Returns the current simulation time.

fn next_time(&self) -> f64

Returns the time at which self.next() needs to be called again.

Even if self.next_time() == self.time(), there is a chance that calling self.next() will return None, having processed an internal event. Regardless, after self.next() has been called repeatedly until it returns None, then self.next_time() will be greater than self.time() again.

This is a fast constant-time operation. The result may be infinity.

fn set_time(&mut self, time: f64)

Advances the simulation time to the given value.

The positions of all hitboxes will be updated based on the velocities of the hitboxes. Will panic if time exceeds self.next_time(). Will also panic if time is less than self.time() (i.e. cannot rewind time).

The hitboxes are updated implicitly, and this is actually a fast constant-time operation.

fn next(&mut self) -> Option<(Event, HitboxId, HitboxId)>

Processes and returns the next Collide or Separate event, or returns None if there are no more events that occured at the given time (although an internal event might have been processed if None is returned). Will always return None if self.next_time() > self.time().

The returned value is a tuple, denoting the type of event (Collide or Separate) and the two HitboxIds involved, in increasing order.

fn add_hitbox_with_interactivity(&mut self,
                                 id: HitboxId,
                                 hitbox: Hitbox,
                                 interactivity: I)

Adds a new hitbox to the collider. The id may be used to track the hitbox over time (will panic if there is an id clash). hitbox is the initial state of the hitbox. interactivity determines which other hitboxes should be checked for Collide/Separate events.

fn remove_hitbox(&mut self, id: HitboxId)

Removes the hitbox with the given id from all tracking. No further events will be generated for this hitbox.

fn get_hitbox(&self, id: HitboxId) -> Hitbox

Returns the current state of the hitbox with the given id.

fn update_hitbox(&mut self, id: HitboxId, hitbox: Hitbox)

Updates the hitbox with the given id to match the position, shape, and velocity provided by hitbox.

If this hitbox had collided (and not separated) with another htibox and still overlaps after this update, then no new Collide/Separate events are generated immediately.

fn update_interactivity(&mut self, id: HitboxId, interactivity: I)

Sets the interactivity of the hitbox with the given id to the new value interactivity.

If this hitbox was currently overlapping with other hitboxes and the new interactivity does not care about such overlaps, then the overlaps will ceased to be tracked without generating a Separation event.

fn update_hitbox_and_interactivity(&mut self,
                                   id: HitboxId,
                                   hitbox: Hitbox,
                                   interactivity: I)

Invokes the functionality of both update_hitbox and update_interactivity, but is more efficient than calling the two methods separately.

impl<I: Interactivity + Default> Collider<I>

fn add_hitbox(&mut self, id: HitboxId, hitbox: Hitbox)

Shorthand for self.add_hitbox_with_interactivity(id, hitbox, I::default());.