Package pymunk :: Class Space
[frames] | no frames]

Class Space

object --+
         |
        Space

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.
Instance Methods
 
__init__(self, iterations=10)
Create a new instace of the Space
 
__del__(self)
 
add(self, *objs)
Add one or many shapes, bodies or joints to the space
 
add_static(self, *objs)
Add one or many static shapes to the space
 
remove(self, *objs)
Remove one or many shapes, bodies or constraints from the space
 
remove_static(self, *objs)
Remove one or many static shapes from the space
 
reindex_static(self)
Update the collision detection info for the static shapes in the space. You only need to call this if you move one of the static shapes.
 
reindex_shape(self, shape)
Update the collision detection data for a specific shape in the space.
 
step(self, dt)
Update the space for the given time step. Using a fixed time step is highly recommended. Doing so will increase the efficiency of the contact persistence, requiring an order of magnitude fewer iterations to resolve the collisions in the usual case.
 
add_collision_handler(self, a, b, begin=None, pre_solve=None, post_solve=None, separate=None, *args, **kwargs)
Add a collision handler for given collision type pair.
 
set_default_collision_handler(self, begin=None, pre_solve=None, post_solve=None, separate=None, *args, **kwargs)
Register a default collision handler to be used when no specific collision handler is found. If you do nothing, the space will be given a default handler that accepts all collisions in begin() and pre_solve() and does nothing for the post_solve() and separate() callbacks.
 
remove_collision_handler(self, a, b)
Remove a collision handler for a given collision type pair.
 
add_post_step_callback(self, callback_function, obj, *args, **kwargs)
Add a function to be called last in the next simulation step.
 
point_query(self, point, layers=-1, group=0)
Query space at point filtering out matches with the given layers and group. Return a list of found shapes.
 
point_query_first(self, point, layers=-1, group=0)
Query space at point and return the first shape found matching the given layers and group. Returns None if no shape was found.
 
segment_query(self, start, end, layers=-1, group=0)
Query space along the line segment from start to end filtering out matches with the given layers and group.
 
segment_query_first(self, start, end, layers=-1, group=0)
Query space along the line segment from start to end filtering out matches with the given layers and group. Only the first shape encountered is returned and the search is short circuited. Returns None if no shape was found.
 
bb_query(self, bb, layers=-1, group=0)
Perform a fast rectangle query on the space.
 
shape_query(self, shape)
Query a space for any shapes overlapping the given shape

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Properties
  shapes
A list of the shapes added to this space
  static_shapes
A list of the static shapes added to this space
  bodies
A list of the bodies added to this space
  constraints
A list of the constraints added to this space
  static_body
A convenience static body already added to the space
  iterations
Number of iterations to use in the impulse solver to solve contacts.
  gravity
Default gravity to supply when integrating rigid body motions.
  damping
Damping rate expressed as the fraction of velocity bodies retain each second.
  idle_speed_threshold
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.
  sleep_time_threshold
Time a group of bodies must remain idle in order to fall asleep.
  collision_slop
Amount of allowed penetration.
  collision_bias
Determines how fast overlapping shapes are pushed apart.
  collision_persistence
Number of frames that contact information should persist.
  enable_contact_graph
Rebuild the contact graph during each step.

Inherited from object: __class__

Method Details

__init__(self, iterations=10)
(Constructor)

 

Create a new instace of the Space

Its usually best to keep the elastic_iterations setting to 0. Only change if you have problem with stacking elastic objects on each other. If that is the case, try to raise it. However, a value other than 0 will affect other parts, most importantly you wont get reliable total_impulse readings from the Arbiter object in collsion callbacks!

Parameters:
  • iterations (int) - Number of iterations to use in the impulse solver to solve contacts.
Overrides: object.__init__

remove(self, *objs)

 

Remove one or many shapes, bodies or constraints from the space

Note When removing objects from the space, make sure you remove any other objects that reference it. For instance, when you remove a body, remove the joints and shapes attached to it.

add_collision_handler(self, a, b, begin=None, pre_solve=None, post_solve=None, separate=None, *args, **kwargs)

 

Add a collision handler for given collision type pair.

Whenever a shapes with collision_type a and collision_type b collide, these callbacks will be used to process the collision. None can be provided for callbacks you do not wish to implement, however pymunk will call it's own default versions for these and not the default ones you've set up for the Space. If you need to fall back on the space's default callbacks, you'll have to provide them individually to each handler definition.

Parameters:
  • a (int) - Collision type of the first shape
  • b (int) - Collision type of the second shape
  • begin (func(space, arbiter, *args, **kwargs) -> bool) - Collision handler called when two shapes just started touching for the first time this step. Return false from the callback to make pymunk ignore the collision or true to process it normally. Rejecting a collision from a begin() callback permanently rejects the collision until separation. Pass None if you wish to use the pymunk default.
  • pre_solve (func(space, arbiter, *args, **kwargs) -> bool) - Collision handler called when two shapes are touching. Return false from the callback to make pymunk ignore the collision or true to process it normally. Additionally, you may override collision values such as Arbiter.elasticity and Arbiter.friction to provide custom friction or elasticity values. See Arbiter for more info. Pass None if you wish to use the pymunk default.
  • post_solve (func(space, arbiter, *args, **kwargs)) - Collsion handler called when two shapes are touching and their collision response has been processed. You can retrieve the collision force at this time if you want to use it to calculate sound volumes or damage amounts. Pass None if you wish to use the pymunk default.
  • separate (func(space, arbiter, *args, **kwargs)) - Collision handler called when two shapes have just stopped touching for the first time this frame. Pass None if you wish to use the pymunk default.
  • args - Optional parameters passed to the collision handler functions.
  • kwargs - Optional keyword parameters passed on to the collision handler functions.

set_default_collision_handler(self, begin=None, pre_solve=None, post_solve=None, separate=None, *args, **kwargs)

 
Register a default collision handler to be used when no specific collision handler is found. If you do nothing, the space will be given a default handler that accepts all collisions in begin() and pre_solve() and does nothing for the post_solve() and separate() callbacks.
Parameters:
  • begin (func(space, arbiter, *args, **kwargs) -> bool) - Collision handler called when two shapes just started touching for the first time this step. Return False from the callback to make pymunk ignore the collision or True to process it normally. Rejecting a collision from a begin() callback permanently rejects the collision until separation. Pass None if you wish to use the pymunk default.
  • pre_solve (func(space, arbiter, *args, **kwargs) -> bool) - Collision handler called when two shapes are touching. Return False from the callback to make pymunk ignore the collision or True to process it normally. Additionally, you may override collision values such as Arbiter.elasticity and Arbiter.friction to provide custom friction or elasticity values. See Arbiter for more info. Pass None if you wish to use the pymunk default.
  • post_solve (func(space, arbiter, *args, **kwargs)) - Collsion handler called when two shapes are touching and their collision response has been processed. You can retrieve the collision force at this time if you want to use it to calculate sound volumes or damage amounts. Pass None if you wish to use the pymunk default.
  • separate (func(space, arbiter, *args, **kwargs)) - Collision handler called when two shapes have just stopped touching for the first time this frame. Pass None if you wish to use the pymunk default.
  • args - Optional parameters passed to the collision handler functions.
  • kwargs - Optional keyword parameters passed on to the collision handler functions.

remove_collision_handler(self, a, b)

 
Remove a collision handler for a given collision type pair.
Parameters:
  • a (int) - Collision type of the first shape
  • b (int) - Collision type of the second shape

add_post_step_callback(self, callback_function, obj, *args, **kwargs)

 

Add a function to be called last in the next simulation step.

Post step callbacks are the place where you can break the rules about removing objects from within a callback. In fact, their primary function is to help you safely remove objects from the space that were destroyed or disabled during the step.

Post step callbacks are registered as a function and an object used as a key. You can only register one post step callback per object. This prevents you from removing an object more than once. For instance, say that you get a collision callback between a bullet and object A. The bullet and object A are destroyed, so you add a post step callback for each to remove. In the same step, the same bullet also hit object B and you add two more callbacks, one for object B and a second for the bullet. This is actually just fine, and the callback to remove the bullet will only be called once!

Parameters:
  • callback_function (func(obj, *args, **kwargs)) - The callback function.
  • obj (Any object) - This object is used as a key, you can only have one callback for a single object. It is passed on to the callback function.
  • args - Optional parameters passed to the callback function.
  • kwargs - Optional keyword parameters passed on to the callback function.

point_query(self, point, layers=-1, group=0)

 

Query space at point filtering out matches with the given layers and group. Return a list of found shapes.

If you don't want to filter out any matches, use -1 for the layers and 0 as the group.

Parameters:
  • point ((x,y) or Vec2d) - Define where to check for collision in the space.
  • layers (int) - Only pick shapes matching the bit mask. i.e. (layers & shape.layers) != 0
  • group (int) - Only pick shapes in this group.

point_query_first(self, point, layers=-1, group=0)

 
Query space at point and return the first shape found matching the given layers and group. Returns None if no shape was found.
Parameters:
  • point ((x,y) or Vec2d) - Define where to check for collision in the space.
  • layers (int) - Only pick shapes matching the bit mask. i.e. (layers & shape.layers) != 0
  • group (int) - Only pick shapes in this group.

segment_query(self, start, end, layers=-1, group=0)

 

Query space along the line segment from start to end filtering out matches with the given layers and group.

Segment queries are like ray casting, but because pymunk uses a spatial hash to process collisions, it cannot process infinitely long queries like a ray. In practice this is still very fast and you don't need to worry too much about the performance as long as you aren't using very long segments for your queries.

Returns:
[SegmentQueryInfo] - One SegmentQueryInfo object for each hit.

bb_query(self, bb, layers=-1, group=0)

 

Perform a fast rectangle query on the space.

Only the shape's bounding boxes are checked for overlap, not their full shape. Returns a list of shapes.

shape_query(self, shape)

 

Query a space for any shapes overlapping the given shape

Returns a list of shapes.


Property Details

shapes

A list of the shapes added to this space
Get Method:
_get_shapes(self)

static_shapes

A list of the static shapes added to this space
Get Method:
_get_static_shapes(self)

bodies

A list of the bodies added to this space
Get Method:
_get_bodies(self)

constraints

A list of the constraints added to this space
Get Method:
_get_constraints(self)

static_body

A convenience static body already added to the space
Get Method:
_get_static_body(self) - A convenience static body already added to the space

iterations

Number of iterations to use in the impulse solver to solve contacts.
Get Method:
_get_iterations(self)
Set Method:
_set_iterations(self, iterations)

gravity

Default gravity to supply when integrating rigid body motions.
Get Method:
_get_gravity(self)
Set Method:
_set_gravity(self, gravity_vec)

damping

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.

Get Method:
_get_damping(self)
Set Method:
_set_damping(self, damping)

idle_speed_threshold

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.
Get Method:
_get_idle_speed_threshold(self)
Set Method:
_set_idle_speed_threshold(self, idle_speed_threshold)

sleep_time_threshold

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 inf disables the sleeping algorithm.

Get Method:
_get_sleep_time_threshold(self)
Set Method:
_set_sleep_time_threshold(self, sleep_time_threshold)

collision_slop

Amount of allowed penetration.

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.

Get Method:
_get_collision_slop(self)
Set Method:
_set_collision_slop(self, collision_slop)

collision_bias

Determines how fast overlapping shapes are pushed apart.

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

Get Method:
_get_collision_bias(self)
Set Method:
_set_collision_bias(self, collision_bias)

collision_persistence

Number of frames that contact information should persist.

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

Get Method:
_get_collision_persistence(self)
Set Method:
_set_collision_persistence(self, collision_persistence)

enable_contact_graph

Rebuild the contact graph during each step.

Must be enabled to use the cpBodyEachArbiter() function. Disabled by default for a small performance boost.

Get Method:
_get_enable_contact_graph(self)
Set Method:
_set_enable_contact_graph(self, enable_contact_graph)