Moscrif API Docs for: 2012q3
Show:

PhysicsSprite Class

include "lib://box2d/physicsSprite.ms";
Library: box2d

The physics sprite represents rigid body in the physics simulation. The sprite's behaviour can be customized by several properties like density, friction or bounce. Three types of sprites are supported: #dynamic, #static, #kinematic. Every body type have different behaviour. Instances of this class are usually created by addCircleBody or addPolygonBodymethods.

Methods

_createBody

() private

Create box2d body

_createShape

(
  • shapeType
)
private

Private function, which is used to create create shape of the sprite.

Parameters:

  • shapeType Symbol

    shapeType #polygon #circle

applyAngularImpulse

(
  • impulse
)

Apply an angular impulse.

Parameters:

applyForce

(
  • forceX
  • forceY
  • pointX
  • pointY
)

Apply a force at a world point. If the force is not applied at the center of mass, it will generate a torque and affect the angular velocity This wakes up sleeping body.

Parameters:

  • forceX Float

    The world force on x axis, usually in Newtons

  • forceY Float

    The world force on y axis, usually in Newtons

  • pointX Float

    The world x coordinate of the point of force application

  • pointY Float

    The world y coordinate of the point of force application

applyLinearImpulse

(
  • impulseX
  • impulseY
  • pointX
  • pointY
)

Apply an impulse at a point. This immediately modifies the velocity. It also modifies the angular velocity if the point of application is not at the center of mass. If the body is sleeping, this wakes up it.

Parameters:

  • impulseX Float

    The world impulse on x axis, usually in N-seconds or kg-m/s.

  • impulseY Float

    The world impulse on y axis, usually in N-seconds or kg-m/s.

  • pointX Float

    The world x position of the point of application.

  • pointY Float

    The world y position of the point of application.

applyTorque

(
  • torque
)

Apply a torque. This affects the angular velocity without affecting the linear velocity of the center of mass. This wakes up the body.

Parameters:

create

(
  • scene
  • image
  • shape
  • bodyType
  • density
  • friction
  • bounce
  • calledClass
)

Create Physics Body into current PhysicsWorld.

Parameters:

  • scene PhysicsScene

    instance of scene into which should be sprite added

  • image Bitmap

    Image drawen in the body

  • shape B2CircleShape | B2PolygonShape

    Shape of new object.

  • bodyType Symbol

    BodyType's type #static - A static body has does not move under simulation and behaves as if it has infinite mass. Internally, Box2D stores zero for the mass and the inverse mass. Static bodies can be moved manually by the user. A static body has zero velocity. Static bodies do not collide with other static or kinematic bodies. #dynamic - A dynamic body is fully simulated. They can be moved manually by the user, but normally they move according to forces. A dynamic body can collide with all body types. A dynamic body always has finite, non-zero mass. If you try to set the mass of a dynamic body to zero, it will automatically acquire a mass of one kilogram. #kinematic - A kinematic body moves under simulation according to its velocity. Kinematic bodies do not respond to forces. They can be moved manually by the user, but normally a kinematic body is moved by setting its velocity. A kinematic body behaves as if it has infinite mass, however, Box2D stores zero for the mass and the inverse mass. Kinematic bodies do not collide with other static or kinematic bodies

  • density Float

    Density of the sprite.

  • friction Float

    Friction of the sprite, affects the body adhesion.

  • bounce Float

    Bounce number from 0 to 1. The zero means non bounce -> one means full bounce.

  • calledClass Class

    = null Class to create a sprite. It should be class extended from PhysicsSprite..

Returns:

PhysicsSprite

draw

(
  • canvas
)
protected

Method to be executed when PhysicsSprite going to be drawn. The draw method can draw onto whole canvas, also outside the sprite. To ensure correct drawing sprite's image should have same dimensions as the sprite.

Parameters:

  • canvas Canvas

    Canvas used for drawing.

getAngularDamping

() Float

Get angular damping of the body. Damping is used to reduce the bodies' velocity. Damping is different than friction because friction only occurs with contact. Damping is not a replacement for friction and these two effects should be used together.

Returns:

Float: Angular damping of the body.

getBodyType;

()

Get type of body. The body type affects its behaviour in the simulation. Three body types are supported:

static - A static body has does not move under simulation and behaves as if it has infinite mass. Internally, Box2D stores zero for the mass and the inverse mass. Static bodies can be moved manually by the user. A static body has zero velocity. Static bodies do not collide with other static or kinematic bodies.

dynamic - A dynamic body is fully simulated. They can be moved manually by the user, but normally they move according to forces. A dynamic body can collide with all body types. A dynamic body always has finite, non-zero mass. If you try to set the mass of a dynamic body to zero, it will automatically acquire a mass of one kilogram.

kinematic - A kinematic body moves under simulation according to its velocity. Kinematic bodies do not respond to forces. They can be moved manually by the user, but normally a kinematic body is moved by setting its velocity. A kinematic body behaves as if it has infinite mass, however, Box2D stores zero for the mass and the inverse mass. Kinematic bodies do not collide with other static or kinematic bodies

Returns:

Symbol type of the body: #static, #kinematic or #dynamic

getGravity;

()

Get the global gravity. The gravity is a base feature of the physics scene and is same for all bodies

Returns:

Multivalue Pair of float values. First is gravity one x axis and second one y axis.

getInertia()

() Float

Get the rotational inertia of the body about the local origin.

Returns:

Float: The rotational inertia, usually in kg-m^2.

getLinearDamping

() Float

Get linear damping of the body. Damping is used to reduce the bodies' velocity. Damping is different than friction because friction only occurs with contact. Damping is not a replacement for friction and these two effects should be used together.

Returns:

Float: Linear damping of the body.

getLinearVelocity

() Multivalue

Get linear velocity of the center of mass.

Returns:

Multivalue: Pair of float values: linear velocity of the center of mass on x and y axis

Example:

var (vX, vY) = this._character.getLinearVelocity();

getLinearVelocityFromLocalPoint

(
  • lx
  • ly
)
Multivalue

Get the world linear velocity of a world point attached to this body.

Parameters:

  • lx Float

    X coordinate of point in world coordinates.

  • ly Float

    Y coordinate of point in world coordinates.

Returns:

Multivalue: Pair of float values: the world velocity on x and y axis of a point.

getLinearVelocityFromWorldPoint

(
  • wx
  • wy
)
Multivalue

Get the world velocity of a local point.

Parameters:

  • wx Float

    X coordinate of point in local coordinates.

  • wy Float

    Y coordinate of point in local coordinates.

Returns:

Multivalue: Pair of float values: the world velocity on x and y axis of a point.

getLocalCenter

()

Get the local position of the center of mass in screen coordinates -> pixels from left top corner of the screen.

Returns:

Multivalue Pair of float values: x,y.

getLocalPoint

(
  • worldPointX
  • worldPointY
)
Multivalue

Gets a local point relative to the body's origin given a world point in screen coordinates -> pixels from left top corner of the screen.

Parameters:

  • worldPointX Float

    X coordinate of point in world coordinates.

  • worldPointY Float

    Y coordinate of point in world coordinates.

Returns:

Multivalue: Pair of float values: the corresponding local point relative to the body's origin.

getLocalVector

(
  • localPointX
  • localPointY
)
Multivalue

Gets a local vector's x and y from given world vector's x and y coordinates in screen coordinates -> pixels from left top corner of the screen..

Parameters:

  • localPointX Float

    A world vector's x component.

  • localPointY Float

    A world vector's y component.

Returns:

Multivalue: The corresponding local vector's x and y components.

getMass

() Float

Get the total mass of the body in kilograms. The mass is calculated as a densityvolume. Because of the the box2d does not support the third dimension the volume is calculated like: volume = widthheight (width and height in box2d coordinates -> (width in pixels) / (scene scale) - same for width)

Returns:

Float: Total mass of the body in kilograms.

Example:

var jointDef = {
    ...
    maxMotorForce       : this._body.getMass() * 8.5,
}

getPosition

() Multivalue

Get the body's origin position in pixels from left top corner of the device's screen.

Returns:

Multivalue: Pair of float values: x, y - the world position of the body's origin.

getWorldCenter

()

Get the world position of the center of mass in screen coordinates -> pixels from left top corner of the screen.

Returns:

Multivalue Pair of values: x and y world coordinate.

getWorldPoint

(
  • localPointX
  • localPointY
)
Multivalue

Get the world coordinates of a point given by the local coordinates in screen coordinates -> pixels from left top corner of the screen..

Parameters:

  • localPointX Float

    A point x coordinate on the body measured relative the the body's origin.

  • localPointY Float

    A point x coordinate on the body measured relative the the body's origin.

Returns:

Multivalue: Pair of values: x and y coordinate of the same point expressed in world coordinates.

getWorldVector

(
  • localVectorX
  • localVectorY
)
Multivalue

Convert local vector's x and y component to world vector's components in screen coordinates -> pixels from left top corner of the screen..

Parameters:

  • localVectorX Float

    X component of vector fixed in the body.

  • localVectorY Float

    Y component of vector fixed in the body.

Returns:

Multivalue: The same vector x and y component expressed in world coordinates.

init

() protected

Init of the PhysicsSprite instance. It sets default values for density, friction, bounce and body type. An instance of PhysicsSprite is usually not created by a keyword new. It is usually created using methods: addCircleBody or addPolygonBody

setAngularDamping

(
  • damping
)

Set angular damping of the body. Damping is used to reduce the bodies' velocity. Damping is different than friction because friction only occurs with contact. Damping is not a replacement for friction and these two effects should be used together.

Parameters:

  • damping Float

    Angular damping.

setGravity

(
  • Float
  • Float
)

Set world’s gravity (separately for x and y axis). The gravity is a base feature of the physics scene and is same for all bodies

Parameters:

  • Float Object

    gx Gravity on x axis.

  • Float Object

    gy Gravity on y axis.

Example:

// create sensor
var sensor = new Sensor(#acceleration, 40);
// setup handler for receiving data
sensor.onDataReceived = function(sender, timestamp, params) {
    var (x, y, z) = (params[0], params[1], params[2]);
    app.world.setGravity(-x * 5., -y * 5.);
};
// start receiving data
sensor.start();

setLinearDamping

(
  • damping
)

Set linear damping of the body. Damping is used to reduce the bodies' velocity. Damping is different than friction because friction only occurs with contact. Damping is not a replacement for friction and these two effects should be used together. Damping parameters should be between 0 and infinity, with 0 meaning no damping, and infinity meaning full damping. Normally you will use a damping value between 0 and 0.5.

Parameters:

  • damping Float

    linear damping

Example:

sprite.setLinearDamping(0.3);

setLinearVelocity

(
  • x
  • y
)

Set linear velocity of the center of mass.

Parameters:

  • x Float

    The new linear velocity on x axis of the center of mass.

  • y Float

    The new linear velocity on y axis of the center of mass.

Example:

var (vX, vY) = this._character.getLinearVelocity();
// if character only slows -> speed it up
if (vX >  2.0 && this.vX < 4.7)
    this._character.setLinearVelocity(5.0, vY);

setPosition

(
  • x
  • Y
)

Place sprite to x, y. When the sprite is moving using setPosition function it does not interacts with other sprites in the scene.

Parameters:

  • x Float

    The world position (x) of the body's local origin in pixels from left top corner.

  • Y Float

    The world position (y) of the body's local origin in pixels from left top corner..

setTransform

(
  • x
  • y
  • angle
)

Set the position of the body's origin and rotation. This breaks any contacts and wakes the other bodies. Manipulating a body's transform may cause non-physical behavior.

Parameters:

  • x Float

    The world x position of the body's local origin.

  • y Float

    The world y position of the body's local origin.

  • angle Float

    The world rotation in radians.

Properties

active

Boolean

Set the active state of the body. Inactive bodies are added in the scene, but do not interacts in the physical simulation.

angle

Float

Current body rotation angle in radians.

awake

Boolean

Set to true to put body to sleep, false to wake it. A sleeping sprite has very low CPU cost.

bullet

Boolean

Flag to treat sprite like a bullet for continuous collision detection (CCD). If the sprite is set as a bullet CCD detect colisions also with dynamic bodies, otherwise it detect colisions only with static bodies. What is CCD? Continuous collision detection (also called CCD), is a box2d feature which ensures correct simulation of fast moving objects. Some older physical engines do not supports CCD, what means that they calculate positions and colisions of bodies for every time step, what is called discrete simulation. However in discrete simulation rigid body can move long distance in time step. (If the body has sufficiently high speed, it can be before time step few meters in front of the barrier and after time step it can be few meters behind the barrier.) It caused that the fast moving body can move throw another body without detection of collision between these two bodies. This effect is called tunneling. By default box2d uses CCD to prevent tunneling effect. CCD looks for all collisions between the position before and after time step. For every collision it calculates time of impact (TOI). On the next time step the body moves only to the next TOI and then wait for the rest of time step and does not move anymore during the time step. To ensure the best performace the CCD calculates contacts only between dynamic and static bodies (not between the dynamic bodies each other). However, onto dynamic bodies can be set CCD separately. If there is fast moving body, which hit other dynamic bodies, you can set the fast moving body’s property bullet to true to allows CCD onto it. True to enable CCD on this body, false to disable it

fixedRotation

Boolean

Enable / disable rotation of the body. True to enable rotation, false to disbable.

native

Boolean

Native instance of b2Body contained in the PhysicsSprite object.

scene

PhysicsScene

Instance of PhysicsScene into which is added this sprite

sleepingAllowed

Boolean

You can disable sleeping on this body. If you disable sleeping on actualy sleeping body, the body will be woken.

world

B2world

Instance of b2world into which is added this sprite.