gamedev-skills/awesome-gamedev-agent-skills

physics-tuning

Engine-neutral physics tuning with Godot checks: fixed timestep and interpolation, CCD against tunnelling, damping, solver iterations and collision layer matrices.

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill physics-tuning

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

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.

  1. Simulate in the fixed step. Forces, velocities and collision reads go in

_physics_process / FixedUpdate and use that step's dt.

  1. Interpolate rendering between ticks with the engine's built-in option before

hand-rolling it.

  1. 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.

  1. Tune the body, not the scene: mass for relative weight, damping for drag, gravity scale

per object, bounce and friction in a physics material.

  1. Stabilize stacks and joints with modest mass ratios, more solver iterations and sleeping.
  2. Plan the layer matrix as a named table: what each layer is, and what it scans.
  3. Run the checks below, then ask the user to judge feel with specific questions.

Patterns

1. Fixed step for simulation, interpolation for display

gdscript
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

gdscript
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

gdscript
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

gdscript
# 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)

gdscript
# 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

gdscript
# 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.

  1. Grep for forces, velocity writes and move_and_slide in _process / Update; move them

to the fixed step.

  1. 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).

来自同一仓库

更多 Skills

全部 Skills
gamedev-skills
社区

game-ui-ux

Engine-neutral design rules for game HUDs and menus: anchors and containers, scaling, safe areas, gamepad focus, HUDs driven by events instead of polling, and accessibility minimums. Use for menus, health bars or inventory screens that break on ultrawide or phones. Pair with godot-ui-control or roblox-ui. Not for button juice (game-feel) or rebinding (input-systems).

24小时安装量
433
GitHub Stars
1万
最近更新
11月12日
gamedev-skills
社区

game-feel

Adds engine-neutral juice to a working mechanic: trauma-based screen shake, hit-stop, eased tweens, squash and stretch, and knockback. Use when the game feels flat, weightless or not punchy, or hits and jumps should feel satisfying. Not for coyote time (platformer), input buffering (input-systems), camera follow (camera-systems) or HUD layout (game-ui-ux).

24小时安装量
431
GitHub Stars
1万
最近更新
11月12日
gamedev-skills
社区

create-game-assets

Plans, generates or sources, and validates consistent game art: style guides, sprites, pixel art, tilesets, icons and textures, with QA and licence records. Use when making or AI-generating game art, fixing fake transparency, or checking Steam AI disclosure. Not for engine import (godot-tilemap, godot-animation, unity-tilemap-2d), UI layout (game-ui-ux) or sound (audio-design).

24小时安装量
365
GitHub Stars
1万
最近更新
11月12日
gamedev-skills
社区

performance-optimization

Finds and fixes game frame-rate problems by measurement in Godot, Unity, Unreal or Roblox: CPU- vs GPU-bound, then the biggest fix (draw calls, pooling, GC spikes). Use for low FPS, stutter, a first-use hitch, or requests to optimize or profile. Not for build size (unity-build-size), physics jitter (physics-tuning) or network lag (roblox-networking, godot-multiplayer).

24小时安装量
360
GitHub Stars
1万
最近更新
11月12日