| 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/<br>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
<aname="how-it-works"></a>
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](#simple-variables) 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](#start_dialog).
* If the player selected an option, the target dialog of that option is shown.
* If the NPC inherits some [generic behaviour](#generic_behaviour), it may show another dialog or additional options.<br>*Note:* As a player, you have no influence on this.
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](#quests)) - based on a system of [variables](#variables)
* _check_ the value of a [property of the NPC](#properties) (for [generic NPC](#generic_behaviour))
* something that has to be calculated or evaluated (=call a function); this can be extended with [custom functions](#precon_action_effect) on the server
* a block somewhere (i.e. that block is cobble, or not dirt, or air, or...)
* a [trade](#trading-simple) - 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](#npc_wants))
* 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](#trading-simple) - one item(stack) for another item(stack)
* The NPC gives something to the player (i.e. a [quest item](#quest-items)) out of its inventory.
* The player is expected to give something to the NPC (i.e. a [quest item](#quest-items)). The NPC will store it in his inventory.
* The player has to manually [enter a password or passphrase or some other text](#quest-passwords).
* Show something [custom (has to be provided by the server)](#precon_action_effect).
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](#quests)) - based on a system of [variables](#variables)
* _change_ the value of a [property of the NPC](#properties) (for [generic NPC](#generic_behaviour))
* something that has to be calculated or evaluated (=call a function); this can be extended with [custom functions](#precon_action_effect) 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
* 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](#privs) for you _and_ the NPC)
* take item from player and destroy it (requires extra [privs](#privs) for you _and_ the NPC)
* move the player to a given position (requires extra [privs](#privs) for you _and_ the NPC)
* execute any Lua code (requires extra [privs](#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](#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.
| `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.<br> 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](#chat-commands-server) that require [further privs](#privs) for some special functionality (i.e. [generic NPC behaviour](#generic_behaviour)).
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](#trading-simple)
* 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](#privs) - 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](#autoselect_autoanswer)
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:<br>`"an item the player offered/gave to the NPC" (precondition)`
* and an effect/result that deals with the item:<br>`"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
<aname="quests"></a>
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
<aname="properties"></a>
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
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](#tutorial) 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](#properties) are very helpful for determining if a particular NPC ought
to offer a generic dialog.
Requirements for a generic dialog to work:
* _Generic dialogs_ have to [start with a dialog](#start_dialog) with _just one option_.
* This _option_ has to be set to _"automaticly"_ (see [Autoanswer](#autoselect_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](#start_dialog) leads via the usual `"dialog"` effect to the actual [start dialog](#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](#privs)) is used to list, add or remove NPC from the list of generic dialog/behaviour providers.
### 2.2 Chat Commands for moderators
<aname="chat-commands-moderators"></a>
In general, chat commands used by this mod have the form `/npc_talk <command> [<optional parameters>]`.
The [chat commands for players](#chat-commands-players) are still important and valid. In addition,
commands for managing [generic NPC](#generic_behaviour) 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|
| `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.<br>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.<br>Allows to use the the command `/npc_talk generic` and add or remove an NPC from the list of generic dialog providers.<br>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`).<br>This is very powerful and allows to enter and execute lua code without restrictions.<br>Only grant this to staff members you ***really*** trust. The priv is usually not needed.|
| `privs` | Necessary for the commands<br>`/npc_talk privs` - grant NPC privs like e.g. execute lua and <br>`/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
<aname="chat-commands-owners"></a>
The [chat commands for players](#chat-commands-players) and the [chat commands for moderators](#chat-commands-moderators) are still important and valid. In addition, commands for managing [privs](#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>`|
* NPC need privs for some dangerous things like executing lua code.<br>Example: `/npc_talk privs grant n_3 effect_exec_lua`<br>grants NPC n_3 the right to execute lua code as an effect/result.<br>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.
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](#precon_action_effect) 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
<aname="npc_restore"></a>
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
<aname="tools"></a>
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.
* 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
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.
