Skip to content

gamedev-skills/awesome-gamedev-agent-skills / skills/disciplines/physics-tuning

physics-tuning

Verified

Engine-neutral physics tuning with Godot checks: fixed timestep and interpolation, CCD against tunnelling, damping, solver iterations and collision layer matrices. Use when bodies jitter, fast objects pass through walls or physics feels floaty or wrong. Not for engine physics APIs (`godot-physics`, `unity-physics`, `roblox-physics`, `phaser-arcade-physics`) or jump feel (`platformer`).

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

  1. Read the current settings first: tick rate, max steps per frame, interpolation, physics engine (Godot [physics] in project.godot; Unity ProjectSettings/TimeManager.asset and DynamicsManager.asset). Change one knob at a time.
  2. Simulate in the fixed step. Forces, velocities and collision reads go in _physics_process / FixedUpdate and use that step's dt.
  3. Interpolate rendering between ticks with the engine's built-in option before hand-rolling it.
  4. Stop tunnelling: keep speed / tick_rate below the thinnest wall, or enable CCD on the small fast bodies, or use a ray or shape cast for bullets.
  5. Tune the body, not the scene: mass for relative weight, damping for drag, gravity scale per object, bounce and friction in a physics material.
  6. Stabilize stacks and joints with modest mass ratios, more solver iterations and sleeping.
  7. Plan the layer matrix as a named table: what each layer is, and what it scans.
  8. 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 = material

4. 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 player

Write 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

  1. Run the tunnel test with the game's fastest body and thinnest wall; it must print ok.
  2. Run the rate probe at --fixed-fps 30 and --fixed-fps 144 on the player or a thrown body; the positions must match.
  3. Grep for forces, velocity writes and move_and_slide in _process / Update; move them to the fixed step.
  4. 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_SHAPE did 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, while CCD_MODE_CAST_RAY stopped 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 dt after a hitch launches bodies. Clamp steps per frame (Godot physics/common/max_physics_steps_per_frame, default 8; Unity Maximum Allowed Timestep). The price is slow motion below tick_rate / max_steps FPS.
  • 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 direct transform write unless it is followed by Physics.SyncTransforms(); move the Rigidbody instead.
  • Feel changes after raising the tick rate: Godot (GodotPhysics and Jolt alike) damps by multiplying velocity by 1 - damp * step each tick, clamped at 0, so large damping values behave differently at another tick rate. Re-tune them after changing physics_ticks_per_second.
  • Raising Godot solver_iterations with no effect: that setting only affects GodotPhysics3D. Jolt uses its own velocity_steps and position_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 is velocity *= max(1 - damp * step, 0) in both modules/jolt_physics/objects/jolt_body_3d.cpp and modules/godot_physics_3d/godot_body_3d.cpp at 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.SyncTransforms after a direct write (https://docs.unity.com/en-us/engine/6000.3/script-reference/unityengine/rigidbody/interpolation).
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall