Dev_Dialogues

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:

npc.dialogue.register_dialogue(def)

The def argument is a Lua table that can have the following attributes:

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:

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.