Skip to content

Space

class CP::Space
inherits Reference #

Spaces are the basic unit of simulation. You add rigid bodies, shapes and joints to it and then step them all forward together through time.

Constructors#

.new(*, threaded : Bool = true)#

View source

Methods#

#add(body : Body) : Body#

Add a body to the simulation.

If this method is called during a simulation step, the addition will be delayed until the step is finished.

Returns the same Body, for convenience.

View source

#add(shape : Shape) : Shape#

Add a shape to the simulation.

If the collision shape is attached to a static body, it will be added as a static shape.

If this method is called during a simulation step, the addition will be delayed until the step is finished.

Returns the same Shape, for convenience.

View source

#add(constraint : Constraint) : Constraint#

Add a constraint to the simulation.

If this method is called during a simulation step, the addition will be delayed until the step is finished.

Returns the same Constraint, for convenience.

View source

#add(*items : Shape | Body | Constraint)#

Add multiple items

View source

#add_collision_handler(a : Int, b : Int, handler : CollisionHandler) : CollisionHandler#

Whenever shapes with collision types a and b collide, this handler will be used to process the collision events.

If wildcard handlers are used with either of the collision types, it's the responibility of the custom handler to invoke the wildcard handlers.

View source

#add_collision_handler(type : Int, handler : CollisionHandler) : CollisionHandler#

Set a wildcard collision handler for the specified type.

This handler will be used any time an object with this type collides with another object, regardless of its type.

View source

#add_collision_handler(handler : CollisionHandler) : CollisionHandler#

Set a collision handler that is called for all collisions that are not handled by a more specific collision handler.

View source

#bb_query(bb : BB, filter : ShapeFilter = ShapeFilter::ALL, &block : Shape -> )#

Perform a fast rectangle query on the space, yielding each shape found.

Only the shapes' bounding boxes are checked for overlap, not their full shape.

View source

#bb_query(bb : BB, filter : ShapeFilter = ShapeFilter::ALL) : Array(Shape)#

Perform a fast rectangle query on the space, yielding each shape found.

Only the shapes' bounding boxes are checked for overlap, not their full shape.

View source

#collision_bias : Float64#

Determines how fast overlapping shapes are pushed apart.

Expressed as a fraction of the error remaining after each second. Defaults to (1.0 - 0.1)**60.0 meaning that Chipmunk fixes 10% of overlap each frame at 60Hz.

View source

#collision_bias=(collision_bias : Number)#

View source

#collision_persistence : Timestamp#

Number of frames that contact information should persist.

Defaults to 3. There is probably never a reason to change this value.

View source

#collision_persistence=(collision_persistence : Timestamp)#

View source

#collision_slop : Float64#

Amount of encouraged penetration between colliding shapes.

Used to reduce oscillating contacts and keep the collision cache warm. Defaults to 0.1. If you have poor simulation quality, increase this number as much as possible without allowing visible amounts of overlap.

View source

#collision_slop=(collision_slop : Number)#

View source

#contains?(body : Body) : Bool#

Test if a body has been added to the space.

View source

#contains?(shape : Shape) : Bool#

Test if a shape has been added to the space.

View source

#contains?(constraint : Constraint) : Bool#

Test if a constraint has been added to the space.

View source

#current_time_step : Float64#

Returns the current (or most recent) time step used with the given space.

Useful from callbacks if your time step is not a compile-time global.

View source

#damping : Float64#

Damping rate expressed as the fraction of velocity bodies retain each second.

A value of 0.9 would mean that each body's velocity will drop 10% per second. The default value is 1.0, meaning no damping is applied.

Note: This damping value is different than those of DampedSpring and DampedRotarySpring.

View source

#damping=(damping : Number)#

View source

#each_body#

Yield each body in the space.

View source

#each_constraint#

Yield each constraint in the space.

View source

#each_shape#

Yield each shape in the space.

View source

#gravity : Vect#

Gravity to pass to rigid bodies when integrating velocity.

Defaults to (0,0).

View source

#gravity=(gravity : Vect)#

View source

#idle_speed_threshold : Float64#

Speed threshold for a body to be considered idle.

The default value of 0 means to let the space guess a good threshold based on gravity.

View source

#idle_speed_threshold=(idle_speed_threshold : Number)#

View source

#iterations : Int32#

Number of iterations to use in the impulse solver to solve contacts and other constraints.

Chipmunk uses an iterative solver to figure out the forces between objects in the space. What this means is that it builds a big list of all of the collisions, joints, and other constraints between the bodies and makes several passes over the list considering each one individually. The number of passes it makes is the iteration count, and each iteration makes the solution more accurate. If you use too many iterations, the physics should look nice and solid, but may use up too much CPU time. If you use too few iterations, the simulation may seem mushy or bouncy when the objects should be solid. Setting the number of iterations lets you balance between CPU usage and the accuracy of the physics. Chipmunk's default of 10 iterations is sufficient for most simple games.

View source

#iterations=(iterations : Int)#

View source

#locked? : Bool#

Returns true from inside a callback when objects cannot be added/removed.

View source

#point_query(point : Vect, max_distance : Number = 0, filter : ShapeFilter = ShapeFilter::ALL, &block : PointQueryInfo -> )#

Query the space at a point for shapes within the given distance range.

The filter is applied to the query and follows the same rules as the collision detection. Sensor shapes are included. If a max_distance of 0 is used, the point must lie inside a shape. Negative max_distance is also allowed meaning that the point must be a under a certain depth within a shape to be considered a match.

View source

#point_query(point : Vect, max_distance : Number = 0, filter : ShapeFilter = ShapeFilter::ALL) : Array(PointQueryInfo)#

Query the space at a point for shapes within the given distance range.

The filter is applied to the query and follows the same rules as the collision detection. Sensor shapes are included. If a max_distance of 0 is used, the point must lie inside a shape. Negative max_distance is also allowed meaning that the point must be a under a certain depth within a shape to be considered a match.

View source

#point_query_nearest(point : Vect, max_distance : Number = 0, filter : ShapeFilter = ShapeFilter::ALL) : PointQueryInfo?#

Query the space at a point and return the nearest shape found.

Returns nil if no shapes were found.

View source

#reindex(shape : Shape)#

Update the collision detection data for a specific shape in the space.

View source

#reindex_shapes_for(body : Body)#

Update the collision detection data for all shapes attached to a body.

View source

#reindex_static#

Update the collision detection info for the static shapes in the space.

View source

#remove(body : Body)#

Remove a body from the simulation.

If this method is called during a simulation step, the removal will be delayed until the step is finished.

View source

#remove(shape : Shape)#

Remove a shape from the simulation.

If this method is called during a simulation step, the removal will be delayed until the step is finished.

View source

#remove(constraint : Constraint)#

Remove a constraint from the simulation.

If this method is called during a simulation step, the removal will be delayed until the step is finished.

View source

#remove(*items : Shape | Body | Constraint)#

Remove multiple items

View source

#segment_query(start : Vect, end end_ : Vect, radius : Number = 0, filter : ShapeFilter = ShapeFilter::ALL, &block : SegmentQueryInfo -> )#

Perform a directed line segment query (like a raycast) against the space and yield each shape intersected.

The filter is applied to the query and follows the same rules as the collision detection. Sensor shapes are included.

View source

#segment_query(start : Vect, end end_ : Vect, radius : Number = 0, filter : ShapeFilter = ShapeFilter::ALL) : Array(SegmentQueryInfo)#

Perform a directed line segment query (like a raycast) against the space and yield each shape intersected.

The filter is applied to the query and follows the same rules as the collision detection. Sensor shapes are included.

View source

#segment_query_first(start : Vect, end end_ : Vect, radius : Number = 0, filter : ShapeFilter = ShapeFilter::ALL) : SegmentQueryInfo?#

Perform a directed line segment query (like a raycast) against the space and return the first shape hit.

Returns nil if no shapes were hit.

View source

#shape_query(shape : Shape, &block : Shape, ContactPointSet -> )#

Query a space for any shapes overlapping the given shape and yield each shape found.

View source

#shape_query(shape : Shape) : Array(Shape)#

Query a space for any shapes overlapping the given shape and yield each shape found.

View source

#sleep_time_threshold : Float64#

Time a group of bodies must remain idle in order to fall asleep.

Enabling sleeping also implicitly enables the the contact graph. The default value of INFINITY disables the sleeping algorithm.

View source

#sleep_time_threshold=(sleep_time_threshold : Number)#

View source

#static_body : Body#

The Space provided static body for a given Space.

This is merely provided for convenience and you are not required to use it.

View source

#step(dt : Number)#

Step the space forward in time by dt seconds.

View source

#threads : Int#

Returns number of threads for multithreaded physics solver or 0 if the space isn't hasty

View source

#threads=(nthreads : Int)#

Set number of threads for multithreaded physics solver

View source

#use_spatial_hash(dim : Number, count : Int)#

Switch the space to use a spatial has as its spatial index.

View source

alias CP::Space::Timestamp #

Alias definition

UInt32