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/aka Bastrabun Massive rewrite/extension: Sokomine

Quick installation

License: From now (24.03.2024) on (but not past versions), this mod (minus the editor, which is now a seperate mod) is available under the MIT license. License of textures (yl_speak_up_bg_dialog*.png plus masks): AliasAlreadyTaken/aka Bastrabun CC0

Reporting bugs: Please report issues here.

Clone via i.e. git clone https://gitea.your-land.de/Sokomine/yl_speak_up or install via ContentDB.

In order to be able to edit the dialogs of the NPC ingame, please install npc_talk_edit. The only situation where you might not need this extra mod is when you design your own adventure game and your players are not expected to edit the NPC.

Optional dependency: mobs_redo is highly recommended. You may be able to use other mob mods with manual adjustments as well (This is for very advanced users).

This mod here does not provide any NPC as such. You need a mod that does so. The mod npc_talk adds the actual NPC. It is highly recommended to use npc_talk or to create your own according to your needs.

You might also wish to use mobs_npc from TenPlus1 as that mod provides very useful actual NPC and will be used by npc_talk if installed.

To get started, best install yl_speak_up, npc_talk_edit, npc_talk, mobs_redo and mobs_npc in your world.

Table of Content

1. For players: How to use it as a player

   1. 1.1 Terminology
   2. 1.2 How it works
   3. 1.3 How to configure NPC and add dialogs
   4. 1.4 Skin
   5. 1.5 Mute
   6. 1.6 Chat Commands for players
   7. 1.7 Simple replacements (NPC name, player name etc)
   8. 1.8 Alternate Text
   9. 1.9 Autoselect/Autoanswer
   10. 1.10 Random Dialogs
   11. 1.11 Maximum recursion depth
   12. 1.12 Changing the start dialog
   13. 1.13 Special dialogs
   14. 1.14 Trading (simple)
   15. 1.15 Quest items
   16. 1.16 Entering Passwords
   17. 1.17 Giving things to the NPC
   18. 1.18 Quests
   19. 1.19 Properties
   20. 1.20 Logging
   21. 1.21 Export/Import
   22. 1.22 Storing internal notes
   23. 1.23 Counting visits to dialogs and options

2. For moderators: Generic NPCs

   1. 2.1 Generic behaviour
   2. 2.2 Chat Commands for moderators

3. For server owners: What to consider as a server owner

   1. 3.1 Tutorial
   2. 3.2 The privs
   3. 3.3 Chat Commands for server owners
   4. 3.4 Reload mod without server restart
   5. 3.5 Restoring a lost NPC
   6. 3.6 Tools
   7. 3.7 Configuration
   8. 3.8 Adding local overrides for your server
   9. 3.9 Data saved in modstorage
   10. 3.10 Files generated in world folder
   11. 3.11 Additional custom replacements (in addition to NPC name, player name etc)
   12. 3.12 Custom Preconditions, Actions and Effects
   13. 3.13 Integration into your own NPC/mob mods
   14. 3.14 Dynamic dialog

4. Future

1. For players: How to use it as a player

You need:

• the npc_talk_owner priv
• an actual NPC of which you are owner
• to be able to right-click your NPC

1.1 Terminology

Word used	What it means [and how it's called; names and numbers are assigned automaticly]
dialog	A text said by the NPC, with diffrent replys the player can select from. [d_<nr>]
option	A reply/answer to the text the NPC said. The player selects one by clicking on it. [o_<nr>]
precondition/ prerequirement	All listed preconditions have to be true in order for the NPC to offer an option. [p_<nr>]
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. The action happens after the option is selected by the player. [a_<nr>]
effect/result	Further effects (like setting variables, handing out items) that take place after the action was successful. If there was no action, the effects/results will be executed directly after selecting the option. [r_<nr>]
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. [-]

1.2 How it works

When someone right-clicks your NPC, the NPC will show a dialog. Remember: The dialog is the text the NPC says to the player plus the options (or answers, choices) offered to the player.

Some texts, like i.e. the name of the NPC or its owner, can be automaticly replaced in the dialog text and the text of the options/answers.

The dialog that is to be shown is selected this way:

• At first, the NPC will usually show the start dialog.
• If the player selected an option, the target dialog of that option is shown.
• If the NPC inherits some generic behaviour, it may show another dialog or additional options.
  Note: As a player, you have no influence on this.
• Autoselect/Autoanswer may select an option automaticly if all preconditions are met and switch to a diffrent dialog.
• If the options are set to random Dialog, then an option is choosen randomly and the appropriate dialog will be shown.

Not all options of a dialog will be shown in all situations. An option/answer can have one or more preconditions. All preconditions of an option have to be true in order for the option to be offered to the player. A precondition is something that can be either true or false. This can be:

• check an internal state (i.e. of a quest) - based on a system of variables
• check the value of a property of the NPC (for generic NPC)
• something that has to be calculated or evaluated (=call a function); this can be extended with custom functions on the server
• a block somewhere (i.e. that block is cobble, or not dirt, or air, or...)
• a trade - Is the trade possible?
• the inventory of the player (contains an item or does not, has room for item etc.)
• the inventory of the NPC (similar to the player's inventory above)
• the inventory of a block somewhere (for chests, furnaces etc; similar to the player's inventory above)
• an item the player offered/gave to the NPC (react to the last thing the player gave to the NPC)
• execute Lua code (requires npc_master priv) - extremly powerful and dangerous
• The preconditions of another dialog option are fulfilled/not fulfilled.
• nothing - always true (useful for generic dialogs)
• nothing - always false (useful for temporally deactivating an option)

If the preconditions of the option the player clicked on are all true, operation proceeds with that option.

If the preconditions are not fullfilled, the NPC can show an alternate text or a greyed out text. That option cannot be selected by the player then but is visible.

There may be one action defined. Actions are situations where the NPC shows a formspec to the player and expects some reaction. When the player reacts, the NPC evaluates the action as either successful (i.e. gave the right thing, right password) or a failure. Possible actions are:

• No action (default)
• Normal trade - one item(stack) for another item(stack)
• The NPC gives something to the player (i.e. a quest item) out of its inventory.
• The player is expected to give something to the NPC (i.e. a quest item). The NPC will store it in his inventory.
• The player has to manually enter a password or passphrase or some other text.
• Show something custom (has to be provided by the server). The NPC may react diffrently when the action failed and show a diffrent dialog. It's also possible to limit how often a player may guess wrongly withhin a given timespan and how often an action may be repeated withhin a given timespan.

If the action was successful (or there was no action at all), then the effects/results are executed. Possible effects are:

• change an internal state (i.e. of a quest) - based on a system of variables
• change the value of a property of the NPC (for generic NPC)
• something that has to be calculated or evaluated (=call a function); this can be extended with custom functions on the server; Example: Set a variable to a random number.
• place, dig, punch or right-click a block somewhere
• put item from the NPC's inventory into a chest etc.
• take item from a chest etc. and put it into the NPC's inventory
• deal with (accept or refuse) an item the player offered to the NPC - the last thing the player gave to the NPC)
• NPC crafts something with the things he has in its inventory
• go to other dialog if the previous effect failed
• send a chat message to all players
• give item (created out of thin air) to player (requires extra privs for you and the NPC)
• take item from player and destroy it (requires extra privs for you and the NPC)
• move the player to a given position (requires extra privs for you and the NPC)
• execute any Lua code (requires extra privs for you and the NPC)

The effects also contain a special effect named dialog. This effect determines which dialog will be shown next if the player selected this option and all went well. The target dialog is usually set in other parts of the formspec and not set manually as an effect.

It is possible to show an alternate text instead of the normal dialog text when the target dialog is shown. This may help in situations where the NPC may have to answer a lot of questions and an extra dialog for each answer seems impractical.

1.3 How to configure NPC and add dialogs

Just talk to the NPC and click on the "I am your owner"-Dialog. This opens up a menu where you can edit most things.

Most of the basic configuration and adding of new dialogs and options can be done in the menu that pops up on rightclick. However, more advanced things such as preconditions, actions and effects can only be set in the Edit options menu. You can reach it by clicking on the button of the option, i.e. on o_1.

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.

The text the NPC says is written in the markup language Minetest uses. See lua_api.md for more details. You can use the elements of that markup language for the text that the NPC says, i.e. <img name=default_cobble.png width=100 height=100> will display the image default_cobble.png.

1.4 Skin

The skin and what the NPC wields can be changed via the "Edit Skin" button. It is also possible to set the animation the NPC shows (sitting, lying down, walking, mining etc.) if that is configured for this NPC.

1.5 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 by selecting the appropriate option in the talk menu after having started edit mode by claiming to be the NPC's owner.

1.6 Chat Commands for players

In general, chat commands used by this mod have the form /npc_talk <command> [<optional parameters>].

Command	Description
style <nr>	Allows to select the formspec version with <nr> beeing 1, 2 or 3. Important for very old clients.
list	Shows a list of all your NPC and where they are.
debug [<npc_id>]	Toggle debug mode for NPC <npc_id>. Warning: May scroll a lot.
debug off	Turn debug mode off again.
force_edit	Toggles edit mode for you. 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.

There are additional commands that require further privs for some special functionality (i.e. generic NPC behaviour).

1.7 Simple replacements (NPC name, player name etc)

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 in the options the player can select from:

Variable	will be replaced with..
$MY_NAME$	..the name of the NPC
$NPC_NAME$	..same as above (name of the NPC)
$OWNER_NAME$	..the name of the owner of the NPC
$PLAYER_NAME$	..the name of the player talking to the NPC
$GOOD_DAY$	.."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")

The replacements will not be applied in edit mode.

Servers can define additional custom replacements.

1.8 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.

1.9 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_<nr>"]:" 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.

1.10 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!

There is no way to assign weights to the options. All are choosen with equal probability.

1.11 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.

1.12 Changing the start dialog]

The start dialog is usually the first dialog of the NPC: d_1. It may sometimes become necessary to change that when your NPC gets a new (temporary?) job or when you're designing a generic NPC. You can change the start dialog easily with the options the NPC offers you when you talk to it as owner.

1.13 Special dialogs

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

Dialog	Meaning
d_<nr>	Normal dialog. They are automaticly numbered.
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.
d_trade	Trade-specific options. I.e. crafting new items when stock is low.
d_dynamic	Dynamic dialog that is changed on the fly. Each NPC has exactly one.

1.14 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.

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.

1.15 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).

1.16 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.

1.17 Giving things to the NPC

There are several ways of giving items to the NPC:

• selecting "Show me your inventory" and putting it directly into the NPC's inventory (as owner)
• trading
• 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_talk_admin priv - or whichever priv you set in config.lua as yl_speak_up.npc_privs_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. This is what the special dialog d_got_item is for.

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.

It is also possible to examine the item the NPC got using the precondition "an item the player offered/gave to the NPC".

1.18 Quests

NPC love handing out quests! Especially if they got any complex quests. A simple "bring me 10 dead rats" may not excite players or NPC much. But a true riddle, something that involves some thinking and puzzling - that's great! Every NPC which got such a quest will be proud (just search for "Epic NPC man" on youtube).

Quest handling is far from optimal yet and will be improved in the future.

In order to manage a quest, you need to store information about a player. You can create variables that will hold data for each player. That way you can remember which quest step the player has already completed.

Variables can be created and managed by adding and editing preconditions and effects of the type "an internal state (i.e. of a quest)".

Inside a precondition, you can check the value of a variable (it's always evaluated for the current player that clicked on your NPC), and in an effect you can change the value of the variable for that player.

You can also grant access to a variable you've created to other players so that they may use it in their quests and NPC.

You can also check the values for all players (regarding your own variables) and edit those values if needed.

Checking and setting quest progress currently has to be done manually. It's ongoing work to move that to the edit options menu (only partially implemented so far).

1.19 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_talk_admin priv.

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

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

1.20 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.

Admins can keep an NPC from logging by setting the property server_nolog_effects to i.e true That way, the NPC will no longer log or send debug messages when executing effects.

1.21 Export/Import

It's possible to export the full dialog data of an NPC and to view it in more human-readable form. It's also possible to export it in some degree in the format the mod simple_dialogs uses (minus preconditions, actions, effects and all other special things).

Players with the privs priv can also import those dialogs into an NPC in their local singleplayer game. But be warned: The dialog is not checked for consistency or anything yet! That is why it requires the privs priv. Don't just import any NPC data someone sends to you!

It is planned to check the dialog (.json format) more fully in the future so that players can import data on a server as well. However, we are not that far yet.

1.22 Storing internal notes

It's possible to take internal notes on your NPC by clicking on the "Notes" button. You can help your memory and store information about your plans with this NPC - its character, how it behaves and talks, who his friends are etc. These internal notes are only shown to players who can edit this NPC.

1.23 Counting visits to dialogs and options

Whenever a dialog text is displayed to the player and whenever the player selects an option which is successful (no aborted actions or on_failure effects inbetween), a counter called visits is increased by one for that dialog or option.

This information is not persistent! When the player leaves the talk by choosing Farewell! or pressing ESC all visit information is lost.

The feature can be used to help players see which options they've tried and which path they've followed. If an option is set to *once* instead of the default often in the edit options dialog, that option can only be selected once each time the player talks to this NPC. After that the option gets greyed out and displays "[Done]" followed by the normal option text.

Visits are not counted in edit mode and not counted for generic dialogs.

There are custom preconditions for checking the number of visits to a dialog and/or option.

2. For moderators: Generic NPCs

You need:

• the npc_talk_admin priv

With this priv you can edit and maintain NPC that show generic behaviuor and which may influence or override all other NPC on the server.

2.1 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 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.

Properties are very helpful for determining if a particular NPC ought to offer a generic dialog.

The entity_type precondition can also be helpful in this case. It allows to add dialogs for specific types of mobs only (i.e. npc_talk:talking_npc).

Requirements for a generic dialog to work:

• 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 npc_talk_admin priv) is used to list, add or remove NPC from the list of generic dialog/behaviour providers.

2.2 Chat Commands for moderators

In general, chat commands used by this mod have the form /npc_talk <command> [<optional parameters>].

The chat commands for players are still important and valid. In addition, commands for managing generic NPC become available:

Command	Description
generic list	list all NPC that provide generic dialogs
generic add <npc_id>	add NPC <npc_id> as a new provider of generic dialogs
generic remove <npc_id>	remove NPC <npc_id> as a provider of generic dialogs
generic reload	reload data regarding generic dialogs

3. For server owners: What to consider as a server owner

3.1 Tutorial

There is an NPC that explains a few things and adds as a tutuor.

The savefile is: n_1.json

Copy that file to the folder <your world 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 now become a tutor (after you spawned it and set its name).

3.2 The privs

Minetest priv	what this priv grants the player who has it
npc_talk_owner	will allow players to edit their own NPC by talking to them. Ought to be given to all players.
npc_talk_master	allows players to edit any NPC supported by this mod. 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_talk_admin	Generic maintenance of NPC. Allows to use the the command /npc_talk generic and add or remove an NPC from the list of generic dialog providers. Also allows to set and change NPC properties starting with the prefix "server".
npc_master	allows players to edit any NPC supported by this mod. Does include usage of the staffs (now part of yl_npc). This is very powerful and allows to enter and execute lua code without restrictions. Only grant this to staff members you really trust. The priv is usually not needed.
privs	Necessary for the commands /npc_talk privs - grant NPC privs like e.g. execute lua and /npc_talk_reload - reload code of this mod

NPC can have privs as well:

NPC priv	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

3.3 Chat Commands for server owners

The chat commands for players and the chat commands for moderators are still important and valid. In addition, commands for managing privs become available:

In general, chat commands used by this mod have the form /npc_talk <command> [<optional parameters>].

Command	Description
privs list	List the privs of all NPC. NPC need privs for some dangerous things like executing lua code.
privs grant <npc_id> <priv>	grant NPC <npc_id> the priv <priv>
privs revoke <npc_id> <priv>	revoke priv <priv> for NPC <npc_id>

• NPC need privs for some dangerous things like executing lua code.
  Example: /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.

3.4 Reload mod without server restart

The mod doesn't define any items or NPC itself. It is designed in a way that you can reload the code of this mod without having to restart the server.

The command /npc_talk_reload reloads almost all of the code of this mod.

When you add new custom 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.

3.5 Restoring a lost NPC

Sometimes (hopefully rarely!) an NPC entity and its egg may get lost. It may have got lost due to someone having misplaced its egg (happens). Or it might have been killed somehow.

In that case, you can run /npc_talk force_restore_npc <id> [<copy_from_id>]

The optional parameter <copy_from_id> is only used when the NPC is not listed in /npc_talk list. You won't need it. It's for legacy NPC.

WARNING: If the egg or the NPC turns up elsewhere, be sure to have only one NPC with that ID standing around! Else you'll get chaos.

3.6 Tools

There are no more tools (=staffs) provided. You can do all you could do with them with the staffs by just talking to the NPC. The staffs are deprecated.

Use /npc_talk force_edit if the NPC is broken and cannot be talked to normally anymore.

3.7 Configuration

Please make sure that the tables

yl_speak_up.blacklist_effect_on_block_<type> with <type>:<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.

yl_speak_up.blacklist_effect_tool_use

is a similar table. Please let it contain a list of all the tool item names that NPC are not allowed to u se.

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.

3.8 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.

3.9 Data saved in modstorage

Variable	Usage
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.

3.10 Files generated in world folder

Path/File name	Content
yl_speak_up.path	Directory containing the JSON files containing the stored dialogs of the NPC.
yl_speak_up.inventory_path	Directory containing the detatched inventories of the NPC.
yl_speak_up.log_path	Directory containing the logfiles of the NPC.
yl_speak_up.quest_path	Directory containing information about quests.
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.

3.11 Additional custom replacements (in addition to NPC name, player name etc)

In addition to the simple replacements (NPC name, player name etc), a server owner can add server-specific replacements as needed.

In order to do this, add 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

3.12 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.

3.13 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.

You also need to make sure that the textures of your mob can be edited. In order to do so,

• add an entry in yl_speak_up.mesh_data[<model.b3d>] for your model
• add an entry in yl_speak_up.mob_skins[<entity_name>] = {"skin1.png", "skin2.png", "another_skin.png"}
• call table.insert(yl_speak_up.emulate_orders_on_rightclick, <entity_name>) if your mob is a mobs_redo one and can stand, follow (its owner) and walk around randomly. As you override on_rightclick, this setting will make sure to add buttons to emulate previous behaviour shown when clicking on the NPC.

3.14 Dynamic dialogs

Sometimes you may have to generate a dialog on the fly and/or wish for more dynamic texts and answers.

Each NPC has a d_dynamic dialog that will never be saved with the NPC data and that can be changed each time the player selected an option.

This is particulary useful for using external functions for generating dialog texts and options/answers plus their reactions.

Warning: This feature is not finished yet and undergoing heavy changes. Do not rely on its functionality yet!

4. Future

Creating quests is possible but not very convincing yet. It is too tedious and errorprone. I'm working on a better mechanism.