Skip to content

Collisions

struct CP::Arbiter
inherits Struct #

The Arbiter object encapsulates a pair of colliding shapes and all of the data about their collision.

They are created when a collision starts, and persist until those shapes are no longer colliding.

Warning: Because arbiters are handled by the space you should never hold on to an arbiter as you don't know when it will be destroyed! Use them within the callback where they are given to you and then forget about them or copy out the information you need from them.

Methods#

#bodies : ::Tuple(Body, Body)#

Return the colliding bodies involved for this arbiter.

The order of the collision_type the bodies are associated with values will match the order set when the collision handler was registered.

View source

#call_wildcard_begin_a(space : Space) : Bool#

If you want a custom callback to invoke the wildcard callback for the first collision type, you must call this function explicitly.

You must decide how to handle the wildcard's return value since it may disagree with the other wildcard handler's return value or your own.

View source

#call_wildcard_begin_b(space : Space) : Bool#

If you want a custom callback to invoke the wildcard callback for the second collision type, you must call this function explicitly.

You must decide how to handle the wildcard's return value since it may disagree with the other wildcard handler's return value or your own.

View source

#call_wildcard_post_solve_a(space : Space)#

If you want a custom callback to invoke the wildcard callback for the first collision type, you must call this function explicitly.

View source

#call_wildcard_post_solve_b(space : Space)#

If you want a custom callback to invoke the wildcard callback for the second collision type, you must call this function explicitly.

View source

#call_wildcard_pre_solve_a(space : Space) : Bool#

If you want a custom callback to invoke the wildcard callback for the first collision type, you must call this function explicitly.

You must decide how to handle the wildcard's return value since it may disagree with the other wildcard handler's return value or your own.

View source

#call_wildcard_pre_solve_b(space : Space) : Bool#

If you want a custom callback to invoke the wildcard callback for the second collision type, you must call this function explicitly.

You must decide how to handle the wildcard's return value since it may disagree with the other wildcard handler's return value or your own.

View source

#call_wildcard_separate_a(space : Space)#

If you want a custom callback to invoke the wildcard callback for the first collision type, you must call this function explicitly.

View source

#call_wildcard_separate_b(space : Space)#

If you want a custom callback to invoke the wildcard callback for the second collision type, you must call this function explicitly.

View source

#contact_point_set : ContactPointSet#

Return a contact set from an arbiter.

View source

#contact_point_set=(contact_point_set : ContactPointSet)#

Replace the contact point set for an arbiter.

This can be a very powerful feature, but use it with caution!

View source

#count : Int32#

Get the number of contact points for this arbiter.

View source

#data : ::Pointer(Void)#

The user data pointer associated with this pair of colliding objects.

View source

#data=(data)#

View source

#depth(i : Int) : Float64#

Get the depth of the i-th contact point.

View source

#first_contact? : Bool#

Returns true if this is the first step a pair of objects started colliding.

This can be useful for sound effects for instance. If it's the first frame for a certain collision, check the energy of the collision in a post_step() callback and use that to determine the volume of a sound effect to play.

View source

#friction : Float64#

The friction coefficient that will be applied to the pair of colliding objects.

Setting the value in a pre_solve() callback will override the value calculated by the space. The default calculation multiplies the friction of the two shapes together.

View source

#friction=(friction : Number)#

View source

#ignore : Bool#

Mark a collision pair to be ignored until the two objects separate.

Pre-solve and post-solve callbacks will not be called, but the separate callback will be called.

View source

#normal : Vect#

Get the normal of the collision.

View source

#point_a(i : Int) : Vect#

Get the position of the i-th contact point on the surface of the first shape.

View source

#point_b(i : Int) : Vect#

Get the position of the i-th contact point on the surface of the second shape.

View source

#removal? : Bool#

Returns true during a separate() callback if the callback was invoked due to an object removal.

View source

#restitution : Float64#

The restitution (elasticity) that will be applied to the pair of colliding objects.

Setting the value in a pre_solve() callback will override the value calculated by the space. The default calculation multiplies the elasticity of the two shapes together.

View source

#restitution=(restitution : Number)#

View source

#shapes : ::Tuple(Shape, Shape)#

Return the colliding shapes involved for this arbiter.

The order of their collision_type values will match the order set when the collision handler was registered.

View source

#surface_velocity : Vect#

The relative surface velocity of the two shapes in contact.

Setting the value in a pre_solve() callback will override the value calculated by the space. the default calculation subtracts the surface velocity of the second shape from the first and then projects that onto the tangent of the collision. This is so that only friction is affected by default calculation. Using a custom calculation, you can make something that responds like a pinball bumper, or where the surface velocity is dependent on the location of the contact point.

View source

#surface_velocity=(vr : Vect)#

View source

#total_impulse : Vect#

Calculate the total impulse including the friction that was applied by this arbiter.

This function should only be called from a post-solve, post-step or each_arbiter callback.

View source

#total_ke : Float64#

Calculate the amount of energy lost in a collision including static, but not dynamic friction.

This function should only be called from a post-solve, post-step or each_arbiter callback.

View source

class CP::CollisionHandler
inherits Reference #

Defines callbacks to configure custom collision handling.

Collision handlers have a pair of types; when a collision occurs between two shapes that have these types, the collision handler functions are triggered.

Shapes tagged as sensors (Shape#sensor? == true) never generate collisions that get processed, so collisions between sensors shapes and other shapes will never call the post_solve callback. They still generate begin, and separate callbacks, and the pre_solve callback is also called every frame even though there is no collision response.

pre_solve callbacks are called before the sleeping algorithm runs. If an object falls asleep, its post_solve callback won't be called until it's reawoken.

Methods#

#begin(arbiter : Arbiter, space : Space) : Bool#

This function is called when two shapes with types that match this collision handler begin colliding.

Returning false from a begin callback causes the collision to be ignored until the the separate callback is called when the objects stop colliding.

View source

#post_solve(arbiter : Arbiter, space : Space)#

This function is called each step when two shapes with types that match this collision handler are colliding.

It's called after the collision solver runs, so you can retrieve the collision impulse or kinetic energy if you want to use it to calculate sound volumes or damage amounts.

View source

#pre_solve(arbiter : Arbiter, space : Space) : Bool#

This function is called each step when two shapes with types that match this collision handler are colliding.

It's called before the collision solver runs so that you can affect a collision's outcome (by editing Arbiter#friction, Arbiter#restitution, Arbiter#surface_velocity).

Returning false from a pre-step callback causes the collision to be ignored until the next step.

View source

#separate(arbiter : Arbiter, space : Space)#

This function is called when two shapes with types that match this collision handler stop colliding.

To ensure that begin/separate are always called in balanced pairs, it will also be called when removing a shape while it's in contact with something or when deallocating the space.

View source

#type_a#

Collision type identifier of the first shape that this handler recognizes.

In the collision handler callback, the shape with this type will be the first argument.

View source

#type_b#

Collision type identifier of the second shape that this handler recognizes.

In the collision handler callback, the shape with this type will be the second argument.

View source

alias CP::CollisionHandler::CollisionType #

Alias definition

UInt64

struct CP::ContactPointSet
inherits Struct #

A struct that wraps up the important collision data for an arbiter.

Constructors#

.new(points : Slice(ContactPoint), normal : Vect)#

View source

Methods#

#count : Int32#

The number of contact points in the set.

View source

#normal : Vect#

The normal of the collision.

View source

#points : Slice(ContactPoint)#

The contact points (at most 2).

View source

struct CP::ContactPointSet::ContactPoint
inherits Struct #

Contains information about a contact point.

Constructors#

.new(point_a : Vect, point_b : Vect, distance : Number)#

View source

Methods#

#distance : Float64#

Penetration distance of the two shapes. Overlapping means it will be negative.

This value is calculated as (point2 - point1).dot(normal) and is ignored by Arbiter#contact_point_set=.

View source

#point_a : Vect#

The position of the contact on the surface of the first shape.

View source

#point_b : Vect#

The position of the contact on the surface of the second shape.

View source