physics-tuning Checked

# Physics callback: runs at the FIXED rate. Use its dt for all integration.
func _physics_process(dt):                  # Unity: void FixedUpdate()
    velocity += gravity * dt                # integrate with the FIXED dt
    move_and_slide()                        # engine resolves collisions this step
    _prev_pos = _curr_pos; _curr_pos = global_position   # record for interpolation

# Render frame: runs as fast as the display. Interpolate between physics states.
func _process(_frame_dt):                   # Unity: void Update()
    var alpha = Engine.get_physics_interpolation_fraction()  # 0..1 within the tick
    visual.global_position = _prev_pos.lerp(_curr_pos, alpha)
# RIGHT: integrate in the fixed step, render via interpolation.
# WRONG: applying forces in _process/Update with frame dt — speed and collisions
# then depend on frame rate and jitter under load.

Most engines offer this for you (Godot physics_interpolation/Rigidbody

interpolate; Unity Rigidbody.interpolation = Interpolate). Prefer the built-in

before hand-rolling.

### 2. Stop tunneling: CCD + a speed cap

# Fast, small bodies skip past thin colliders between ticks. Two fixes:
body.continuous_cd = true            # RigidBody3D bool (RigidBody2D: CCD_MODE_* enum). Unity: rb.collisionDetectionMode = Continuous
# Cap velocity so a single step can't move more than ~one collider thickness.
const MAX_SPEED := 40.0
if velocity.length() > MAX_SPEED:
    velocity = velocity.normalized() * MAX_SPEED
# Rule of thumb: max_distance_per_step (= speed / physics_hz) should be < the
# thinnest wall. Raise physics_hz or enable CCD when that fails.

### 3. Body tuning: mass, drag, gravity scale, material

# Mass is RELATIVE weight in collisions; it does NOT change fall speed (gravity
# accelerates all masses equally). Use drag and gravity_scale to shape feel.
body.mass = 2.0                      # heavier pushes lighter in collisions
body.linear_damp = 0.5               # air drag: higher = stops sooner (Unity: drag)
body.gravity_scale = 1.5             # per-object gravity multiplier (snappier fall)
# Bounce/slide come from the physics material, not code:
material.bounce = 0.2                # restitution 0..1 (Unity: bounciness)
material.friction = 0.8              # surface grip

### 4. Collision layers and masks (who collides with whom)

# A body is ON its layer(s) and SCANS the layers in its mask. Both directions of a
# pair must be configured for them to interact.
player.collision_layer = LAYER_PLAYER
player.collision_mask  = LAYER_WORLD | LAYER_ENEMY     # player detects world+enemies
pickup.collision_layer = LAYER_PICKUP
pickup.collision_mask  = LAYER_PLAYER                  # pickup only reacts to player
# Unity equivalent: assign GameObject layers and edit the Physics collision matrix
# (or Physics.IgnoreLayerCollision). Keep a named layer constant table, not magic numbers.

Pitfalls

• **Applying forces/movement in the render frame** (Update/_process) makes

behavior frame-rate dependent — faster PCs run faster, and collisions get

flaky. Do simulation in the fixed step.

• **Visible jitter** even with a fixed step usually means no render

interpolation: the physics rate and display rate beat against each other.

Enable interpolation.

• **Tunneling** through thin walls: discrete collision misses fast movers. Enable

CCD, cap speed, thicken walls, or raise the physics rate.

• **Expecting heavier objects to fall faster.** Gravity is acceleration; mass

affects collision response, not fall speed. Use gravity_scale/drag for feel.

• **Exploding stacks / jittery joints**: mass ratios too extreme, or too few

solver iterations. Keep mass ratios modest and raise iteration counts.

• **Bodies that never rest** burn CPU and twitch. Enable sleeping and a sensible

sleep threshold for resting objects.

• **One-directional layer setup**: A's mask includes B but B's mask excludes A.

Detection/collision can need both sides; verify the full matrix.

• **Huge dt spikes** (load hitches, breakpoints) blow up integration. Clamp the

max physics step / substep count so a stall doesn't launch everything.

References

• references/timestep-and-ccd.md — the fixed-timestep accumulator loop,

interpolation math, substepping, CCD modes, solver/iteration tuning, sleeping,

and a stability checklist.

Related skills

• godot-physics, unity-physics — concrete bodies, colliders, and callbacks.
• input-systems — responsive controls, jump buffering, coyote time.
• game-ai — agent movement that must agree with the physics step.
• platformer, fps-shooter — genres whose feel depends on this tuning.