Godot Camera Systems

NEVER Do

• NEVER use `global_position = target.global_position` every frame — Instant position matching causes jittery movement. Use lerp() or position_smoothing_enabled = true.
• NEVER use `offset` for permanent camera positioning — offset is for shake, sway, or temporary recoil effects only. Use position for permanent framing.
• NEVER forget `limit_smoothed = true` for `Camera2D` — Hard boundaries cause jarring visual stops.
• NEVER enable multiple `Camera2D` nodes in the same viewport simultaneously — Only the last enabled camera takes precedence. Explicitly disable inactive cameras.
• NEVER use `SpringArm3D` without a collision mask — It will clip through terrain and walls. Set it to the world/environment layer.
• NEVER implement screen shake by randomizing `position` (or `randf` on `offset` as the whole system) — Use a dedicated Trauma/Noise system layered on follow (camera_shake_trauma_pro.gd).
• NEVER parent the Camera directly to a high-speed physics body as the default rig — Physics stutter or parent rotation causes motion sickness. Prefer RemoteTransform2D/3D / phantom decoupling with rotation sync disabled (remote_transform_decoupling.gd, phantom_decoupling.gd).
• NEVER use `look_at()` in 3D without a fallback for the 'Up' vector — Targets directly above/below flip the camera; use guards or Quaternion math.
• NEVER rely on `SubViewport` defaults for Mini-maps — Set render_target_update_mode to UPDATE_WHEN_VISIBLE or a lower fixed rate.
• NEVER use linear interpolation for Zoom — Prefer exponential lerp or Tween TRANS_CUBIC.

Parenting / Decoupling (resolved)

Available Scripts

MANDATORY: Read before implementing the matching behavior. No randf shake samples in project code.

• camera_shake_trauma_pro.gd — MANDATORY for any screen shake / impact juice.
• camera_shake_trauma.gd — Lighter trauma variant.
• remote_transform_decoupling.gd — MANDATORY default for physics-body follow.
• phantom_decoupling.gd — Alternate stable follow phantom.
• spring_lerp_camera_3d.gd — MANDATORY before custom 3D follow springs.
• deadzone_drag_margins.gd — Platformer drag/deadzone.
• camera_follow_2d.gd — Smooth 2D follow helpers.
• zoom_damping_controller.gd — Non-linear zoom.
• camera_state_machine.gd — Follow / Static / Cinematic transitions.
• cinematic_framing_logic.gd — Rule of thirds / lead room.
• minimap_viewport_manager.gd — SubViewport update modes.
• split_screen_setup.gd — Local multi camera viewports.
• first_person_sway.gd — FPS bob/sway on offset.
• juice_camera.gd — Combined juice helpers.
• framing_box_camera_2d.gd — Multi-target AABB framing + zoom fit.
• occlusion_aware_camera_3d.gd — Raycast occlusion when SpringArm is insufficient.
• trauma_debugger.gd — On-screen trauma decay curve (debug builds).

Expert Camera Architectures

1. Multi-target framing

Compute AABB of targets → lerp camera to center → zoom/distance to fit with margin. Keep juice shake on offset only. MANDATORY: framing_box_camera_2d.gd.

2. Occlusion (3D)

Prefer SpringArm3D with world collision mask; custom rigs use intersect_ray between ideal camera pos and target — occlusion_aware_camera_3d.gd (peer godot-raycasting-queries).

3. Trauma audit

Plot trauma decay (debug draw) while tuning camera_shake_trauma_pro.gd — wire trauma_debugger.gd to get_trauma(). Never validate feel with raw randf offset demos.

MANDATORY for multi-target framing, custom occlusion rigs, 2D/3D follow recipes, and cinematic transitions: camera-expert-patterns.md. Do NOT Load when golden-path scripts already cover your rig.

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Camera2D — Position/drag margins, limit_* / limit_smoothed, and position_smoothing_* that underpin 2D follow, deadzones, and level bounds.
• Camera3D — Projection, look_at, current-camera rules, and environment overrides used by third-person, FPS, and cinematic 3D rigs.
• Third-person camera with spring arm — Why parenting a Camera3D alone clips geometry and how SpringArm3D length/shape keep the view clear.
• SpringArm3D — Collision mask, margin, and spring length API required before third-person occlusion pulls feel trustworthy.
• Using Viewports — Multiple cameras, SubViewport architecture, and when split-screen / minimap views share or isolate worlds.
• SubViewport — render_target_update_mode and audio-listener flags that decide minimap and local-coop GPU/audio cost.
• RemoteTransform2D — Decouple camera position from player rotation/scale without parenting the camera under a physics body.
• Interpolation — Lerp / exponential follow and zoom damping math so custom cameras do not feel robotic or jittery.
• Physics interpolation (introduction) — Why cameras following CharacterBody motion stutter when render and physics ticks disagree.
• FastNoiseLite — Coherent noise for trauma/offset shake instead of raw randf position thrashing.
• PathFollow2D — Progress-ratio driven cinematic paths when Tweening a camera along a Path2D.
• Mouse and input coordinates — Wheel zoom and mouse-look coordinate spaces so FPS pitch/yaw and tactical zoom stay consistent across viewports.

Related Skills

Prerequisites