Missions

## Overview

The missions in Horizon are built using XML. There are two types of XML files for quests: Mission and Dialogue.
See the "Sample - New Quests" mod for an example.

## Mission Files

These files layout the logical structure of the missions.
The basic layout should resemble the following:

```
<QuestGroup id="MyGroupName">
  <Quest id="MyFirstQuest">
    <Stage id="firstStage">
      <Setup>
      </Setup>
      <Listener>
      </Listener>
      <Dialogue>
        <Option>
        </Option>
      </Dialogue>
    </Stage>
  </Quest>
</QuestGroup>

```

Note: Make use of the Quests.xsd schema when writing scripts, to ensure the format is correct.

Some special characters and attributes will come in handy when writing new scripts.

### XML Nodes

#### Quest Group

This is the root node of a quest document. A quest group can contain any number of quests, so long as they do not share a quest id.
It is valid for Quest groups to be divided into multiple files.

A Quest Group can only contain the 'id' attribute and . This id attribute is referenced quite often, and it can be thought of as a type of 'namespace' for quests. (note that quest variables are global, they do not benefit from this namespace behaviour)

**Valid Children**:
* Quest (0-\*)

**Attributes**:
* id (unique name - global)

#### Quest

A quest contains "execution stages". They do not necessarily reflect in-game quests, as in a single in game 'mission' or 'quest' can be made up of many sub quests.
These can often be used as 'functions' as well. The 'LoadJournals' quest in the mod sample is a good example of this usage.

**Valid Children**:
* Stage(1-\*)

**Attributes**:
* id (unique name - per quest group)
* disableForRace (optional, Race Id)

#### Stage

Stages are essentially the 'state' that the mission is in. When a quest enters a new stage, it executes in the following order:

1. Instantiates listeners
2. Runs Setup node actions
3. Runs the Dialogue node

**Valid Children**:
* Setup(0-1)
* Listener(0-\*)
* Dialogue(0-1)

**Attributes**:
* id (unique name - per quest)

#### Setup

This node is executed immediately as the quest stage is entered.

**Valid Children**:
* Action(1-\*)

**Attributes**:
* None

#### Listener

These wait for events to be fired by the game and execute the actions specified within the body of the node once the event is caught, and the optional parameters match that of the executed event.

Note: Listeners are only active while the quest remains within the stage it is defined in.

Game Events

**Valid Children**:
* Action(1-\*)

**Attributes**:
* event (required, this is the name of the event)
* event parameters (this can be anything the event sends. It is optional to specify any parameters when listening for events, see the events table for a list of events and their optional parameters.)

#### Dialogue

A dialogue node is executed immediately after the Setup node has completed. This will result in the dialogue prompt being displayed in game, with the content specified from the associated dialogue files.

**Valid Children**:
* Option(1-3)

**Attributes**:
* file (the name of the dialogue xml file to find the content)
* dialogueId (the name of the dialogue within the specified file to use)

#### Option

An option node is essentially a button on the dialogue prompt. There is a maximum of 3 buttons per prompt, and the text that it contains is limited to these options.

**Valid Children**:
* Action(1-\*)

**Attributes**:
* textId (required - the option button text id)

#### Action

The action node is the most common node. When this node is processed, the action specified is executed with the given parameters.

**Valid Children**:
* None

**Attributes**:
* name (required - this is the name of the action to run)
* All parameters (parameters are specific to the action executed. See the action list for details.)

### Reference Tables

Actions
Dialogue Option Button Texts
Events
Race Ids
Relation Ids
Request Types
Special Mission Characters and Attributes
Tech Fields

## Dialogue Files

These files layout the logical structure of the missions. The basic layout should resemble the following:

```
 <Dialogue>
   <Item>
     <Title>
     </Title>
     <Image>
     </Image>
     <Text>
     </Text>
   </Item>
 </Dialogue>

```

Note: Make use of the Dialogue.xsd schema when writing scripts, to ensure the format is correct.

### XML Nodes

#### Dialogue

This is a required root node. Only one can exist.

**Valid Children**:
* Item (1-\*)

**Attributes**:
* None

#### Item

Each dialogue is it's own Item node.

**Valid Children**:
* Title(1)
* Image(1)
* text(1)

**Attributes**:
* id (this is the name of the dialogue, referenced by the mission layout)

#### Title

This node contains the title displayed in the dialogue window's header.

**Valid Children**:
* None

**Attributes**:
* None

#### Image

This node expects the relative path to the image displayed in the dialogue window.

eg. An image's path 'HorizonInstallPath/mods/myMod/Quests/SuperLollyPopGoons/lollyPopGoon.png' would be 'Quests/SuperLollyPopGoons/lollyPopGoon.png'

**Valid Children**:
* None

**Attributes**:
* None

#### Text

As expected, this node is the text in the dialogue box.

**Valid Children**:
* None

**Attributes**:
* None