Add dialogue API documentation (WIP)

Dev_Dialogues.md

@@ -0,0 +1,88 @@
+## Dialogues API
+
+__How dialogues work__
+
+Every time a NPC is spawned, it gets a number of dialogues assigned to it. These dialogues are randomly selected based on specific criteria. A dialogue is 'tagged' with different categories, which makes it possible to search by criteria.
+
+
+__Registering dialogues and the dialogue definition__
+
+Dialogues are registered when the mod is loaded at Minetest's start time. The registered dialogues are in the random data (if file is included, `data\dialogues_data.lua`) and any occupation definition that register dialogues. Dialogues are registered using the following API method:
+
+```lua
+npc.dialogue.register_dialogue(def)
+```
+
+The `def` argument is a Lua table that can have the following attributes:
+```lua
+dialogue = {
+		text = "",
+		-- ^ The "spoken" dialogue line
+		flag =
+		-- ^ If the flag with the specified name has the specified value
+		-- then this dialogue is valid
+		{
+			name = "",
+			-- Name of the flag
+			value = ""
+			-- Expected value of the flag. A flag can be a function. In such a case, it is
+			-- expected the function will return this value.
+		},
+		tags = {
+			-- Tags are an array of string that allow to classify dialogues
+			-- A dialogue can have as many tags as desired and can take any form.
+			-- However, for consistency, some predefined tags can be found at
+			-- npc.dialogue.tags.
+			-- Example:
+			"phase1",
+			"any"
+		},
+		responses = {
+			-- Array of responses the player can choose. A response can be of
+			-- two types: as [1] or as [2] (see example below)
+			[1] = {
+				text = "Yes",
+				-- Text displayed to the player
+				action_type = "dialogue",
+				-- Type of action that happens when the player chooses this response.
+				--  can be "dialogue" or "function". This example shows "dialogue"
+				action = {
+					text = "It's so beautiful, and big, and large, and infinite, and..."
+				},
+			},
+			-- A table containing a dialogue. This means you can include not only
+			-- text but also flag and responses as well. Dialogues are recursive.
+			[2] = {
+				text = "No",
+				action_type = "function",
+				action = function(self, player)
+					-- A function will have access to self, which is the NPC
+					-- and the player, which is the player ObjectRef. You can
+					-- pretty much do anything here. The example here is very simple,
+					-- just sending a chat message. But you can add items to players
+					-- or to NPCs and so on.
+					minetest.chat_send_player(player:get_player_name(), "Oh, ok...")
+				end,
+			},
+		}
+	}
+```
+In the above definition, you can see that the `responses` array is actually an array of Lua tables defining more dialogue objects. Therefore, in this sense, dialogues can be recursive. You can have a dialogue have many responses which produces many dialogues.
+
+Also, dialogues can do more than just showing text. A response can have parameter `action_type = "function"`, which means the `action` will actually define a function, `function(self, player)`. The player here is the full Player object in Minetest and not just the name. 
+ 
+You can see more examples in `data\dialogues_data.lua` and `data\occupations_data.lua`.
+
+
+__Tags__
+
+Tags are a fundamental part of the dialogue system. A dialogue definition can have as many tags as you want. When a new NPC is created, it will search dialogues that have *at least* one of the following tags:
+* "unisex",
+* "male" or "female", depending on the NPC's sex,
+* "phase1" (this is for dialogues related to a NPC's relationship phase)
+
+Dialogues can be searched using the following API function:
+```lua
+npc.dialogue.search_dialogue_by_tags(tags, find_all)
+```
+In the above function, `tags` is a Lua array of tags and `find_all` is a boolean value. If true, the function will only return those dialogues that have ___all___ the tags in the `tags` array. If false (or not given), it will return all dialogues that have ___at least___ one tag in the `tags` array.