HSDollyCam/docs/system_architecture.md

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).