godot-camera-systems

Files (15)

• SKILL.md
• camera_follow_2d.gd · scripts/
• camera_shake_trauma.gd · scripts/
• camera_shake_trauma_pro.gd · scripts/
• camera_state_machine.gd · scripts/
• cinematic_framing_logic.gd · scripts/
• deadzone_drag_margins.gd · scripts/
• first_person_sway.gd · scripts/
• juice_camera.gd · scripts/
• minimap_viewport_manager.gd · scripts/
• phantom_decoupling.gd · scripts/
• remote_transform_decoupling.gd · scripts/
• split_screen_setup.gd · scripts/
• spring_lerp_camera_3d.gd · scripts/
• zoom_damping_controller.gd · scripts/

SKILL.md (first lines)

## Godot 4.7 Baseline

- Expert patterns in this skill target **Godot 4.7+** (stable, 2026-06-18).
- Consult the [Godot 4.7 migration guide](https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.7.html) when upgrading projects from 4.6.
- **NEVER** assume 4.6 defaults (stretch mode, audio area_mask, RichTextLabel percent flags) without checking 4.7 migration notes.

# Camera Systems

Expert guidance for creating smooth, responsive cameras in 2D and 3D games.

## NEVER Do

- **NEVER use `global_position = target.global_position` every frame** — Instant position matching causes jittery movement. Use `lerp()` or `position_smoothing_enabled = true` [12].
- **NEVER use `offset` for permanent camera positioning** — `offset` is for shake, sway, or temporary recoil effects only. Use `position` for permanent framing to avoid logic conflicts [14].
- **NEVER forget `limit_smoothed = true` for `Camera2D`** — Hard boundaries cause jarring visual stops. Smoothing against limits ensures a professional feel [13].
- **NEVER enable multiple `Camera2D` nodes in the same viewport simultaneously** — Only the last enabled camera takes precedence. Explicitly disable inactive cameras [15].
- **NEVER use `SpringArm3D` without a collision mask** — It will clip through terrain and walls. Set it to the world/environment layer [16].
- **NEVER implement screen shake by randomizing `position` directly** — This overwrites follow-logic. Use `offset` or a dedicated Trauma/Noise system to Layer shake over the follow-position [27, 28].
- **NEVER parent the Camera directly to a high-speed physics body** — Physics stutter or parent rotation will cause motion sickness. Use `RemoteTransform2D/3D` with rotation sync disabled for a stable view [30].
- **NEVER use `look_at()` in 3D without a fallback for the 'Up' vector** — If the target is directly above/below, the camera will flip wildly. Use guards or `Quaternion` math for vertical tracking.
- **NEVER rely on `SubViewport` defaults for Mini-maps** — Viewports are expensive; explicitly set `render_target_update_mode` to `UPDATE_WHEN_VISIBLE` or a fixed lower framerate to save GPU [156].
- **NEVER use linear interpolation for Zoom** — It feels 'robotic'. Use exponential lerp or a `Tween` with `TRANS_CUBIC` for a more natural tactical feel.

---

## Available Scripts

> **MANDATORY**: Read before implementing camera behaviors.

### [camera_shake_trauma_pro.gd](scripts/camera_shake_trauma_pro.gd)
Advanced noise-based screenshake (Trauma system) for organic, non-jittery explosions and impacts.

### [cinematic_framing_logic.gd](scripts/cinematic_framing_logic.gd)
Rule of Thirds and Lead Room management in code, ensuring high-quality cinematic composition.

### [camera_state_machine.gd](scripts/camera_state_machine.gd)
Managing transitions between 'Follow', 'Static', and 'Cinematic' camera states with Tweens.

### [minimap_viewport_manager.gd](scripts/minimap_viewport_manager.gd)
SubViewport optimization for Mini-maps and UI overlays. Reduces render updates for better FPS.

### [split_screen_setup.gd](scripts/split_screen_setup.gd)
Dynamic split-screen architecture for local multiplayer, handling viewport stretching and audio listeners.

### [remote_transform_decoupling.gd](scripts/remote_transform_decoupling.gd)
Decoupling camera position from player rotation/scale using `RemoteTransform2D` for high-speed stability.

### [zoom_damping_controller.gd](scripts/zoom_damping_controller.gd)
Non-linear, smooth zoom logic with tactical overview bounds and mouse-wheel support.

### [spring_lerp_camera_3d.gd](scripts/spring_lerp_camera_3d.gd)
Physics-stable 3D follow camera using spring-mass interpolation to reduce follow-latency jitter.

### [first_person_sway.gd](scripts/first_person_sway.gd)
Procedural 8-figure head bob and weapon sway logic for immersive First-Person systems.

### [deadzone_drag_margins.gd](scripts/deadzone_drag_margins.gd)
Platformer-specific deadzone management using code to control follow-margins and drag-center behavior.

---

## Camera2D Basics

```gdscript
extends Camera2D

@export var target: Node2D
@export var follow_speed := 5.0

func _process(delta: float) -> void:
    if target:
        global_position = global_position.lerp(
            target.global_position,
            follow_speed * delta
        )
```

## Position Smoothing

```gdscript
extends Camera2D

func _ready() -> void:
    # Built-in smoothing
    position_smoothing_enabled = true
    position_smoothing_speed = 5.0
```

## Camera Limits

```gdscript
extends Camera2D

func _ready() -> void:
    # Constrain camera to level bounds
    limit_left = 0
    limit_top = 0
    limit_right = 1920
    limit_bottom = 1080
    
    # Smooth against limits
    limit_smoothed = true
```

## Camera Shake

```gdscript
extends Camera2D

var shake_amount := 0.0
var shake_decay := 5.0

func _process(delta: float) -> void:
    if shake_amount > 0:
        shake_amount = max(shake_amount - shake_decay * delta, 0)
        offset = Vector2(
            randf_range(-shake_amount, shake_amount),
            randf_range(-shake_amount, shake_amount)
        )

From bgrenat/godot-game-dev-studio, LGPL-3.0.

More from bgrenat/godot-game-dev-studio