HSDollyCam/_bmad-output/planning-artifacts/ux-design.md

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