Physics

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 Name	Type	Default	Description
shape	Number		ecs.ColliderShape.Box, Sphere, Plane, Capsule, Cone, or Cylinder
width	Number		X Size, used by Box and Plane
height	Number		Y Size, used by Box, Plane, Capsule, Cone, and Cylinder
depth	Number		Z Size, used by Box
radius	Number		Used for Sphere, Capsule, Cone, Cylinder
mass	Number	0	Leave 0 to make static.
eventOnly	Boolean	false	When enabled, the object will pass through other objects but still dispatch collision events.
gravityFactor	Number	1.0	A factor of world gravity.
lockXAxis	Boolean	false	Disables rotation on the X axis.
lockYAxis	Boolean	false	Disables rotation on the Y axis.
lockZAxis	Boolean	false	Disables rotation on the Z axis.
friction	Number	0.5	Simulate contact friction.
restitution	Number	0	Controls the bounciness of the object.
linearDamping	Number	0	Simulate air friction while moving.
angularDamping	Number	0	Simulate air friction while rotating.
rollingFriction	Number	0	Simulate friction on rolling surfaces.
spinningFriction	Number	0	Simulate friction on surfaces twisting against each other.

Events

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

• ecs.physics.COLLISION_START_EVENT
• ecs.physics.COLLISION_END_EVENT

On the emitted event, event.data.other 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,
    radius,
    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.

ecs.physics.setLinearVelocity(
  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.

Force

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

Torque

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

Impulse

This function is used to apply a one-time instantaneous force to a physics collider, altering its velocity based on the given impulse vector. This method is useful for events that require a quick, single action response, such as jumping, punching, or a sudden push.

ecs.physics.applyImpulse(world, eid, impulseX, impulseY, impulseZ)

Gravity

In every scene gravity will be a constant value, we call this 'World Gravity'. Every collider in the scene that is set to dynamic will be affected by this force. To modify how world gravity interacts with an individual collider we introduced an attribute called 'Gravity Factor'.

Example:

World gravity = 9.8
Collider A gravity factor = 1.0
Collider B gravity factor =  0.5
Collider C gravity factor =  -1.0

The resulting gravity for each collider will be:

Collider A = 9.8
Collider B = 4.9
Collider C = -9.8 (inverted gravity)

Set World Gravity

ecs.physics.setWorldGravity(world, gravity)