AI SceneDialogue

SceneDialogue Handling in cabinScene.lua - Detailed Explanation

Mermaid Diagram

flowchart TB
    B[Array of Dialogue Steps]

    B --> D[Step Types Processed by executeSceneStep]

    D --> E[type: narration]
    E --> F[showDialogue - Display Text in Dialogue Box]

    D --> G[type: show]
    G --> H[showObject - Make Object Visible]

    D --> I[type: object_state]
    I --> J[changeObjectState - Change Object Appearance]

    D --> K[type: object_state_conditional]
    K --> L[changeObjectStateConditional - Conditional Object Change]

    D --> M[type: sfx]
    M --> N[playSFX - Play Sound Effect]

    D --> O[type: emotion]
    O --> P[changeEmotion - Change Character Expression]

    D --> Q[type: custom]
    Q --> R[executeAction - Run Custom Function]

    D --> S[type: choice]
    S --> T[showChoice - Display Choice Buttons]

    F --> U[User Clicks Next Button]
    U --> V[advanceDialogue Called]
    V --> W[executeSceneStep with Next Index]

    H --> X[Timer Delay then Continue]
    J --> X
    L --> X
    N --> W
    P --> W
    R --> W

    T --> Y[User Selects Choice]
    Y --> Z[handleChoice - Process Selection]
    Z --> AA[Transition to Next Scene]

    X --> W
    W --> BB{More Steps?}
    BB -->|Yes| D
    BB -->|No| CC[Dialogue Sequence Complete]

flowchart TD

    subgraph Helper_Functions
        DD[common_helpers.lua]
        EE[executeSceneStep Function]
        FF[showDialogue Function]
        GG[changeObjectState Function]
        HH[changeObjectStateConditional Function]
        II[playSFX Function]
        JJ[showChoice Function]
        KK[cabinScene_helpers.lua]
        LL[Condition Registry]
        MM[Action Registry]
    end

    DD --> EE
    EE --> FF
    EE --> GG
    EE --> HH
    EE --> II
    EE --> JJ
    KK --> LL
    KK --> MM

Detailed Explanation

The sceneDialogue system in cabinScene.lua works through a structured sequence:

1. Scene Dialogue Definition

The sceneDialogue table in cabinScene.lua defines an array of steps, each with a specific type and parameters:

local sceneDialogue = {
    { type = "narration", text = "You stand before an old cabin in the woods." },
    { type = "show", what = "cabin_door" },
    { type = "object_state", object = "cabin_door", state = "closed" },
    -- ... more steps
}

2. Execution Flow

The dialogue execution begins in scene:show() which calls self:executeSceneStep(1) to start with the first step.

3. Step Processing

The executeSceneStep function in common_helpers.lua processes each step based on its type:

• narration: Calls showDialogue to display text in the dialogue box
• show: Calls showObject to make an object visible
• object_state: Calls changeObjectState to change an object’s appearance
• object_state_conditional: Calls changeObjectStateConditional for conditional object changes
• sfx: Calls playSFX to play sound effects
• emotion: Calls changeEmotion to change character expressions
• custom: Calls executeAction to run custom functions from the action registry
• choice: Calls showChoice to display choice buttons

4. Helper Systems

• Condition Registry: Located in cabinScene_helpers.lua, defines boolean functions for conditional logic
• Action Registry: Also in cabinScene_helpers.lua, defines custom functions that can be executed
• Global State: Uses _G.gameData to persist state across scenes

5. User Interaction

• For linear dialogue, the user clicks a “Next” button to advance
• For choices, the user selects from displayed options
• The system automatically continues to the next step after non-interactive actions

This architecture provides a flexible system for creating complex interactive narratives with visual and audio elements.