physics-patterns

Physics Patterns

Collision Layer Configuration

# 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

CharacterBody3D Controller (Full Featured)

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