Awaken3D

RigidBody ​

The RigidBody component turns an object into a fully simulated dynamic body - it falls under gravity, responds to forces, and bounces off other colliders.

What RigidBody does ​

Add a RigidBody and, during Play, the object becomes a dynamic physics body: Rapier integrates its motion every step and Awaken writes the result back into the object's Transform. Without a RigidBody, a Collider alone is static scenery - solid and immovable. The RigidBody is what says "this thing moves."

A RigidBody on its own has no shape. It needs a Collider too, otherwise there is nothing for the simulation to collide with (an empty collider falls back to a default box so Play still works, but you should give it a real shape).

The component fields ​

RigidBody has three fields, edited in the Inspector:

FieldTypeDefaultMeaning
velocityvec3(0, 0, 0)Initial linear velocity in world units/second, applied at Play start.
useGravitybooltrueWhen on, the body falls under scene gravity (0, -9.81, 0). When off, its gravity scale is set to 0.
restitutionnumber0.3Bounciness, 0–1. Becomes the collider material's restitution - 0 = no bounce, 1 = fully elastic.

At Play start the runner reads these into a BodyDesc: velocity seeds the body's linear velocity, useGravity maps to gravityScale (1 on, 0 off), and restitution is applied to every collider attached to the body.

Dynamic vs static - the deciding rule ​

Whether an entity becomes a dynamic body or a fixed (immovable) one is decided at Play start:

  • Dynamic requires a RigidBody and that the object is not marked Static.
  • The Static checkbox in the Inspector header wins over everything. Marking an object Static forces a fixed body even if it carries a RigidBody - the same flag that enables draw-call batching and cached shadows also pins the object in the simulation. This is deliberate: it lets you keep authoring data on an object while treating it as scenery.

So the mental model is: RigidBody = "can move", Static = "never moves". If both are set, Static wins.

How poses flow back to the Transform ​

Each frame, after stepping the simulation, the runner walks the dynamic bodies and copies each one's new position and rotation back into its Transform:

Two things make this cheap:

  • Only dynamic bodies get written back. Fixed bodies never move, so they are skipped entirely - and crucially they are not flagged as moved, so a 15,000-prop static scene never floods the render dirty-set.
  • Settled bodies are skipped. If a body's pose is unchanged from its Transform within a tiny epsilon (it has gone to sleep or simply didn't move this step), the runner writes nothing and doesn't mark it moved. Only the bodies that actually moved trigger a render re-sync.

Dynamic bodies are simulated and written back in local space - they behave as effectively root objects. Static colliders are placed at their full world transform (composed through parents) so a nested or imported collider lines up with its mesh.

The zero-cost all-static case ​

If a scene has no dynamic bodies and no active characters, the whole physics step is skipped - fixed bodies can't collide with each other, so nothing can change. A scene of pure static scenery therefore costs zero physics per frame. The simulation wakes up automatically the moment you spawn a dynamic body (api.spawn) or a character starts moving. This is why marking scenery Static matters for performance.

📸 Screenshot - save as img/physics-rigidbody.png

The Inspector showing a Cube with a RigidBody component (velocity / useGravity / restitution) above a Collider, with the Static checkbox in the header visible and unchecked.

Editing during Play ​

RigidBody and Collider are built into the simulation once, at Play start. Editing either component while playing triggers a soft re-sync - the running sim is rebuilt in place from the current world so your change takes effect immediately (dynamic bodies keep their current pose; the player and animations are not reset).

See also ​

Awaken — browser-native WebGPU game engine.

© 2026 Ciarán McCormack