Sets the sprite up for automatic collision using the built physics system. Once you have set a sprite to be controlled by physics you should use SetSpritePosition and SetSpriteAngle sparingly as these will interrupt the physics motion of the sprite. You can also use the SetSpritePhysicsVelocity and SetSpritePhysicsAngularVelocity to change the speed and direction of a sprite, but again these will interfere with the physics motion of the sprite. If you wish to influence the position or rotation of a physics sprite you should use the force and torque (rotational force) functions where possible, these will maintain smooth physics motion.

The mode parameter lets you choose how the sprite should behave in the physics world. Static means it will never move or rotate, dynamic means it will respond to all collisions and forces it encounters, including gravity and collisions with static objects. Kinematic is a special case which can be thought of as a moving static body, it will not respond to collisions or forces and will continue at its specified velocity forever, but dynamic items will respond to it and effectively be pushed out of the way.

The physics shape used is determined by the SetSpriteShape command, which must be called before this command and is expensive to change for circle and polygon shapes as they rebuild a shape from the pixels of the sprite's image.

Once you have called this command to determine the mode of the sprite, further calls will ignore the mode values and it will only reactivate a sprite that has been turned off, as the mode cannot be changed whilst the sprite is in the physics system. If you wish to change the mode of a sprite call SetSpritePhysicsDelete, which will delete all its physics settings, then call SetSpritePhysicsOn with the new mode. But doing this too often will slow the system down.

All physics sprites should be world sprites (not fixed to the screen), unless SetViewOffset is set to 0,0 in which case this doesn't matter. Otherwise debug shapes will not line up and sprites from different view spaces will not interact properly.


SetSpritePhysicsOn( iSpriteIndex, mode )