physics3d

The 3D rigid-body world: bodies and colliders on nodes, their velocities, and overlap queries. physics holds what spans both worlds.

78 functions, 6 constants. Scripts reach it as physics3d::.

Acts on body3d, character3d, collider3d, joint3d, vehicle3d, wheel3d: those functions are also methods on the component's handle, without the node argument.

Functions

Argument kinds are the script values a call passes: node is a node handle, any a table or value of any kind, fn a callback.

function	acts on	what it does
aabb(node) -> float, float, float, float, float, float	collider3d	The world-space box the collider currently occupies, as its two opposite corners.
add_ball_collider(node, float)	collider3d	Attach a sphere collider of the given radius.
add_body(node, string)	body3d	Give the node a rigid body of the given kind (BODY_DYNAMIC, BODY_STATIC, BODY_KINEMATIC, BODY_KINEMATIC_VELOCITY).
add_cuboid_collider(node, float, float, float)	collider3d	Attach a box collider from its three half-extents.
add_force(node, float, float, float)	body3d	Push the body until the force is reset; unlike an impulse this is spread over time.
add_force_at_point(node, float, float, float, float, float, float)	body3d	Push at a world point, which also turns the body.
add_joint(node, any)	joint3d	Tie this node's body to another with a joint, from a joint3d table: kind, body, anchor, axis, limits, and the rest of the component's own vocabulary.
add_torque(node, float, float, float)	body3d	Turn the body until the torque is reset.
angular_velocity(node) -> float, float, float	body3d	How fast the body is spinning, in radians per second about each axis.
apply_impulse(node, float, float, float)	body3d	Add an instant change in momentum, as if the body were struck.
apply_impulse_at_point(node, float, float, float, float, float, float)	body3d	Strike the body at a world point, which spins it as well as moves it.
apply_torque_impulse(node, float, float, float)	body3d	Add an instant change in angular momentum, as if the body were spun.
body_kind(node) -> string	body3d	Whether the body is dynamic, static, kinematic or kinematic_velocity.
box_hits(any) -> any	—	Every collider whose bounds meet an axis-aligned box; cheaper and looser than shape_hits.
closest_points(node, node) -> any	—	The nearest point on each of two nodes' colliders.
collider_mass(node) -> float	collider3d	What this collider weighs, density and size together.
collider_mesh(node) -> any	collider3d	The collider's shape as points and triangles — including a voxel grid's — for drawing it or for spawning the pieces it broke into.
contacts(node) -> any	collider3d	Every contact point on this node's collider this step: #{ node, point, normal, impulse } each. Empty for a sensor, which has no contacts by definition.
damping(node) -> float, float	body3d	This body's linear and angular damping.
distance(node, node) -> any	—	The gap between two nodes' colliders, zero when they touch or overlap.
dominance(node) -> float	body3d	This body's dominance group.
gravity() -> float, float, float	—	The 3D world's gravity.
gravity_scale(node) -> float	body3d	This body's gravity multiplier.
intersects(node, node) -> any	—	Whether two nodes' colliders overlap right now, sensor or not.
is_ccd(node) -> bool	body3d	Whether continuous collision detection is on for this body.
is_enabled(node) -> bool	body3d	Whether the body is being simulated.
is_grounded(node) -> bool	character3d	Whether the last move ended with ground under the character's feet.
is_sleeping(node) -> bool	body3d	Whether the body is asleep and being skipped.
joint_impulse(node) -> float	joint3d	How hard the joint is pulling right now: what a breakable one is measured against.
kinetic_energy(node) -> float	body3d	The body's kinetic energy, for a rest test the solver agrees with.
linear_velocity(node) -> float, float, float	body3d	How fast the body is travelling, in units per second.
locked_axes(node) -> bool, bool, bool, bool, bool, bool	body3d	Which translation and rotation axes are frozen.
mass(node) -> float	body3d	The body's total mass, colliders included.
max_contact_impulse(node) -> float	collider3d	The hardest contact this node took in the last step, zero when nothing touched it: a damage threshold in one number.
move_character(node, float, float, float) -> any	character3d	Move the character by an offset, sliding along walls, climbing steps and staying on the ground: returns #{ x, y, z, grounded, sliding, collisions }. Call it from fixed_update — it reads the world the step just wrote.
nearest_point(any) -> any	—	The closest point on any collider to a world point.
next_position(node) -> float, float, float	body3d	The pose a kinematic body has been told to move to.
overlaps(node) -> [node]	collider3d	The nodes this one currently intersects; rapier reports a pair only when one of the two colliders is a sensor.
point_hits(any) -> any	—	Every collider containing a world point.
predict_position(node, float) -> float, float, float	body3d	Where the body will be after dt seconds at its current velocity.
raycast(any) -> any	—	The first collider a ray meets: #{ from = [x, y, z], dir = [x, y, z], max = 100.0, filter = #{ exclude = node, only = "dynamic" } }. Returns #{ node, point, normal, distance }, or nothing.
raycast_all(any) -> any	—	Every collider a ray meets, nearest first.
remove_joint(node)	joint3d	Undo the node's joint, leaving both bodies free.
reset_forces(node)	body3d	Drop every force added since the last step.
reset_torques(node)	body3d	Drop every torque added since the last step.
set_angular_velocity(node, float, float, float)	body3d	Set how fast the body spins, in radians per second about each axis.
set_body_kind(node, string)	body3d	Change the body between dynamic, static and kinematic in place, keeping its velocity.
set_brake(node, float)	wheel3d	How hard this wheel brakes.
set_ccd(node, bool)	body3d	Sweep this body's whole path each step so it cannot pass through a wall.
set_collider(node, any)	collider3d	Replace the node's collider from a collider3d table: kind, radius, half_extents, friction, and the rest of the component's own vocabulary.
set_damping(node, float, float)	body3d	Set linear and angular damping together.
set_dominance(node, float)	body3d	Set the group that decides which of two bodies can push the other.
set_enabled(node, bool)	body3d	Simulate this body or leave it out entirely, keeping its state.
set_engine_force(node, float)	wheel3d	How hard this wheel drives, in newtons; negative reverses.
set_gravity(float, float, float)	—	Set the 3D world's gravity, in units per second squared.
set_gravity_scale(node, float)	body3d	Scale world gravity for this body alone.
set_joint_limits(node, float, float)	joint3d	Set how far the joint may travel, in radians for a revolute one and units for a prismatic one.
set_linear_velocity(node, float, float, float)	body3d	Set how fast the body travels, in units per second.
set_lock_rotation(node, bool, bool, bool)	body3d	Freeze the body's spin about each world axis: how an upright character stays upright.
set_lock_translation(node, bool, bool, bool)	body3d	Freeze the body's movement along each world axis.
set_motor_position(node, float, float, float)	joint3d	Drive the joint towards an angle or a distance, with a spring's stiffness and damping.
set_motor_velocity(node, float, float)	joint3d	Drive the joint towards a speed: how a wheel is powered or a door swings itself shut.
set_steering(node, float)	wheel3d	Turn this wheel, in radians.
set_voxel(node, int, int, int, bool)	collider3d	Fill or empty one cell of a voxel collider: digging a hole, or building a wall, while the game runs.
shape_hits(any) -> any	—	Every collider a shape overlaps where it stands: an explosion's reach, a melee arc.
shapecast(any) -> any	—	Sweep a shape along a direction until it hits something: a thick raycast, and how a camera avoids walls.
sleep(node)	body3d	Put the body to sleep now.
solve_ik(node, float, float, float)	joint3d	Move a reduced-coordinates chain so its last link reaches a world position, leaving every joint inside its limits.
teleport(node, float, float, float)	body3d	Move the body to a world position at once, clearing its velocity: what assigning the node's position cannot do, because the step writes that back every tick.
user_force(node) -> float, float, float	body3d	The force the next step will integrate.
user_torque(node) -> float, float, float	body3d	The torque the next step will integrate.
vehicle_speed(node) -> float	vehicle3d	How fast the chassis is going along its forward axis, in units per second.
velocity_at_point(node, float, float, float) -> float, float, float	body3d	How fast a world point on the body is moving, spin included.
voxel(node, int, int, int) -> bool	collider3d	Whether one cell of a voxel collider is filled.
voxel_at(node, float, float, float) -> int, int, int	collider3d	The cell a world position falls in, as three whole numbers.
wake_all()	—	Wake every sleeping body in the 3D world.
wake_up(node)	body3d	Wake the body, so the next step moves it.
wheel_state(node) -> any	wheel3d	What the last step did with this wheel: #{ rotation, suspension_force, grounded, engine_force, brake, steering }.

Constants

name	value
BODY_DYNAMIC	dynamic
BODY_KINEMATIC	kinematic
BODY_KINEMATIC_VELOCITY	kinematic_velocity
BODY_STATIC	static
SHAPE_BALL	ball
SHAPE_CUBOID	cuboid