Apple Hills Dialogue System

This document provides an overview of the dialogue system used in Apple Hills, intended primarily for designers working with the dialogue creation tools.

Overview

The Apple Hills dialogue system is a node-based dialogue management system that allows for interactive conversations with NPCs. The system currently supports linear, condition-guarded dialogue paths that can respond to various game conditions such as puzzle completion, item pickups, and item combinations. While the architecture was designed to facilitate branching dialogue in future extensions, the current implementation follows a linear progression through nodes.

Dialogue Structure

The dialogue system uses a graph-based structure with different types of nodes that control the flow of conversation. Each dialogue is represented as a graph containing multiple nodes connected through defined paths.

Core Components

1. RuntimeDialogueGraph: The container for all dialogue nodes that make up a conversation
2. DialogueComponent: Attached to game objects to manage dialogue state and progression
3. SpeechBubble: Handles the visual presentation of dialogue text

QuickStart Guide

Setting up a dialogue interaction in your scene is straightforward:

1. Component Setup

1. Place the Dialogue Component:

   • Add the DialogueComponent to any game object that has an Interactable component
   • The Interactable component handles player proximity and interaction triggers
   • Make sure the interactable is properly configured with appropriate interaction radius

2. Add DialogueCanvas:

   • Add the "DialogueCanvas" prefab from the project assets as a child of your object
   • Position the speech bubble appropriately above or near the interactable object
   • The speech bubble should be clearly visible but not obstruct important scene elements
   • You can adjust the scale and position to fit your specific character or object

3. Assign Dialogue Graph:

   • Create a RuntimeDialogueGraph scriptable object (Right Click > Create > Dialogue Graph)
   • Set up your dialogue nodes in the graph (see Node Types for details)
   • Assign the created graph to the DialogueComponent on your object
   • Make sure to set the entry node ID in the dialogue graph

2. Testing Your Dialogue

1. Enter play mode and approach the interactable object
2. When the component has any lines to serve, the speech bubble should display the prompt ("...")
3. Interact with the object to advance through dialogue lines
4. Test any conditional nodes by completing their requirements
5. Verify that the dialogue progresses as expected

3. Common Issues

• No speech bubble appears: Check that the DialogueCanvas is properly added as a child and is active
• Dialogue doesn't advance: Ensure the node connections (in/out) are properly set in the dialogue graph
• Condition not triggering: Verify that the condition IDs (puzzle step, item, etc.) match exactly with your game systems

Node Types

The dialogue system supports several node types, each serving a specific purpose in the conversation flow:

1. Dialogue Node

Simple dialogue nodes display text to the player. They can contain multiple lines that are shown sequentially when the player interacts with the NPC.

Key features:

• Multiple dialogue lines displayed in sequence
• Optional looping through lines
• Automatic progression to the next node when all lines are exhausted

2. WaitOnPuzzleStep Node

This node pauses dialogue progression until a specific puzzle step has been completed by the player.

Key features:

• Automatically advances when the specified puzzle step is completed
• Displays dialogue while waiting for the condition to be met
• Visual prompt appears when the condition is met, indicating available dialogue

3. WaitOnPickup Node

This node waits until the player has picked up a specific item before advancing the dialogue.

Key features:

• Automatically advances when the player picks up the specified item
• Shows dialogue while waiting for the item pickup
• Visual prompt appears when the item is picked up, indicating available dialogue

4. WaitOnSlot Node

This node requires the player to place a specific item in a designated slot before the dialogue can progress.

Key features:

• Supports different dialogue lines for different slot states:
  • Default lines when no item is slotted
  • Incorrect item lines when the wrong item is placed
  • Forbidden item lines when a specifically disallowed item is placed
• Visual prompt appears when the correct item is slotted, indicating available dialogue

5. WaitOnCombination Node

This node waits for the player to create a specific item through the combination system.

Key features:

• Automatically advances when the player creates the specified item through combination
• Shows dialogue while waiting for the item combination
• Visual prompt appears when the item is created, indicating available dialogue

6. End Node

Terminates the dialogue sequence.

Key features:

• Marks the dialogue as completed
• No further interaction available until the dialogue is restarted

Dialogue Flow

1. Dialogue Initialization

   • When a dialogue is started (often through character interaction), the system begins at the entry node
   • Each node's dialogue lines are displayed in sequence as the player interacts

2. Interaction Mechanism

   • Dialogue advances when the player interacts with the NPC
   • Each interaction displays the next line of dialogue
   • When all lines in a node are displayed, the system moves to the next node (unless waiting on a condition)

3. Conditional Progress

   • When the dialogue reaches a conditional node (like WaitOnPuzzleStep), it waits for the condition to be met
   • Once the condition is satisfied, the speech bubble shows a prompt
   • The next interaction after the condition is met advances to the next node

4. Visual Indicators

   • Speech bubbles show ellipses ("...") as a prompt when dialogue is available
   • The dialogue text can be displayed instantly or with a typewriter effect
   • The speech bubble hides when no dialogue is available

Designer Tips

1. Node Organization

   • Start every dialogue graph with a standard Dialogue node as the entry point
   • End every dialogue path with an End node to properly terminate the conversation
   • Use conditional nodes strategically to create gameplay-driven dialogue experiences

2. Dialogue Writing

   • Keep individual dialogue lines concise for better readability
   • Consider using the looping option for nodes when you want to repeat information
   • For WaitOnSlot nodes, write unique dialogue for incorrect/forbidden items to provide clear feedback

3. Flow Control

   • Ensure all nodes (except End nodes) have a valid next node specified
   • Test dialogue paths to verify all conditions can be met during gameplay
   • Consider using multiple dialogue lines within a single node rather than creating separate nodes for sequential lines

4. Best Practices

   • Name your nodes descriptively in the editor for easier management
   • Group related dialogue sequences into separate dialogue graphs
   • Use the speaker name field to clearly identify who is speaking

Technical Details

Public Events and APIs

The dialogue system exposes several events that can be used by other systems:

DialogueComponent

• Events:

  • OnDialogueChanged: Triggered when the dialogue text changes

• Properties:

  • IsActive: Indicates whether the dialogue is currently active
  • IsCompleted: Indicates whether the dialogue has reached an End node
  • CurrentSpeakerName: Returns the name of the current speaker

• Public Methods:

  • StartDialogue(): Initiates the dialogue from the beginning
  • GetCurrentDialogueLine(): Retrieves the current dialogue line text
  • HasAnyLines(): Checks if the dialogue component has any lines available
  • SetDialogueGraph(RuntimeDialogueGraph): Sets the dialogue graph for the component

SpeechBubble

• Public Methods:
  • Show(): Makes the speech bubble visible
  • Hide(): Hides the speech bubble
  • Toggle(): Toggles the visibility of the speech bubble
  • SetText(string): Sets the text displayed in the speech bubble
  • DisplayDialogueLine(string, bool): Displays a dialogue line and handles prompt visibility
  • UpdatePromptVisibility(bool): Updates the speech bubble to show a prompt or hide based on dialogue availability
  • SetDisplayMode(TextDisplayMode): Changes how text is displayed (instant or typewriter)
  • SkipTypewriter(): Immediately displays the full text, skipping the typewriter effect
  • SetTypewriterSpeed(float): Sets the speed of the typewriter effect

Integration with Other Systems

The dialogue system integrates with several other game systems:

1. Puzzle System: Monitors puzzle completion events to advance WaitOnPuzzleStep nodes
2. Item System: Tracks item pickups, combinations, and slot interactions to advance respective node types
3. Interaction System: Responds to player interaction with the NPC to progress through dialogue lines

Technical Workflow

1. Create a RuntimeDialogueGraph asset in the Unity editor
2. Add nodes and connections using the dialogue editor
3. Assign the graph to a DialogueComponent on an NPC GameObject
4. Ensure a SpeechBubble component is available (as a child object or referenced)
5. Set up any necessary puzzle steps, items, or slots that the dialogue will reference

Summary

The Apple Hills dialogue system provides a powerful and flexible way to create interactive conversations that respond to player actions and game state. By using different node types and conditions, designers can craft engaging dialogues that feel natural and responsive within the game world.