# HS_DollyCam System Architecture

## Overview
HS_DollyCam is a specialized, high-performance camera control system for Second Life, designed to handle complex, multi-waypoint camera tours, precision movement, and automated playlist playback while strictly adhering to LSL (Linden Scripting Language) memory constraints.

## System Architecture

The system follows a decoupled, multi-script architecture where responsibilities are split across specialized components to optimize memory usage and computational performance.

### 1. Orchestration Layer (`HS_CamController.lsl`)
**Role:** The central command and state coordinator.
- **Responsibilities:**
  - Handles all user input via Chat (`/88`) and Dialog Menus.
  - Mantains persistent state in **Linkset Data** (e.g., active Follow/Lock targets, Marker visibility).
  - Routes high-level commands to the specialized helper scripts.
  - Manages the lifecycle of presets (Save/Load/Delete).
- **Key Feature:** Acts as the "brain," deciding whether to trigger a one-shot movement or delegate to a continuous tour engine.

### 2. Automation Layer (`HS_CamPlaylist.lsl`)
**Role:** The asynchronous, notecard-driven automation engine.
- **Responsibilities:**
  - Parses and executes complex command sequences from inventory notecards.
  - Manages "Continuous Tours" by building large, multi-waypoint payloads.
  - Handles "DollyZoom" generation and "Wait"/"Delay" logic.
- **Key Feature:** Decouples heavy parsing and long-running sequential logic from the main controller, preventing script timeouts and memory spikes in the Controller.

### 3. Runtime/Execution Layer (`HS_CamEngineTour.lsl`)
**Role:** The high-frequency movement engine for continuous tours.
- **Responsibilities:**
  - Decomposes large tour payloads into a high-frequency stream of camera frames.
  - Implements complex trajectory mathematics (Catmull-Rom/Spline and Trapezoidal motion profiles).
  - Manages waypoint-specific properties like weights, holds, and FOV ramps.
- **Key Feature:** Uses optimized segment caching and throttled updates (e.g., 30Hz) to ensure smooth, high-fidelity camera movement without saturating the simulator's message buffer.

### 4. Hardware Interface Layer (`HS_CamEngineCore.lsl`)
**Role:** The low-level interface to the Second Life viewer.
- **Responsibilities:**
  - Manages `PERMISSION_CONTROL_CAMERA` and `PERMISSION_TRACK_CAMERA`.
  - Executes the actual `llSetCameraParams` calls.
  - Implements the low-level math for "Follow" (World/Local/Yaw) and "Lock" modes.
- **Key Feature:** Provides the fundamental "Engine" for all movement, acting as the final recipient of all `CE_INT_SET_CMD` messages.

---

## Communication Protocol

The system communicates primarily via `llMessageLinked` using the following categorized constants:

| Category | Prefix | Examples |
| :--- | :--- | :--- |
| **Engine Commands** | `CE_CMD_` | `MOVE`, `TOUR`, `STOP`, `LOCK`, `FOLLOW` |
| **Engine Events** | `CE_EVT_` | `READY`, `DENIED`, `MOVE_DONE`, `STATE` |
| **Internal (Engine-to-Core)** | `CE_INT_` | `SET_CAM`, `TOUR_BEGIN`, `TOUR_END`, `TOUR_STOP` |
| **Playlist Commands** | `PH_CMD_` | `PLAY`, `STOP`, `CHAT_TOUR`, `TOURRUN` |
| **Menu/Marker Commands**| `MN_CMD`, `MC_CMD` | `MENU_CMD`, `MARKER_SHOW`, `MARKER_HIDE` |

---

## Critical Implementation Rules (for AI Agents)

**1. Memory Preservation (The Golden Rule):**
- **NEVER** use `llParseString2List` in high-frequency paths (e.g., `on_timer` or `link_message` for `CE_INT_SET_CAM`).
- **USE** targeted parsing (token-based or manual character scanning) to avoid creating large, temporary string/list objects.
able-type lists in LSL are extremely expensive.

**2. Computational Efficiency:**
- **USE** segment caching in the Tour Engine to avoid repeated `llList2Vector` lookups.
- **USE** `llRegionSayTo` for marker communication whenever the target key is known.
- **THROTTLE** camera frame updates (e.g., 30Hz) to prevent simulator network congestion.

**3. Precision & Reliability:**
- **ENSURE** all movement math (splines, trapezoids) accounts for the `gMOVE_STEP` and `gTOUR_CAM_MIN_INTERVAL` parameters.
- **IMPLEMENT** error-handling for broken payloads (e.g., malformed `CE_CMD_TOUR` strings).