godot-camera-systems

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 0c0182b848c3 · 24 Oct 2026Report an issue or request a re-scan

• Publisherthedivergentai GitHub userOwner of the repository this skill is read from
• Source folderthedivergentai/gd-agentic-skills/skills/godot-camera-systemsThe exact folder we audited
• LicenceLGPL-3.0As the repository states it
• Commit pinned for this verdict0c0182b848c3A new audit runs when the source changes
• Repository statusNot archivedLast push 7 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Expert patterns for 2D/3D camera control including smooth following (lerp, position_smoothing), camera shake (trauma system), screen shake with frequency parameters, deadzone/drag for platformers, look-ahead prediction,…

---
name: godot-camera-systems
description: "Expert patterns for 2D/3D camera control including smooth following (lerp, position_smoothing), camera shake (trauma system), screen shake with frequency parameters, deadzone/drag for platformers, look-ahead prediction, and camera transitions. Use for player cameras, cinematic sequences, or multi-camera systems. Trigger keywords: Camera2D, Camera3D, SpringArm3D, position_smoothing, camera_shake, trauma_system, look_ahead, drag_margin, camera_limits, camera_transition."
---

## 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](scripts/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](scripts/remote_transform_decoupling.gd), [phantom_decoupling.gd](scripts/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)

| Rig | When | Script |
|-----|------|--------|
| **Default:** RemoteTransform / phantom | Player is CharacterBody / high-speed / rotates | [remote_transform_decoupling.gd](scripts/remote_transform_decoupling.gd), [phantom_decoupling.gd](scripts/phantom_decoupling.gd) |
| Camera as child of player | Slow top-down / locked rotation / prototype only | Explicit caveat: disable if motion sickness or physics jitter appears; never combine with position-overwrite shake |
| SpringArm3D + Camera3D | Third-person occlusion | [spring_lerp_camera_3d.gd](scripts/spring_lerp_camera_3d.gd) — mask required |

## Available Scripts

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

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

### 3. Trauma audit
Plot trauma decay (debug draw) while tuning [camera_shake_trauma_pro.gd](scripts/camera_shake_trauma_pro.gd) — wire [trauma_debugger.gd](scripts/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](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](https://docs.godotengine.org/en/stable/classes/class_camera2d.html) 

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/thedivergentai/gd-agentic-skills
git -C gd-agentic-skills checkout 0c0182b848c3

Works in

1. 2026-10-24
   ✓SAFE B 89 / 100

   first audit · source 0c0182b848c3

Questions about godot-camera-systems

• github.com/thedivergentai/gd-agentic-skills/tree/main/skills/god — the audited source at commit 0c0182b848c3 and every finding aboveObserved · 24 Oct 2026

Spotted something wrong? Report a correction · Methodology