Skip to content

Class PhysicsWorld

Namespace: Apogee.Physics
Assembly: Apogee.Physics.dll

The physics simulation of one ECS : Jolt Physics with double-precision positions, stepped at a fixed rate. Entities get a with ; a dynamic body's entity follows the simulation (its is written, local to its parent, so the world's transform system then fills in the ), and a kinematic body follows its entity.

public sealed class PhysicsWorld : EngineObject, IDisposable

Inheritance

object ← EngineObject ← PhysicsWorld

Implements

IDisposable

Inherited Members

EngineObject.IsAdopted, EngineObject.Handle, EngineObject.IsDestroyed, EngineObject.Class, EngineObject.Adopt(), EngineObject.TryGet(SlotHandle, out EngineObject), EngineObject.Destroy(), object.Equals(object?), object.Equals(object?, object?), object.GetHashCode(), object.GetType(), object.ReferenceEquals(object?, object?), object.ToString()

Remarks

A frame calls once, before World.Progress, so that the transforms the physics wrote are the ones the frame's systems see and the transform system composes. Everything runs on the thread that calls it (Jolt's workers run inside and never call managed code). A body's ancestors must not be dynamic bodies.

Constructors

PhysicsWorld(World, PhysicsOptions?)

Makes the physics world of ecs. Dispose it before the ECS world.

public PhysicsWorld(World ecs, PhysicsOptions? options = null)

Parameters

ecs World

options PhysicsOptions?

Properties

BodyCount

How many bodies the world has.

public int BodyCount { get; }

Property Value

int

BodySlept

public Signal<Entity> BodySlept { get; }

Property Value

Signal<Entity>

BodyWoke

A body with woke up or went to sleep.

public Signal<Entity> BodyWoke { get; }

Property Value

Signal<Entity>

Class

What the registry knows about this object's class.

public override ClassInfo Class { get; }

Property Value

ClassInfo

ContactBegan

Two bodies started touching, at least one of them with : the two entities, the contact point and the normal (pointing from the first to the second).

public Signal<Entity, Entity, Double3, Vector3> ContactBegan { get; }

Property Value

Signal<Entity, Entity, Double3, Vector3>

ContactEnded

public Signal<Entity, Entity> ContactEnded { get; }

Property Value

Signal<Entity, Entity>

DebugDraw

Draw the bodies, joints and characters over the world (wireframes, colored by what each body is): the host that renders the world calls when this is on. Scripts turn it on with physics.debug_draw = true; the dev overlay has a checkbox.

public bool DebugDraw { get; set; }

Property Value

bool

DroppedEvents

Events that did not fit the queue and were lost (see ).

public long DroppedEvents { get; }

Property Value

long

Ecs

The ECS world this one simulates.

public World Ecs { get; }

Property Value

World

Gravity

public Vector3 Gravity { get; set; }

Property Value

Vector3

Interpolate

Show bodies between their last two steps instead of at the last one: smooth at any frame rate, at the price of showing the past by up to a step.

public bool Interpolate { get; set; }

Property Value

bool

Paused

While true does nothing: no time is added and no step runs, so a pause menu stops the world and the bodies stay where they are.

public bool Paused { get; set; }

Property Value

bool

SensorEntered

A body came into a sensor: the sensor's entity, then the other.

public Signal<Entity, Entity> SensorEntered { get; }

Property Value

Signal<Entity, Entity>

SensorExited

public Signal<Entity, Entity> SensorExited { get; }

Property Value

Signal<Entity, Entity>

StepSeconds

Seconds per step ().

public float StepSeconds { get; }

Property Value

float

Stepping

Emitted before each fixed step with its length. Vehicle controllers and anything else that must act once per step belongs here, not in a frame callback.

public Signal<float> Stepping { get; }

Property Value

Signal<float>

Steps

The number of steps taken so far.

public long Steps { get; }

Property Value

long

Methods

AddBody(Entity, BodyDesc)

Gives entity a body made as desc describes, where its transform puts it now (its scale scales the shape). The entity gets a if it has none.

public void AddBody(Entity entity, BodyDesc desc)

Parameters

entity Entity

desc BodyDesc

AddForce(Entity, Vector3)

A force in newtons through the center of mass, applied during the next step only (call it every step to push continuously).

public void AddForce(Entity entity, Vector3 force)

Parameters

entity Entity

force Vector3

AddImpulse(Entity, Vector3)

An instant change of momentum in newton seconds through the center of mass.

public void AddImpulse(Entity entity, Vector3 impulse)

Parameters

entity Entity

impulse Vector3

AddTorque(Entity, Vector3)

public void AddTorque(Entity entity, Vector3 torque)

Parameters

entity Entity

torque Vector3

CastSphere(Double3, Vector3, float, float, uint, Entity)

Sweeps a sphere along direction and returns the first body it touches: whether there was one, the entity, the point of contact, the normal and how far the sphere got.

public (bool Hit, Entity Entity, Double3 Point, Vector3 Normal, float Distance) CastSphere(Double3 origin, Vector3 direction, float radius, float maxDistance, uint mask = 16383, Entity ignore = default)

Parameters

origin Double3

direction Vector3

radius float

maxDistance float

mask uint

ignore Entity

Returns

(bool Hit, Entity Entity, Double3 Point, Vector3 Normal, float Distance)

Create(World)

Makes the physics of an ECS world from a script (a game's own is the global physics). Destroy it, or let the script drop it, before the ECS world goes.

public static PhysicsWorld Create(World ecs)

Parameters

ecs World

Returns

PhysicsWorld

CreateCharacter(Entity, float, float, uint, uint)

Makes a walking character for entity: a capsule of this height (feet to top, at least twice the radius) and radius, standing with its feet at the entity's position. layers and mask are the collision layers it is in and collides with.

public CharacterController CreateCharacter(Entity entity, float height, float radius, uint layers = 1, uint mask = 16383)

Parameters

entity Entity

height float

radius float

layers uint

mask uint

Returns

CharacterController

CreateHitch(Entity, HitchKind)

Makes a hitch of kind on hitchEntity, which must be under the entity of a dynamic body (the vehicle): its transform is the hitch's frame in the vehicle's space. Move the entity to lift what a mount hitch carries.

public Hitch CreateHitch(Entity hitchEntity, HitchKind kind)

Parameters

hitchEntity Entity

kind HitchKind

Returns

Hitch

CreateVehicle(Entity, VehicleDesc)

Makes a vehicle of desc on the dynamic body of entity. The vehicle's space is the entity's, +Z forward, +Y up, +X left. Set its inputs, drive_ratio and clutch in its stepping signal (or the world's); destroying the vehicle, its body or its entity ends it.

public Vehicle CreateVehicle(Entity entity, VehicleDesc desc)

Parameters

entity Entity

desc VehicleDesc

Returns

Vehicle

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

DrawDebug(DebugDraw, PhysicsDebugOptions?, Double3)

Adds the picture of the world (options says what) to draw, in world positions. camera picks the level of detail of round shapes. The drawing is of the state the last left, not interpolated between steps.

public void DrawDebug(DebugDraw draw, PhysicsDebugOptions? options = null, Double3 camera = default)

Parameters

draw DebugDraw

options PhysicsDebugOptions?

camera Double3

GetAngularVelocity(Entity)

public Vector3 GetAngularVelocity(Entity entity)

Parameters

entity Entity

Returns

Vector3

GetLinearVelocity(Entity)

public Vector3 GetLinearVelocity(Entity entity)

Parameters

entity Entity

Returns

Vector3

GetMass(Entity)

The mass of the body of entity in kilograms (0 for a static or kinematic one).

public float GetMass(Entity entity)

Parameters

entity Entity

Returns

float

HasBody(Entity)

Whether entity has a body here.

public bool HasBody(Entity entity)

Parameters

entity Entity

Returns

bool

IsAwake(Entity)

public bool IsAwake(Entity entity)

Parameters

entity Entity

Returns

bool

OnDestroyed()

protected override void OnDestroyed()

OverlapBox(Double3, Quaternion, Vector3, uint, Entity)

The entities of the bodies that touch this box (centered on center, turned by rotation), each once.

public Entity[] OverlapBox(Double3 center, Quaternion rotation, Vector3 halfExtents, uint mask = 16383, Entity ignore = default)

Parameters

center Double3

rotation Quaternion

halfExtents Vector3

mask uint

ignore Entity

Returns

Entity[]

OverlapSphere(Double3, float, uint, Entity)

The entities of the bodies that touch this sphere (sensors excluded), each once.

public Entity[] OverlapSphere(Double3 center, float radius, uint mask = 16383, Entity ignore = default)

Parameters

center Double3

radius float

mask uint

ignore Entity

Returns

Entity[]

Pose(Entity)

The exact pose of the body in the world after the last step (the entity's own transform may show a blend between two steps, see ).

public (Double3 Position, Quaternion Rotation) Pose(Entity entity)

Parameters

entity Entity

Returns

(Double3 Position, Quaternion Rotation)

Raycast(Double3, Vector3, float, uint, Entity)

Casts a ray and returns the nearest hit: whether there was one, the entity, the hit point, the surface normal and the distance. mask picks the collision layers that count; ignore is an entity (the shooter's own body) the ray passes through. Sensors are never hit.

public (bool Hit, Entity Entity, Double3 Point, Vector3 Normal, float Distance) Raycast(Double3 origin, Vector3 direction, float maxDistance, uint mask = 16383, Entity ignore = default)

Parameters

origin Double3

direction Vector3

maxDistance float

mask uint

ignore Entity

Returns

(bool Hit, Entity Entity, Double3 Point, Vector3 Normal, float Distance)

RemoveBody(Entity)

Takes the body off entity (the entity stays, where the body left it).

public void RemoveBody(Entity entity)

Parameters

entity Entity

SetAngularVelocity(Entity, Vector3)

public void SetAngularVelocity(Entity entity, Vector3 velocity)

Parameters

entity Entity

velocity Vector3

SetLinearVelocity(Entity, Vector3)

public void SetLinearVelocity(Entity entity, Vector3 velocity)

Parameters

entity Entity

velocity Vector3

Teleport(Entity, Double3, Quaternion)

Puts the body at this world pose at once, keeping its velocity, and its entity too (no blend). For a static body this is how it moves at all.

public void Teleport(Entity entity, Double3 position, Quaternion rotation)

Parameters

entity Entity

position Double3

rotation Quaternion

Update(float)

Advances the simulation by deltaSeconds of game time in fixed steps (at most a call; a slower frame loses time), then writes the bodies' poses to their entities. Call it once a frame, before World.Progress.

public void Update(float deltaSeconds)

Parameters

deltaSeconds float

Wake(Entity)

public void Wake(Entity entity)

Parameters

entity Entity