• Public
  • Public/Protected
  • All

Class Physics

The Physics object is the global configuration object for all Excalibur physics.

Excalibur comes built in with two physics systems. The first system is Box physics, and is a simple axis-aligned way of doing basic collision detection for non-rotated rectangular areas, defined by an actor's bounding box.

Physics hierarchy

Excalibur physics are organized into a hierarchy, each has a specific single role in the collision system.

Actor (game entity)
  -> Body (transform information)
     -> Collider (collision related information)
        -> Shape (geometry for collision)

For example:

const actor = new ex.Actor({
  pos: new ex.Vector(100, 100),
  body: new ex.Body({
    vel: new ex.Vector(20, 0), // velocity
    acc: new ex.Vector(0, 100), // acceleration
    collider: new ex.Collider({
      mass: 100, // mass of 100
      type: ex.CollisionType.Active, // active collision type
      shape: ex.Shape.Circle(50) // circle geometry of radius 50


Actor's have position, velocity, and acceleration in physical space, all of these positional physical attributes are contained inside the Body. Only 1 actor can be associated with a Body.

Body is the container for all transform related information for physics and any associated colliders.

This looks like this:

const actor = new ex.Actor({
    // actor's position is stored on a default body
    pos: new ex.Vector(40, 40);

// actor position is stored on the body, actor.pos is a convenience
actor.pos === actor.body.pos

// actor velocity is stored on the body, actor.vel is a convenience
actor.vel === actor.body.vel

// actor acceleration is stored on the body, actor.acc is a convenience
actor.acc === actor.body.acc


Body's have a default box collider that is derived from the width and height of the Actor associated. Only 1 Collider can be associated with a Body, and by extension an Actor. (Collision events are re-emitted onto Actor)

Collider is the container of all collision related information, collision type, collision events, mass, inertia, friction, bounciness, shape, etc.


Collider's have CollisionShape's that represent physical geometry. The possible shapes in Excalibur are Circle, Edge, and ConvexPolygon. A collider can only have 1 CollisionShape associated with them at a time.

Collision Types

Colliders have the default collision type of CollisionType.PreventCollision, this is so colliders don't accidentally opt into something computationally expensive. In order for colliders to participate in collisions and the global physics system, colliders must have a collision type of CollisionType.Active or CollisionType.Fixed.


Actors with the CollisionType.PreventCollision setting do not participate in any collisions and do not raise collision events.


Actors with the CollisionType.Passive setting only raise collision events, but are not influenced or moved by other actors and do not influence or move other actors.


Actors with the CollisionType.Active setting raise collision events and participate in collisions with other actors and will be push or moved by actors sharing the CollisionType.Active or CollisionType.Fixed setting.


Actors with the CollisionType.Fixed setting raise collision events and participate in collisions with other actors. Actors with the CollisionType.Fixed setting will not be pushed or moved by other actors sharing the CollisionType.Fixed.

Think of Fixed actors as "immovable/unstoppable" objects. If two CollisionType.Fixed actors meet they will not be pushed or moved by each other, they will not interact except to throw collision events.

Collision Type Behavior Matrix

This matrix shows what will happen with 2 actors of any collision type.

Collision Type Prevent Passive Active Fixed
Prevent None None None None
Passive None Events Only Events Only Events Only
Active None Events Only Resolution & Events Resolution & Events
Fixed None Events Only Resolution & Events None
  • None = No collision resolution and no collision events
  • Events Only = No resolution is performed, only collision events are fired on colliders, except for postcollision which only fires if resolution was performed.
  • Resolution & Events = Collider positions are resolved according to their collision type and collision events are fired on both colliders

Enabling Excalibur physics

To enable physics in your game it is as simple as setting Physics.enabled to true and picking your CollisionResolutionStrategy

Excalibur supports 3 different types of collision area shapes in its physics simulation: polygons, circles, and edges. To use any one of these areas on an actor there are convenience methods off of the actor physics body: useBoxCollider, usePolygonCollider, useCircleCollider, and Body.useEdgeCollider

Collision Event Lifecycle

Collision Events Diagram

Collision Start "collisionstart"

The collisionstart event is fired when a physics body, usually attached to an actor, first starts colliding with another body, and will not fire again while in contact until the the pair separates and collides again.

Use cases for the collisionstart event may be detecting when an actor has touch a surface (like landing) or if a item has been touched and needs to be picked up.

actor.on('collisionstart', () => {...})
// or
actor.body.collider.on('collisionstart', () => {...})

Collision End "collisionend"

The collisionend event is fired when two physics bodies are no longer in contact. This event will not fire again until another collision and separation.

Use cases for the collisionend event might be to detect when an actor has left a surface (like jumping) or has left an area.

actor.on('collisionend', () => {...})
// or
actor.body.collider.on('collisionend', () => {...})

Pre Collision "precollision"

The precollision event is fired every frame where a collision pair is found and two bodies are intersecting.

This event is useful for building in custom collision resolution logic in Passive-Passive or Active-Passive scenarios. For example in a breakout game you may want to tweak the angle of ricochet of the ball depending on which side of the paddle you hit.

actor.on('precollision', () => {...})
// or
actor.body.collider.on('precollision', () => {...})

Post Collision "postcollision"

The postcollision event is fired for every frame where collision resolution was performed. Collision resolution is when two bodies influence each other and cause a response like bouncing off one another. It is only possible to have postcollision event in Active-Active and Active-Fixed type collision pairs.

Post collision would be useful if you need to know that collision resolution is happening or need to tweak the default resolution.

actor.on('postcollision', () => {...})
// or
actor.body.collider.on('postcollision', () => {...})

Example Active-Active/Active-Fixed scenario

// setup game
const game = new ex.Engine({
  width: 600,
  height: 400
// use rigid body
ex.Physics.collisionResolutionStrategy = ex.CollisionResolutionStrategy.RigidBody;
// set global acceleration simulating gravity pointing down
ex.Physics.acc.setTo(0, 700);

const block = new ex.Actor({
  pos: new ex.Vector(300, 0),
  width: 20,
  height: 20,
  color: ex.Color.Blue
block.body.useBoxCollider(); // useBoxCollision is the default, technically optional
block.body.collider.type = ex.CollisionType.Active;

// or

const block = new ex.Actor({
    pos: new ex.Vector(300, 0),
    color: ex.Color.Blue,
    body: new ex.Body({
        collider: new ex.Collider({
            type: ex.CollisionType.Active,
            shape: ex.Shape.Box(20, 20)

const circle = new ex.Actor({
  x: 301,
  y: 100,
  width: 20,
  height: 20,
  color: ex.Color.Red
circle.body.collider.type = ex.CollisionType.Active;

// or

const circle = new ex.Actor({
    pos: new ex.Vector(301, 100),
    color: ex.Color.Red,
    body: new ex.Body({
        collider: new ex.Collider({
            shape: ex.Shape.Circle(10),
            type: ex.CollisionType.Active

const ground = new ex.Actor({
  x: 300,
  y: 380,
  width: 600,
  height: 10,
  color: ex.Color.Black;

ground.body.useBoxCollider(); // optional
ground.body.collider.type = ex.CollisionType.Fixed;

// start the game



Currently Excalibur only supports single contact point collisions and non-sleeping physics bodies. This has some negative stability and performance implications. Single contact point collisions can have odd oscillating behavior. Non-sleeping bodies will recalculate collisions whether they need to or not. We fully intend to add these features into Excalibur in future releases.


  • Physics



Static acc

acc: Vector = new Vector(0, 0)

Global acceleration that is applied to all vanilla actors that have a active collision type. Global acceleration won't effect labels, ui actors, or triggers in Excalibur.

This is a great way to globally simulate effects like gravity.

Static allowRigidBodyRotation

allowRigidBodyRotation: boolean = true

Gets or sets whether rotation is allowed in a RigidBody collision resolution

Static boundsPadding

boundsPadding: number = 5

Pad RigidBody BoundingBox by a constant amount

Static broadphaseDebug

broadphaseDebug: boolean = false

Globally switches the debug information for the broadphase strategy

Static broadphaseStrategy

broadphaseStrategy: BroadphaseStrategy = BroadphaseStrategy.DynamicAABBTree

Gets or sets the broadphase pair identification strategy.

The default strategy is BroadphaseStrategy.DynamicAABBTree which uses a binary tree of axis-aligned bounding boxes to identify potential collision pairs which is O(nlog(n)) faster. The other possible strategy is the BroadphaseStrategy.Naive strategy which loops over every object for every object in the scene to identify collision pairs which is O(n^2) slower.

Static checkForFastBodies

checkForFastBodies: boolean = true

Enable fast moving body checking, this enables checking for collision pairs via raycast for fast moving objects to prevent bodies from tunneling through one another.

Static collisionPasses

collisionPasses: number = 5

Gets or sets the number of collision passes for Excalibur to perform on physics bodies.

Reducing collision passes may cause things not to collide as expected in your game, but may increase performance.

More passes can improve the visual quality of collisions when many objects are on the screen. This can reduce jitter, improve the collision resolution of fast move objects, or the stability of large numbers of objects stacked together.

Fewer passes will improve the performance of the game at the cost of collision quality, more passes will improve quality at the cost of performance.

The default is set to 5 passes which is a good start.

Static collisionResolutionStrategy

collisionResolutionStrategy: CollisionResolutionStrategy = CollisionResolutionStrategy.Box

Gets or sets the global collision resolution strategy (narrowphase).

The default is CollisionResolutionStrategy.Box which performs simple axis aligned arcade style physics.

More advanced rigid body physics are enabled by setting CollisionResolutionStrategy.RigidBody which allows for complicated simulated physical interactions.

Static collisionShift

collisionShift: number = 0.001

Small value to help collision passes settle themselves after the narrowphase.

Static defaultMass

defaultMass: number = 10

The default mass to use if none is specified

Static disableMinimumSpeedForFastBody

disableMinimumSpeedForFastBody: boolean = false

Disable minimum fast moving body raycast, by default if ex.Physics.checkForFastBodies = true Excalibur will only check if the body is moving at least half of its minimum dimension in an update. If ex.Physics.disableMinimumSpeedForFastBody is set to true, Excalibur will always perform the fast body raycast regardless of speed.

Static dynamicTreeVelocityMultiplier

dynamicTreeVelocityMultiplier: number = 2

Factor to add to the RigidBody BoundingBox, bounding box (dimensions += vel * dynamicTreeVelocityMultiplier);

Static enabled

enabled: boolean = true

Globally switches all Excalibur physics behavior on or off.

Static integrationSteps

integrationSteps: number = 1

Number of steps to use in integration. A higher number improves the positional accuracy over time. This can be useful to increase if you have fast moving objects in your simulation or you have a large number of objects and need to increase stability.

Static integrator

integrator: Integrator = Integrator.Euler

Gets or sets the position and velocity positional integrator, currently only Euler is supported.

Static showArea

showArea: boolean = false

Show the bounding collision area shapes

Static showBounds

showBounds: boolean = false

Show the axis-aligned bounding boxes of the collision bodies on the screen.

Static showCollisionNormals

showCollisionNormals: boolean = false

Show the normals as a result of collision on the screen.

Static showContacts

showContacts: boolean = false

Show points of collision interpreted by excalibur as a result of collision.

Static showMotionVectors

showMotionVectors: boolean = false

Show the position, velocity, and acceleration as graphical vectors.

Static showNormals

showNormals: boolean = false

Show the surface normals of the collision areas.

Static surfaceEpsilon

surfaceEpsilon: number = 0.1

Surface epsilon is used to help deal with surface penetration


Static dynamicTreeVelocityMultiplyer

  • get dynamicTreeVelocityMultiplyer(): number
  • set dynamicTreeVelocityMultiplyer(value: number): void


Static useBoxPhysics

  • useBoxPhysics(): void
  • Configures Excalibur to use box physics. Box physics which performs simple axis aligned arcade style physics.

    Returns void

Static useRigidBodyPhysics

  • useRigidBodyPhysics(): void
  • Configures Excalibur to use rigid body physics. Rigid body physics allows for complicated simulated physical interactions.

    Returns void