82 lines
4.4 KiB
Markdown
82 lines
4.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
This is a **SillyTavern extension** called "RTS Chat Mode (Modular)" that creates a real-time strategy-style interface for interactive storytelling. The extension transforms normal chat interactions into a game-like experience with maps, entities, resources, and narrative events.
|
|
|
|
## Key Architecture Components
|
|
|
|
### Core System Files (`src/`)
|
|
- **GameStateManager.js**: Central state management with enhanced tracking for casualties, escaped animals, incidents, personnel, and map entities. Handles state persistence and updates from AI responses.
|
|
- **LLMAdapter.js**: Processes user commands and LLM responses. Handles JSON extraction from AI responses and synchronizes AI state with the map canvas.
|
|
- **PresetManager.js**: Loads and manages game scenarios/presets from JSON files.
|
|
- **EventManager.js**: Manages narrative events based on zones and threat levels.
|
|
- **PromptCompressor.js**: Builds optimized prompts for the LLM including game state and context.
|
|
|
|
### UI Components (`ui/`)
|
|
- **RTSUIController.js**: Main UI controller that manages fullscreen interface, command input, quick actions, and status displays.
|
|
- **MapCanvas.js**: Interactive canvas-based map renderer for visualizing entities and game world.
|
|
- **ResourcePanel.js**: Status panel showing game statistics and information.
|
|
|
|
### Entry Point
|
|
- **index.js**: Main extension loader that registers slash commands, handles SillyTavern integration, and manages the top bar button.
|
|
|
|
## Game Preset System
|
|
|
|
The extension uses JSON preset files (`presets/` and `maps/`) that define:
|
|
- **Scenarios**: Story setup, character descriptions, initial messages
|
|
- **Maps**: Entity positions, terrain data, zone definitions
|
|
- **Narrative Engine**: Zone-based threat tables for dynamic events
|
|
- **Features**: UI options like quickActions, resources, fogOfWar
|
|
|
|
### Key Preset Properties
|
|
- `narrativeEngine.zones[]`: Defines map areas with associated threat tables
|
|
- `narrativeEngine.threatTables`: Collections of events by threat level (low/medium/high)
|
|
- `features.quickActions[]`: Configurable action buttons with commands
|
|
- `initialState`: Starting game conditions and threat levels
|
|
|
|
## Development Commands
|
|
|
|
The extension integrates with SillyTavern's existing systems and doesn't have separate build/test commands. Development workflow:
|
|
|
|
1. **Testing**: Load SillyTavern and activate the extension via the top bar button
|
|
2. **Debugging**: Check browser console for logs prefixed with "RTS-MODE:" or "RTS:"
|
|
3. **Preset Testing**: Modify JSON files in `presets/` and `maps/` directories
|
|
|
|
## Slash Commands
|
|
|
|
- `/rts-start` - Resets game state with selected preset
|
|
- `/rts-cmd <command>` - Sends action to the game master
|
|
- `/rts-ui` - Toggles fullscreen RTS interface
|
|
- `/rts-observe`, `/rts-move`, `/rts-hide`, `/rts-interact` - Quick actions
|
|
|
|
## State Management Architecture
|
|
|
|
The system uses a multi-layered state approach:
|
|
1. **Game State** (GameStateManager): Core game logic, entities, tracking systems
|
|
2. **Map State**: Visual representation with entity positions and visibility
|
|
3. **AI Response State**: Structured data from LLM containing narrative and updates
|
|
4. **UI State**: Display state for panels, logs, and user interactions
|
|
|
|
### State Synchronization Flow
|
|
1. User action → LLMAdapter → AI response → GameStateManager.setState()
|
|
2. State changes → UI updates → Map canvas refresh → Status panel updates
|
|
3. Entity updates → Map entity sync → Visual position updates
|
|
|
|
## Extension Integration
|
|
|
|
This extension follows SillyTavern's extension patterns:
|
|
- Uses `renderExtensionTemplateAsync()` for HTML templates
|
|
- Integrates with `generateQuietPrompt()` for LLM communication
|
|
- Respects SillyTavern's settings system via `extension_settings`
|
|
- Registers with the extension system through `manifest.json`
|
|
|
|
## Important Implementation Notes
|
|
|
|
- **Entity Management**: The system maintains entity data in both GameStateManager and map canvas, requiring careful synchronization
|
|
- **AI Response Parsing**: Handles multiple JSON formats and reasoning model outputs with thought blocks
|
|
- **Map Coordinate System**: Uses x,y grid coordinates for entity positioning
|
|
- **Event System**: Custom events (`rts-narrative-update`, `rts-map-update`) coordinate between UI components
|
|
- **Fullscreen Mode**: Completely replaces SillyTavern UI when active, managed by RTSUIController |