Claude-Code-Game-Studios/docs/engine-reference/godot/modules/physics.md

Godot Physics — Quick Reference

Last verified: 2026-02-12 | Engine: Godot 4.6

What Changed Since ~4.3 (LLM Cutoff)

4.6 Changes

• Jolt Physics is the DEFAULT 3D engine for new projects
  • Existing projects keep their current physics engine setting
  • Better determinism, stability, and performance than GodotPhysics3D
  • Some HingeJoint3D properties (damp) only work with GodotPhysics3D
  • 2D physics UNCHANGED (still Godot Physics 2D)

4.5 Changes

• 3D physics interpolation rearchitected: Moved from RenderingServer to SceneTree
  • User-facing API unchanged, but internal behavior may differ in edge cases

Physics Engine Selection (4.6)

Project Settings → Physics → 3D → Physics Engine:
- Jolt Physics (DEFAULT for new projects)
- GodotPhysics3D (legacy, still available)

Jolt vs GodotPhysics3D

Feature	Jolt (default)	GodotPhysics3D
Determinism	Better	Inconsistent
Stability	Better	Adequate
Performance	Better for complex scenes	Adequate
HingeJoint3D damp	NOT supported	Supported
Runtime warnings	Yes, for unsupported properties	No
Collision margins	May behave differently	Original behavior

Current API Patterns

Basic Physics Setup (unchanged)

# CharacterBody3D movement — API unchanged across engines
extends CharacterBody3D

@export var speed: float = 5.0
@export var jump_velocity: float = 4.5

func _physics_process(delta: float) -> void:
    if not is_on_floor():
        velocity += get_gravity() * delta

    if Input.is_action_just_pressed("jump") and is_on_floor():
        velocity.y = jump_velocity

    var input_dir: Vector2 = Input.get_vector("left", "right", "forward", "back")
    var direction: Vector3 = (transform.basis * Vector3(input_dir.x, 0, input_dir.y)).normalized()
    velocity.x = direction.x * speed
    velocity.z = direction.z * speed

    move_and_slide()

Raycasting (unchanged)

var space_state: PhysicsDirectSpaceState3D = get_world_3d().direct_space_state
var query := PhysicsRayQueryParameters3D.create(from, to)
query.collision_mask = collision_mask
var result: Dictionary = space_state.intersect_ray(query)
if result:
    var hit_point: Vector3 = result.position
    var hit_normal: Vector3 = result.normal

Common Mistakes

• Assuming GodotPhysics3D is the default (Jolt since 4.6)
• Using HingeJoint3D damp property without checking physics engine (Jolt ignores it)
• Not testing collision edge cases when switching between physics engines