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: numberSeconds per step (PhysicsOptions.StepRate). Read-only.steps: numberThe number of steps taken so far. Read-only.body_count: numberHow many bodies the world has. Read-only.dropped_events: numberEvents that did not fit the queue and were lost (see PhysicsOptions.EventCapacity). Read-only.paused: booleanWhile 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: booleanShow 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: Vector3debug_draw: booleanDraw 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.