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.
#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.
#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.
#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.
#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.
#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.
#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.
#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.
#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.
#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!
#data : ::Pointer(Void)
#
The user data pointer associated with this pair of colliding objects.
#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.
#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.
#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.
#point_a(i : Int) : Vect
#
Get the position of the i-th contact point on the surface of the first shape.
#point_b(i : Int) : Vect
#
Get the position of the i-th contact point on the surface of the second shape.
#removal? : Bool
#
Returns true during a separate()
callback if the callback was
invoked due to an object removal.
#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.
#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.
#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.
#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.
#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.
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.
#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.
#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.
#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.
#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.
#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.