Physics

The Physics namespace — 42 functions.

globals/Physics/addCollider

globals/Physics/addCollider(entityId: string, config: table)

Add a Collider component to an entity.

globals/Physics/addConstraint

globals/Physics/addConstraint(entityId: string, opts: table?)

Add a transform constraint to an entity.

globals/Physics/addJoint

globals/Physics/addJoint(entityIdA: string, entityIdB: string, opts: table?)

Add a Joint component connecting two entities. Accepts either vec3-style anchor inputs (localAnchor = {x,y,z}) or pre-split scalar keys (localAnchorX/Y/Z).

globals/Physics/addVelocity

globals/Physics/addVelocity(a: string | number | vec3, b: (number | vec3)?, c: number?, d: number?)

Add to the linear velocity of an entity. Same call shapes as setVelocity.

globals/Physics/addWheelCollider

globals/Physics/addWheelCollider(entityId: string, config: table?)

Add a WheelCollider to an entity. The entity must be a child (or descendant) of a rigid body — the system walks up the hierarchy to find the Physics component.

globals/Physics/applyForce

globals/Physics/applyForce(entityIdOrForce: string | vec3, force: vec3?)

Apply a force to an entity's rigid body for the next physics step — call every frame for continuous thrust. With one argument the script-context entity is targeted; with two args the explicit entity id wins.

globals/Physics/applyForceAtPoint

globals/Physics/applyForceAtPoint(entityId: string, force: vec3, point: vec3)

Apply a force at a specific world-space point — generates the matching torque from the lever arm.

globals/Physics/applyImpulse

globals/Physics/applyImpulse(entityIdOrImpulse: string | vec3, impulse: vec3?)

Apply an instantaneous impulse (one-shot velocity change). With one argument the script-context entity is targeted; with two args the explicit entity id wins.

globals/Physics/applyTorque

globals/Physics/applyTorque(entityIdOrTorque: string | vec3, torque: vec3?)

Apply a torque to an entity's rigid body for the next physics step — call every frame for continuous spin-up. With one argument the script-context entity is targeted; with two args the explicit entity id wins.

globals/Physics/boxCast

globals/Physics/boxCast(origin: vec3, halfExtents: vec3, direction: vec3, maxDistance: number?) -> table?

Cast a box along a direction and return the first hit.

globals/Physics/colliderShapes

globals/Physics/colliderShapes(entityId: string) -> table

Read an entity's resolved physics collider shape(s) — box half-extents, sphere/capsule radius, or convex line points — as the physics engine sees them, including auto-sized colliders.

globals/Physics/getAngularVelocity

globals/Physics/getAngularVelocity(entityId: string?) -> vec3?

Read the angular velocity of an entity's rigid body.

globals/Physics/getGravity

globals/Physics/getGravity() -> vec3

Read the current world gravity vector.

globals/Physics/getVelocity

globals/Physics/getVelocity(entityId: string?) -> vec3?

Read the linear velocity of an entity's rigid body.

globals/Physics/getWheelState

globals/Physics/getWheelState(entityId: string) -> table?

Read a wheel collider's runtime state. Reads the native component the wheel system writes after each physics step.

globals/Physics/hasLineOfSight

globals/Physics/hasLineOfSight(fromId: string, toId: string) -> boolean

Check whether two entities have line-of-sight between their origins.

globals/Physics/ignoreCollision

globals/Physics/ignoreCollision(entityIdA: string, entityIdB: string, ignore: boolean?)

Toggle ignored-collision state between two specific entities.

globals/Physics/isSleeping

globals/Physics/isSleeping(entityId: string?) -> boolean?

Whether an entity's rigid body is currently asleep (at rest and not simulating). A body sleeps once it stops moving, to save simulation cost.

globals/Physics/overlapSphere

globals/Physics/overlapSphere(center: vec3, radius: number) -> table

Find every entity id whose colliders overlap a sphere.

globals/Physics/raycast

globals/Physics/raycast(origin: vec3, direction: vec3, maxDistance: number?, exclude: (string | {string})?) -> table?

Cast a ray and return the first hit.

globals/Physics/raycastAll

globals/Physics/raycastAll(origin: vec3, direction: vec3, maxDistance: number?, maxHits: number?, exclude: (string | {string})?) -> table

Cast a ray and return every hit up to maxHits.

globals/Physics/raycastBetween

globals/Physics/raycastBetween(fromId: string, toId: string, maxDistance: number?) -> table?

Cast a ray from one entity toward another and return the first hit.

globals/Physics/raycastScreen

globals/Physics/raycastScreen(sx: number, sy: number, maxDistance: number?, exclude: (string | {string})?) -> table?

Cast a ray from a screen pixel into the scene and return the first hit. Unprojects the pixel with screenToRay, then casts with raycast.

globals/Physics/removeCollider

globals/Physics/removeCollider(entityId: string)

Remove the Collider component from an entity (if present).

globals/Physics/removeConstraint

globals/Physics/removeConstraint(entityId: string, index: number?)

Remove transform constraints from an entity (if any are present).

globals/Physics/removeJoint

globals/Physics/removeJoint(entityId: string)

Remove the Joint component from an entity (if present).

globals/Physics/removeWheelCollider

globals/Physics/removeWheelCollider(entityId: string)

Remove the WheelCollider component from an entity (if present).

globals/Physics/setAngularDamping

globals/Physics/setAngularDamping(entityIdOrDamping: string | number, damping: number?)

Set angular damping on an entity's rigid body. One-arg form targets the script-context entity.

globals/Physics/setAngularVelocity

globals/Physics/setAngularVelocity(a: string | number | vec3, b: (number | vec3)?, c: number?, d: number?)

Set the angular velocity of an entity (radians/sec). Same call shapes as setVelocity.

globals/Physics/setBodyType

globals/Physics/setBodyType(entityId: string, bodyType: string)

Change a rigid body's type at runtime. Mass, colliders, and joints are preserved — only the body's response to forces and position writes changes.

globals/Physics/setCcdEnabled

globals/Physics/setCcdEnabled(entityIdOrEnabled: string | boolean, enabled: boolean?)

Enable or disable continuous collision detection on an entity's rigid body. One-arg form targets the script-context entity.

globals/Physics/setCollisionGroups

globals/Physics/setCollisionGroups(entityId: string, membership: number, filter: number)

Set the collision-group membership and filter bitmasks on an entity's colliders. Adds a CollisionGroup component if missing.

globals/Physics/setGravity

globals/Physics/setGravity(gravity: vec3)

Replace the world gravity vector.

globals/Physics/setGravityScale

globals/Physics/setGravityScale(entityIdOrScale: string | number, scale: number?)

Set the per-entity gravity scale (1.0 = normal, 0.0 = no gravity). One-arg form targets the script-context entity.

globals/Physics/setJointMotor

globals/Physics/setJointMotor(entityId: string, targetVelocity: number, maxForce: number)

Set a motor on an entity's joint.

globals/Physics/setLinearDamping

globals/Physics/setLinearDamping(entityIdOrDamping: string | number, damping: number?)

Set linear damping on an entity's rigid body (0 = no damping). One-arg form targets the script-context entity.

globals/Physics/setMass

globals/Physics/setMass(entityIdOrMass: string | number, mass: number?)

Set the mass of an entity's rigid body (kg). One-arg form targets the script-context entity.

globals/Physics/setRotationLocks

globals/Physics/setRotationLocks(entityId: string, x: boolean, y: boolean, z: boolean)

Lock or unlock rotation on specific axes.

globals/Physics/setTranslationLocks

globals/Physics/setTranslationLocks(entityId: string, x: boolean, y: boolean, z: boolean)

Lock or unlock translation on specific axes.

globals/Physics/setVelocity

globals/Physics/setVelocity(a: string | number | vec3, b: (number | vec3)?, c: number?, d: number?)

Set the linear velocity of an entity. Accepts (x, y, z) or a {x, y, z} vector for the script-context entity, or the same prefixed with an explicit entityId.

globals/Physics/sphereCast

globals/Physics/sphereCast(origin: vec3, radius: number, direction: vec3, maxDistance: number?) -> table?

Cast a sphere along a direction and return the first hit.

globals/Physics/wakeUp

globals/Physics/wakeUp(entityId: string?)

Wake an entity's sleeping rigid body so it resumes simulating. The motion setters (applyImpulse, setVelocity, setAngularVelocity) wake the body for you; call this to wake one explicitly.