Skip to main content


This section provides guidance for setting up Physics.

Physics Colliders can be added to the entity via the Studio interface or in code. Adding them in Studio is done via the 'New Component' button. The Collider component enables physics for the attached entity. If mass is left as 0, it will be immobile (static/kinematic), and if mass is set, it will become affected by collisions and gravity (dynamic).


Things to note:

  • Colliders can be nested in some configurations, but not others. For example, a static collider inside a dynamic collider, or two nested dynamic colliders, could misbehave.
  • Future work will enable attaching multiple colliders to each other using constraints/joints
  • Unless you have a Geometry component that is also a valid Collider Shape, you’ll need to specify a shape manually. For example there isn’t a supported matching collider for the tetrahedron primitive.
  • GLTF model collider generation for complex models might affect performance.

Physics Properties

Property NameTypeDefaultDescription
shapeNumberecs.ColliderShape.Box, Sphere, Plane, Capsule, Cone, or Cylinder
widthNumberX Size, used by Box and Plane
heightNumberY Size, used by Box, Plane, Capsule, Cone, and Cylinder
depthNumberZ Size, used by Box
radiusNumberUsed for Sphere, Capsule, Cone, Cylinder
massNumber0Leave 0 to make static.
eventOnlyBooleanfalseWhen enabled, the object will pass through other objects but still dispatch collision events.
lockXAxisBooleanfalseDisables rotation on the X axis.
lockYAxisBooleanfalseDisables rotation on the Y axis.
lockZAxisBooleanfalseDisables rotation on the Z axis.
frictionNumber0.5Simulate contact friction.
restitutionNumber0Controls the bounciness of the object.
linearDampingNumber0Simulate air friction while moving.
angularDampingNumber0Simulate air friction while rotating.
rollingFrictionNumber0Simulate friction on rolling surfaces.
spinningFrictionNumber0Simulate friction on surfaces twisting against each other.


The following events are exposed. (see Events for how to listen)

  • ecs.physics.COLLISION_END_EVENT

On the emitted event, will be the entity id of the colliding entity. More fields are coming!

Configure physics collider

import * as ecs from '@8thwall/ecs'
ecs.physics.Collider.set(world, eid, {
shape: ecs.ColliderShape.Sphere,
mass: 1,
eventOnly: false,
lockXAxis: false,
lockYAxis: false,
lockZAxis: false,
friction: 0.5,
restitution: 0.5,
linearDamping: 0,
angularDamping: 0,
rollingFriction: 0.1,
spinningFriction: 0.1,

Set Velocity of a collider

You can set the linear velocity of an entity within the physics engine.

world: World, eid: Eid, velocityX: number, velocityY: number, velocityZ: number)

Force & Torque

You can directly apply forces (linear and angular) to any entity with a physics collider. These forces are applied in the next physics simulation update, which takes place at regular intervals. The function accepts a 3D vector to define the force direction and magnitude.

Note: This is dependent on the frequency of calls to requestAnimationFrame() or your devices refresh rate.


ecs.physics.applyForce(world, eid, forceX, forceY, forceZ)


ecs.physics.applyTorque(world, eid, torqueX, torqueY, torqueZ)