ChipmunkSpace Class Reference

Chipmunk spaces are simulation containers. More...

#import <ChipmunkSpace.h>

List of all members.

Public Member Functions
(void)	- setDefaultCollisionHandler:begin:preSolve:postSolve:separate:
	Set the default collision handler.
(void)	- addCollisionHandler:typeA:typeB:begin:preSolve:postSolve:separate:
	Set a collision handler to handle specific collision types.
(void)	- removeCollisionHandlerForTypeA:andB:
	Remove a collision handler.
(id)	- add:
	Add an object to the space.
(id)	- remove:
	Remove an object from the space.
(id< ChipmunkObject >)	- smartAdd:
	If the space is locked and it's unsafe to call add: it will call addPostStepAddition: instead.
(id< ChipmunkObject >)	- smartRemove:
	If the space is locked and it's unsafe to call remove: it will call addPostStepRemoval: instead.
(void)	- addPostStepCallback:selector:key:
	Define a callback to be run just before [ChipmunkSpace step:] finishes.
(typedef)	- void
	Block type used with [ChipmunkSpace addPostStepBlock:].
(void)	- addPostStepBlock:key:
	Same as [ChipmunkSpace addPostStepCallback:] but with a block. The passed block is copied instead of retained.
(void)	- addPostStepAddition:
	Add the Chipmunk Object from the space at the end of the step.
(void)	- addPostStepRemoval:
	Remove the Chipmunk Object from the space at the end of the step.
(NSArray *)	- pointQueryAll:layers:group:
	Returns a NSArray of all shapes that overlap the given point. The point is treated as having the given group and layers.
(ChipmunkShape *)	- pointQueryFirst:layers:group:
	Returns the first shape that overlaps the given point. The point is treated as having the given group and layers.
(NSArray *)	- segmentQueryAllFrom:to:layers:group:
	Return a NSArray of ChipmunkSegmentQueryInfo objects for all the shapes that overlap the segment. The objects are unsorted.
(ChipmunkSegmentQueryInfo *)	- segmentQueryFirstFrom:to:layers:group:
	Returns the first shape that overlaps the given segment. The segment is treated as having the given group and layers.
(NSArray *)	- bbQueryAll:layers:group:
	Returns a NSArray of all shapes whose bounding boxes overlap the given bounding box. The box is treated as having the given group and layers.
(NSArray *)	- shapeQueryAll:
	Returns a NSArray of ChipmunkShapeQueryInfo objects for all the shapes that overlap shape.
(BOOL)	- shapeTest:
	Returns true if the shape overlaps anything in the space.
(void)	- activateShapesTouchingShape:
	Perform a shape query for shape and call cpBodyActivate() for everythnig it touches.
(NSArray *)	- bodies
	Get a copy of the list of all the bodies in the space.
(NSArray *)	- shapes
	Get a copy of the list of all the shapes in the space.
(NSArray *)	- constraints
	Get a copy of the list of all the constraints in the space.
(void)	- reindexStatic
	Update all the static shapes.
(void)	- reindexShape:
	Update the collision info for a single shape.
(void)	- reindexShapesForBody:
	Update the collision info for all shapes attached to a body.
(void)	- step:
	Step time forward. While variable timesteps may be used, a constant timestep will allow you to reduce CPU usage by using fewer iterations.
(void)	- addBounds:thickness:elasticity:friction:layers:group:collisionType:
	Add a border of collision segments around a box. See ChipmunkShape for more information on the other parameters.
(ChipmunkBody *)	- addBody:
	Add a body to the space. Normally you would simply use add:.
(ChipmunkBody *)	- removeBody:
	Remove a body to the space. Normally you would simply use remove:.
(ChipmunkShape *)	- addShape:
	Add a shape to the space. Normally you would simply use add:.
(ChipmunkShape *)	- removeShape:
	Remove a shape to the space. Normally you would simply use remove:.
(ChipmunkShape *)	- addStaticShape:
	Add a static shape to the space. Normally you would simply create a static shape use add:.
(ChipmunkShape *)	- removeStaticShape:
	Remove a static shape to the space. Normally you would simply create a static shape use remove:.
(ChipmunkConstraint *)	- addConstraint:
	Add a constraint to the space. Normally you would simply use add:.
(ChipmunkConstraint *)	- removeConstraint:
	Remove a constraint to the space. Normally you would simply use remove:.
Properties
int	iterations
	The iteration count is how many solver passes the space should use when solving collisions and joints (default is 10).
cpVect	gravity
	Global gravity value to use for all rigid bodies in this space (default value is cpvzero).
cpFloat	damping
	Global viscous damping value to use for all rigid bodies in this space (default value is 1.0 which disables damping).
cpFloat	idleSpeedThreshold
	If a body is moving slower than this speed, it is considered idle. The default value is 0, which signals that the space should guess a good value based on the current gravity.
cpFloat	sleepTimeThreshold
	Elapsed time before a group of idle bodies is put to sleep (defaults to infinity which disables sleeping).
cpFloat	collisionSlop
cpFloat	collisionBias
cpTimestamp	collisionPersistence
bool	enableContactGraph
cpSpace *	space
	Returns a pointer to the underlying cpSpace C struct.
ChipmunkBody *	staticBody
	The space's designated static body.
cpFloat	currentTimeStep
	Retrieves the current (if you are in a callback from [ChipmunkSpace step:]) or most recent (outside of a [ChipmunkSpace step:] call) timestep.
id	data
	An object that this space is associated with.

---

Detailed Description

Chipmunk spaces are simulation containers.

You add a bunch of physics objects to a space (rigid bodies, collision shapes, and joints) and step the entire space forward through time as a whole.

---

Member Function Documentation

- (id) add:

(id< ChipmunkObject >)

obj

Add an object to the space.

This can be any object that implements the ChipmunkObject protocol. This includes all the basic types such as ChipmunkBody, ChipmunkShape and ChipmunkConstraint as well as any composite game objects you may define that implement the protocol.

Warning:

This method may not be called from a collision handler callback. See smartAdd: or ChipmunkSpace.addPostStepCallback:selector:context: for information on how to do that.

- (void) addCollisionHandler:		(id)	delegate
typeA:		(id)	a
typeB:		(id)	b
begin:		(SEL)	begin
preSolve:		(SEL)	preSolve
postSolve:		(SEL)	postSolve
separate:		(SEL)	separate

Set a collision handler to handle specific collision types.

The methods are called only when shapes with the specified collisionTypes collide.

typeA and typeB should be the same object references set to ChipmunkShape.collisionType. They can be any uniquely identifying object. Class and global NSString objects work well as collision types as they are easy to get a reference to and do not require you to allocate any objects.

The expected method selectors are as follows:

- (bool)begin:(cpArbiter *)arbiter space:(ChipmunkSpace*)space
- (bool)preSolve:(cpArbiter *)arbiter space:(ChipmunkSpace*)space
- (void)postSolve:(cpArbiter *)arbiter space:(ChipmunkSpace*)space
- (void)separate:(cpArbiter *)arbiter space:(ChipmunkSpace*)space

- (void) addPostStepCallback:		(id)	target
selector:		(SEL)	selector
key:		(id)	key

Define a callback to be run just before [ChipmunkSpace step:] finishes.

The main reason you want to define post-step callbacks is to get around the restriction that you cannot call the add/remove methods from a collision handler callback. Post-step callbacks run right before the next (or current) call to step: returns when it is safe to add and remove objects. You can only schedule one post-step callback per key value, this prevents you from accidentally removing an object twice. Registering a second callback for the same key is a no-op.

The method signature of the method should be:

- (void)postStepCallback:(id)key</code></pre>

This makes it easy to call a removal method on your game controller to remove a game object that died or was destroyed as the result of a collision:

[space addPostStepCallback:gameController selector:@selector(remove:) key:gameObject];

Attention:

Not to be confused with post-solve collision handler callbacks.

Warning:

target and object cannot be retained by the ChipmunkSpace. If you need to release either after registering the callback, use autorelease to ensure that they won't be deallocated until after [ChipmunkSpace step:] returns.

See also:

- addPostStepRemoval:

- (void) reindexShape:

(ChipmunkShape *)

shape

Update the collision info for a single shape.

Can be used to update individual static shapes that were moved or active shapes that were moved that you want to query against.

- (id) remove:

(id< ChipmunkObject >)

obj

Remove an object from the space.

This can be any object that implements the ChipmunkObject protocol. This includes all the basic types such as ChipmunkBody, ChipmunkShape and ChipmunkConstraint as well as any composite game objects you may define that implement the protocol.

Warning:

This method may not be called from a collision handler callback. See smartRemove: or ChipmunkSpace.addPostStepCallback:selector:context: for information on how to do that.

- (void) setDefaultCollisionHandler:		(id)	delegate
begin:		(SEL)	begin
preSolve:		(SEL)	preSolve
postSolve:		(SEL)	postSolve
separate:		(SEL)	separate

Set the default collision handler.

The default handler is used for all collisions when a specific collision handler cannot be found.

The expected method selectors are as follows:

- (bool)begin:(cpArbiter *)arbiter space:(ChipmunkSpace*)space
- (bool)preSolve:(cpArbiter *)arbiter space:(ChipmunkSpace*)space
- (void)postSolve:(cpArbiter *)arbiter space:(ChipmunkSpace*)space
- (void)separate:(cpArbiter *)arbiter space:(ChipmunkSpace*)space

---

Property Documentation

- (cpFloat) damping [read, write, assign]

Global viscous damping value to use for all rigid bodies in this space (default value is 1.0 which disables damping).

This value is the fraction of velocity a body should have after 1 second. A value of 0.9 would mean that each second, a body would have 80% of the velocity it had the previous second.

- (id) data [read, write, assign]

An object that this space is associated with.

You can use this get a reference to your game state or controller object from within callbacks.

Attention:

Like most delegate properties this is a weak reference and does not call retain. This prevents reference cycles from occuring.

- (int) iterations [read, write, assign]

The iteration count is how many solver passes the space should use when solving collisions and joints (default is 10).

Fewer iterations mean less CPU usage, but lower quality (mushy looking) physics.

- (cpFloat) sleepTimeThreshold [read, write, assign]

Elapsed time before a group of idle bodies is put to sleep (defaults to infinity which disables sleeping).

If an entire group of touching or jointed bodies has been idle for at least this long, the space will put all of the bodies into a sleeping state where they consume very little CPU.

- (ChipmunkBody*) staticBody [read, assign]

The space's designated static body.

Collision shapes added to the body will automatically be marked as static shapes, and rigid bodies that come to rest while touching or jointed to this body will fall asleep.

---

The documentation for this class was generated from the following file:

• ChipmunkSpace.h