hermeticormus/claude-code-game-development/physics-patterns

# Define collision layers as constants - never magic numbers
class_name PhysicsLayers
# Layer values: collision_layer and collision_mask use bitmasks
const WORLD: int        = 1 << 0  # Layer 1: Static geometry (terrain, walls)
const PLAYER: int       = 1 << 1  # Layer 2: Player character
const ENEMY: int        = 1 << 2  # Layer 3: Enemy characters
const PROJECTILE: int   = 1 << 3  # Layer 4: Bullets, arrows, spells
const PICKUP: int       = 1 << 4  # Layer 5: Collectible items
const TRIGGER: int      = 1 << 5  # Layer 6: Area3D triggers (checkpoints)
const VEHICLE: int      = 1 << 6  # Layer 7: Driveable objects
 
# Layer assignment table:
# Body Type          | collision_layer    | collision_mask
# Player             | PLAYER             | WORLD | ENEMY | PICKUP | TRIGGER
# Enemy              | ENEMY              | WORLD | PLAYER | PROJECTILE
# Projectile         | PROJECTILE         | WORLD | ENEMY (not PLAYER if friendly fire off)
# Pickup (Area3D)    | PICKUP             | PLAYER (only player can collect)
# Terrain (Static)   | WORLD              | 0 (statics don't need to detect anything)
 
# Usage:
# player_body.collision_layer = PhysicsLayers.PLAYER
# player_body.collision_mask = PhysicsLayers.WORLD | PhysicsLayers.ENEMY | PhysicsLayers.PICKUP

class_name PlatformerCharacter extends CharacterBody3D
const SPEED: float = 6.0
const JUMP_VELOCITY: float = 6.0
const GRAVITY: float = 20.0
const FALL_GRAVITY_MULTIPLIER: float = 2.0  # Fast fall on descent
const MAX_FALL_SPEED: float = -30.0
 
@export var floor_snap_length: float = 0.3  # Prevents bouncing on slopes
 
func _ready() -> void:
    # Floor snap prevents character bouncing when descending slopes
    motion_mode = CharacterBody3D.MOTION_MODE_GROUNDED
    floor_snap_length = 0.3
    floor_stop_on_slope = true
    floor_max_angle = deg_to_rad(46)  # Max walkable slope
 
func _physics_process(delta: float) -> void:
    _apply_gravity(delta)
    _handle_movement()
    move_and_slide()
    # move_and_slide() updates velocity for you after collisions
 
func _apply_gravity(delta: float) -> void:
    if is_on_floor():
        # Keep small downward velocity for slope snapping
        velocity.y = -0.1
    else:
        var grav := GRAVITY * delta
        if velocity.y < 0:
            grav *= FALL_GRAVITY_MULTIPLIER  # Faster fall = better game feel
        velocity.y = maxf(velocity.y - grav, MAX_FALL_SPEED)
 
func _handle_movement() -> void:
    var input := Input.get_axis(&"move_left", &"move_right")
    velocity.x = input * SPEED
 
func jump() -> void:
    if is_on_floor():
        velocity.y = JUMP_VELOCITY

# Physics-based destructible prop
class_name DestructibleProp extends RigidBody3D
@export var health: float = 30.0
@export var break_force_threshold: float = 10.0  # Newtons to break
@export var debris_scene: PackedScene
@export var break_sound: AudioStream
 
signal destroyed(position: Vector3)
 
func _ready() -> void:
    contact_monitor = true
    max_contacts_reported = 4
 
func _on_body_shape_entered(body_rid: RID, body: Node, body_shape_index: int, local_shape_index: int) -> void:
    var contact_velocity := linear_velocity.length()
    var impact_force := contact_velocity * mass
    if impact_force > break_force_threshold:
        _break(global_position)
 
func take_damage(amount: float) -> void:
    health -= amount
    if health <= 0.0:
        _break(global_position)
 
func _break(position: Vector3) -> void:
    destroyed.emit(position)
    if debris_scene:
        for i in 3:
            var debris := debris_scene.instantiate() as RigidBody3D
            get_parent().add_child(debris)
            debris.global_position = position + Vector3(randf_range(-0.3, 0.3), 0.2, randf_range(-0.3, 0.3))
            debris.apply_central_impulse(Vector3(randf_range(-2, 2), randf_range(1, 3), randf_range(-2, 2)))
    queue_free()

# Multiple raycast patterns for different use cases
class_name PhysicsQueries extends Node
 
# Single raycast - weapon hit detection
func raycast_hit(from: Vector3, to: Vector3, mask: int = 0b0111) -> Dictionary:
    var space := get_world_3d().direct_space_state
    var params := PhysicsRayQueryParameters3D.create(from, to, mask)
    params.hit_back_faces = false
    return space.intersect_ray(params)
 
# Sphere cast - area of effect check
func sphere_overlap(center: Vector3, radius: float, mask: int) -> Array[Dictionary]:
    var space := get_world_3d().direct_space_state
    var shape := SphereShape3D.new()
    shape.radius = radius
    var params := PhysicsShapeQueryParameters3D.new()
    params.shape = shape
    params.transform = Transform3D(Basis(), center)
    params.collision_mask = mask
    return space.intersect_shape(params)
 
# Ground check raycast
func is_grounded(body_position: Vector3, check_distance: float = 0.1) -> bool:
    var result := raycast_hit(
        body_position + Vector3.UP * 0.05,
        body_position + Vector3.DOWN * check_distance,
        PhysicsLayers.WORLD
    )
    return not result.is_empty()
 
# Line of sight check
func has_line_of_sight(from: Vector3, to: Vector3) -> bool:
    var result := raycast_hit(from, to, PhysicsLayers.WORLD)
    return result.is_empty()  # No hit = clear line of sight

# Flexible trigger volume for game events
class_name TriggerVolume extends Area3D
signal player_entered
signal player_exited
 
@export var trigger_once: bool = false
var _triggered: bool = false
 
func _ready() -> void:
    collision_layer = PhysicsLayers.TRIGGER
    collision_mask = PhysicsLayers.PLAYER
    body_entered.connect(_on_body_entered)
    body_exited.connect(_on_body_exited)
 
func _on_body_entered(body: Node3D) -> void:
    if _triggered and trigger_once:
        return
    if body.is_in_group(&"player"):
        _triggered = true
        player_entered.emit()
        if trigger_once:
            set_deferred(&"monitoring", false)
 
func _on_body_exited(body: Node3D) -> void:
    if body.is_in_group(&"player"):
        player_exited.emit()

# Hinged door using HingeJoint3D
class_name HingeDoor extends Node3D
@onready var door_body: RigidBody3D = $DoorBody
@onready var hinge: HingeJoint3D = $HingeJoint3D
 
@export var max_angle_degrees: float = 90.0
@export var damping: float = 0.5
 
func _ready() -> void:
    # HingeJoint3D connects door_body to a StaticBody3D frame
    hinge.set_flag(HingeJoint3D.FLAG_USE_LIMIT, true)
    hinge.set_param(HingeJoint3D.PARAM_LIMIT_LOWER, deg_to_rad(-max_angle_degrees))
    hinge.set_param(HingeJoint3D.PARAM_LIMIT_UPPER, deg_to_rad(max_angle_degrees))
    hinge.set_param(HingeJoint3D.PARAM_MOTOR_TARGET_VELOCITY, 0.0)
    hinge.set_param(HingeJoint3D.PARAM_MOTOR_MAX_IMPULSE, damping)
 
func open(direction: float = 1.0) -> void:
    door_body.apply_torque(door_body.global_transform.basis.y * direction * 100.0)