neon-sprawl/docs/decomposition/modules/E1_M2_IsometricCameraController.md

E1.M2 — IsometricCameraController

Summary

Field	Value
Module ID	E1.M2
Epic	Epic 1 — Core Player Runtime
Stage target	Prototype
Status	Planned (see dependency register)
Jira	Feature NEON-10; prototype backlog stories under parent NEON-1 — Jira backlog

Purpose

Authority: Client vs server — camera is client-local for prototype; server does not use camera pose for gameplay checks.

Delivers an isometric follow camera that keeps the player readable during motion: follow behavior, discrete zoom bands, occlusion handling, and yaw held at a fixed default for players in early prototypes so combat telegraphs and UI stay easy to reason about. After release, the shipped camera model is settled (fixed presentation vs product setting that allows yaw)—we do not plan to revisit that post-launch. Before release, we may still decide to expose yaw orbit for comfort; the implementation follows the mid-project rotation policy so that decision stays mid-project scope, not a rewrite.

Responsibilities

• Locked isometric follow for player-facing controls in prototype: yaw = 0 (no orbit bound in UI) while the rig and CameraState still model yaw explicitly so optional orbit can be enabled later via config and input binding.
• Zoom bands and configuration-driven limits.
• Occlusion policy so critical gameplay elements remain visible where possible.
• Pitch / roll remain fixed for the isometric presentation; only yaw is the optional future degree of freedom.

Mid-project rotation policy (practical compromise)

Intent: Ship prototypes and early milestones as if the camera were fully fixed from the player’s perspective, without closing the door to yaw orbit before release.

Topic	Direction
When this applies	Mid-project only. We may enable or keep disabled yaw orbit while still in development. Post-release, treat the chosen shipped behavior as final—no planned pivot between “fixed” and “orbit” for live players.
Implementation	Single seam: e.g. allow_yaw, max_yaw_deg, or equivalent; default keeps yaw at 0 and no rotate input until product + combat readability agree. CameraState carries yaw (default 0) so consumers do not assume “camera yaw does not exist.”
Gameplay semantics	Prefer world-anchored movement, targeting, and server checks—not camera-relative aim—so turning yaw on later is mostly presentation + UI, not a combat authority redesign.
Telegraphs & VFX	Design now for a world where yaw might exist: ground shapes remain world-accurate; plan screen-space or height readability affordances where foreshortening under yaw would otherwise lie (outlines, rings, bars—exact art TBD).
Migration risk	If we add yaw mid-project, expect a telegraph + minimap / compass pass. Fixed → yaw is usually lower risk than yaw → fixed (content and players may already assume spin for sightlines).

Key contracts

Contract	Role
CameraState	Current follow target, zoom level, yaw (default 0; optional future orbit), and policy flags for consumers (e.g. risk UX).
ZoomBandConfig	Data-driven min/max or discrete zoom steps.
OcclusionPolicy	Rules for fading, dithering, or offset when geometry blocks the view.

Module dependencies

• E1.M1 — InputAndMovementRuntime: camera follows the player anchor derived from movement/position.

Dependents (by design)

• E6.M2 — Consent and risk UX may use camera-adjacent presentation; epic lists E1.M2 as a dependency for in-zone risk signaling and readability.

Related implementation slices

See Epic 1 Slice 2 — Locked isometric camera: follow-center, zoom bands, occlusion policy, yaw fixed for players in prototype (implementation still models yaw per mid-project rotation policy); optional telemetry such as throttled camera_zoom_changed and perf stress markers for occluders.

Jira backlog

Parent epic: NEON-1 — Epic 1 — Core Player Runtime.

Key	Type	Summary
NEON-10	Feature	E1.M2 — IsometricCameraController (module umbrella)
NEON-25	Story	Isometric follow camera (fixed yaw prototype; CameraState seam)
NEON-26	Story	ZoomBandConfig + discrete zoom input (clamped)
NEON-27	Story	OcclusionPolicy — keep player readable through geometry
NEON-28	Story	Camera integration hardening + dependent contract notes

Suggested order: NEON-25 → NEON-26 → NEON-27 → NEON-28.

Risks and telemetry

• Occlusion hiding telegraphs: tune policy early and include readability checklist in prototype gates.
• Enabling yaw orbit mid-project without a telegraph/UI/minimap pass can undermine readability; design ground effects for world accuracy plus screen-space or height cues early (see mid-project rotation policy).

Source anchors

• Master plan: neon_sprawl_vision.plan.md — Core Epic Map, Epic 1.
• Module dependency register