Skip to content

Search

Documentation

body3d component

A 3D rigid body simulated by rapier. kind is dynamic, static, kinematic or kinematic_velocity; add a collider3d for its shape.

本页内容

3d · physics · 25 properties · 3D

A 3D rigid body simulated by rapier. kind is dynamic, static, kinematic or kinematic_velocity; add a collider3d for its shape.

In a scene, body3d is the node key that applies it. A script reaches each property below as a field on node.body3d: reading one asks the running component, and assigning one leaves the rest alone. The whole table is node.body3d.get() and node.body3d.set(table).

Properties

property type default description
allow_fast_rotation bool false Allow a spin fast enough that rapier would otherwise clamp it
angular_damping float 0 Drag on spin, in the same terms as linear_damping At least 0.
can_sleep bool true Let the body stop being simulated once it has held still
center_of_mass vec3 [0,0,0] Where the extra mass sits, in the node's own space; only read when mass is set
continuous_collision bool false Also sweep moving bodies: a fast dynamic body sweeps static colliders without this, and this adds kinematic and dynamic ones
dominance int 0 A body in a higher group is unpushable by a lower one; a kinematic body keeps its own group, and only a static body outranks every group Range -128–127.
enabled bool true Simulate this body at all; a disabled body keeps its state and costs nothing
gravity_scale float 1 Multiplier on world gravity for this body: 0 hangs in the air, negative floats up
gyroscopic_forces bool false Model the wobble a spinning body's own inertia gives it, as a thrown American football has
inertia vec3 [0,0,0] Resistance to spin about each axis, read when mass is set; 0 derives it from the colliders' shapes scaled to the mass, about center_of_mass when that is set
inertia_rotation vec3 [0,0,0] Turns the axes inertia is measured about, x first; read with a non-zero inertia. Euler radians in the file
initial_angular_velocity vec3 [0,0,0] How fast the body spins when it is made, about each axis; radians per second in the file, and a later patch does not reapply it
initial_linear_velocity vec3 [0,0,0] How fast the body travels when it is made, in units per second; a later patch does not reapply it
internal_iterations int 0 Extra Gauss-Seidel iterations inside each substep for the island this body is in; the island runs the largest any of its bodies asks At least 0.
kind enum dynamic How physics drives the node: simulated, immovable, moved by script, or moved by a velocity you set One of dynamic, static, kinematic, kinematic_velocity.
linear_damping float 0 Drag on travel: how fast the body loses speed with nothing touching it At least 0.
lock_rotation flags [] World axes the body may not turn about; locking all three keeps a character upright One of x, y, z.
lock_translation flags [] World axes the body may not move along One of x, y, z.
mass float 0 The body's total mass; 0 sums what its colliders weigh At least 0.
sleep_angular_threshold float 0.5 The spin below which a body with no collider counts as still; radians per second in the file At least 0.
sleep_threshold float 0.05 The speed of the body's farthest point below which it counts as still, in length units per second scaled by [physics] length_unit At least 0.
solver_iterations int 0 Extra solver substeps for the whole island this body is in, joints and contacts together: everything it touches pays for them At least 0.
speculative_distance float 0 Distance ahead the body predicts contacts, in units; cheaper than ccd for merely fast bodies At least 0.
start_asleep bool false Make the body asleep, with no velocity, until something wakes it; read once, when the body is made
time_to_sleep float 0.5 Seconds of stillness before the body sleeps At least 0.

Script functions

Methods of node.body3d, the handle a node carrying this component exposes. Every handle also has get(), set(table), patch(table), has() and remove().

From physics3d:

method what it does
add_constant_force(float, float, float) 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(float, float, float, float, float, float) Push at a world point every step, which also turns the body.
add_constant_torque(float, float, float) Turn the body every step until the constant torque is set back to zero.
angular_velocity() -> float, float, float How fast the body is spinning, in radians per second about each axis.
apply_force(float, float, float) Push the body for the next step only; add_constant_force keeps pushing.
apply_force_at_point(float, float, float, float, float, float) Push at a world point for the next step only, which also turns the body.
apply_impulse(float, float, float) Add an instant change in momentum, as if the body were struck.
apply_impulse_at_point(float, float, float, float, float, float) Strike the body at a world point, which spins it as well as moves it.
apply_torque(float, float, float) Turn the body for the next step only; add_constant_torque keeps turning it.
apply_torque_impulse(float, float, float) Add an instant change in angular momentum, as if the body were spun.
constant_force() -> float, float, float The force every step integrates until it is set back to zero.
constant_torque() -> float, float, float The torque every step integrates until it is set back to zero.
effective_angular_inertia() -> any The world-space inertia the solver turns, rotation locks applied, as its three rows.
effective_dominance() -> float The dominance rapier will use for this body: its own group, or the rank every non-dynamic body outranks with.
effective_mass() -> any The mass the solver pushes against along each world axis: zero along a locked axis, and on any body that is not dynamic.
is_ccd_active() -> bool Whether the body moved fast enough last step for rapier to sweep it, with or without continuous_collision.
is_moving() -> bool Whether the body is awake and actually going somewhere.
is_sleeping() -> bool Whether the body is asleep and being skipped.
kinetic_energy() -> float The body's kinetic energy, for a rest test the solver agrees with.
linear_velocity() -> float, float, float How fast the body is travelling, in units per second.
local_center_of_mass() -> any Where the body's whole mass sits, in the body's own space.
next_position() -> any The pose a kinematic body has been told to move to, as #{ position, rotation }.
potential_energy() -> float The body's gravitational potential energy over one step.
predict_position(float) -> any Where the body will be after dt seconds at its current velocity, as #{ position, rotation }.
predict_position_with_forces(float) -> any The same, with the forces already applied taken into account: where a thrust or a spring will have put it.
set_angular_velocity(float, float, float) Set how fast the body spins, in radians per second about each axis.
set_constant_force(float, float, float) Replace the constant force with this one; zero stops the push.
set_constant_torque(float, float, float) Replace the constant torque with this one; zero stops the turn.
set_linear_velocity(float, float, float) Set how fast the body travels, in units per second.
sleep() Put the body to sleep now.
teleport(float, float, float, any?) 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. #{ rotation = [x, y, z] } turns it too, in Euler radians.
time_since_can_sleep() -> float Seconds the body has spent under its sleep thresholds; it sleeps once this reaches time_to_sleep.
total_inertia() -> any The body's resistance to spin about each of its principal axes, colliders included.
total_inertia_rotation() -> any How those principal axes are turned in the body's own space, as Euler radians, x first.
total_mass() -> float The body's total mass: its mass when it states one, or what its colliders weigh.
velocity_at_point(float, float, float) -> float, float, float How fast a world point on the body is moving, spin included.
wake_up() Wake the body, so the next step moves it.
world_center_of_mass() -> any Where the body's whole mass sits, in world space.