- name
>
SKILL.md
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill physics-tuning -a cursor -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill physics-tuning -a claude-code -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill physics-tuning -a codex -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill physics-tuning -a grok -ySend the copied message in a Grok Bot chat. The Bot fetches this SKILL.md from GitHub and adds it to the skills all your Bots share.
Install this skill: https://github.com/gamedev-skills/awesome-gamedev-agent-skills/tree/HEAD/skills/disciplines/physics-tuningFrom the publisher
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.
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).
[physics] in project.godot; Unity ProjectSettings/TimeManager.asset and
DynamicsManager.asset). Change one knob at a time._physics_process / FixedUpdate and use that step's dt.speed / tick_rate below the thinnest wall, or enable CCD on the
small fast bodies, or use a ray or shape cast for bullets.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.
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.
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
# 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.
# 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.
# 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.
ok.--fixed-fps 30 and --fixed-fps 144 on the player or a thrown body;
the positions must match.velocity writes and move_and_slide in _process / Update; move them
to the fixed step.--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.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.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.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.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.solver_iterations with no effect: that setting only affects GodotPhysics3D.
Jolt uses its own velocity_steps and position_steps (see the reference).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.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.Last verified: 2026-11-11.
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.Physics.SyncTransforms
after a direct write
(https://docs.unity.com/en-us/engine/6000.3/script-reference/unityengine/rigidbody/interpolation).© 2026 Skills Rack.
---name: physics-tuningdescription: >---# skills/disciplines/physics-tuning/SKILL.mdFAQ
Download skills/disciplines/physics-tuning/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
The publisher keeps it at https://github.com/gamedev-skills/awesome-gamedev-agent-skills.
Claude, Cursor, Codex, and Grok Build can read a SKILL.md you add from the publisher's repository. Grok Bot installs it when you send the skill's GitHub folder link in a chat.