Skip to content

PhysicsWorld

Extends EngineObject.

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

Properties

  • step_seconds: number Seconds per step (PhysicsOptions.StepRate). Read-only.
  • steps: number The number of steps taken so far. Read-only.
  • body_count: number How many bodies the world has. Read-only.
  • dropped_events: number Events that did not fit the queue and were lost (see PhysicsOptions.EventCapacity). Read-only.
  • paused: boolean While true Update does nothing: no time is added and no step runs, so a pause menu stops the world and the bodies stay where they are.
  • interpolate: boolean 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.
  • gravity: Vector3
  • debug_draw: boolean Draw the bodies, joints and characters over the world (wireframes, colored by what each body is): the host that renders the world calls DrawDebug when this is on. Scripts turn it on with physics.debug_draw = true; the dev overlay has a checkbox.

Signals

  • stepping: Signal<number> 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.
  • contact_began: Signal<Entity, Entity, Vector3, Vector3> Two bodies started touching, at least one of them with BodyDesc.Events: the two entities, the contact point and the normal (pointing from the first to the second).
  • contact_ended: Signal<Entity, Entity>
  • sensor_entered: Signal<Entity, Entity> A body came into a sensor: the sensor's entity, then the other.
  • sensor_exited: Signal<Entity, Entity>
  • body_woke: Signal<Entity> A body with BodyDesc.Events woke up or went to sleep.
  • body_slept: Signal<Entity>

Methods

has_body

function has_body(self, entity: Entity): boolean

Whether entity has a body here.

add_body

function add_body(self, entity: Entity, desc: BodyDesc): ()

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

remove_body

function remove_body(self, entity: Entity): ()

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

pose

function pose(self, entity: Entity): (Vector3, Quat)

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 Interpolate).

teleport

function teleport(self, entity: Entity, position: Vector3, rotation: Quat): ()

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.

get_linear_velocity

function get_linear_velocity(self, entity: Entity): Vector3

set_linear_velocity

function set_linear_velocity(self, entity: Entity, velocity: Vector3): ()

get_angular_velocity

function get_angular_velocity(self, entity: Entity): Vector3

set_angular_velocity

function set_angular_velocity(self, entity: Entity, velocity: Vector3): ()

add_force

function add_force(self, entity: Entity, force: Vector3): ()

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

add_torque

function add_torque(self, entity: Entity, torque: Vector3): ()

add_impulse

function add_impulse(self, entity: Entity, impulse: Vector3): ()

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

wake

function wake(self, entity: Entity): ()

is_awake

function is_awake(self, entity: Entity): boolean

update

function update(self, deltaSeconds: number): ()

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

create_character

function create_character(self, entity: Entity, height: number, radius: number, layers: number?, mask: number?): CharacterController

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.

create_hitch

function create_hitch(self, hitchEntity: Entity, kind: HitchKind): Hitch

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.

create_vehicle

function create_vehicle(self, entity: Entity, desc: VehicleDesc): Vehicle

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.

get_mass

function get_mass(self, entity: Entity): number

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

raycast

function raycast(self, origin: Vector3, direction: Vector3, maxDistance: number, mask: number?, ignore: Entity?): (boolean, Entity, Vector3, Vector3, number)

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.

cast_sphere

function cast_sphere(self, origin: Vector3, direction: Vector3, radius: number, maxDistance: number, mask: number?, ignore: Entity?): (boolean, Entity, Vector3, Vector3, number)

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.

overlap_sphere

function overlap_sphere(self, center: Vector3, radius: number, mask: number?, ignore: Entity?): { Entity }

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

overlap_box

function overlap_box(self, center: Vector3, rotation: Quat, halfExtents: Vector3, mask: number?, ignore: Entity?): { Entity }

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

Functions

create

PhysicsWorld.create: (ecs: World) -> PhysicsWorld

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.