# Epics and Stories — HS_DollyCam

## Epic Map

```
Epic 1: Core Camera Engine     (HS_CamEngineCore.lsl)
Epic 2: Tour Runtime           (HS_CamEngineTour.lsl)
Epic 3: Playlist Engine        (HS_CamPlaylist.lsl)
Epic 4: Chat Commands          (HS_CamController.lsl)
Epic 5: Menu UI                (HS_CamMenu.lsl)
Epic 6: Visual Markers         (HS_CamMarkers.lsl)
Epic 7: FOV Control            (HS_CamFov.lsl)
Epic 8: Tour Commands Helper   (HS_CamTourCommands.lsl)
Epic 9: Configuration          (HS_CamEngine.properties)
Epic 10: Documentation         (AGENTS.md, manuals)
```

---

## Epic 1: Core Camera Engine (`HS_CamEngineCore.lsl`)

> Low-level camera interface. Manages permissions, `llSetCameraParams`, Follow/Lock math.

| Story ID | Story | Status |
|----------|-------|--------|
| 1.1 | As a user, I can request camera control via `/88 cam on` and release it via `/88 cam off` | Done |
| 1.2 | As a user, I can move the camera smoothly to a target position with configurable duration | Done |
| 1.3 | As a user, I can lock the camera to a target (position or object UUID) | Done |
| 1.4 | As a user, I can follow a target object in World/Local/Yaw coordinate frame | Done |
| 1.5 | As a developer, the engine dumps configuration via `CE_EVT_CFG_DUMP` for consumption by Playlist/TourEngine | Done |
| 1.6 | As the system, `CE_INT_SET_CAM` hot path uses direct separator lookup (no `llParseString2List`) | Done |
| 1.7 | As the system, Follow/Lock mutual exclusion is enforced (enabling one disables the other) | Done |

---

## Epic 2: Tour Runtime (`HS_CamEngineTour.lsl`)

> High-frequency multi-waypoint tour playback. Catmull-Rom splines, trapezoidal motion, ~30Hz throttling.

| Story ID | Story | Status |
|----------|-------|--------|
| 2.1 | As a user, I can run a continuous tour across multiple presets with spline interpolation | Done |
| 2.2 | As a user, I can specify linear interpolation mode for tours | Done |
| 2.3 | As the system, tour frames are throttled to ~30Hz via `tour_cam_min_interval` | Done |
| 2.4 | As the system, segment caching avoids repeated `llList2Vector` lookups during timer playback | Done |
| 2.5 | As a user, tour waypoints can have specific hold times and weights | Done |
| 2.6 | As a user, FOV ramps between waypoints are supported in tours | Done |
| 2.7 | As the system, `startfirst` mode flag allows tours to begin from first preset without camera state roundtrip | Done |
| 2.8 | As the system, active tour lists stay in script memory (not Linkset Data) for performance | Done |

---

## Epic 3: Playlist Engine (`HS_CamPlaylist.lsl`)

> Notecard-driven playlist playback. Reads inventory notecards, executes commands sequentially.

| Story ID | Story | Status |
|----------|-------|--------|
| 3.1 | As a user, I can play a playlist from an inventory notecard: `/88 play <notecard> [gap_ms]` | Done |
| 3.2 | As a user, my notecard supports `moveto`, `goto`, `load`, `wait`, `tour...endtour`, `dollyzoom`, `fov`, `lock`, `follow` commands | Done |
| 3.3 | As a user, tour blocks in notecards build a single continuous payload sent to TourEngine | Done |
| 3.4 | As a user, compact notecard tours (`tour <ms> [mode] <idx...>`) avoid slow multi-line reads | Done |
| 3.5 | As the system, playlist chains moves on `MOVE_DONE` unless a `wait` line appears after `moveto` (early cut) | Done |
| 3.6 | As the system, `loadPreset()` uses targeted field parsing instead of full string splitting | Done |
| 3.7 | As the system, notecard reading uses `llGetNotecardLineSync` with `NAK` fallback | Done |
| 3.8 | As a user, I can stop any active playlist with `/88 stop` | Done |

---

## Epic 4: Chat Commands (`HS_CamController.lsl`)

> Central command router. Preset management, state persistence, command dispatch.

| Story ID | Story | Status |
|----------|-------|--------|
| 4.1 | As a user, I can save the current camera as a numbered preset: `/88 save <idx>` | Done |
| 4.2 | As a user, I can load a preset instantly: `/88 load <idx>` | Done |
| 4.3 | As a user, I can smoothly move to a preset: `/88 moveto <idx> [ms]` | Done |
| 4.4 | As a user, I can delete a preset: `/88 del <idx>` | Done |
| 4.5 | As a user, I can list all saved presets: `/88 list [from] [count]` | Done |
| 4.6 | As a user, I can get help with all available commands: `/88 help` | Done |
| 4.7 | As a user, presets are stored in Linkset Data with keys `P1`, `P2`, … | Done |
| 4.8 | As a user, Follow/Lock state persists across script resets | Done |
| 4.9 | As a user, marker visibility state persists across script resets | Done |
| 4.10 | As the system, all commands are restricted to the object owner | Done |
| 4.11 | As a demo user, saving is limited to `DEMO_MAX_SLOTS` when `DEMO_MODE=TRUE` | Done |
| 4.12 | As a user, the HUD auto-hides during animated moves to prevent flicker | Done |

---

## Epic 5: Menu UI (`HS_CamMenu.lsl`)

> Dialog menus for common workflows. Secondary to notecard playlist.

| Story ID | Story | Status |
|----------|-------|--------|
| 5.1 | As a user, I can touch the HUD to open a menu with Save/MoveTo/Load/Play/Tour/Follow/Lock buttons | Done |
| 5.2 | As a user, the menu shows page state (pagination for many presets/targets) | Done |
| 5.3 | As a user, the menu can list nearby avatars/objects as follow/lock targets | Done |
| 5.4 | As a user, menu-built tours are forwarded to TourCommands via `PH_CMD_TOURRUN` | Done |
| 5.5 | As a user, menu Follow/Lock actions are mutually exclusive | Done |

---

## Epic 6: Visual Markers (`HS_CamMarkers.lsl`)

> Marker pyramids rezzed at preset positions for visual navigation.

| Story ID | Story | Status |
|----------|-------|--------|
| 6.1 | As a user, I can rez N marker pyramids at preset positions: `/88 show cams [N]` | Done |
| 6.2 | As a user, I can remove all markers: `/88 hide cams` | Done |
| 6.3 | As a user, clicking a marker pyramid loads and moves to the corresponding preset | Done |
| 6.4 | As a user, marker count is limited to 1–30 | Done |
| 6.5 | As a user, marker state (shown/hidden, count) persists across script resets | Done |
| 6.6 | As the system, marker communication uses `llRegionSayTo` when target key is known | Done |

---

## Epic 7: FOV Control (`HS_CamFov.lsl`)

> Field of View adjustment via RLVa.

| Story ID | Story | Status |
|----------|-------|--------|
| 7.1 | As a user, I can set the viewer FOV in radians: `/88 fov <rad>` | Done |
| 7.2 | As a user, I can set the viewer FOV in degrees: `/88 fovdeg <deg>` | Done |
| 7.3 | As a user, FOV values are clamped to 10°–179° range | Done |
| 7.4 | As a user, FOV commands are no-ops if RLVa is disabled (graceful degradation) | Done |
| 7.5 | As the system, FOV state syncs across scripts when presets are loaded/saved | Done |

---

## Epic 8: Tour Commands Helper (`HS_CamTourCommands.lsl`)

> Secondary tour command builder. Absorbs memory pressure from chat/menu one-shot tours.

| Story ID | Story | Status |
|----------|-------|--------|
| 8.1 | As a user, I can run a one-liner tour: `/88 tour <ms> [mode] <idx1> <idx2> ...` | Done |
| 8.2 | As a user, I can run a dolly zoom: `/88 dollyzoom <ms> [mode] <idxA> <idxB>` | Done |
| 8.3 | As a user, menu-built tours are handled without adding memory pressure to Playlist | Done |
| 8.4 | As the system, tour parsing uses targeted preset helpers (no full `llParseString2List`) | Done |

---

## Epic 9: Configuration (`HS_CamEngine.properties`)

> Engine configuration parameters.

| Story ID | Story | Status |
|----------|-------|--------|
| 9.1 | As a developer, I can tune `move_step`, `follow_step`, `default_move_ms`, `default_focus_dist` | Done |
| 9.2 | As a developer, I can tune move/follow lag values (`move_pos_lag`, `move_focus_lag`, etc.) | Done |
| 9.3 | As a developer, I can tune tour parameters (`tour_cam_min_interval`, `tour_pos_epsilon`, `tour_max_points`) | Done |
| 9.4 | As a developer, I can tune position/focus thresholds (`pos_threshold`, `focus_threshold`) | Done |
| 9.5 | As a developer, `follow_predict=0.10` controls follow prediction offset | Done |

---

## Epic 10: Documentation

> Project documentation for AI agents and developers.

| Story ID | Story | Status |
|----------|-------|--------|
| 10.1 | As a developer, I can read `AGENTS.md` for detailed component docs and communication constants | Done |
| 10.2 | As a developer, I can read `project-context.md` for AI agent rules | Done |
| 10.3 | As a developer, I can read `docs/system_architecture.md` for high-level architecture | Done |
| 10.4 | As a user, I can read `HS_DollyCam_Manual` for setup and usage instructions | Done |
| 10.5 | As a user, I can read `HS_DollyCam_Manual_FOV_Extension` for FOV-specific documentation | Done |

---

## Future Epic Candidates (Not Yet Implemented)

| Epic | Description |
|------|-------------|
| **Epic F1: Preset Export/Import** — Export presets to notecard, import from notecard |
| **Epic F2: Tour Preset Save** — Save current tour configuration as a reusable preset |
| **Epic F3: Multi-Object HUD** — Split Controller into smaller prims for reduced memory pressure |
| **Epic F4: Tour Preview** — Play tour at reduced speed for preview before full-speed playback |
| **Epic F5: Marker Customization** — Customize marker color/size/transparency |
| **Epic F6: Tour Editor Notecard** — Generate/edit playlist notecards from menu |
| **Epic F7: Camera State Dump** — Export current camera position/focus as a notecard command |
| **Epic F8: Tour Loop Mode** — Loop tours continuously with configurable repeat count |