lens-rig

# Lens Rig

The camera is the player's window into the world. A great game with a bad camera still feels bad. This skill helps you design follow, deadzone, look-ahead, bounds, and orbit so the view feels intentional and framerate-stable.

Inspired by gamedev-skills/awesome-gamedev-agent-skills camera-systems (Apache-2.0). Original Grok remake. Complements stick-map (input), juice-pass (shake MAGNITUDE/trigger lives there; this skill only exposes an additive shake offset hook), room-flow (space), save-slot. Not godot-teacher.

Read `references/camera-rules.md` before you write. Fill the three templates under `templates/`.

## When to use

- Smooth camera follow that shouldn't twitch on micro-movement
- Look-ahead based on motion or facing
- Level-edge clamping so the view stays inside the playable area
- 3D orbit with pitch clamp and wall collision push-in
- First-person look (yaw/pitch only) with a clean shake offset hook
- Tuning feel across low and high FPS

## When NOT to use

- Screen-shake magnitude or trauma curves (use juice-pass)
- Godot Camera2D tutorials or engine API dumps (use godot-teacher)
- Level blockout and room layout (use room-flow)
- Input mapping and stick curves (use stick-map)
- Aimbots, wallhacks, ESP, camera-injection cheats, or any malware

## Inputs

- Genre and viewpoint (platformer, top-down, third-person, first-person)
- Follow target (player, vehicle, party lead)
- 2D or 3D
- Level bounds rect or volume (world space)
- Desired deadzone half-extents and look-ahead distance
- Whether late/post update is available in the engine

## Procedure

1. Pick genre rules. Platformers lead the jump and reveal hazards. Top-down favors a box deadzone. Third-person separates look (orbit) from collision (spring arm). First-person is look only.
2. Fill `templates/rig-card.md`: target, plane, bounds, deadzone, look-ahead, late-update note.
3. Choose frame-rate independent smoothing. Prefer `1 - exp(-rate * dt)` or a spring / SmoothDamp. Never a fixed `lerp(a, b, 0.1)` every frame.
4. Add a box deadzone so the camera only chases when the target overflows the box.
5. Add look-ahead along motion or facing. Ease it so direction flips don't whip the view.
6. Clamp so the VIEWPORT stays inside level bounds, not just the camera center. Account for half-width and half-height. Ease into the edge.
7. For 3D orbit: yaw/pitch on a pivot with pitch clamped near ±80°. Run a spring-arm or ray pull-in so the lens doesn't clip walls.
8. Update the camera AFTER the target moves (late / post step) to avoid one-frame lag jitter.
9. Expose an additive shake offset hook only. Compose follow first, add shake last. Never let shake drive the follow target. Magnitude and triggers belong in juice-pass.
10. On teleport or respawn, hard-cut and reset smoothing state, or fast-ease. Don't SmoothDamp across the whole level.
11. Fill `templates/feel-tune.md` with rates, deadzone, look-ahead ease, pitch clamp, spring-arm length, shake hook name.
12. Fill `templates/verify.md` and run checks at low FPS, high FPS, corners, walls, edges, teleport cut, and shake compose.

## Output format

- Completed `templates/rig-card.md`
- Completed `templates/feel-tune.md`
- Completed `templates/verify.md`
- Short design notes in plain words (engine-neutral). Tiny original pseudocode only if the user asked. No vendor API dumps.

## Safety

- Gaming camera design only.
- Refuse aimbots, wallhacks, ESP, camera injection, cheats, and malware.
- Do not dump engine tutorials that belong in godot-teacher.
- Do not own shake trauma; only the additive offset hook.

## Stop conditions

- User only needs shake magnitude (hand off to juice-pass)
- User wants a Godot Camera2D walkthrough (hand off to godot-teacher)
- Request is about level layout (room-flow) or input binding (stick-map)
- Request is a cheat or exploit
- Rig card, feel tune, and verify templates are filled and checks pass