Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Body

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

Events

Properties

Methods

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 body

The body that was involved in the collision.

param contact

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.

        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 = BODY_SLEEP_STATES.AWAKE

        AWAKE

        Static DYNAMIC

        DYNAMIC: 1 = BODY_TYPES.DYNAMIC

        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 = BODY_TYPES.KINEMATIC

        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 = BODY_SLEEP_STATES.SLEEPING

        SLEEPING

        Static SLEEPY

        SLEEPY: 1 = BODY_SLEEP_STATES.SLEEPY

        SLEEPY

        Static STATIC

        STATIC: 2 = BODY_TYPES.STATIC

        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

        vectorToWorldFrame

        wakeUp

        • wakeUp(): void