experiment-adventure-ai/architecture/dialogue_system_architecture.md

Dialogue System Architecture

graph TD
    A[Base Character Scene] --> B(DialogueSystem)
    B --> C(DialogueBox UI)
    B --> D(TextRevealer)
    B --> E(AnimationController)
    B --> F(Timer)
    
    C --> G[Visual Display]
    D --> H[Character-by-Character Reveal]
    E --> I[Show/Hide Animations]
    F --> J[Duration Management]
    
    subgraph "Dialogue Flow"
        B --> K{Trigger Dialogue}
        K -->|Text + Duration| L[Show Dialogue Box]
        L --> M[Start Text Reveal]
        M --> N[Wait for Duration]
        N --> O[Hide Dialogue Box]
    end
    
    subgraph "Components"
        C --> C1[White Background]
        C --> C2[Positioning]
        D --> D1[Character Timing]
        D --> D2[Text Display]
        E --> E1[Animation Playback]
        F --> F1[Timer Management]
    end
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e8f5e9
    style D fill:#fff3e0
    style E fill:#fce4ec
    style F fill:#f1f8e9

Component Descriptions

Base Character Scene (A)

• Contains the character sprite (Polygon2D)
• Acts as the entry point for dialogue triggering
• Manages the dialogue system interface

DialogueSystem (B) - Main Controller

• Coordinates all dialogue functionality
• Interfaces with UI components
• Handles timing and state management
• Provides public API for triggering dialogue

DialogueBox UI (C)

• Visual representation of dialogue
• White background container
• Proper positioning relative to character
• Handles visibility states

TextRevealer (D)

• Manages character-by-character text display
• Controls reveal timing
• Updates text label content incrementally
• Handles text formatting and wrapping

AnimationController (E)

• Manages show/hide animations
• Controls timing of UI transitions
• Ensures smooth visual experience
• Handles animation cleanup

Timer (F)

• Manages dialogue duration
• Triggers automatic closure
• Provides timing feedback to system
• Handles edge cases (zero/negative durations)

Flow Description

1. Trigger: Base character calls trigger_dialogue(text, duration)
2. Show: DialogueSystem initiates show animation for DialogueBox
3. Reveal: TextRevealer starts character-by-character text display
4. Wait: Timer waits for specified duration
5. Hide: AnimationController triggers hide animation
6. Complete: System returns to idle state

Integration Points

• Base Character Scene: Public API interface
• DialogueBox UI: Visual rendering component
• TextRevealer: Text animation logic
• AnimationController: UI transition handling
• Timer: Duration management