# Dialogue System

The Dialogue System provides a node-based, graph-driven conversation framework that handles everything from simple NPC exchanges to branching narratives, quest integration, camera control, and character animations — all authored visually without writing code.

***

### How It Fits Together

Conversations are defined as **Dialogue Graphs** — visual node networks stored in `DialogueContainerSO` ScriptableObject assets. Each graph has a single entry point and flows through connected nodes that control what is said, what choices are offered, what happens in the game world, and where the conversation ends.

At runtime, the **Dialogue Manager** is the central authority. It receives a request to play a graph, walks the node sequence frame by frame, drives the **Dialogue UI** to display text and choices, and fires any events or actions encountered along the way. When dialogue ends, it notifies the rest of the system including the Quest System via `QuestEventReporter`.

In the scene, **Dialogue Speaker** components sit on NPCs and interactable objects, identifying them and providing the speaker data (name, portrait) used by the UI. **Dialogue Trigger** components initiate conversations in response to player interaction, trigger zones, or manual calls — and integrate with the save system to ensure one-time dialogues do not replay after a save/load cycle.

***

### Structure

| Section               | Description                                                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Core Components**   | `DialogueManager`, `DialogueSpeaker`, `DialogueTrigger`, `DialogueUI` — the runtime layer that plays, displays, and manages conversations. |
| **Dialogue Graph**    | The visual node editor and `DialogueContainerSO` asset — where conversations are authored.                                                 |
| **Nodes**             | Individual graph nodes that define dialogue content, branching logic, and game world actions.                                              |
| **Save System**       | `DialogueSaveSystem` and `DialogueSaveData` — tracks which dialogues have been completed to prevent replaying one-time conversations.      |
| **Custom Conditions** | Flag, integer, and string-based conditions for controlling branching logic within graphs.                                                  |

***

### Node Types at a Glance

| Node                         | Purpose                                                          |
| ---------------------------- | ---------------------------------------------------------------- |
| **Start**                    | Entry point for every dialogue graph                             |
| **End**                      | Terminates the conversation                                      |
| **Simple Dialogue**          | Displays a line of text from a named speaker                     |
| **Choice**                   | Presents player-selectable options, branching the graph          |
| **Wait**                     | Pauses execution for a specified duration                        |
| **True / False**             | Branches based on a condition (quest state, dialogue flag, etc.) |
| **Random**                   | Randomly selects one of several output paths                     |
| **Quest**                    | Starts, completes, or manipulates a quest                        |
| **Audio**                    | Plays an audio clip                                              |
| **Malbers Event**            | Fires a Malbers `MEvent`                                         |
| **Malbers Character Action** | Triggers a character action via the Malbers controller           |
| **Reactions 2**              | Triggers a Malbers Reactions 2 asset                             |
| **Cinemachine Dialogue**     | Blends to a Cinemachine virtual camera for the conversation      |
| **Modal Window**             | Displays a modal confirmation or information window              |

***

### Design Principles

* **Visual-first** — Conversations are built in a graph editor, not in code or data files. The flow of a dialogue is visible at a glance.
* **Non-destructive** — Dialogue graphs are ScriptableObject assets. Changing a graph does not require scene modifications.
* **Integrated** — The system connects natively to quests (via Quest nodes and `QuestEventReporter`), the Malbers Animation system (via Character Action and Reactions 2 nodes), and Cinemachine cameras.
* **Save-aware** — One-time dialogues are tracked by `DialogueSaveSystem`. Triggers recheck their completed state after a save load, ensuring players are never re-shown conversations they have already seen.