Physics – AWE

Working with Physics

When you add models or avatars in the Studio, you must attach a Collider for collisions. This section shows how.

awe uses Rapier (opens in a new tab), a fast Rust-based physics engine. Collider settings in the Studio mirror Rapier’s options:

Fixed: Ideal for static objects (walls, floors).
Dynamic: Objects that respond to full physics (rolling balls).
Kinematic: Objects moved only by code (moving platforms).

Tip: Use predefined shapes (Cube, Sphere, etc.) instead of full Mesh colliders for faster performance.

Collider as a Sensor

Sensors don’t block movement but still fire collision events. Use them for things like pickups or damage zones.

Accessing Rapier Entities

const myComponent = Components.byId("component-id");
const rigidBody = myComponent.rigidBody;
const collider = myComponent.collider;
 
const rapierRb = myComponent.collider.rigidBody;
const allColliders = myComponent.rigidBody.colliders;

Check the Collider and Rigid Body docs for deeper details, or see Rapier’s own Rigid Bodies (opens in a new tab) and Colliders (opens in a new tab).

Manually Listening for Collision Events

const myComponent = Components.byId("component-id");
 
const unsubscribe = myComponent.onCollisionEnter((collision) => {
    console.log("new collision", collision)
});
 
// ...
 
unsubscribe(); // stops listening

onCollisionEnter: Called when two objects start colliding.
onCollisionStay: Called every frame while they remain in contact.
onCollisionExit: Called when they stop colliding.
onSensorEnter / onSensorStay / onSensorExit: Same pattern, but for Sensors.

myComponent.onCollisionEnter(() => console.log("collision enter"));
myComponent.onCollisionStay(() => console.log("collision stay"));
myComponent.onCollisionExit(() => console.log("collision exit"));
myComponent.onSensorEnter(() => console.log("sensor enter"));
myComponent.onSensorStay(() => console.log("sensor stay"));
myComponent.onSensorExit(() => console.log("sensor exit"));

Physics for Behaviors and Components

Scripted Behaviors or Components have direct access to physics methods:

import { ScriptBehavior } from '@oo/scripting'
 
export default class ExampleBehavior extends ScriptBehavior {
 
    onReady = () => {
        const collider = this.host.collider // for Components: this.collider
        const rigidBody = this.host.rigidBody // for Components: this.rigidBody
    }
 
    handleCollisionEnter = (collision) => {
        console.log("collision enter", collision)
    }
 
    handleCollisionStay = (collision) => {
        console.log("collision stay", collision)
    }
 
    handleCollisionExit = (collision) => {
        console.log("collision exit", collision)
    }
 
    handleSensorEnter = (collision) => {
        console.log("sensor enter", collision)
    }
 
    handleSensorStay = (collision) => {
        console.log("sensor stay", collision)
    }
 
    handleSensorExit = (collision) => {
        console.log("sensor exit", collision)
    }
}

Use these lifecycle methods to customize object interactions in your awe world.