You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The physics module is how gameplay both drives and interrogates the physics
world. On the driving side it moves character bodies (move_and_slide,
apply_gravity) and pushes rigid bodies with forces and impulses. On the query
side it casts rays and shapes for line-of-sight, ground checks, and hit-scan
weapons, and reports contacts. It also carries trajectory solvers for aiming
lobbed projectiles and global/per-body gravity controls. Both 2D and 3D
variants exist for every core operation.
Character-body helpers keep you out of the raw solver: move_and_slide sweeps a
motion vector and slides along walls, while apply_gravity integrates fall
speed and reports grounding — you supply intent, the engine handles the sweep.
Use Cases
Platformer / character controller: slide along walls with physics_move_and_slide_3d!(ctx.run, body, motion) and fall with grounding via physics_apply_gravity_3d!(ctx.run, body, dt).
Hit-scan weapon or AI line-of-sight: ctx.run.Physics().raycast_3d(origin, dir, max_distance) returns the first PhysicsRayHit3D.
Knockback, jump impulse, explosion push: apply_impulse!(ctx.run, body, impulse) for an instant kick, apply_force! for sustained force (both dispatch to 2D or 3D by the vector type).
Ground / ledge / wall probe: a short raycast or shape_cast_3d in the desired direction.
Aim a grenade or basketball arc: ctx.run.Physics().solve_launch_velocity_3d(...) (or solve_velocity_to_target_3d) computes the throw velocity; predict_body_3d previews the path.
Floaty jumps or a low-gravity zone: ctx.run.Physics().set_body_gravity_scale(body, 0.5).
Pause the simulation for a menu or cutscene: physics_pause!(ctx.run, true).
React to collisions: read physics_contacts_3d!(ctx.run, body) and respond (damage, bounce, stick).
Context
Script context path: ctx.run
Module access: ctx.run.Physics()
Lifecycle examples stay inside lifecycle! because script hooks get API from the macro expansion.
Practical Example
A side-scroller character controller: read held movement input, slide the body
horizontally, and let engine gravity handle falling and landing. on_jump fires
an upward impulse when the jump action is pressed.
lifecycle!({fn on_update(&self, ctx:&mutScriptContext<'_,API>){// Clamp so a frame spike cannot fling the body through a wall.let dt = delta_time_capped!(ctx.run,0.1);letmut motion = Vector3::ZERO;if action_down!(ctx.ipt,"move_right"){
motion.x += 6.0* dt;}if action_down!(ctx.ipt,"move_left"){
motion.x -= 6.0* dt;}// Slide along walls instead of stopping dead on contact.
physics_move_and_slide_3d!(ctx.run, ctx.id, motion);// Engine gravity + ground detection, run separately from the slide.let _ = physics_apply_gravity_3d!(ctx.run, ctx.id, dt);if action_pressed!(ctx.ipt,"jump"){
apply_impulse!(ctx.run, ctx.id,Vector3::new(0.0,8.0,0.0));}}});
Set local gravity multiplier for RigidBody2D or RigidBody3D.
Fails when / edge behavior
Returns false when node is missing, not a rigid body, or scale is not finite. Effective gravity is world gravity * physics coefficient * gravity_scale.
get_coefficient
Field
Detail
Access
ctx.run.Physics()
Signature
pub fn get_coefficient(&mut self) -> f32
Params
&mut self
Returns
f32
Use when
Use get_coefficient to get coefficient in the physics world; reads are snapshots and force/state calls affect runtime bodies.
Fails when / edge behavior
Has no optional/error return; get_coefficient returns the documented value directly.
Move a physics body toward a target position without clipping through blocking colliders.
Fails when / edge behavior
Syncs current physics bodies, sweeps attached body colliders, excludes the moving body, writes the safe global position, and returns hit/clipped state. Does not clear velocity.
Move a physics body toward a target position without clipping through blocking colliders.
Fails when / edge behavior
Syncs current physics bodies, sweeps attached body colliders, excludes the moving body, writes the safe global position, and returns hit/clipped state. Does not clear velocity.
Move a character-style body by a motion vector, sliding along hit surfaces instead of stopping.
Fails when / edge behavior
Sweeps up to 4 slide iterations, projecting unconsumed motion onto each hit plane. Writes the safe global position. remainder holds motion still blocked (e.g. cornered). hits lists each clipped iteration in order.
Move a character-style body by a motion vector, sliding along hit surfaces instead of stopping.
Fails when / edge behavior
Sweeps up to 4 slide iterations, projecting unconsumed motion onto each hit plane. Writes the safe global position. remainder holds motion still blocked (e.g. cornered). hits lists each clipped iteration in order.
Script wants engine gravity on a character body without owning the fall-speed integration. Call once per update; separate from move_and_slide.
Fails when / edge behavior
Character bodies only — returns None for other body types or non-positive dt. Integrates an internal fall speed from world gravity (physics_set_gravity respected), clamps to max_fall_speed, sweeps down, resets fall speed on landing. clipped == true in the result means grounded.
Script wants engine gravity on a character body without owning the fall-speed integration. Call once per update; separate from move_and_slide.
Fails when / edge behavior
Character bodies only — returns None for other body types or non-positive dt. Integrates an internal fall speed from world gravity (physics_set_gravity respected), clamps to max_fall_speed, sweeps down, resets fall speed on landing. clipped == true in the result means grounded.
Use physics_solve_velocity_to_target_2d to physics solve velocity to target 2d in the physics world; queries return a snapshot while setters/forces mutate runtime body state.
Fails when / edge behavior
Uses the backing physics_solve_velocity_to_target_2d return and failure behavior unchanged; the wrapper adds no coercion or fallback.
Use physics_solve_velocity_to_target_3d to physics solve velocity to target 3d in the physics world; queries return a snapshot while setters/forces mutate runtime body state.
Fails when / edge behavior
Uses the backing physics_solve_velocity_to_target_3d return and failure behavior unchanged; the wrapper adds no coercion or fallback.
Use physics_solve_launch_velocity_2d to physics solve launch velocity 2d in the physics world; queries return a snapshot while setters/forces mutate runtime body state.
Fails when / edge behavior
Uses the backing physics_solve_launch_velocity_2d return and failure behavior unchanged; the wrapper adds no coercion or fallback.
Use physics_solve_launch_velocity_3d to physics solve launch velocity 3d in the physics world; queries return a snapshot while setters/forces mutate runtime body state.
Fails when / edge behavior
Uses the backing physics_solve_launch_velocity_3d return and failure behavior unchanged; the wrapper adds no coercion or fallback.
physics_predict_body_2d
Field
Detail
Access
ctx.run.Physics()
Signature
physics_predict_body_2d!(ctx.run, body_id, time)
Params
ctx, body_id, time
Returns
same as backing method
Use when
Use physics_predict_body_2d to physics predict body 2d in the physics world; queries return a snapshot while setters/forces mutate runtime body state.
Fails when / edge behavior
Uses the backing physics_predict_body_2d return and failure behavior unchanged; the wrapper adds no coercion or fallback.
physics_predict_body_3d
Field
Detail
Access
ctx.run.Physics()
Signature
physics_predict_body_3d!(ctx.run, body_id, time)
Params
ctx, body_id, time
Returns
same as backing method
Use when
Use physics_predict_body_3d to physics predict body 3d in the physics world; queries return a snapshot while setters/forces mutate runtime body state.
Fails when / edge behavior
Uses the backing physics_predict_body_3d return and failure behavior unchanged; the wrapper adds no coercion or fallback.
apply_impulse
Field
Detail
Access
ctx.run.Physics()
Signature
apply_impulse!(ctx.run, body_id, impulse)
Params
ctx, body_id, impulse
Returns
same as backing method
Use when
Use apply_impulse to apply impulse in the physics world; reads are snapshots and force/state calls affect runtime bodies.
Fails when / edge behavior
Uses the backing apply_impulse return and failure behavior unchanged; the wrapper adds no coercion or fallback.
Use physics_raycast_3d_with_areas to physics raycast 3d with areas in the physics world; queries return a snapshot while setters/forces mutate runtime body state.
Fails when / edge behavior
Uses the backing physics_raycast_3d_with_areas return and failure behavior unchanged; the wrapper adds no coercion or fallback.
Use physics_raycast_3d_without_areas to physics raycast 3d without areas in the physics world; queries return a snapshot while setters/forces mutate runtime body state.
Fails when / edge behavior
Uses the backing physics_raycast_3d_without_areas return and failure behavior unchanged; the wrapper adds no coercion or fallback.