Dialogue Trees

In AsciiMason, dialogue trees can be used to create game mechanics like having conversations with NPCs (non-playable characters) or prompting the player for an action.

AsciiMason comes with a simple dialogue tree editor.

Dialogue trees are created by stringing together dialogue lines. Each dialogue line contains dialogue options for the player to choose from, which usually take the player to another dialogue line.

Dialogue lines are not tied/connected to in-game objects or object templates. Instead, the user can set an object template's onCollision function (or onActionButton function) to initiate dialogue using the `dialogueLine()` command.

## How to...

### Start a dialogue tree

1. Press the + Dialogue button in the bottom right corner of the game window.
2. Write your first line of dialogue in the provided prompt. The dialogue window will open and the line will appear there.

### Get the ID of a dialogue line

1. While a dialogue line is open in the dialogue window, its ID appears in the upper right corner.
2. To get the ID of a dialogue line which is not currently open, see Browse Dialogue Lines further down.

### Add a dialogue option

1. Click the + Add Option button above the dialogue window.
2. Fill out the text for this option that the player will see.

### Edit a dialogue option

Use the Edit Option button to modify an object's text, function, or requirement, or to edit which dialogueLine it leads to. (See dialogue option attributes below). To have an option end the dialogue, set its function to "`exitDialogue()`".

1. Click the Edit Option button above the dialogue window.
2. Select an option from the dialogue window.
3. You will be prompted to make some changes. To leave something the way it is, or to leave it blank, just press "Ok". Why does a prompt appear?

### Expand the dialogue tree

1. Make sure Auto-add Branch (above the dialogue window) is set to on. This will automatically create the next line of dialogue for you when you click on an option
2. Click on an option. You will be prompted to enter the text of the next dialogueLine. To cancel, hit 'cancel' or leave the prompt blank.

### Close the dialogue window

1. In edit mode, press the escape key on the keyboard.

**Important:** In play mode, the player can only close the dialogue window by clicking on a dialogue option that has the command "`exitDialogue()`" as a function. This is why it is very important to include "`exitDialogue()`" in the function of every dialogue option that ends the dialogue.

### With commands...

#### Delete a Dialogue Line

1. In the >> command window, select Dialogue tree commands > Delete dialogue line
2. Replace this placeholder:
	* `DIALOGUE_ID_HERE :` Integer. The ID of the dialogue line you wish to delete.

#### Browse Dialogue Lines

AsciiMason does not come with a tool for browsing a list of already-created dialogue lines. As a workaround:

1. In the >> command window, select Dialogue tree commands > [Log dialogueLines to the web console]
2. Open the web console on your browser. How do I do that?
3. You will see that a list of dialogueLines has been **logged** to the console. Expand this list by clicking on the arrow(s) next to it. You can now see which dialogueLines have which IDs.

#### Have an Object Template initiate Dialogue

1. Find out the ID of the dialogue line you wish to initiate. (See "Get the ID of a Dialogue Line" above)
2. In the >> command window, select Object commands > Object template commands > Modify object template > Action-button Function (or Collision function, if you want the dialogue to initiate right on the player's collision with this object)
3. Replace this placeholder:
	* `TEMPLATE_NAME :` String. The name of the object template you want to initiate the dialogue.
4. Press "execute".
5. In the prompt, enter `dialogueLine(DIALOGUE_ID_HERE)`, replacing DIALOGUE\_ID\_HERE with the ID of the dialogue line you wish to initiate. Why does a prompt appear?
6. When you approach an object that has that object template and press the action key (E), it should initiate the dialogue.

## Dialogue Line Attributes

`{`

`"id": DIALOGUE_ID_HERE,`

`"text": 'DIALOGUE_LINE_TEXT',`

`"options": []`

`}`

### id

Integer. The dialogue line's unique ID which can be referenced in commands.

Ex. `7`

### text

String. The text the player sees when this dialogue line is visible.

`Ex. "Would you like to exchange your coin for a soda?"`

### options

Array. The list of dialogue options that are contained in this dialogue line.

`Ex. [ {"text":"Yes"...}, {"text":"No"...} ]`

## Dialogue Option Attributes

`{`

`'text': 'TEXT_HERE',`

`'function': 'FUNCTION_HERE',`

`'requirement': 'REQUIREMENT_HERE',`

`'nextDialogue': null,`

`}`

### text

String. The line of text the player sees when this option is visible.

Ex. `"Yes, I *would* like to exchange my coin for a soda!"`

### function

String. The javascript command(s) that will be executed when the user clicks on this option. (Can be left blank). Include `'exitDialogue();'` in your function to allow the player to close the dialogue window. **Otherwise, the player will not be able to close the dialogue window.**

Ex. "`addToInventory('soda',1); addToInventory('coin',-1); exitDialogue();"`

### requirement

String. A javascript condition that is required to be true for this dialogue option to display.

Ex. `"inventoryCount('coin') >= 1"`

### nextDialogue

The ID of the line of dialogue that comes next if the player selects this option. If this dialogue option does not lead to more options, it is set to "null".

`Ex. 7`