Physics tuning
Most "bad physics" is a mismatch between the fixed-rate simulation and the variable-rate render
loop, or untuned CCD, mass, damping and layer settings. This skill owns those engine-neutral
decisions and the checks that prove them. The engine's bodies, callbacks and settings come from
godot-physics, unity-physics or roblox-physics; load both when tuning inside an engine.
When to use
- Motion jitters, bodies tunnel through walls, stacks explode, joints shake, or speed depends on frame rate.
- Deciding what runs in the fixed step and what in the render frame, and how to interpolate.
- Tuning gravity, mass, damping, restitution, solver iterations, sleeping and the layer matrix.
Not this skill: engine API (godot-physics, unity-physics, roblox-physics), character
controller code (godot-2d-movement), jump arcs and forgiveness windows (platformer), camera
smoothing (camera-systems), CPU cost of the simulation (performance-optimization).
Core workflow
- Read the current settings first: tick rate, max steps per frame, interpolation, physics
engine (Godot
[physics]inproject.godot; UnityProjectSettings/TimeManager.assetandDynamicsManager.asset). Change one knob at a time. - Simulate in the fixed step. Forces, velocities and collision reads go in
_physics_process/FixedUpdateand use that step'sdt. - Interpolate rendering between ticks with the engine's built-in option before hand-rolling it.
- Stop tunnelling: keep
speed / tick_ratebelow the thinnest wall, or enable CCD on the small fast bodies, or use a ray or shape cast for bullets. - Tune the body, not the scene: mass for relative weight, damping for drag, gravity scale per object, bounce and friction in a physics material.
- Stabilize stacks and joints with modest mass ratios, more solver iterations and sleeping.
- Plan the layer matrix as a named table: what each layer is, and what it scans.
- Run the checks below, then ask the user to judge feel with specific questions.
Patterns
1. Fixed step for simulation, interpolation for display
func _physics_process(dt): # Unity: FixedUpdate()
velocity += gravity * dt # integrate with the FIXED dt
move_and_slide()
# WRONG: forces or movement in _process/Update with the frame dt: speed and collisions then
# depend on frame rate.Turn on the built-in interpolation: Godot physics/common/physics_interpolation = true (off by
default; it covers 2D and 3D nodes), Unity Rigidbody.interpolation = Interpolate on the player
and the bodies the camera follows. Hand-roll (Engine.get_physics_interpolation_fraction(),
lerp previous to current) only for something the engine does not cover, and never both on one
node.
2. Tunnelling: CCD and a speed cap
body.continuous_cd = true # RigidBody3D: a bool
body2d.continuous_cd = RigidBody2D.CCD_MODE_CAST_RAY # RigidBody2D: an enum; see Gotchas
# Unity: CollisionDetectionMode.ContinuousSpeculative (cheap, covers dynamic bodies) or
# ContinuousDynamic (fast vs fast). Plain Continuous only sweeps against static colliders.
const MAX_SPEED := 40.0
if velocity.length() > MAX_SPEED:
velocity = velocity.normalized() * MAX_SPEED
# Rule of thumb: speed / ticks_per_second < thinnest wall, or CCD, or a ray cast.3. Body tuning
body.mass = 2.0 # relative weight in collisions; does not change fall speed
body.linear_damp = 0.5 # drag (Unity 6: linearDamping, formerly drag)
body.gravity_scale = 1.5 # per-object gravity (Unity: Rigidbody2D.gravityScale)
var material := PhysicsMaterial.new()
material.bounce = 0.2 # restitution 0..1 (Unity: PhysicsMaterial.bounciness)
material.friction = 0.8
body.physics_material_override = material4. Collision layer matrix as data
# A body is ON its layers and SCANS its mask. Name the bits once and build masks from names.
const LAYER := { "world": 1 << 0, "player": 1 << 1, "enemy": 1 << 2, "pickup": 1 << 3 }
player.collision_layer = LAYER.player
player.collision_mask = LAYER.world | LAYER.enemy
pickup.collision_layer = LAYER.pickup
pickup.collision_mask = LAYER.player # the pickup only reacts to the playerWrite the same table into the engine's layer names (Godot [layer_names] in project.godot;
Unity's Physics collision matrix) so the editor and code agree.
5. Tunnel test (headless, exits 1 on failure)
# tools/tunnel_test.gd: godot --headless --path . --script res://tools/tunnel_test.gd
# Fires a small fast body at a thin wall; exits 1 if it ends up on the far side.
extends SceneTree
const SPEED := 3000.0 # px/s: the fastest body in the game
const WALL := 4.0 # px: the thinnest wall it must not cross
const RADIUS := 4.0 # px: that body's collision radius
const MODE := RigidBody2D.CCD_MODE_CAST_RAY # the CCD mode the game uses
func _initialize() -> void:
var wall := StaticBody2D.new()
var wall_shape := CollisionShape2D.new()
wall_shape.shape = RectangleShape2D.new()
wall_shape.shape.size = Vector2(WALL, 400)
wall.add_child(wall_shape)
wall.position = Vector2(500, 0)
root.add_child(wall)
var body := RigidBody2D.new()
var shape := CollisionShape2D.new()
shape.shape = CircleShape2D.new()
shape.shape.radius = RADIUS
body.add_child(shape)
body.gravity_scale = 0.0
body.continuous_cd = MODE
body.position = Vector2(23, 0) # not a multiple of the step distance
body.linear_velocity = Vector2(SPEED, 0)
root.add_child(body)
for i in 60:
await physics_frame
var crossed := body.position.x > wall.position.x
print("TUNNEL mode=%d x=%.1f %s" % [MODE, body.position.x, "FAIL: crossed" if crossed else "ok"])
quit(1 if crossed else 0)Set the constants to the game's fastest body and thinnest wall. For 3D, use RigidBody3D with
continuous_cd = true, BoxShape3D and SphereShape3D; that passed here on both GodotPhysics3D
and Jolt.
6. Frame-rate independence probe
# tools/rate_probe.gd: print a node's position after 2 s of game time. Run at two frame rates:
# godot --headless --path . --fixed-fps 30 --script res://tools/rate_probe.gd -- res://main.tscn Player
# godot --headless --path . --fixed-fps 144 --script res://tools/rate_probe.gd -- res://main.tscn Player
extends SceneTree
func _initialize() -> void:
var args := OS.get_cmdline_user_args()
var scene: Node = load(args[0]).instantiate()
root.add_child(scene)
var target: Node = scene.get_node(args[1]) if args.size() > 1 else scene
for i in Engine.physics_ticks_per_second * 2: # 2 s of simulated time at any frame rate
await physics_frame
print("RATE position=%s" % [target.position])
quit(0)Movement done in the physics step prints the same position at both rates. A falling body moved
in _process landed about 23 px apart after 2 s at 30 and 144 FPS in a test here, while the
same code in _physics_process matched to the last digit. Any difference means simulation code
is reading the frame dt.
Check it
- Run the tunnel test with the game's fastest body and thinnest wall; it must print
ok. - Run the rate probe at
--fixed-fps 30and--fixed-fps 144on the player or a thrown body; the positions must match. - Grep for forces,
velocitywrites andmove_and_slidein_process/Update; move them to the fixed step. - Ask the user to play at a capped low frame rate and at an uncapped high one (Godot
--max-fps 30, then--disable-vsync), throw the fastest object at the thinnest wall, stack ten crates and push them, and report any jitter, pass-through or explosion, and whether the motion feels floaty or heavy. Feel is their call; the numbers above are yours.
Gotchas
- Jitter even with a fixed step usually means no render interpolation: the physics and display rates beat against each other.
- Godot 2D
CCD_MODE_CAST_SHAPEdid not stop tunnelling in a 4.7.2 GodotPhysics2D test: a 4 px circle at 600-6000 px/s crossed a 4 px wall exactly as with CCD off, whileCCD_MODE_CAST_RAYstopped it every time. Use the ray mode and prove it with the tunnel test. - Discrete collision pushes a body out the far side once its centre passes the middle of a thin wall in one step, so it tunnels even at speeds where the shapes do overlap.
- Expecting heavier objects to fall faster. Gravity is an acceleration; mass changes collision response. Shape feel with gravity scale and damping.
- Exploding stacks and jittery joints: extreme mass ratios (keep within about 1:10) or too few solver iterations.
- Bodies that never sleep burn CPU and twitch. Enable sleeping and check the thresholds.
- One-sided layer setup: A scans B but B does not scan A. Check both directions of the matrix.
- Huge
dtafter a hitch launches bodies. Clamp steps per frame (Godotphysics/common/max_physics_steps_per_frame, default 8; Unity Maximum Allowed Timestep). The price is slow motion belowtick_rate / max_stepsFPS. - Teleports smear across the screen with interpolation on. Godot: call
reset_physics_interpolation()after moving the node. Unity: with interpolation on, the physics system owns the transform and ignores a directtransformwrite unless it is followed byPhysics.SyncTransforms(); move the Rigidbody instead. - Feel changes after raising the tick rate: Godot (GodotPhysics and Jolt alike) damps by
multiplying velocity by
1 - damp * stepeach tick, clamped at 0, so large damping values behave differently at another tick rate. Re-tune them after changingphysics_ticks_per_second. - Raising Godot
solver_iterationswith no effect: that setting only affects GodotPhysics3D. Jolt uses its ownvelocity_stepsandposition_steps(see the reference).
References
references/timestep-and-ccd.md: read when you need the accumulator loop and the clamp trade-off, interpolation maths and teleport resets, substepping, CCD modes per engine, solver iterations (including Jolt's settings), sleeping, or the stability checklist.
Related skills
godot-physics,unity-physics,roblox-physics: engine bodies, colliders and callbacks.platformer: jump arcs, coyote time and jump buffering on top of this tuning.camera-systems: following an interpolated body without jitter.performance-optimization: when the physics step itself is too slow.
Version notes
Last verified: 2026-11-11.
- Godot 4.7:
physics/common/physics_interpolation(default false),max_physics_steps_per_frame(default 8),physics_ticks_per_second(default 60); damping isvelocity *= max(1 - damp * step, 0)in bothmodules/jolt_physics/objects/jolt_body_3d.cppandmodules/godot_physics_3d/godot_body_3d.cppat the 4.7-stable tag. - The tunnel test, the CCD mode results and the rate probe were run on Godot 4.7.2 headless.
- Unity 6.3: interpolation takes control of the transform and needs
Physics.SyncTransformsafter a direct write (https://docs.unity.com/en-us/engine/6000.3/script-reference/unityengine/rigidbody/interpolation).