sillytavern-rts-mode/CLAUDE.md

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