OUTDATED Conversation framework

OUTDATED

There is two ways to create a sentence that is displayed on the screen.

pr0_fnc_dialogue_createSimple - Useful for single sentences.

pr0_fnc_dialogue_create - Used when you want to create complex conversations.

Say simple sentence (pr0_fnc_dialogue_createSimple)

[_unit_1, "_sentence", _loudness] call pr0_fnc_dialogue_createSimple;

* _unit_1 [Object]: unit who is talking	
* _sentence [String, Array]: text to be spoken by unit, can be an array of strings (random one will be chosen). 
* _loudness [Float](optional): hearing distance multiplier default 1	

Creating coversation between two units (pr0_fnc_dialogue_create)

There are four steps that need to be taken to make an conversation.

Creating and registering a dialogue array

All conversations are placed in a array as followed:

_dialogue_array = [
	DEFAULT_EVENT,
	NODE_1,
	NODE_2,
	....
];

To register the dialogue so it can be used by the frame work we use:

[_dialogue_id,_dialogue_array] call pr0_fnc_dialogue_registerDataSet;

* _dialogue_id: must be an unequal string
* _dialogue_array: an array of all nodes in the dialogue (explained later).

with the new dialogue register we can now add it to a unit. We need to use the same _dialogue_id as you register above

Add dialogues to an unit (or object)

To let the framework know what dialogue can be used for a specific unit we need to call the following:

[_unit,_dialogue_id_array] call pr0_fnc_dialogue_setDataSets;

* _unit [Object]: the unit or object
* _dialogue_id_array [Array, String]: an array of dialogue_ids or a dialogue_id that the unit can use.

or

[_unit,_dialogue_id] call pr0_fnc_dialogue_removeDataSet;
[_unit,_dialogue_id] call pr0_fnc_dialogue_addDataSet;

* _unit [Object]: the unit or object
* _dialogue_id [String]: dialogue_id that the unit can use.

Starting a conversation

To start a conversation between two units you use:

[_unit_1, _unit_2, "_node_id", {script}, _args] call pr0_fnc_dialogue_create;

* _unit_1 [Object]: unit who is talking to _unit_2.
* _unit_2 [Object]: unit who is talking to _unit_1. (can't be the player, player is always _unit_1)
* _node_id[String]: The ID of the conversation you want to play
* _script[Script](optional): Script you like to execute after the conversation is over (or aborted)
	params["_unit_1 ","_unit_2 ","_args"];
* _args[Any](optional): Arguments you like to pass to all scripts that are run inside the conversation

Creating custom dialogues

All dialogue is stored in an array which we call the dialogue and has an equal dialogue_id. Inside this dialogue are one ore more nodes. a node has a node_id and a array of actions. The array of actionsis placed in an script, to allow for customization on run-time. A node can look like the following:

["node_id",{
	params ["_unit_1","_unit_2","_arg"]
	[
		[TYPE_SENTENCE, "Hello, player", 2],
		[TYPE_SENTENCE, "Hello, AI", 1],
		[TYPE_JUMP_TO, "next_node_id"],
		[TYPE_EVENT_WALKED_AWAY,{
			params ["_unit_1","_unit_2","_arg","_arg_event"];
			_unit_1 setDamage _arg_event;
		},1]
	]
}]

Action Types

every action inside the node needs to start with a type.

TYPE_SENTENCE

Use this when you want to create a sentence.

[TYPE_SENTENCE, _text, _int_speaker, {script}, _args];
* _text[String,Array]: the text that will be displayed. This can be a simple string or a array of strings.
			When a array is given the framework will chose one randomly
* _int_speaker[Int]: 1 or 2 depending on who you want to speak
* _script[Script](optional): Script that needs to be called when the sentence is shown
* _args[Any](optional): Arguments you like to pass too the _script 

TYPE_SENTENCE_SILENCE

Use this when you want to create a silence sentence (usefull for hints). It only shows up for the player who has the conversation, so other players wont see this.

[TYPE_SENTENCE_SILENCE, _text, {script}, _args];
* _text[String,Array]: the text that will be displayed. This can be a simple string or a array of strings.
			When a array is given the framework will chose one randomly
* _script[Script](optional): Script that needs to be called when the sentence is shown
* _args[Any](optional): Arguments you like to pass too the _script 

TYPE_QUESTION and TYPE_QUESTION_SILENCE

When you want to a question you need both a TYPE_QUESTION and also TYPE_OPTION. TYPE_QUESTION is used for the question it self and is used like this:

[TYPE_QUESTION, _text, {script}, _args];
* _text[String,Array]: the text that will be displayed. This can be a simple string or a array of strings.
			When a array is given the framework will chose one randomly
* _script[Script](optional): Script that needs to be called when the question is asked
* _args[Any](optional): Arguments you like to pass too the _script 

TYPE_ANSWER, TYPE_ANSWER_SILENCE, TYPE_ANSWER_AI and TYPE_JUMP_TO

With this types you can move to new nodes. TYPE_ANSWER_XXX needs to be used in combination with TYPE_QUESTION. TYPE_ANSWER_AI is used when a question is asked to a npc. TYPE_JUMP_TO is used when the node doesnt contain a question.

[TYPE_XXX, _jump,{script}, _args];
* _jump[String]: This is the converation_id (node_id) that is called if this option is selected
* _script[Script](optional): Script that needs to be called when the question is asked
* _args[Any](optional): Arguments you like to pass too the _script 

jumping to node "#end" causes the conversation to end

Events

Events can be placed in both dialogue and node arrays. When you place it in the dialogue array it will behave as default. When you place it in a node it will overwrite the default.

TYPE_EVENT_XXX

There are a few events that can happen that causes the conversation to end. The event types are used when you want something to happen in such a case. The following events are available:

* TYPE_EVENT_WALKED_AWAY	triggers when player walks away when he was asked a question
* TYPE_EVENT_OUT_OF_TIME	triggers when player 
* TYPE_EVENT_DEATH		triggers when one of the units was killed
* TYPE_EVENT_UNEXPECTED_END	triggers when one of the above events occur
* TYPE_EVENT_END		triggers when the conversation is ended (always runs)

And are used as followed:

[TYPE_EVENT_XXX,{script}, _args];
* _script[Script](optional): Script that needs to be called when the question is asked
* _args[Any](optional): Arguments you like to pass too the _script 

Combining dialogues

To make even more fancy dialogue you can register multiple dialogues to a unit.

["NODE_ID",TYPE,{
	ACTION_1,
	ACTION_2,
	...
}]

There are 3 types:

TYPE_CREATE

This is the default and doesnt need to be used. When no type is given like the following TYPE_CREATE is used.

["NODE_ID",{
	ACTION_1,
	ACTION_2,
	...
}]

TYPE_OVERWRITE

This type will overwrite nodes with the same node_id

TYPE_INHERIT

This type will use the existing node and add or replace actions

TYPE_ANSWER_AI, TYPE_JUMP_TO, TYPE_ON_WALKED_AWAY, TYPE_ON_OUT_OF_TIME, TYPE_ON_DEATH, TYPE_ON_UNEXPECTED_END