# UX Design — HS_DollyCam

## Interaction Modalities

HS_DollyCam supports three primary input modalities:

| Modality | Description | Use Case |
|----------|-------------|----------|
| **Chat Commands** (`/88`) | Text-based commands on channel 88 | Primary workflow; precise control; scripting |
| **Touch Menu** | Dialog menu opened by touching the HUD prim | GUI-based workflow; discovery; quick actions |
| **Visual Markers** | Clickable pyramid markers rezzed in-world | Spatial navigation; previewing presets |

## Chat Command Reference (`/88`)

```
/88 help                          — Show all available commands
/88 cam on|off                    — Request/release camera control
/88 save <idx>                    — Save current camera as preset
/88 load <idx>                    — Instant cut to preset
/88 moveto <idx> [ms]             — Smooth move to preset
/88 del <idx>                     — Delete preset
/88 list [from] [count]           — List saved presets
/88 play <notecard> [gap_ms]      — Play playlist from notecard
/88 stop                          — Stop current playback/movement
/88 tour <ms> [mode] <idx1> ...   — Continuous tour across presets
/88 dollyzoom <ms> [mode] <idxA> <idxB>  — Dolly zoom between two presets
/88 cfg reload|dump               — Reload/dump engine configuration
/88 show cams [N]                 — Rez marker pyramids
/88 hide cams                     — Remove marker pyramids
/88 lock on [<x,y,z>|uuid]        — Lock camera to target
/88 lock off                      — Release lock
/88 follow on [uuid] [mode] [ms]  — Follow target object
/88 follow off                    — Release follow
/88 fov <rad>                     — Set viewer FOV (radians)
/88 fovdeg <deg>                  — Set viewer FOV (degrees)
```

## Touch Menu Structure

The touch menu (opened by touching the HUD ROOT prim) provides the following workflow groups:

```
┌─────────────────────────────────┐
│  HS DollyCam                    │
├─────────────────────────────────┤
│  [Save 1] [Save 2] [Save 3]    │
│  [Load 1] [Load 2] [Load 3]    │
│  [MoveTo 1] [MoveTo 2]         │
├─────────────────────────────────┤
│  [Play] [Stop] [Tour]          │
├─────────────────────────────────┤
│  [Follow] [Lock] [FOV]         │
├─────────────────────────────────┤
│  [Markers] [Cams] [Help]       │
└─────────────────────────────────┘
```

### Menu Workflow Details

| Screen | Purpose | Key Actions |
|--------|---------|-------------|
| **Preset Grid** | Save/load/move to presets | Save current, load preset, moveto preset |
| **Playback** | Playlist and tour controls | Play notecard, stop, build tour |
| **Tracking** | Lock/follow/FOV controls | Enable tracking, adjust FOV |
| **Helpers** | Markers and camera tools | Show/hide markers, cam on/off |

## Notecard Playlist Syntax

Lines are parsed sequentially. Supported commands:

```
moveto 1 2500          — Smooth move to preset 1 over 2500ms
goto 2                 — Instant cut to preset 2
load 3                 — Alternative: instant cut to preset 3
wait 1000              — Hold for 1000ms before next command
tour 5000 spline 1 2 3 — Begin continuous tour (5s, spline interp)
                       — ... intermediate waypoints ...
endtour                — End tour block, load final position
dollyzoom 2000 1 3     — Dolly zoom from preset 1 to 3 over 2s
fov 1.047              — Set FOV to 60°
lock on <uuid>         — Lock to target
follow on <uuid> yaw   — Follow target in world coordinates
```

## State Machine

```
                    ┌──────────────┐
                    │   IDLE (root) │
                    └──────┬───────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌──────────┐  ┌──────────┐  ┌──────────┐
        │ MOVING   │  │ TOURING  │  │ LOCKED   │
        │ (single) │  │ (multi)  │  │ / FOLLOW │
        └──────────┘  └──────────┘  └──────────┘
              │            │            │
              └────────────┴────────────┘
                           ▼
                    ┌──────────────┐
                    │   STOPPED    │
                    └──────────────┘
```

**Key transitions:**
- Any → STOPPED: `stop`, `load`, `moveto`, menu action, marker click
- IDLE → MOVING: `moveto` with duration > 0
- IDLE → MOVING: `load` (instant, duration = 0)
- IDLE → TOURING: `tour` command or playlist `tour` block
- IDLE → LOCKED/FOLLOW: `lock on` or `follow on`
- Any → IDLE: `cam off`, detach, permission denied

## Memory-Sensitive Design Rules

1. **No full string splitting in hot paths** — Timer events, `link_message` for `CE_INT_SET_CAM`, preset loading must use targeted parsing
2. **Runtime data in script memory** — Tour playback lists (positions, focuses, segment lengths) stay in `HS_CamEngineTour.lsl`, not Linkset Data
3. **Short-lived lists** — Tour payload building stores indices first, loads position/focus at `endtour`, then builds final payload
4. **Throttled output** — Camera frames sent at ≤30Hz via `tour_cam_min_interval`