grease.collision – Collision Detection

Grease collision detection systems

Grease uses two-phase broad and narrow collision detection. Broad-phase collision systems are used to efficiently identify pairs that may be colliding without resorting to a brute-force check of all possible pairs. Narrow-phase collision systems use the pairs generated by the broad-phase and perform more precise collision tests to determine if a collision has actually occurred. The narrow-phase system also calculates more details about each collision, including collision point and normal vector for use in collision response.

A typical collision detection system consists of a narrow-phase system that contains a broad-phased system. The narrow-phase system is usually the only

one that the application directly interacts with, though the application is free to use the broad-phased system directly if desired. This could be useful in cases where speed, rather than precision is paramount.

The narrow-phase system can be assigned handler objects to run after collision detection. These can perform tasks like handling collision response or dispatching collision events to application handlers.

Note that broad-phase systems can return false positives, though they should never return false negatives. Do not assume that all pairs returned by a broad-phase system are actually in collision.

class grease.collision.BroadSweepAndPrune(collision_component='collision')

2D Broad-phase sweep and prune bounding box collision detector

This algorithm is efficient for collision detection between many moving bodies. It has linear algorithmic complexity and takes advantage of temporal coherence between frames. It also does not suffer from bad worst-case performance (like RDC can). Unlike spacial hashing, it does not need to be optimized for specific space and body sizes.

Other algorithms may be more efficient for collision detection with stationary bodies, bodies that are always evenly distributed, or ad-hoc queries.

Args:

collision_component: Name of the collision component used by this system, defaults to ‘collision’. This component supplies each entities’ aabb and collision masks.

collision_component

Name of world’s collision component used by this system

collision_pairs

Candidate collision pairs for this timestep

query_point(x_or_point, y=None, from_mask=4294967295L)

Hit test at the point specified.

Args:

x_or_point: x coordinate (float) or sequence of (x, y) floats.

y: y coordinate (float) if x is not a sequence

from_mask: Bit mask used to filter query results. This value

is bit ANDed with candidate entities’ collision.into_mask. If the result is non-zero, then it is considered a hit. By default all entities colliding with the input point are returned.

Returns:

Return a set of entities where the point is inside their bounding boxes as of the last time step.

set_world(world)

Bind the system to a world

step(dt)

Update the system for this time step, updates and sorts the axis arrays

world

grease.World object this system belongs to

class grease.collision.Circular(handlers=(), position_component='position', collision_component='collision', update_aabbs=True, broad_phase=None)

Basic narrow-phase collision detector which treats all entities as circles with their radius defined in the collision component.

Args:

handlers: A sequence of collision handler functions that are invoked after collision detection.

collision_component: Name of collision component for this system,

defaults to ‘collision’. This supplies each entity’s collision radius and masks.

position_component: Name of position component for this system,

defaults to ‘position’. This supplies each entity’s position.

update_aabbs (bool): If True (the default), then the entities’

collision.aabb fields will be updated using their position and collision radius before invoking the broad phase system. Set this False if another system updates the aabbs.

broad_phase: A broad-phase collision system to use as a source

for collision pairs. If not specified, a BroadSweepAndPrune system will be created automatically.

broad_phase

Broad phase collision system used as a source for collision pairs

collision_component

Name of world’s collision component used by this system

collision_pairs

The set of entity pairs in collision in this timestep

handlers

A sequence of collision handler functions invoke after collision detection

position_component

Name of world’s position component used by this system

query_point(x_or_point, y=None, from_mask=4294967295L)

Hit test at the point specified.

Args:

x_or_point: x coordinate (float) or sequence of (x, y) floats.

y: y coordinate (float) if x is not a sequence

from_mask: Bit mask used to filter query results. This value

is bit ANDed with candidate entities’ collision.into_mask. If the result is non-zero, then it is considered a hit. By default all entities colliding with the input point are returned.

Returns:

Return a set of entities where the point is inside their collision radii as of the last time step.

set_world(world)

Bind the system to a world

step(dt)

Update the collision system for this time step and invoke the handlers

update_aabbs

Flag to indicate whether the system updates the entities’ collision.aabb field before invoking the broad phase collision system

world

grease.World object this system belongs to

class grease.collision.Pair

Pair of entities in collision. This is an ordered sequence of two entities, that compares and hashes unordered.

Also stores additional collision point and normal vectors for each entity.

info

A sequence of (entity, collision point, collision normal) for each entity in the pair

set_point_normal(point0, normal0, point1, normal1)

Set the collision point and normal for both entities

grease.collision.dispatch_events(collision_system)

Collision handler that dispatches on_collide() events to entities marked for collision by the specified collision system. The on_collide() event handler methods are defined by the application on the desired entity classes. These methods should have the following signature:

def on_collide(self, other_entity, collision_point, collision_normal):
        '''Handle A collision between this entity and `other_entity`

        Args:
                `other_entity` (Entity): The other entity in collision with
                `self`

                `collision_point` (Vec2d): The point on this entity (`self`)
                where the collision occurred. Note this may be `None` for some
                collision systems that do not report it.

                `collision_normal` (Vec2d): The normal vector at the point of
                collision. As with `collision_point`, this may be None for
                some collision systems.
        '''

Note the arguments to on_collide() are always passed positionally, so you can use different argument names than above if desired.

If a pair of entities are in collision, then the event will be dispatched to both objects in arbitrary order if all of their collision masks align.