Moscrif API Docs for: 2012q3
Show:

b2Body Class

Library: box2d

This class manages different types of physical bodies with many different properties and behavior.

Methods

applyAngularImpulse

(
  • impulse
)

Apply an angular impulse. This impulse causes rotation of body.

Parameters:

  • impulse Float

    The angular impulse in units of kgmm/s. A positive number to rotate counter clockwise, negative number to rotate clockwise.

Example:

//apply immediate spin counter clockwise
this.bodyA.applyAngularImpulse(this.bodyA.getMass()*1000);
//apply immediate spin clockwise
this.bodyB.applyAngularImpulse(this.bodyB.getMass()*-1000);

applyForce

(
  • xForce
  • yForce
  • xPoint
  • yPoint
)

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:

  • xForce Float

    The world force on x axis, usually in Newtons

  • yForce Float

    The world force on y axis, usually in Newtons

  • xPoint Float

    The world x coordinate of the point of force application

  • yPoint Float

    The world y coordinate of the point of force application

Example:

// get center of the body in world coordinates
var (x, y) = this.body.getWorldCenter();
// apply force
this.body.applyForce(0, this.body.getMass() * -1000, x, y);

applyLinearImpulse

(
  • xForce
  • yForce
  • xPoint
  • yPoint
)

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:

  • xForce Float

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

  • yForce Float

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

  • xPoint Float

    The world x position of the point of application.

  • yPoint Float

    The world y position of the point of application.

Example:

// get center of the body in world coordinates
var (x, y) = this.body.getWorldCenter();
// apply impulse
this.body.applyLinearImpulse(0, this.body.getMass() * -9.8, x, y);

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:

  • torque Float

    About the z-axis (out of the screen), usually in N-m.

Example:

//apply immediate spin counter clockwise
this.bodyA.applyTorque(this.bodyA.getMass()*100000);
//apply immediate spin clockwise
this.bodyB.applyTorque(this.bodyB.getMass()*-100000);

getAngle

() B2Body

Get the body's angle in radians.

Returns:

B2Body: The current body rotation angle in radians.

Example:

….body.onDraw = function(sender, canvas)
{
    var (x, y) = this.getPosition();
    var angleRad = this.getAngle();
    canvas.save();
    canvas.translate(x, y);
    canvas.rotate(-(angleRad * 180.0 / Math.PI)); // rad2deg

    var paint = new Paint();
    paint.color = 0xff00ff00;
    canvas.drawRect(this super.bodyWidth / -2, this super.bodyHeight / -2, this super.bodyWidth / 2, this super.bodyHeight / 2, paint);

    canvas.restore();
}

getAngularDamping

() Float

Get angular damping of the body. 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.

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 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.

Example:

this.body.setLinearDamping(0.1);
// apply linear velocity according to linear damping
this.body.setLinearVelocity(0, this.body.getLinearDamping() * 100);

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

getLinearVelocityFromLocalPoint

(
  • x
  • y
)
Multivalue

Get the world velocity of a local point.

Parameters:

  • x Float

    X coordinate of point in local coordinates.

  • y 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.

getLinearVelocityFromWorldPoint

(
  • x
  • y
)
Multivalue

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

Parameters:

  • x Float

    X coordinate of point in world coordinates.

  • y 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.

getLocalCenter

() Array

Get the local position of the center of mass.

Returns:

Array: Pair of float values: x,y local position of the center of mass.

getLocalPoint

(
  • x
  • y
)
Multivalue

Gets a local point relative to the body's origin given a world point.

Parameters:

  • x Float

    X coordinate of point in world coordinates.

  • y 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

(
  • x
  • y
)
Multivalue

Gets a local vector's x and y from given world vector's x and y coordinates.

Parameters:

  • x Float

    A world vector's x component.

  • y 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.

Returns:

Float: The total mass of the body.

Example:

// apply impulse
this.body.applyLinearImpulse(0, this.body.getMass() * -9.8, x, y);

getPosition

() Multivalue

Get the body's origin position.

Returns:

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

Example:

….body.onDraw = function(sender, canvas)
{
    var (x, y) = this.getPosition();
    var angleRad = this.getAngle();
    canvas.save();
    // move and rotate canvas accoridng to body's position and rotation
    canvas.translate(x, y);
    canvas.rotate(-(angleRad * 180.0 / Math.PI)); // rad2deg

    var paint = new Paint();
    paint.color = 0xff00ff00;
    canvas.drawRect(this super.bodyWidth / -2, this super.bodyHeight / -2, this super.bodyWidth / 2, this super.bodyHeight / 2, paint);

    canvas.restore();
};

getWorldCenter

() Multivalue

Get the world position of the center of mass.

Returns:

Multivalue: Pair of values: x and y world coordinate f the center of mass

Example:

// get center of the body in world coordinates
var (x, y) = this.body.getWorldCenter();
// apply impulse
this.body.applyLinearImpulse(0, this.body.getMass() * -9.8, x, y);

getWorldPoint

(
  • x
  • y
)
Multivalue

Get the world coordinates of a point given by the local coordinates.

Parameters:

  • x Float

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

  • y Float

    A point y 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.

Example:

this._bodyA = this._world.createBody(shape, #dynamic, 0.9 , 0.3, 0.03);

this._bodyA.setPosition(100, 50);
var (wx, wy) = this._bodyA.getWorldPoint(this.img.width / 2, this.img.height / 2);
console<<"world coordinates of center of the body x: "<<wx<<" y: "<<wy<<"\n";

getWorldVector

(
  • x
  • y
)
Multivalue

Convert local vector's x and y component to world vector's components.

Parameters:

  • x Float

    X component of vector fixed in the body.

  • y Float

    Y component of vector fixed in the body.

Returns:

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

setAngle

(
  • angle
)

Set the body's rotation angle in radians.

Parameters:

  • angle Float

    Angle in radians.

Example:

this.body.setAngle(45.0 * Math.PI / 180);

setAngularDamping

(
  • damping
)

Set angular damping of the body. 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.

Example:

this.body.setAngularDamping(0.1);
//apply immediate spin counter clockwise
this.body.applyTorque(this.body.getMass()* 100000);

setLinearDamping

(
  • damping
)

Set linear damping of the body. 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

    Linear damping.

Example:

this.body.setLinearDamping(0.1);
// apply linear velocity according to linear damping
this.body.setLinearVelocity(0, this.body.getLinearDamping() * 100););

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:

this.body.setLinearDamping(0.1);
// apply linear velocity according to linear damping
this.body.setLinearVelocity(0, this.body.getLinearDamping() * 100);

setPosition

(
  • x
  • y
)

Place body to x, y.

Parameters:

  • x Float

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

  • y Float

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

Example:

// create world
this._world = new b2World(0.0, 9.8, false, true);
// change gravity additionaly
this.img = Bitmap.fromFile("app://img.png");
var shape = b2PolygonShape.fromRect(this.img.width, this.img.height);
// create body

this._bodyA = this._world.createBody(shape, #dynamic, 0.9 , 0.3, 0.03);
this._bodyA.setPosition(100, 50);

// draw body
this._bodyA.onDraw = function(sender, g)
{
    var (left, top) = sender.getPosition();
    var angleRad = sender.getAngle();

    g.save();
    g.translate(left, top);
    g.rotate(-(angleRad * 180.0 / Math.PI)); // rad2deg

    var matrix = new Matrix();
    matrix.preTranslate(0, 0).preRotate(0).preTranslate(-this super.img.width/2, -this super.img.height/2);
    g.drawBitmapMatrix(this super.img, matrix);

    g.restore();
}

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 in box2d coordinates.

  • y Float

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

  • angle Float

    The world rotation in radians.

Example:

// place body to the b2world and rotate i
body.setTransform(5, 5, 45*Deg2Rad);

Properties

active

Boolean

Set the active state of the body.An inactive body is not simulated and cannot be collided with or woken up. If it is set to true, all fixtures are added to the broad-phase. otherwise, all fixtures are removed from the broad-phase and all contacts are destroyed. Fixtures and joints are otherwise unaffected. You may continue to create/destroy fixtures and joints on inactive bodies. Fixtures on an inactive body are implicitly inactive and will not participate in collisions, ray-casts, or queries. Joints connected to an inactive body are implicitly inactive. An inactive body is still owned by a b2World object and remains in the body list.

awake

Boolean

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

bodyType

Symbol

The type of this body. This may alter the mass and velocity.

  • #static - A static body behaves as if it has infinite mass. They does not move under simulation and can be moved only manually by b2Body.setPosition or b2Body.setTransform. A static body has zero velocity and do not collide with other static or kinematic bodies.
  • #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, but they do not collide with other static or kinematic bodies.
  • #dynamic - A dynamic body is fully simulated. They can be moved manually by PhysicsBody.setPosition, but normally they move according to forces. A dynamic body can collide with all body types and 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.

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.

sleepingAllowed

Boolean

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

Events

onDraw

This function is called, when body needs to be redrawn.

Event Payload:

  • sender B2Body

    Object, which called this function.

  • canvas Canvas

    Canvas object, which provides ability to draw into the body.

Example:

//create new Body. Position is set to 50, 20.
var body = this.world.createBody(shape, #dynamic, 1, 1, 1, 50, 20);
body.onDraw = function(sender, canvas)
{
    //get position of circle
    var (left, top) = sender.getPosition();

    //draw green circle
    var paint = new Paint();
    paint.color = 0xff00ff00;   // chanels: alpha, red, green, blue
    canvas.drawCircle(left.toInteger(), top.toInteger(), this super.radius, paint);
}