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, elastic_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
 
resize_static_hash(self, dim=100.0, count=1000)
The spatial hashes used by pymunk's collision detection are fairly size sensitive.
 
resize_active_hash(self, dim=100.0, count=1000)
The spatial hashes used by pymunk's collision detection are fairly size sensitive.
 
rehash_static(self)
Rehashes the shapes in the static spatial hash.
 
step(self, dt)
Update the space for the given time step.
 
add_collision_handler(self, a, b, begin, pre_solve, post_solve, separate, *args, **kwargs)
Add a collision handler for given collision type pair.
 
set_default_collision_handler(self, begin, pre_solve, post_solve, separate, *args, **kwargs)
Register a default collision handler to be used when no specific collision handler is found.
 
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.
 
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.
 
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.

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
  gravity
Default gravity to supply when integrating rigid body motions.
  damping
Default damping to supply when integrating rigid body motions.

Inherited from object: __class__

Method Details

__init__(self, iterations=10, elastic_iterations=10)
(Constructor)

 

Create a new instace of the Space

If the objects in your Space does not have any elasticity set elastic_iterations to 0 to gain a little speedup.

Parameters:
  • iterations (int) - Number of iterations to use in the impulse solver to solve contacts.
  • elastic_iterations (int) - Number of iterations to use in the impulse solver to solve elastic 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.

resize_static_hash(self, dim=100.0, count=1000)

 

The spatial hashes used by pymunk's collision detection are fairly size sensitive. dim is the size of the hash cells. Setting dim to the average objects size is likely to give the best performance.

count is the suggested minimum number of cells in the hash table. Bigger is better, but only to a point. Setting count to ~10x the number of objects in the hash is probably a good starting point.

Because static shapes are only rehashed when you request it, it's possible to use a much higher count argument to resize_static_hash() than to resize_active_hash(). Doing so will use more memory though.

resize_active_hash(self, dim=100.0, count=1000)

 

The spatial hashes used by pymunk's collision detection are fairly size sensitive. dim is the size of the hash cells. Setting dim to the average objects size is likely to give the best performance.

count is the suggested minimum number of cells in the hash table. Bigger is better, but only to a point. Setting count to ~10x the number of objects in the hash is probably a good starting point.

rehash_static(self)

 
Rehashes the shapes in the static spatial hash. You only need to call this if you move one of the static shapes.

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, pre_solve, post_solve, separate, *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, pre_solve, post_solve, separate, *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.

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.

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)

gravity

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

damping

Default damping to supply when integrating rigid body motions.
Get Method:
_get_damping(self)
Set Method:
_set_damping(self, damping)