Let NPC talk in Minetest (like in RPGs/point&click) [yl_speak_up]

This mod allows to set RPG-like texts for NPC where the NPC "says" something to the player and the player can reply with a selection of given replies - which most of the time lead to the next dialog.

Original author: AliasAlreadyTaken/Bastrabun Massive rewrite/extension: Sokomine

Table of Content

1. Tutorial
2. Chat Commands
3. [Terminology] (#terminology)
4. [Special dialogs] (#special-dialogs")
5. [How to configure NPC and add dialogs] (#how-to-configure)
6. [The privs] (#privs)
7. [Tools] (#tools)
8. [Mute] (#mute)
9. [Skin] (#skin)
10. [Simple variables] (#simple-variables)
11. [Trading (simple)] (#trading-simple)
12. [Logging] (#logging)
13. [Quest items] (#quest-items)
14. [Entering Passwords] (#quest-passwords)
15. [Custom Preconditions, Actions and Effects] (#precon_action_effect)
16. [Alternate Text] (#alternate_text)
17. [Autoselect/Autoanswer] (#autoselect_autoanswer)
18. [Random Dialogs] (#random_dialogs)
19. [Maximum recursion depth] (#max_recursion_depth)
20. [Giving things to the NPC] (#npc_wants)
21. [Configuration] (#configuration)
22. [Adding local overrides for your server] (#server_overrides)
23. [Data saved in modstorage] (#modstorage)
24. [Files generated in world folder] (#files_generated)
25. [Properties] (#properties)
26. [Generic behaviour] (#generic_behaviour)
27. [Integration into your own NPC/mob mods] (#integration)

1. Tutorial

There is an NPC that explains a few things and adds as a tutuor. His savefile is: n_1.json Copy that file to the folder /yl_speak_up_dialogs/n_1.json (replace the 1 with a higher number if you already have some NPC defined) The first NPC in your world will become a tutor (after you spawned it and set its name).

2. Chat commands

/npc_talk_style Allows to select the formspec version:

• 1: Very rudamentary. Not recommended.
• 2: Shows additional buttons for up and down.
• 3: Default (recommended) version. Scroll via mouse wheel.

/npc_talk_debug Allows to debug dialogs.

/npc_talk_privs grant, revoke or list the privs of NPC. NPC need privs for

             some dangerous things like executing lua code. Examples:
             `/npc_talk_privs list`     lists the privs of all NPC
             `/npc_talk_privs grant n_3 effect_exec_lua`
                                       grants NPC n_3 the right to execute
                                       lua code as an effect/result
             Note: If a precondition or effect originates from a generic
                   NPC, the priv will be considered granted if either the
                   executing NPC or the the generic NPC has the priv.

/npc_talk_generic Add or remove NPC from the list of generic dialog providers.

             `/npc_talk_generic list`      Lists all generic NPC
             `/npc_talk_generic add n_3`   Adds the dialog from NPC as a
                                           generic dialog.
             `/npc_talk_generic add n_3`   Removes the dialog from NPC as a
                                           generic dialog.
	   Requires the privs priv.

/npc_talk_reload Reload almost all of the code of this mod.

	When you add custom new functions to this mod or change a
	custom function - or even code of the mod itself! -, you can
	reload this mod without having to restart the server.
	If you made an error and the files can't load then your
	server will crash - so please test on a test server first!
	   Requires the privs priv.

/npc_talk_force_edit Toggles edit mode.

	From now on (until you issue this command again), all NPC you
	talk to will be in edit mode (provided you are allowed to
	edit them). This is useful if something's wrong with your NPC
	like i.e. you made it select a dialog automaticly and let
	that dialog lead to d_end.

3. Terminology

dialog A text said by the NPC, with diffrent replys the player can select from.

option A reply/answer to the text the NPC said.

precondition/ All listed preconditions have to be true in order for the NPC prerequirement to offer this option.

action An action the player may (or may not) take, i.e. trading, taking an item from the NPC, giving the NPC something, entering the right password etc.

effect/result Further effects (like setting variables, handing out items) that take place after the action was successful.

alternate text Text shown instead of the normal dialog text. This is useful when you have a dialog with a lot of questions and want the player to be able to easily select the next question without having to create a new dialog for each option.

4. Special dialogs

In general, dialogs follow the naming schem "d_". However, some few have a special meaning:

d_end End the conversation (i.e. after teleporting the player). d_got_item The NPC got something and is trying to decide what to do with it.

5. How to configure NPC and add dialogs

There are two ways:

1. Just talk to them and click on the "I am your owner"-Dialog. This opens up a menu where you can edit most things.
2. Use /giveme to get the staff you want, wield the staff and point it at the NPC you want to change. This is much more powerful. Lua code can be entered and later executed by the NPC.

hint: The command /npc_talk_debug <npc_id> allows you to get debug information regarding preconditions and effects. You can turn it off with /npc_talk_debug off. The NPC ID can be seen in the setup dialog for preconditions and effects.

6. The privs

npc_talk_owner will allow players to edit their own NPC by talking to them. Does not include usage of the staffs! Ought to be given to all players.

npc_talk_master allows players to edit any NPC supported by this mod. Does not include usage of the staffs! Ought to be given to selected trusted players who want to help others with their NPC configuration and/or support NPCs owned by the server.

npc_master allows players to edit any NPC supported by this mod. Does include usage of the staffs. This is very powerful and allows to enter and execute lua code without restrictions. Only grant this to staff members you really trust.

privs Necessary for the commands npc_talk_privs - grant NPC privs like e.g. execute lua npc_talk_generic - add or remove an NPC from the list of generic dialog providers

NPC can have privs as well. The NPC...

precon_exec_lua ..is allowed to excecute lua code as a precondition

effect_exec_lua ..is allowed to execute lua code as an effect

effect_give_item ..can give items to the player, created out of thin air

effect_take_item ..can accept and destroy items given to it by a player

effect_move_player ..can move the player to another position

7. Tools

There are diffrent staffs for diffrent functionality: Staff of.. does: ..I-said-so edit what the NPC says (extremly powerful) ..shut-up mute the NPC ..dawai-dawai un-mute the NPC ..game-over remove the NPC (but not its data) ..fashion change skin etc.

Be careful: With the staffs, you can add more than one result of the type "dialog" - which will confuse the NPC and lead to unexpected results. Use the staffs only with care!

8. Mute

When you edit an NPC, you might want to stop it from talking to other players and spoiling unifinished texts/options to the player.

For this case, the NPC can be muted. This works either with the staff or by selecting the appropriate option in the talk menu after having started edit mode by claiming to be the NPC's owner.

9. Skin

The skin and what the NPC wields can be changed via the "Edit Skin" button.

10. Simple variables

If you want to let your NPC greet the player by name, you can do so. Some variables/texts are replaced appropriately in the text the NPC says and the player can reply:

$MY_NAME$ will be replaced by the name of the NPC $NPC_NAME$ same as above $OWNER_NAME$ will be replaced by the name of the owner of the NPC $PLAYER_NAME$ will be replaced by the name of the player talking to the NPC $GOOD_DAY$ will be replaced by "Good morning", "Good afternoon" or "Good evening" - depending on the ingame time of day $good_DAY$ same as above, but starts with a lowercase letter (i.e. "good morning")

Note: If you want to extend this, you can do the following in your own mod:

local old_function = yl_speak_up.replace_vars_in_text
yl_speak_up.replace_vars_in_text = function(text, dialog, pname)
	-- do not forget to call the old function
	text = old_function(text, dialog, pname)
	-- do your own replacements
	text = string.gsub(text, "$TEXT_TO_REPLACE$", "new text")
	-- do not forget to return the new text
	return text
end

The replacements will not be applied in edit mode.

11. Trading (simple)

The NPC can trade item(stacks) with other players. Only undammaged items can be traded. Items that contain metadata (i.e. written books, petz, ..) cannot be traded. Dammaged items and items containing metadata cannot be given to the NPC.

Trades can either be attached to dialog options (and show up as results there) via the edit options dialog or just be trades that are shown in a trade list. The trade list can be accessed from the NPC's inventory.

Trades cannot be added with the staffs.

If there are trades that ought to show up in the general trade list (i.e. not only be attached to dialog options), then a button "Let's trade" will be shown as option for the first dialog.

Trades that are attached to the trade list (and not dialog options) can be added and deleted without entering edit mode ("I am your owner. ...").

If unsure where to put your trades: If your NPC wants to tell players a story about what he sells (or if it is i.e. a barkeeper), put your trades in the options of dialogs. If you just want to sell surplus items to other players and have the NPC act like a shop, then use the trade list.

12. Logging

The trade list view provides access to a log file where all changes to the NPC, inventory movements and purchases are logged.

The log shows the date but not the time of the action. Players can view the logs of their own NPC.

If you want to keep an NPC from logging, set the property server_nolog_effects to i.e "true" That way, the NPC will no longer log or send debug messages when executing effects.

13. Quest items

Quest items can be created to some degree as part of the action of an option through the edit options menu.

MineTest does not allow to create truely new items on a running server on the fly. What can be done is giving specific items (i.e. that one apple, that piece of paper, that stack of wood, ..) a new description that makes it diffrent from all other items of the same type (i.e. all other apples).

A new description alone may also be set by the player with the engraving table (provided that mod is installed): See Minetest Forum Engraving Table Topic

In order to distinguish items created by your NPC and those created through the engraving table or other mods, you can set a special ID. That ID will also contain the name of the player to which the NPC gave the item. Thus, players can't just take the quest items of other players from their bones and solve quests that way.

The actions npc_gives and npc_wants are responsible for handling of quest items. They can of course also handle regular items.

If an NPC creates a special quest item for a player in the npc_gives action, it takes the item out of its inventory from a stack of ordinary items of that type and applies the necessary modifications (change description, set special quest ID, set information which player got it).

If the NPC gets such a quest item in an npc_wants action, it will check the given parameters. If all is correct, it will strip those special parameters from the item, call the action a success and store the item in its inventory without wasting space (the item will likely stack if it is not a quest item).

14. Entering Passwords

Another useful method for quests is the text_input action. It allows the NPC to ask for a passwort or the answer to a question the NPC just asked. The player's answer is checked against the expected answer that you give when you set up this action.

15. Custom Preconditions, Actions and Effects

You can define custom actions and provide up to ten parameters. The file custom_functions_you_can_override.lua holds examplexs. Please do not edit that file directly. Just take a look there and override functions as needed in your own files! That way it is much easier to update.

In general, the table yl_speak_up.custom_functions_p_[ descriptive_name ] holds information about the parameters for display in the formspec (when setting up a precondition, action or effect) and contains the function that shall be executed.

16. Alternate Text

Sometimes you may encounter a situation where your NPC ought to answer to several questions and the player likely wanting an answer to each. In such a situation, you might create a dialog text for each possible option/answer and add an option to each of these new dialogs like "I have more questions.". That is sometimes impractical. Therefore, you can add alternate texts.

These alternate texts can be shown instead of the normal dialog text when the player selected an option/answer. Further alternate texts can be shown if the action (provided there is one defined for the option) or an effect failed.

The alternate text will override the text of the dialog (what the NPC says) but offer the same options/answers as the dialog normally would.

Alternate texts can be converted to normal dialogs, and normal dialogs can vice versa be converted to alternate texts if only one option/answer points to them.

17. Autoselect/Autoanswer

Sometimes you may wish to i.e. greet the player who has been sent on a mission or who is well known to the NPC in a diffrent way. For that purpose, you can use the option in the edit options menu right next to "..the player may answer with this text [dialog option "o_"]:" and switch that from "by clicking on it" to "automaticly". When the NPC shows a dialog, it will evaluate all preconditions of all options. But once it hits an option where selecting has been set to "automaticly" and all other preconditions are true, it will abort processing the current dialog and move on to the dialog stated in the automaticly selected option/answer and display that one.

18. Random Dialogs

If you want the NPC to answer with one of several texts (randomly selected), then add a new dialog with options/answers that lead to your random texts and edit one of these options so that it is "randomly" selected. Note that random selection affects the entire dialog! That dialogs' text isn't shown anymore, and neither are the texts of the options/answers shown. Whenever your NPC ends up at this dialog, he'll automaticly choose one of the options/answers randomly and continue there!

19. Maximum recursion depth

Autoselect/autoanswer and random dialogs may both lead to further dialogs with further autoanswers and/or random selections. As this might create infinite loops, there's a maximum number of "redirections" through autoanswer and random selection that your NPC can take. It is configured in config.lua as yl_speak_up.max_allowed_recursion_depth and usually set to 5.

20. Giving things to the NPC

There are several ways of giving items to the NPC: trade, using an action where the NPC wants a more or less special item, or an effect/result where the NPC just removes the item from the player's inventory and thrashes it (requires npc_master priv). Using an action might work in many situations. There may be situations where it would be far more convenient for the player to just give the items to the NPC and let it deal with it. In order to activate this functionality, just enter edit mode and select the option "I want to give you something.". A new dialog named d_got_item will be created and an option shown to players in the very first dialog where they can tell the NPC that they want to give it something. The dialog d_got_item can have options like any other dialog - except that autoselect will be activated for each option. If there are no options/answers to this dialog or none fits, the NPC will offer the items back automaticly. Please make sure each option of the dialog d_got_item has a precondition that inspects what was offered: "an item the player offered/gave to the NPC" (precondition) and an effect/result that deals with the item: "an item the player offered to the NPC" (effect) Else the items will just be offered back to the player.

21. Configuration

Please make sure that the tables yl_speak_up.blacklist_effect_on_block_ with : <interact|place|dig|punch|right_click|put|take> contain all the blocks which do not allow the NPCs this kind of interaction. You may i.e. set the put and take tables for blocks that do extensive checks on the player object which the NPC simply can't provide. Note: The best way to deal with local adjustments may be to create your own mod, i.e. yl_speak_up_addons, and let that mod depend on this one, yl_speak_up, and do the necessary calls. This is very useful for i.e. adding your own textures or doing configuration. You can then still update the mod without loosing local configuration.

22. Adding local overrides for your server

You can override and add config values by creating and adding a file local_server_config.lua in the mod folder of this mod. It will be executed after the file config.lua has been executed. This happens at startup and each time after the command /npc_talk_reload has been given.

If you want to add or override existing functions (i.e. functions from/for custom_functions_you_can_override.lua), you can create a file named local_server_do_on_reload.lua in the mod folder of this mod. It will be executed at startup and each time /npc_talk_reload is executed.

Note: If you want to register things (call minetest.register_-functions), you have to do that in the file local_server_do_once_on_startup.lua which will be executed only once after server start and not when /npc_talk_reload is executed.

23. Data saved in modstorage

status Set this to 2 to globally deactivate all NPC. amount Number of NPCs generated in this world. This is needed to create a uniqe ID for each NPC. generic_npc_list List of NPC ids whose dialogs shall be used as generic dialogs.

24. Files generated in world folder

yl_speak_up.path/ Folder containing the JSON files containing the stored dialogs of the NPC. yl_speak_up.inventory_path/ Folder containing the detatched inventories of the NPC. yl_speak_up_npc_privs.data File containing the privs of the NPC. yl_speak_up.player_vars_save_file JSON file containing information about quest progress and quest data for individual players.

25. Properties

NPC may have properties. A property is a value a particular NPC has. It does not depend on any player and will remain the same until you change it for this NPC. You can view and change properties via the "Edit" button and then clicking on "Edit properties". There are preconditions for checking properties and effects for changing them.

Properties prefixed by the text "self." originate from the NPC itself, i.e. self.order (as used by many mobs_redo NPC for either following their owner, standing around or wandering randomly). They usually cannot be changed - unless you write a function for them. See yl_speak_up.custom_property_handler and custom_functions_you_can_override.lua You can also react to or limit normal property changes this way.

Properties starting with "server" can only be changed by players who have the npc_master priv.

Example for a property: mood of the NPC (raises when treated well, gets lowered when treated badly).

Properties are also extremyl important for generic behaviour. Depending on the properties of the NPC, a particular generic behaviour might fit or not fit to the NPC.

26. Generic behaviour

Sometimes you may have a group of NPC that ought to show a common behaviour

• like for example guards, smiths, bakers, or inhabitants of a town, or other NPC that have something in common. Not each NPC may warrant its own, individual dialogs.

The Tutoial (TODO!) is another example: Not each NPC needs to present the player with a tutorial, but those that are owned and where the owner tries to program them ought to offer some help.

That's where generic dialogs come in. You can create a new type of generic dialog with any NPC. That NPC can from then on only be used for this one purpose and ought not to be found in the "normal" world! Multiple such generic dialogs and NPC for their creation can exist.

Generic dialogs have to start with a dialog with just one option. This option has to be set to "automaticly" (see Autoanswer). The preconditions of this option are very important: They determine if this particular generic dialog fits to this particular NPC or not. If it fits, all dialogs that are part of this NPC that provides the generic dialog will be added to the "normal" dialogs the importing actual NPC offers. If it doesn't fit, these generic dialogs will be ignored here.

The creator of a generic dialog can't know all situations where NPC may want to use his dialogs and where those NPC will be standing and by whom they are owned. Therefore only a limited amount of types of preconditions are allowed for the preconditions of this first automatic option: state, property, player_inv and custom.

The other dialogs that follow after this first automatic dialog may contain a few more types of preconditions: player_offered_item, function and other are allowed here as well, while block, trade, npc_inv and block_inv make no sense and are not available.

All types of actions are allowed.

Regarding effects/results, the types block, put_into_block_inv, take_from_block_inv and craft are not supported.

The "automaticly" selected only option from the start dialog leads via the usual "dialog" effect to the actual start dialog for the imported dialogs from that NPC. The options found there will be added into the target NPC and the dialog text will be appended to its dialog text.

The chat command /npc_talk_generic (requires privs priv) is used to list, add or remove NPC from the list of generic dialog/behaviour providers.

27. Integration into your own NPC/mob mods

In order to talk to NPC, you need to call if(minetest.global_exists("yl_speak_up") and yl_speak_up.talk) then yl_speak_up.talk(self, clicker) return end in the function that your NPC executes in on_rightclick. Note that capturing and placing of your NPC is not handled by yl_speak_up! Use i.e. the lasso that came with your NPC mod.