class CP::Space

Overview

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.

Defined in:

chipmunk/debug_draw.cr
chipmunk/space.cr

Constructors

Instance Method Summary

Constructor Detail

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

[View source]

Instance Method Detail

def 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]
def 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]
def 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]
def add(*items : Shape | Body | Constraint) #

Add multiple items


[View source]
def 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]
def 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]
def 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]
def 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]
def 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]
def bodies : Set(Body) #

Get all the bodies that are added to the space.


def 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]
def collision_bias=(collision_bias : Number) #

[View source]
def 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]
def collision_persistence=(collision_persistence : Timestamp) #

[View source]
def 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]
def collision_slop=(collision_slop : Number) #

[View source]
def constraints : Set(Constraint) #

Get all the constraints that are added to the space.


def contains?(body : Body) : Bool #

Test if a body has been added to the space.


[View source]
def contains?(shape : Shape) : Bool #

Test if a shape has been added to the space.


[View source]
def contains?(constraint : Constraint) : Bool #

Test if a constraint has been added to the space.


[View source]
def 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]
def 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]
def damping=(damping : Number) #

[View source]
def each_body(&block : Body -> ) #

Yield each body in the space.


[View source]
def each_constraint(&block : Constraint -> ) #

Yield each constraint in the space.


[View source]
def each_shape(&block : Shape -> ) #

Yield each shape in the space.


[View source]
def gravity : Vect #

Gravity to pass to rigid bodies when integrating velocity.

Defaults to (0,0).


[View source]
def gravity=(gravity : Vect) #

[View source]
def 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]
def idle_speed_threshold=(idle_speed_threshold : Number) #

[View source]
def 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]
def iterations=(iterations : Int) #

[View source]
def locked? : Bool #

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


[View source]
def 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]
def 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]
def point_query_nearest(point : Vect, max_distance : Number = 0, filter : ShapeFilter = ShapeFilter::ALL) : PointQueryInfo | Nil #

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

Returns nil if no shapes were found.


[View source]
def reindex(shape : Shape) #

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


[View source]
def reindex_shapes_for(body : Body) #

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


[View source]
def reindex_static #

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


[View source]
def 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]
def 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]
def 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]
def remove(*items : Shape | Body | Constraint) #

Remove multiple items


[View source]
def 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]
def 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]
def segment_query_first(start : Vect, end end_ : Vect, radius : Number = 0, filter : ShapeFilter = ShapeFilter::ALL) : SegmentQueryInfo | Nil #

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]
def shape_query(shape : Shape, &block : Shape, ContactPointSet -> ) #

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


[View source]
def shape_query(shape : Shape) : Array(Shape) #

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


[View source]
def shapes : Set(Shape) #

Get all the shapes that are added to the space.


def 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]
def sleep_time_threshold=(sleep_time_threshold : Number) #

[View source]
def 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]
def step(dt : Number) #

Step the space forward in time by dt seconds.


[View source]
def threads : Int #

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


[View source]
def threads=(nthreads : Int) #

Set number of threads for multithreaded physics solver


[View source]
def use_spatial_hash(dim : Number, count : Int) #

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


[View source]