godot-camera-systems

NEVER Do

• NEVER use globalposition = target.globalposition every frame — Instant position matching causes jittery movement. Use lerp() or positionsmoothingenabled = 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 ([camerashaketraumapro.gd](scripts/camerashaketraumapro.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 ([remotetransformdecoupling.gd](scripts/remotetransformdecoupling.gd), [phantomdecoupling.gd](scripts/phantomdecoupling.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 rendertargetupdatemode to UPDATEWHEN_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.

• [camerashaketraumapro.gd](scripts/camerashaketraumapro.gd) — MANDATORY for any screen shake / impact juice.
• [camerashaketrauma.gd](scripts/camerashaketrauma.gd) — Lighter trauma variant.
• [remotetransformdecoupling.gd](scripts/remotetransformdecoupling.gd) — MANDATORY default for physics-body follow.
• [phantomdecoupling.gd](scripts/phantomdecoupling.gd) — Alternate stable follow phantom.
• [springlerpcamera3d.gd](scripts/springlerpcamera3d.gd) — MANDATORY before custom 3D follow springs.
• [deadzonedragmargins.gd](scripts/deadzonedragmargins.gd) — Platformer drag/deadzone.
• [camerafollow2d.gd](scripts/camerafollow2d.gd) — Smooth 2D follow helpers.
• [zoomdampingcontroller.gd](scripts/zoomdampingcontroller.gd) — Non-linear zoom.
• [camerastatemachine.gd](scripts/camerastatemachine.gd) — Follow / Static / Cinematic transitions.
• [cinematicframinglogic.gd](scripts/cinematicframinglogic.gd) — Rule of thirds / lead room.
• [minimapviewportmanager.gd](scripts/minimapviewportmanager.gd) — SubViewport update modes.
• [splitscreensetup.gd](scripts/splitscreensetup.gd) — Local multi camera viewports.
• [firstpersonsway.gd](scripts/firstpersonsway.gd) — FPS bob/sway on offset.
• [juicecamera.gd](scripts/juicecamera.gd) — Combined juice helpers.
• [framingboxcamera2d.gd](scripts/framingboxcamera2d.gd) — Multi-target AABB framing + zoom fit.
• [occlusionawarecamera3d.gd](scripts/occlusionawarecamera3d.gd) — Raycast occlusion when SpringArm is insufficient.
• [traumadebugger.gd](scripts/traumadebugger.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: [framingboxcamera2d.gd](scripts/framingboxcamera2d.gd).

2. Occlusion (3D)

Prefer SpringArm3D with world collision mask; custom rigs use intersectray between ideal camera pos and target — [occlusionawarecamera3d.gd](scripts/occlusionawarecamera_3d.gd) (peer godot-raycasting-queries).

3. Trauma audit

Plot trauma decay (debug draw) while tuning [camerashaketraumapro.gd](scripts/camerashaketraumapro.gd) — wire [traumadebugger.gd](scripts/traumadebugger.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](references/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 / limitsmoothed, and positionsmoothing_ that underpin 2D follow, deadzones, and level bounds.
• Camera3D — Projection, lookat, 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 — rendertargetupdatemode 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

• godot-project-foundations — Stretch mode, default viewport, and input map setup decide how Camera2D limits and SubViewport sizes behave before any follow script runs.
• godot-gdscript-mastery — Typed nodes, physicsprocess vs _process, and Tween/await patterns used by state machines and spring follow.
• godot-input-handling — Captured mouse, look axes, and mouse-wheel events feed FPS look, zoom damping, and camera orbit controls.

Complements

• godot-tweening — Camera transitions between Follow/Static/Cinematic should use Tweens (ease/trans), not hard snaps or linear zoom.
• godot-characterbody-2d — Look-ahead and deadzone cameras need real velocity / floor state from the platformer body they frame.
• godot-physics-3d — SpringArm collision layers and CharacterBody3D motion are the 3D counterparts to stable third-person and FPS sway parents.
• godot-raycasting-queries — Custom occlusion-aware cameras that do not use SpringArm still need correct intersect_ray masks and excludes.
• godot-state-machine-advanced — Formalize Follow/Static/Cinematic (and cutscene ownership) when camerastatemachine outgrows a simple enum.
• godot-signal-architecture — Trauma add, cutscene handoff, and multi-target framing should be signal-driven so gameplay never reaches into camera internals.

Downstream / consumers

• godot-performance-optimization — Escalate when SubViewport minimaps, split-screen, or always-on secondary cameras still dominate frame time after update-mode tuning.
• godot-monte-carlo-balancer — Simulate shake intensity, zoom fairness, and multi-target framing so camera juice never hides hitboxes or competitive information.
• godot-adapt-single-to-multiplayer — Consumes split-screen SubViewport patterns when local coop needs per-player cameras and listener ownership.
• godot-debugging-profiling — Use monitors and visualizers to prove camera jitter sources (physics tick, RemoteTransform, trauma) before rewriting follow math.

Master

• godot-master — Library router and mirrored module entry; open when discovering which Domain Skill owns a cross-cutting camera concern.