Physics world

The physics world is accessed through Scene.PhysicsWorld (or Game.PhysicsTrace for scene-level traces). Use PhysicsWorld.Trace to build and run queries against the world, then read the result from PhysicsTraceResult.

PhysicsWorld

PhysicsWorld represents the physics simulation for a scene. You rarely construct one yourself — the active scene provides one automatically.

var world = Scene.PhysicsWorld;

Properties

Gravity

Vector3

The gravitational acceleration applied to all dynamic bodies. Default is (0, 0, -800) (Source engine units).

AirDensity

float

Air density used for drag calculations on dynamic bodies.

SleepingEnabled

bool

When true, bodies that have been inactive for a while are put to sleep to save CPU. Default is true.

SubSteps

int

Number of physics sub-steps executed per simulation tick. Increase to reduce tunnelling at the cost of performance. Default is 1.

SimulationMode

PhysicsSimulationMode

Controls collision detection mode. Discrete is faster; Continuous prevents fast-moving bodies from tunnelling through thin geometry.

Trace

PhysicsTraceBuilder

Returns a new PhysicsTraceBuilder targeting this world. Use it to construct and run trace queries.

Bodies

IEnumerable<PhysicsBody>

All valid physics bodies currently in this world.

Gravity example

// Zero gravity
Scene.PhysicsWorld.Gravity = Vector3.Zero;

// Low gravity
Scene.PhysicsWorld.Gravity = new Vector3( 0, 0, -200 );

PhysicsTraceBuilder

PhysicsTraceBuilder is a fluent builder for constructing physics queries. Obtain one from PhysicsWorld.Trace, chain shape and filter methods, then call Run() or RunAll().

Shape methods

Ray(Vector3 from, Vector3 to)

PhysicsTraceBuilder

Cast an infinitely thin ray from from to to.

Ray(Ray ray, float distance)

PhysicsTraceBuilder

Cast a ray from a Ray struct up to distance units.

Sphere(float radius, Vector3 from, Vector3 to)

PhysicsTraceBuilder

Sweep a sphere of radius from from to to.

Sphere(float radius, Ray ray, float distance)

PhysicsTraceBuilder

Sweep a sphere along a Ray up to distance units.

Box(Vector3 extents, Vector3 from, Vector3 to)

PhysicsTraceBuilder

Sweep an axis-aligned box with the given extents (half-sizes) from from to to.

Box(BBox bbox, Vector3 from, Vector3 to)

PhysicsTraceBuilder

Sweep an axis-aligned box defined by a BBox from from to to.

Capsule(Capsule capsule, Vector3 from, Vector3 to)

PhysicsTraceBuilder

Sweep a capsule from from to to.

Capsule(Capsule capsule, Ray ray, float distance)

PhysicsTraceBuilder

Sweep a capsule along a Ray up to distance units.

Filter methods

IgnoreStatic()

PhysicsTraceBuilder

Exclude static (immovable) physics objects from the query.

IgnoreDynamic()

PhysicsTraceBuilder

Exclude dynamic physics bodies from the query.

IgnoreKeyframed()

PhysicsTraceBuilder

Exclude keyframed bodies (moved by code, not simulation) from the query.

HitTriggers()

PhysicsTraceBuilder

Include trigger volumes in the query in addition to solid geometry.

HitTriggersOnly()

PhysicsTraceBuilder

Return only trigger volume hits, ignoring solid geometry.

Execution methods

Run()

PhysicsTraceResult

Execute the trace and return the first (closest) hit.

RunAll()

PhysicsTraceResult[]

Execute the trace and return all hits, sorted by distance.

RunAgainstCapsule(Capsule capsule, Transform transform)

PhysicsTraceResult

Run the trace against a specific capsule at a given transform, ignoring all other physics objects.

RunAgainstSphere(Sphere sphere, Transform transform)

PhysicsTraceResult

Run the trace against a specific sphere at a given transform.

RunAgainstBBox(BBox box, Transform transform)

PhysicsTraceResult

Run the trace against a specific bounding box at a given transform.

PhysicsTraceResult

PhysicsTraceResult is returned by Run() and RunAll(). Always check Hit before reading geometry data.

Fields

Hit

bool

required

true if the trace hit something. Always check this before reading any hit data.

StartedSolid

bool

true if the trace origin was already inside a solid object.

HitPosition

Vector3

World-space position where the trace first intersected geometry.

StartPosition

Vector3

World-space origin of the trace.

EndPosition

Vector3

World-space end position of the trace (the hit point, or the target if there was no hit).

Normal

Vector3

Surface normal at the hit point, pointing away from the hit surface.

Distance

float

Distance between StartPosition and EndPosition.

Fraction

float

A value in [0..1] indicating how far along the trace the hit occurred. 1.0 means no hit.

Body

PhysicsBody

The physics body that was hit, or null if the trace hit world geometry.

Shape

PhysicsShape

The specific physics shape that was hit.

Surface

The physical material properties of the hit surface (footstep sounds, impact effects, etc.).

PhysicsBody

PhysicsBody represents a single rigid body in the physics world. Obtain one from PhysicsTraceResult.Body, from a Rigidbody component, or create one manually.

Motion properties

Velocity

Vector3

Linear velocity of the body in world space. Get or set directly.

AngularVelocity

Vector3

Angular velocity of the body in world space (radians per second around each axis). Get or set directly.

Mass

float

Mass of the body in kilograms. Affects how forces change velocity.

GravityEnabled

bool

Whether gravity is applied to this body. Default is true.

GravityScale

float

Multiplier applied to the world gravity for this body. 2.0 is double gravity.

LinearDamping

float

Coefficient of linear drag — how quickly the body decelerates on its own.

AngularDamping

float

Coefficient of rotational drag.

BodyType

PhysicsBodyType

Movement type: Static, Keyframed, or Dynamic.

Sleeping

bool

Get or set the sleep state. Set to false to wake the body from sleep.

Force methods

ApplyForce(Vector3 force)

void

Apply a continuous force at the center of mass. Force is scaled by the physics timestep, so this is appropriate for forces applied every tick (engines, wind, etc.).

ApplyForceAt(Vector3 position, Vector3 force)

void

Apply a continuous force at a world-space position. Can impart angular velocity.

ApplyImpulse(Vector3 impulse)

void

Apply an instantaneous impulse at the center of mass. Appropriate for one-shot events like bullet impacts or jumps.

ApplyImpulseAt(Vector3 position, Vector3 velocity)

void

Apply an instantaneous impulse at a world-space position.

ApplyAngularImpulse(Vector3 impulse)

void

Apply an instantaneous angular impulse (spin kick).

ApplyTorque(Vector3 force)

void

Apply a continuous torque (rotational force) scaled by the physics timestep.

Utility methods

GetVelocityAtPoint(Vector3 point)

Vector3

Returns the world-space velocity at a specific point on the body, accounting for both linear and angular velocity. Useful for ragdoll and contact calculations.

SmoothMove(Vector3 position, float timeToArrive, float timeDelta)

void

Move the body toward position using velocity damping over timeToArrive seconds. Works well for grabbed objects and kinematic movement.

FindClosestPoint(Vector3 point)

Vector3

Returns the nearest point on the surface of the body to the given world-space position.

GetBounds()

BBox

Returns the axis-aligned world-space bounding box of the body.

Practical examples

Raycast
Sphere sweep
Box sweep
Apply forces

// Basic raycast from camera forward
var ray = Scene.Camera.ScreenPixelToRay( Screen.Size / 2f );
var result = Scene.PhysicsWorld.Trace
    .Ray( ray, 2000f )
    .Run();

if ( result.Hit )
{
    Log.Info( $"Hit {result.Body?.GameObject?.Name} at {result.HitPosition}" );
    Log.Info( $"Surface: {result.Surface?.ResourceName}" );
}

// Sweep a sphere to check for nearby players
var hits = Scene.PhysicsWorld.Trace
    .Sphere( 64f, WorldPosition, WorldPosition + Vector3.Down * 200f )
    .RunAll();

foreach ( var hit in hits )
{
    var player = hit.Body?.GameObject?.Components.Get<PlayerController>();
    if ( player is not null )
    {
        player.TakeDamage( 50f );
    }
}

// Overlap check using a box
var extents = new Vector3( 32, 32, 32 );
var result = Scene.PhysicsWorld.Trace
    .Box( extents, WorldPosition, WorldPosition )
    .IgnoreStatic()
    .Run();

if ( result.Hit )
    Log.Info( "Something is in the box" );

// Explode — apply an impulse to all nearby bodies
var center = WorldPosition;
var radius = 256f;
var force = 1500f;

foreach ( var body in Scene.PhysicsWorld.Bodies )
{
    var delta = body.Position - center;
    var distance = delta.Length;

    if ( distance > radius ) continue;

    var falloff = 1f - (distance / radius);
    body.ApplyImpulse( delta.Normal * force * falloff );
}

When checking what was hit you often only need result.Body?.GameObject to get the GameObject. If the hit body belongs to the world (static map geometry), Body will be non-null but Body.GameObject may be null.

Scene & GameObjects

Built-in Components

Engine APIs

Physics world

PhysicsWorld

Properties

Gravity example

PhysicsTraceBuilder

Shape methods

Filter methods

Execution methods

PhysicsTraceResult

Fields

PhysicsBody

Motion properties

Force methods

Utility methods

Practical examples

Build docs developers (and LLMs) love

Scene & GameObjects

Built-in Components

Engine APIs

​PhysicsWorld

​Properties

​Gravity example

​PhysicsTraceBuilder

​Shape methods

​Filter methods

​Execution methods

​PhysicsTraceResult

​Fields

​PhysicsBody

​Motion properties

​Force methods

​Utility methods

​Practical examples

Build docs developers (and LLMs) love

PhysicsWorld

Properties

Gravity example

PhysicsTraceBuilder

Shape methods

Filter methods

Execution methods

PhysicsTraceResult

Fields

PhysicsBody

Motion properties

Force methods

Utility methods

Practical examples