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

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: useBoxCollision, usePolygonCollision, useCircleCollision, and Body.useEdgeCollision

// setup game
var 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);
var block = new ex.Actor(300, 0, 20, 20, ex.Color.Blue.clone());
block.body.useBoxCollision(); // useBoxCollision is the default, technically optional
var circle = new ex.Actor(300, 100, 20, 20, ex.Color.Red.clone());

var ground = new ex.Actor(300, 380, 600, 10, ex.Color.Black.clone());
ground.collisionType = ex.CollisionType.Fixed;
ground.body.useBoxCollision(); // optional 
// 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 ex.Vector(0, 0)

Global acceleration that is applied to all vanilla actors (it wont effect labels, ui actors, or triggers in Excalibur that have an active collision type).

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 diminension in an update. If ex.Physics.disableMinimumSpeedForFastBody is set to true, Excalibur will always perform the fast body raycast regardless of speed.

Static dynamicTreeVelocityMultiplyer

dynamicTreeVelocityMultiplyer: number = 2

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

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 penatration


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