From 2b00de309bc514d5f8a38eca0ecb709e9c395846 Mon Sep 17 00:00:00 2001 From: VinPropane Date: Tue, 7 Apr 2026 23:12:48 -0400 Subject: [PATCH] chore: expand E1.M2 module doc (Jira backlog, rotation policy) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Link NEON-10/NEON-25–28 under parent NEON-1 in Summary and Jira backlog table - Document mid-project-only yaw orbit compromise; post-release camera model settled - Extend CameraState contract and slice/risk notes accordingly --- .../E1_M2_IsometricCameraController.md | 38 ++++++++++++++++--- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/docs/decomposition/modules/E1_M2_IsometricCameraController.md b/docs/decomposition/modules/E1_M2_IsometricCameraController.md index 61a4719..ce0c46d 100644 --- a/docs/decomposition/modules/E1_M2_IsometricCameraController.md +++ b/docs/decomposition/modules/E1_M2_IsometricCameraController.md @@ -8,25 +8,38 @@ | **Epic** | [Epic 1 — Core Player Runtime](../epics/epic_01_core_player_runtime.md) | | **Stage target** | Prototype | | **Status** | Planned (see [dependency register](module_dependency_register.md)) | +| **Jira** | Feature [NEON-10](https://neon-sprawl.atlassian.net/browse/NEON-10); prototype backlog stories under parent [NEON-1](https://neon-sprawl.atlassian.net/browse/NEON-1) — [Jira backlog](#jira-backlog) | ## Purpose **Authority:** [Client vs server](client_server_authority.md#e1m2-isometriccameracontroller) — camera is client-local for prototype; server does not use camera pose for gameplay checks. -Delivers a locked isometric camera that keeps the player readable during motion: follow behavior, discrete zoom bands, occlusion handling, and explicit **no rotation** so combat telegraphs and UI remain consistent with the vision for fixed isometric presentation. +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](#mid-project-rotation-policy-practical-compromise) so that decision stays mid-project scope, not a rewrite. ## Responsibilities -- Locked isometric follow (camera does not freely orbit). +- 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. -- Enforcement of no-rotation rules for the prototype camera model. +- 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, and policy flags for consumers (e.g. risk UX). | +| `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. | @@ -40,11 +53,26 @@ Delivers a locked isometric camera that keeps the player readable during motion: ## Related implementation slices -See Epic 1 **Slice 2 — Locked isometric camera**: follow-center, zoom bands, occlusion policy, no rotation; optional telemetry such as throttled `camera_zoom_changed` and perf stress markers for occluders. +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](#mid-project-rotation-policy-practical-compromise)); 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](https://neon-sprawl.atlassian.net/browse/NEON-1). + +| Key | Type | Summary | +|-----|------|---------| +| [NEON-10](https://neon-sprawl.atlassian.net/browse/NEON-10) | Feature | E1.M2 — IsometricCameraController (module umbrella) | +| [NEON-25](https://neon-sprawl.atlassian.net/browse/NEON-25) | Story | Locked isometric follow camera (no rotation) | +| [NEON-26](https://neon-sprawl.atlassian.net/browse/NEON-26) | Story | ZoomBandConfig + discrete zoom input (clamped) | +| [NEON-27](https://neon-sprawl.atlassian.net/browse/NEON-27) | Story | OcclusionPolicy — keep player readable through geometry | +| [NEON-28](https://neon-sprawl.atlassian.net/browse/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](#mid-project-rotation-policy-practical-compromise)). ## Source anchors