Colliders and Rigidbody

Colliders define the physical boundary of a GameObject. On their own they are static obstacles. Pair them with a Rigidbody component to get full dynamic simulation — gravity, forces, torque, and collision response.

All collider components inherit from the abstract Collider base class and share common surface properties. The Rigidbody component must be on the same GameObject as the colliders it should drive.

Collider base properties

Every collider type exposes the following shared properties.

Static

bool

default:"false"

When true the collider is fixed in the world and does not move with its GameObject’s transform. Concave shapes (e.g. ModelCollider with mesh hulls) are always static.

IsTrigger

bool

default:"false"

Makes the shape a trigger volume. Triggers detect overlaps but do not physically block other objects. Use the OnTriggerEnter / OnTriggerExit callbacks to respond.

Friction

float?

default:"null"

Overrides the surface friction. null defers to the material default. Valid range is 0–1 (values above 1 give very grippy friction).

Elasticity

float?

default:"null"

Overrides surface bounciness. null defers to the material default. Range 0–1.

RollingResistance

float?

default:"null"

Controls how easily rolling shapes (spheres, capsules) roll on surfaces. Range 0–1.

Surface

The physical surface material. Drives friction, elasticity, footstep sounds, and other surface-specific effects.

SurfaceVelocity

Vector3

Local surface velocity. Useful for conveyor belts — objects resting on the collider slide in this direction.

Trigger callbacks

OnTriggerEnter

Action<Collider>

Fires when another collider begins overlapping this trigger.

OnTriggerExit

Action<Collider>

Fires when another collider stops overlapping this trigger.

OnObjectTriggerEnter

Action<GameObject>

Same as OnTriggerEnter but provides the entering GameObject instead of the Collider.

OnObjectTriggerExit

Action<GameObject>

Same as OnTriggerExit but provides the exiting GameObject.

Collider types

BoxCollider
SphereCollider
CapsuleCollider
ModelPhysics

A solid rectangular box defined by a center point and extents.

Scale

Vector3

default:"50,50,50"

Corner-to-corner size of the box in local units.

Center

Vector3

default:"0,0,0"

Center offset relative to the GameObject’s origin.

var box = Components.Get<BoxCollider>();
box.Scale = new Vector3( 100, 100, 100 );
box.Center = Vector3.Up * 50;

A sphere defined by a center and radius. Ideal for balls and smooth rolling objects.

Center

Vector3

default:"0,0,0"

Center offset relative to the GameObject’s origin.

Radius

float

default:"32"

Sphere radius in local units.

var sphere = Components.Get<SphereCollider>();
sphere.Radius = 48f;

A capsule shape defined by two end-points and a radius. Commonly used for character bodies.

Start

Vector3

default:"0,0,0"

Bottom center of the capsule in local space.

End

Vector3

default:"0,0,10"

Top center of the capsule in local space.

Radius

float

default:"16"

Radius of the capsule in local units.

var capsule = Components.Get<CapsuleCollider>();
capsule.Start  = Vector3.Zero;
capsule.End    = Vector3.Up * 64;
capsule.Radius = 16f;

Drives full ragdoll or multi-body model physics. The model’s physics asset defines the set of convex hulls and joints. Requires a SkinnedModelRenderer on the same GameObject.

Model

The model whose physics asset is used to generate bodies, collision shapes, and constraints.

Renderer

SkinnedModelRenderer

The skinned renderer that receives bone transform updates from the physics simulation.

MotionEnabled

bool

default:"true"

When true, physics drives the renderer (ragdoll mode). When false, the animation drives the physics bodies (keyframed mode).

IgnoreRoot

bool

default:"false"

When true, the root physics body does not update the component’s world transform.

StartAsleep

bool

default:"false"

All bodies start in a sleeping state and only wake on impact.

Call CopyBonesFrom(renderer, teleport) to initialize ragdoll bone positions from an animated renderer — for example when a character dies and switches from animation to physics.

Rigidbody

Rigidbody adds dynamic physics to a GameObject. The engine integrates forces and resolves collisions each physics step, then writes the resulting position and rotation back to the transform.

A Rigidbody requires at least one collider on the same GameObject to function. Without a collider there is no shape for the physics engine to simulate.

Motion properties

MotionEnabled

bool

default:"true"

Enables dynamic motion. Set to false to make the body kinematic — it still participates in collision but is moved by code rather than physics forces.

Velocity

Vector3

Current linear velocity in world space. Readable and writable. On network proxies this returns the last synced value.

AngularVelocity

Vector3

Current angular velocity in world space (radians per second). Readable and writable.

Gravity

bool

default:"true"

Whether gravity is applied to this body.

GravityScale

float

default:"1.0"

Multiplier for the scene gravity. 2 doubles gravity; 0 disables it without removing the flag.

LinearDamping

float

default:"0"

Drag applied to linear velocity each step.

AngularDamping

float

default:"0"

Drag applied to angular velocity each step.

Locking

PhysicsLock

Bit-mask that constrains position or rotation axes.

Mass properties

Mass

float

Actual mass computed from the attached shapes (read-only).

MassOverride

float

default:"0"

Override the calculated mass. Only applied when greater than zero.

MassCenter

Vector3

Center of mass in local space (read-only).

OverrideMassCenter

bool

default:"false"

When true, uses MassCenterOverride instead of the calculated center.

MassCenterOverride

Vector3

Manual center of mass in local space, used when OverrideMassCenter is true.

State

Sleeping

bool

Whether the body is currently sleeping. Set to true to force sleep; the engine wakes it on contact.

StartAsleep

bool

default:"false"

Body starts the scene in a sleeping state.

EnhancedCcd

bool

default:"false"

Enables enhanced continuous collision detection for fast-moving objects such as projectiles.

Physics body

PhysicsBody

The underlying native physics body. Use this for low-level operations. Can be null if the component is disabled.

Methods

Method	Description
`ApplyForce(Vector3 force)`	Applies a continuous force this physics step.
`ApplyForceAt(Vector3 pos, Vector3 force)`	Applies a force at a world-space point (generates torque).
`ApplyImpulse(Vector3 force)`	Applies an instantaneous impulse (e.g. bullet impact).
`ApplyImpulseAt(Vector3 pos, Vector3 force)`	Applies an instantaneous impulse at a world-space point.
`ApplyTorque(Vector3 force)`	Applies angular force around the body’s axes.
`ClearForces()`	Discards accumulated forces for the current step.
`SmoothMove(Transform, float, float)`	Moves the body cooperatively with the physics engine.
`SmoothRotate(Rotation, float, float)`	Rotates the body cooperatively with the physics engine.
`GetVelocityAtPoint(Vector3)`	World-space velocity at a specific point (includes rotational contribution).
`FindClosestPoint(Vector3)`	Nearest point on the body’s convex shapes to a world-space position.

Setting up a physics object

The following example creates a crate that falls with gravity and reports its velocity when it collides.

using Sandbox;

public sealed class PhysicsCrate : Component
{
    protected override void OnStart()
    {
        // Add a box collider matching the model's bounds
        var collider = Components.GetOrCreate<BoxCollider>();
        collider.Scale  = new Vector3( 50, 50, 50 );
        collider.Center = Vector3.Up * 25;

        // Add a rigidbody so the crate reacts to gravity
        var rb = Components.GetOrCreate<Rigidbody>();
        rb.Gravity      = true;
        rb.GravityScale = 1.0f;
        rb.MassOverride = 10f; // 10 kg
    }

    protected override void OnFixedUpdate()
    {
        var rb = Components.Get<Rigidbody>();
        if ( rb is null ) return;

        // Push the crate upward with a force every step
        rb.ApplyForce( Vector3.Up * 2000f );
    }
}

Prefer ApplyForce inside OnFixedUpdate for continuous forces. Use ApplyImpulse for one-shot events such as explosions or projectile impacts.

Trigger example

using Sandbox;

public sealed class DeathZone : Component
{
    protected override void OnStart()
    {
        var collider = Components.GetOrCreate<BoxCollider>();
        collider.Scale     = new Vector3( 200, 200, 50 );
        collider.IsTrigger = true;
        collider.OnTriggerEnter = OnEnter;
    }

    void OnEnter( Collider other )
    {
        Log.Info( $"{other.GameObject.Name} entered the death zone" );
        other.GameObject.Destroy();
    }
}

Scene & GameObjects

Built-in Components

Engine APIs

Colliders and Rigidbody

Collider base properties

Trigger callbacks

Collider types

Rigidbody

Motion properties

Mass properties

State

Physics body

Methods

Setting up a physics object

Trigger example

Build docs developers (and LLMs) love

Scene & GameObjects

Built-in Components

Engine APIs

​Collider base properties

​Trigger callbacks

​Collider types

​Rigidbody

​Motion properties

​Mass properties

​State

​Physics body

​Methods

​Setting up a physics object

​Trigger example

Build docs developers (and LLMs) love

Collider base properties

Trigger callbacks

Collider types

Rigidbody

Motion properties

Mass properties

State

Physics body

Methods

Setting up a physics object

Trigger example