Skip to content

Search

Documentation

physics3d

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

On this page

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

139 functions, 118 constants. Scripts reach it as physics3d::.

Acts on body3d, character3d, collider3d, follow3d, joint3d, softbody3d, 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] collider3d The world-space box the collider currently occupies, as its two opposite corners.
active_bodies() -> [Node] — Every node whose body is awake this step: what a game loops over when it wants to touch only what is moving.
add_constant_force(Node, float, float, float) body3d Push the body every step until the constant force is set back to zero; unlike an impulse this is spread over time.
add_constant_force_at_point(Node, float, float, float, float, float, float) body3d Push at a world point every step, which also turns the body.
add_constant_torque(Node, float, float, float) body3d Turn the body every step until the constant torque is set back to zero.
add_particle_force(Node, int, Vec3) softbody3d Push one particle with force each step until reset_softbody_forces.
add_softbody_force(Node, Vec3) softbody3d Push every free particle with force each step until reset_softbody_forces.
angular_velocity(Node) -> Vec3 body3d How fast the body is spinning, in radians per second about each axis.
apply_force(Node, float, float, float) body3d Push the body for the next step only; add_constant_force keeps pushing.
apply_force_at_point(Node, float, float, float, float, float, float) body3d Push at a world point for the next step only, which also turns the body.
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_particle_impulse(Node, int, Vec3) softbody3d Strike one particle.
apply_softbody_impulse(Node, Vec3) softbody3d Change every free particle's velocity by impulse at once, as a kick to the whole body.
apply_softbody_impulse_at(Node, Vec3, Vec3, float) softbody3d Strike the particles within radius of point, less the further they are; a radius of 0 strikes them all.
apply_softbody_radial_impulse(Node, Vec3, float, float) softbody3d Push the particles within radius away from center, as a blast does.
apply_torque(Node, float, float, float) body3d Turn the body for the next step only; add_constant_torque keeps turning it.
apply_torque_impulse(Node, float, float, float) body3d Add an instant change in angular momentum, as if the body were spun.
attach_particle(Node, int, Node) softbody3d Tie one particle to a node's rigid body where it is now: the body and the particle pull on each other.
bodies() -> [Node] — Every node with a rigid body, sorted.
broad_phase_aabb(Node) -> [float] collider3d The box the broad phase files the collider under, which also reaches ahead by its body's speculative_distance.
closest_point(physics3d::PointQuery) -> physics3d::Closest? — The closest point on any collider to a world point.
closest_points(Node, Node) -> physics3d::ClosestPoints? — The nearest point on each of two nodes' colliders.
collider_mass(Node) -> float collider3d What this collider weighs, density and size together.
collider_mass_properties(Node) -> physics3d::MassProperties collider3d What this collider adds to its body, in its own space.
collider_mesh(Node) -> physics3d::ColliderMesh 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.
collider_volume(Node) -> float collider3d How much space the shape encloses.
collision_aabb(Node) -> [float] collider3d The box the narrow phase tests the collider in: its shape's box grown by its collision_margin and the world's prediction distance.
combine_voxels(Node, Node) collider3d Tell two voxel colliders on one lattice about each other's cells, so a body sliding from one onto the other does not catch on the seam. Both must share a cell size and a rotation.
constant_force(Node) -> Vec3 body3d The force every step integrates until it is set back to zero.
constant_torque(Node) -> Vec3 body3d The torque every step integrates until it is set back to zero.
contacts(Node) -> [physics3d::Contact] collider3d Every contact point on this node's collider this step. Empty for a sensor, which has no contacts by definition.
crop_voxels(Node, int, int, int, int, int, int) collider3d Empty every cell outside the cells from (min_x, min_y, min_z) to (max_x, max_y, max_z), both included. A range holding no filled cell leaves the grid as it was.
cut_softbody(Node, [Vec3]) -> [physics3d::SoftTear] softbody3d Cut the body along a blade at once, as softbody_crossing reads it; answers a record for each piece it changed, the one on_tear hears.
detach_particle(Node, int) -> bool softbody3d Untie one particle from every body it was attached to; answers whether it was attached.
distance(Node, Node) -> float — The gap between two nodes' colliders, zero when they touch or overlap.
effective_angular_inertia(Node) -> [Vec3] body3d The world-space inertia the solver turns, rotation locks applied, as its three rows.
effective_dominance(Node) -> float body3d The dominance rapier will use for this body: its own group, or the rank every non-dynamic body outranks with.
effective_mass(Node) -> Vec3 body3d The mass the solver pushes against along each world axis: zero along a locked axis, and on any body that is not dynamic.
gravity() -> Vec3 — The 3D world's gravity.
handles(Node) -> physics3d::Handles collider3d The rapier handles behind this node, its body and its colliders. For matching a log line against rapier's own output.
has_pending_tears(Node) -> bool softbody3d Whether some edge or cell is marked to tear at the end of the next step.
heightfield_hole(Node, int, int) -> bool collider3d Whether a heightfield cell has no ground.
intersects(Node, Node) -> bool — Whether two nodes' colliders overlap right now, sensor or not.
is_ccd_active(Node) -> bool body3d Whether the body moved fast enough last step for rapier to sweep it, with or without continuous_collision.
is_moving(Node) -> bool body3d Whether the body is awake and actually going somewhere.
is_on_floor(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_force(Node) -> physics3d::JointForce joint3d The force and the torque the joint held through the last step: what break_force and break_torque are measured against. An articulation has none to read, and says so.
joint_state(Node) -> physics3d::JointState joint3d What the joint is doing.
kinetic_energy(Node) -> float body3d The body's kinetic energy, for a rest test the solver agrees with.
linear_velocity(Node) -> Vec3 body3d How fast the body is travelling, in units per second.
local_center_of_mass(Node) -> Vec3 body3d Where the body's whole mass sits, in the body's own space.
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) -> physics3d::CharacterMove character3d Move the character by an offset, sliding along walls, climbing steps and staying on the ground. Every solid collider of the character is swept. Call it from fixed_update. It reads the world the step just wrote.
next_position(Node) -> physics3d::Pose body3d The pose a kinematic body has been told to move to.
overlap_aabb(physics3d::BoxQuery) -> [Node] — Every collider whose bounds meet an axis-aligned box; cheaper and looser than shape_hits.
overlap_point(physics3d::PointQuery) -> [Node] — Every collider containing a world point.
overlap_shape(physics3d::ShapeQuery) -> [Node] — Every collider a shape overlaps where it stands: an explosion's reach, a melee arc.
overlaps(Node) -> [Node] collider3d The nodes this one currently intersects; rapier reports a pair only when one of the two colliders is a sensor.
pin_particle(Node, int) softbody3d Hold one particle where it is, which is how a cloth hangs from a hook.
pose_in_body(Node) -> physics3d::Pose? collider3d Where the collider sits in its body's frame; nothing for a collider with no body.
potential_energy(Node) -> float body3d The body's gravitational potential energy over one step.
predict_position(Node, float) -> physics3d::Pose body3d Where the body will be after dt seconds at its current velocity.
predict_position_with_forces(Node, float) -> physics3d::Pose body3d The same, with the forces already applied taken into account: where a thrust or a spring will have put it.
ragdoll(Node, physics3d::RagdollOptions?) -> [Node] — Build a 3D ragdoll from the rig under this node: a body and a shape per bone, held to its parent's by a ball socket whose zero is the pose the rig is in. Options: shape (capsule, box or sphere), thickness (the capsule's radius and the box's half width, as a fraction of bone length), density, friction, restitution, collision_layer and collision_mask (layer numbers) for the shapes; linear_damping, angular_damping, gravity_scale and continuous_collision for the bodies; axes (joint3d axes records, on rotation_x, rotation_y, rotation_z: twist and swing limits), articulation and collide_connected for the joints; drive (none, or motors: a position motor on every turn towards the built pose, of stiffness 100 and damping 20 unless given; or follow: a follow3d on every body towards its bone, so the bodies chase the clip, its keys in a follow table); influence; and parent, the node the bodies' container is kept under, the root unless given. Answers the body nodes it made.
raycast(physics3d::RayQuery) -> physics3d::Hit? — The first collider a ray meets, or nothing.
raycast_all(physics3d::RayQuery) -> [physics3d::Hit] — Every collider a ray meets, nearest first.
remove_joint(Node) joint3d Undo the node's joint, leaving both bodies free.
reset_follow(Node) follow3d Forget what a pid follow summed, so it pulls from now as if it had just started.
reset_plasticity(Node) softbody3d Undo every permanent set the body took: rest lengths, rest angles and rest shapes go back to how it was built, and it springs back from where it is.
reset_softbody_forces(Node) softbody3d Take back every force add_softbody_force and add_particle_force gave the body.
set_angular_velocity(Node, float, float, float) body3d Set how fast the body spins, in radians per second about each axis.
set_brake(Node, float) wheel3d How hard this wheel brakes, as an impulse; ignored while its engine force is not 0.
set_cell_tear_resistance(Node, int, float) softbody3d The same for one cell's tear strain.
set_constant_force(Node, float, float, float) body3d Replace the constant force with this one; zero stops the push.
set_constant_torque(Node, float, float, float) body3d Replace the constant torque with this one; zero stops the turn.
set_edge_tear_resistance(Node, int, float) softbody3d How many times the material's threshold one edge takes to tear; 1 is the material's.
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_heightfield_hole(Node, int, int, bool) collider3d Remove or restore the ground of one heightfield cell, named by the row and column of its first corner.
set_joint_limits(Node, string, float, float) joint3d Set how far one of the joint's free axes may travel, in radians about a rotation axis and units along a linear one; equal values lift the limit. Rewrites that axis's axes record.
set_linear_velocity(Node, float, float, float) body3d Set how fast the body travels, in units per second.
set_motor_position(Node, string, float, float, float) joint3d Drive one of the joint's free axes towards an angle or a distance, with a spring's stiffness and damping. Rewrites that axis's axes record.
set_motor_velocity(Node, string, float, float) joint3d Drive one of the joint's free axes towards a speed: how a wheel is powered or a door swings itself shut. Rewrites that axis's axes record.
set_particle_damaged(Node, int, bool) softbody3d Mark one particle as damaged or mend it: a damaged particle tears as an outside one does, which seeds where a crack starts.
set_particle_position(Node, int, Vec3) softbody3d Put one particle at at with no change of velocity.
set_particle_target(Node, int, Vec3) softbody3d Move a held particle to at over the next step, with the velocity that takes, which is how a cloth is dragged.
set_particle_velocity(Node, int, Vec3) softbody3d Set one particle's velocity; a held one keeps moving at it.
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.
set_voxel_size(Node, float, float, float) collider3d Resize every cell of a voxel collider, keeping which cells are filled.
set_wheel_rotation(Node, float) wheel3d Set how far the wheel has turned about its axle, in radians: the angle wheel_state reads as rotation.
shapecast(physics3d::ShapeQuery) -> physics3d::Hit? — 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.
softbody_attachments(Node) -> [physics3d::SoftAttachment] softbody3d Every particle tied to a rigid body.
softbody_boundary(Node) -> [[int]] softbody3d The body's surface as particle indices: segments in 2D, triangles in 3D.
softbody_cell(Node, int) -> physics3d::SoftCell softbody3d Everything one cell holds.
softbody_cells(Node) -> [[int]] softbody3d Every cell as its particle indices: triangles in 2D, tetrahedra in 3D.
softbody_center(Node) -> Vec3 softbody3d The centre of mass of the body and its pieces, which is where it is when a deformable body has no one position.
softbody_contacts(Node) -> physics3d::SoftContacts softbody3d What the body's surface touched in the last step.
softbody_crossing(Node, [Vec3]) -> physics3d::SoftCrossing softbody3d The edges and cells a blade meets, without cutting: the blade is a segment's two points in 2D, a triangle's three in 3D.
softbody_dihedral(Node, int) -> physics3d::SoftDihedral softbody3d Everything one hinge holds.
softbody_dihedrals(Node) -> [[int]] softbody3d Every bending hinge between two surface triangles, as four particle indices: the shared edge, then the two opposite particles.
softbody_edge(Node, int) -> physics3d::SoftEdge softbody3d Everything one edge holds.
softbody_edges(Node) -> [[int]] softbody3d Every edge as the two particle indices it joins, in the order softbody_stress reports them.
softbody_mass(Node) -> float softbody3d What the whole body weighs, every piece included.
softbody_particle(Node, int) -> physics3d::SoftParticle softbody3d Everything one particle holds.
softbody_particle_radius(Node) -> float softbody3d How thick the particles are: what was asked for, or what the layout worked out.
softbody_particles(Node) -> int softbody3d How many particles the body has, every piece torn off it included: a generator decides, not the author.
softbody_position(Node, int) -> Vec3 softbody3d Where one particle is, in world space.
softbody_rest_volume(Node) -> float softbody3d How much they enclose at rest.
softbody_sleeping(Node) -> bool softbody3d Whether the body has come to rest and stopped being simulated.
softbody_stress(Node) -> [float] softbody3d Each edge's load as a fraction of its tear threshold, smoothed over tear_smoothing: 0 slack, 1 tearing; the larger of its stretch over tear_strain and its force over tear_force, and 0 while neither is set.
softbody_velocity(Node, int) -> Vec3 softbody3d How fast one particle is moving, in world space.
softbody_volume(Node) -> float softbody3d How much space the body and every piece torn off it enclose right now, against softbody_rest_volume for how far it is squeezed.
softbody_volume_pieces(Node) -> [physics3d::SoftVolumePiece] softbody3d Each closed piece of the surface whose volume is held; an open sheet has none.
solve_ik(Node, float, float, float, physics3d::IkOptions?) joint3d Move a reduced-coordinates chain so its last link reaches a world position, leaving every joint inside its limits. Options: rotation (euler radians to turn the link to), constrain (the world axes to match: x, y, z, rotation_x, rotation_y, rotation_z; the translation by default, every axis when rotation is given), damping (1.0), iterations (10), tolerance (0.001).
swept_aabb(Node) -> [float] collider3d The box the collider covers over the next fixed step, from where it is to where its body's velocity and forces carry it.
tear_cell(Node, int) softbody3d Tear one cell at the end of the next step: a particle near its middle splits across its main stretch.
tear_edge(Node, int) softbody3d Tear one edge at the end of the next step.
tear_softbody(Node, [int], [int]) -> [physics3d::SoftTear] softbody3d Tear the given edges and cells at once; answers a record for each piece it changed, the one on_tear hears.
teleport(Node, float, float, float, physics3d::TeleportOptions?) 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. A rotation turns it too, in Euler radians.
time_of_impact(Node, Node, physics3d::ImpactOptions) -> physics3d::Impact? — When two moving colliders would meet, given each one's velocity. Nothing when they never do.
time_since_can_sleep(Node) -> float body3d Seconds the body has spent under its sleep thresholds; it sleeps once this reaches time_to_sleep.
total_inertia(Node) -> Vec3 body3d The body's resistance to spin about each of its principal axes, colliders included.
total_inertia_rotation(Node) -> Vec3 body3d How those principal axes are turned in the body's own space, as Euler radians, x first.
total_mass(Node) -> float body3d The body's total mass: its mass when it states one, or what its colliders weigh.
unpin_particle(Node, int) softbody3d Let a held particle go; it keeps the velocity it had.
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) -> Vec3 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] collider3d The cell a world position falls in, as three whole numbers.
voxel_size(Node) -> Vec3 collider3d How big one cell of a voxel collider is, along each axis.
wake_all() — Wake every sleeping body in the 3D world.
wake_softbody(Node) softbody3d Start simulating a resting body again.
wake_up(Node) body3d Wake the body, so the next step moves it.
wheel_state(Node) -> physics3d::WheelState wheel3d What the last step did with this wheel.
world_center_of_mass(Node) -> Vec3 body3d Where the body's whole mass sits, in world space.

Constants

name value
AXIS_NEGATIVE_X "-x"
AXIS_NEGATIVE_Y "-y"
AXIS_NEGATIVE_Z "-z"
AXIS_ROTATION_X "rotation_x"
AXIS_ROTATION_Y "rotation_y"
AXIS_ROTATION_Z "rotation_z"
AXIS_X "x"
AXIS_Y "y"
AXIS_Z "z"
BIND_CELLS "cells"
BIND_NEAREST "nearest"
BIND_PARTICLES "particles"
BODY_DYNAMIC "dynamic"
BODY_KINEMATIC "kinematic"
BODY_KINEMATIC_VELOCITY "kinematic_velocity"
BODY_STATIC "static"
CELL_COROTATIONAL "corotational"
CELL_NEO_HOOKEAN "neo_hookean"
CELL_VOLUME "volume"
COLLIDE_DYNAMIC_DYNAMIC "dynamic_dynamic"
COLLIDE_DYNAMIC_KINEMATIC "dynamic_kinematic"
COLLIDE_DYNAMIC_STATIC "dynamic_static"
COLLIDE_KINEMATIC_KINEMATIC "kinematic_kinematic"
COLLIDE_KINEMATIC_STATIC "kinematic_static"
COLLIDE_STATIC_STATIC "static_static"
COMBINE_AVERAGE "average"
COMBINE_CLAMPED_SUM "clamped_sum"
COMBINE_GEOMETRIC_MEAN "geometric_mean"
COMBINE_MAX "max"
COMBINE_MIN "min"
COMBINE_MULTIPLY "multiply"
DRIVE_FOLLOW "follow"
DRIVE_MOTORS "motors"
DRIVE_NONE "none"
EDGES_CHAIN "chain"
EDGES_MESH "mesh"
FILL_SOLID "solid"
FILL_SURFACE "surface"
FIT_AABB "aabb"
FIT_CONVEX_DECOMPOSITION "convex_decomposition"
FIT_CONVEX_HULL "convex_hull"
FIT_OBB "obb"
FLOW_BOTH "both"
FLOW_COMPRESSION "compression"
FLOW_TENSION "tension"
FOLLOW_PD "pd"
FOLLOW_PID "pid"
FRICTION_PER_CONTACT "per_contact"
FRICTION_SIMPLIFIED "simplified"
IGNORE_DYNAMIC "dynamic"
IGNORE_KINEMATIC "kinematic"
IGNORE_SENSORS "sensors"
IGNORE_SOLIDS "solids"
IGNORE_STATIC "static"
JOINT_BALL_SOCKET "ball_socket"
JOINT_BODY_DISABLED "body_disabled"
JOINT_DISABLED "disabled"
JOINT_ENABLED "enabled"
JOINT_FIXED "fixed"
JOINT_GENERIC "generic"
JOINT_HINGE "hinge"
JOINT_ROPE "rope"
JOINT_SLIDER "slider"
JOINT_SPRING "spring"
JOINT_WAITING "waiting"
LENGTHS_ABSOLUTE "absolute"
LENGTHS_RELATIVE "relative"
METHOD_VHACD "vhacd"
METHOD_VOXELS "voxels"
MOTOR_MODEL_ACCELERATION "acceleration"
MOTOR_MODEL_AUTO "auto"
MOTOR_MODEL_FORCE "force"
MOTOR_OFF "off"
MOTOR_POSITION "position"
MOTOR_VELOCITY "velocity"
ORIENTATION_AUTO "auto"
ORIENTATION_SHELL "shell"
ORIENTATION_SOLID "solid"
SHAPE_BOX "box"
SHAPE_CAPSULE "capsule"
SHAPE_CONE "cone"
SHAPE_CONVEX_DECOMPOSITION "convex_decomposition"
SHAPE_CONVEX_HULL "convex_hull"
SHAPE_CONVEX_MESH "convex_mesh"
SHAPE_CYLINDER "cylinder"
SHAPE_FIT "fit"
SHAPE_HEIGHTFIELD "heightfield"
SHAPE_MATCHING_AUTO "auto"
SHAPE_MATCHING_OFF "off"
SHAPE_MATCHING_ON "on"
SHAPE_POLYLINE "polyline"
SHAPE_SEGMENT "segment"
SHAPE_SPHERE "sphere"
SHAPE_TRIANGLE "triangle"
SHAPE_TRIANGLE_MESH "triangle_mesh"
SHAPE_VOXELIZED_MESH "voxelized_mesh"
SHAPE_VOXELIZED_POINTS "voxelized_points"
SHAPE_VOXELS "voxels"
SHAPE_WORLD_BOUNDARY "world_boundary"
SOFT_BOX "box"
SOFT_CLOTH "cloth"
SOFT_CLOTH_TUBE "cloth_tube"
SOFT_CUSTOM "custom"
SOFT_ROPE "rope"
SOFT_SOLVER_CONSTRAINTS "constraints"
SOFT_SOLVER_FEM "fem"
SOFT_SPHERE "sphere"
SOFT_TRIANGLE_MESH "triangle_mesh"
SOFT_VOLUMETRIC "volumetric"
SWEEP_CONVERGED "converged"
SWEEP_FAILED "failed"
SWEEP_OUT_OF_ITERATIONS "out_of_iterations"
SWEEP_PENETRATING "penetrating"
TENSION_ALL "all"
TENSION_LISTED "listed"
TENSION_NONE "none"
TEST_BOTH "both"
TEST_EITHER "either"

Are you sure?