Options
All
  • Public
  • Public/Protected
  • All
Menu

Base class for all body types.

example
const shape = new CANNON.Sphere(1)
const body = new CANNON.Body({
  mass: 1,
  shape,
})
world.addBody(body)

Hierarchy

Index

Constructors

constructor

  • new Body(options?: { allowSleep?: boolean; angularDamping?: number; angularFactor?: Vec3; angularVelocity?: Vec3; collisionFilterGroup?: number; collisionFilterMask?: number; collisionResponse?: boolean; fixedRotation?: boolean; isTrigger?: boolean; linearDamping?: number; linearFactor?: Vec3; mass?: number; material?: Material; position?: Vec3; quaternion?: Quaternion; shape?: Shape; sleepSpeedLimit?: number; sleepTimeLimit?: number; type?: BodyType; velocity?: Vec3 }): Body
  • Parameters

    • options: { allowSleep?: boolean; angularDamping?: number; angularFactor?: Vec3; angularVelocity?: Vec3; collisionFilterGroup?: number; collisionFilterMask?: number; collisionResponse?: boolean; fixedRotation?: boolean; isTrigger?: boolean; linearDamping?: number; linearFactor?: Vec3; mass?: number; material?: Material; position?: Vec3; quaternion?: Quaternion; shape?: Shape; sleepSpeedLimit?: number; sleepTimeLimit?: number; type?: BodyType; velocity?: Vec3 } = ...
      • Optional allowSleep?: boolean

        If true, the body will automatically fall to sleep.

        default

        true

      • Optional angularDamping?: number

        How much to damp the body angular velocity each step. It can go from 0 to 1.

        default

        0.01

      • Optional angularFactor?: Vec3

        Use this property to limit the rotational motion along any world axis. (1,1,1) will allow rotation along all axes while (0,0,0) allows none.

      • Optional angularVelocity?: Vec3

        Angular velocity of the body, in world space. Think of the angular velocity as a vector, which the body rotates around. The length of this vector determines how fast (in radians per second) the body rotates.

      • Optional collisionFilterGroup?: number

        The collision group the body belongs to.

        default

        1

      • Optional collisionFilterMask?: number

        The collision group the body can collide with.

        default

        -1

      • Optional collisionResponse?: boolean

        Whether to produce contact forces when in contact with other bodies. Note that contacts will be generated, but they will be disabled - i.e. "collide" events will be raised, but forces will not be altered.

      • Optional fixedRotation?: boolean

        Set to true if you don't want the body to rotate. Make sure to run .updateMassProperties() if you change this after the body creation.

        default

        false

      • Optional isTrigger?: boolean

        When true the body behaves like a trigger. It does not collide with other bodies but collision events are still triggered.

        default

        false

      • Optional linearDamping?: number

        How much to damp the body velocity each step. It can go from 0 to 1.

        default

        0.01

      • Optional linearFactor?: Vec3

        Use this property to limit the motion along any world axis. (1,1,1) will allow motion along all axes while (0,0,0) allows none.

      • Optional mass?: number

        The mass of the body.

        default

        0

      • Optional material?: Material

        The physics material of the body. It defines the body interaction with other bodies.

      • Optional position?: Vec3

        World space position of the body.

      • Optional quaternion?: Quaternion

        World space orientation of the body.

      • Optional shape?: Shape

        Add a Shape to the body.

      • Optional sleepSpeedLimit?: number

        If the speed (the norm of the velocity) is smaller than this value, the body is considered sleepy.

        default

        0.1

      • Optional sleepTimeLimit?: number

        If the body has been sleepy for this sleepTimeLimit seconds, it is considered sleeping.

        default

        1

      • Optional type?: BodyType

        One of: Body.DYNAMIC, Body.STATIC and Body.KINEMATIC.

      • Optional velocity?: Vec3

        World space velocity of the body.

    Returns Body

Events

Static COLLIDE_EVENT_NAME

COLLIDE_EVENT_NAME: string = 'collide'

Dispatched after two bodies collide. This event is dispatched on each of the two bodies involved in the collision.

param

The body that was involved in the collision.

param

The details of the collision.

Static sleepEvent

sleepEvent: {} = ...

Dispatched after a body has fallen asleep.

Type declaration

Static sleepyEvent

sleepyEvent: {} = ...

Dispatched after a body has gone in to the sleepy state.

Type declaration

Static wakeupEvent

wakeupEvent: {} = ...

Dispatched after a sleeping body has woken up.

Type declaration

Properties

aabb

aabb: AABB

World space bounding box of the body and its shapes.

aabbNeedsUpdate

aabbNeedsUpdate: boolean

Indicates if the AABB needs to be updated before use.

allowSleep

allowSleep: boolean

If true, the body will automatically fall to sleep.

default

true

angularDamping

angularDamping: number

How much to damp the body angular velocity each step. It can go from 0 to 1.

default

0.01

angularFactor

angularFactor: Vec3

Use this property to limit the rotational motion along any world axis. (1,1,1) will allow rotation along all axes while (0,0,0) allows none.

angularVelocity

angularVelocity: Vec3

Angular velocity of the body, in world space. Think of the angular velocity as a vector, which the body rotates around. The length of this vector determines how fast (in radians per second) the body rotates.

boundingRadius

boundingRadius: number

Total bounding radius of the Body including its shapes, relative to body.position.

collisionFilterGroup

collisionFilterGroup: number

The collision group the body belongs to.

default

1

collisionFilterMask

collisionFilterMask: number

The collision group the body can collide with.

default

-1

collisionResponse

collisionResponse: boolean

Whether to produce contact forces when in contact with other bodies. Note that contacts will be generated, but they will be disabled - i.e. "collide" events will be raised, but forces will not be altered.

fixedRotation

fixedRotation: boolean

Set to true if you don't want the body to rotate. Make sure to run .updateMassProperties() if you change this after the body creation.

default

false

force

force: Vec3

Linear force on the body in world space.

id

id: number

Identifier of the body.

index

index: number

Position of body in World.bodies. Updated by World and used in ArrayCollisionMatrix.

inertia

inertia: Vec3

The inertia of the body.

initAngularVelocity

initAngularVelocity: Vec3

Initial angular velocity of the body.

initPosition

initPosition: Vec3

Initial position of the body.

initQuaternion

initQuaternion: Quaternion

Initial quaternion of the body.

initVelocity

initVelocity: Vec3

Initial velocity of the body.

interpolatedPosition

interpolatedPosition: Vec3

Interpolated position of the body.

interpolatedQuaternion

interpolatedQuaternion: Quaternion

Interpolated orientation of the body.

isTrigger

isTrigger: boolean

When true the body behaves like a trigger. It does not collide with other bodies but collision events are still triggered.

default

false

linearDamping

linearDamping: number

How much to damp the body velocity each step. It can go from 0 to 1.

default

0.01

linearFactor

linearFactor: Vec3

Use this property to limit the motion along any world axis. (1,1,1) will allow motion along all axes while (0,0,0) allows none.

mass

mass: number

The mass of the body.

default

0

material

material: null | Material

The physics material of the body. It defines the body interaction with other bodies.

position

position: Vec3

World space position of the body.

postStep

postStep: null | (() => void)

Callback function that is used AFTER stepping the system. Inside the function, "this" will refer to this Body object. Deprecated - use World events instead.

deprecated

Use World events instead

preStep

preStep: null | (() => void)

Callback function that is used BEFORE stepping the system. Use it to apply forces, for example. Inside the function, "this" will refer to this Body object. Deprecated - use World events instead.

deprecated

Use World events instead

quaternion

quaternion: Quaternion

World space orientation of the body.

shapeOffsets

shapeOffsets: Vec3[]

Position of each Shape in the body, given in local Body space.

shapeOrientations

shapeOrientations: Quaternion[]

Orientation of each Shape, given in local Body space.

shapes

shapes: Shape[]

List of Shapes that have been added to the body.

sleepSpeedLimit

sleepSpeedLimit: number

If the speed (the norm of the velocity) is smaller than this value, the body is considered sleepy.

default

0.1

sleepState

sleepState: BodySleepState

Current sleep state.

sleepTimeLimit

sleepTimeLimit: number

If the body has been sleepy for this sleepTimeLimit seconds, it is considered sleeping.

default

1

torque

torque: Vec3

World space rotational force on the body, around center of mass.

type

type: BodyType

One of: Body.DYNAMIC, Body.STATIC and Body.KINEMATIC.

velocity

velocity: Vec3

World space velocity of the body.

world

world: null | World

Reference to the world the body is living in.

Static AWAKE

AWAKE: 0 = ...

AWAKE

Static DYNAMIC

DYNAMIC: 1 = ...

A dynamic body is fully simulated. 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.

Static KINEMATIC

KINEMATIC: 4 = ...

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

Static SLEEPING

SLEEPING: 2 = ...

SLEEPING

Static SLEEPY

SLEEPY: 1 = ...

SLEEPY

Static STATIC

STATIC: 2 = ...

A static body does not move during simulation and behaves as if it has infinite mass. Static bodies can be moved manually by setting the position of the body. The velocity of a static body is always zero. Static bodies do not collide with other static or kinematic bodies.

Methods

addEventListener

  • addEventListener(type: string, listener: Function): EventTarget

addShape

  • Add a shape to the body with a local offset and orientation.

    Parameters

    Returns Body

    The body object, for chainability.

applyForce

  • applyForce(force: Vec3, relativePoint?: Vec3): void
  • Apply force to a point of the body. This could for example be a point on the Body surface. Applying force this way will add to Body.force and Body.torque.

    Parameters

    • force: Vec3

      The amount of force to add.

    • relativePoint: Vec3 = ...

      A point relative to the center of mass to apply the force on.

    Returns void

applyImpulse

  • applyImpulse(impulse: Vec3, relativePoint?: Vec3): void
  • Apply impulse to a point of the body. This could for example be a point on the Body surface. An impulse is a force added to a body during a short period of time (impulse = force * time). Impulses will be added to Body.velocity and Body.angularVelocity.

    Parameters

    • impulse: Vec3

      The amount of impulse to add.

    • relativePoint: Vec3 = ...

      A point relative to the center of mass to apply the force on.

    Returns void

applyLocalForce

  • applyLocalForce(localForce: Vec3, localPoint?: Vec3): void
  • Apply force to a local point in the body.

    Parameters

    • localForce: Vec3
    • localPoint: Vec3 = ...

      A local point in the body to apply the force on.

    Returns void

applyLocalImpulse

  • applyLocalImpulse(localImpulse: Vec3, localPoint?: Vec3): void
  • Apply locally-defined impulse to a local point in the body.

    Parameters

    • localImpulse: Vec3
    • localPoint: Vec3 = ...

      A local point in the body to apply the force on.

    Returns void

applyTorque

  • applyTorque(torque: Vec3): void
  • Apply torque to the body.

    Parameters

    • torque: Vec3

      The amount of torque to add.

    Returns void

dispatchEvent

getVelocityAtWorldPoint

  • getVelocityAtWorldPoint(worldPoint: Vec3, result: Vec3): Vec3

hasAnyEventListener

  • hasAnyEventListener(type: string): boolean

hasEventListener

  • hasEventListener(type: string, listener: Function): boolean

integrate

  • integrate(dt: number, quatNormalize: boolean, quatNormalizeFast: boolean): void
  • Move the body forward in time.

    Parameters

    • dt: number

      Time step

    • quatNormalize: boolean

      Set to true to normalize the body quaternion

    • quatNormalizeFast: boolean

      If the quaternion should be normalized using "fast" quaternion normalization

    Returns void

pointToLocalFrame

pointToWorldFrame

removeEventListener

  • removeEventListener(type: string, listener: Function): EventTarget

removeShape

sleep

  • sleep(): void

sleepTick

  • sleepTick(time: number): void
  • Called every timestep to update internal sleep timer and change sleep state if needed.

    Parameters

    • time: number

      The world time in seconds

    Returns void

updateAABB

  • updateAABB(): void

updateBoundingRadius

  • updateBoundingRadius(): void
  • Update the bounding radius of the body. Should be done if any of the shapes are changed.

    Returns void

updateInertiaWorld

  • updateInertiaWorld(force?: boolean): void
  • Update .inertiaWorld and .invInertiaWorld

    Parameters

    • Optional force: boolean

    Returns void

updateMassProperties

  • updateMassProperties(): void
  • Should be called whenever you change the body shape or mass.

    Returns void

updateSolveMassProperties

  • updateSolveMassProperties(): void
  • If the body is sleeping, it should be immovable / have infinite mass during solve. We solve it by having a separate "solve mass".

    Returns void

vectorToLocalFrame

  • vectorToLocalFrame(worldVector: Vec3, result?: Vec3): Vec3

vectorToWorldFrame

  • vectorToWorldFrame(localVector: Vec3, result?: Vec3): Vec3

wakeUp

  • wakeUp(): void