mita
f9ad14e192
- Introduced a comprehensive skill manifest in `skill-manifest.csv` with various skills for advanced elicitation, brainstorming, customization, and more. - Added `.DS_Store` files in the `bmm` directory for macOS compatibility. - Created a new `config.yaml` for BMM module configuration, detailing user skill level and project paths. - Established `module-help.csv` for BMM, providing descriptions and actions for each skill. - Implemented `config.toml` and `config.user.toml` for core and user-specific configurations, including agent descriptions and project settings. - Developed `resolve_config.py` and `resolve_customization.py` scripts for merging configuration files, enhancing customization capabilities. - Documented the system architecture for HS_DollyCam, outlining components and communication protocols.
74 lines
4.1 KiB
Markdown
74 lines
4.1 KiB
Markdown
# 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).
|