diff --git a/readme.md b/readme.md index 05b2ee5..8538eb4 100644 --- a/readme.md +++ b/readme.md @@ -23,153 +23,161 @@ TODO: This mod will be made available soon. ## Table of Content -1. [Tutorial](#tutorial) -2. [Chat Commands](#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) -28. [Future](#future) - - -### 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 - `/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). - - -### 2. Chat Commands - - -In general, chat commands used by this mod have the form `/npc_talk []`. - - | Command | Description | - | ------- | ----------- | - | `style ` | Allows to select the formspec version with `` beeing 1, 2 or 3. Important for very old clients.| - | `list` | Shows a list of all your NPC and where they are.| - | `debug []` | Toggle debug mode for NPC ``. 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`. | - | `privs list` | List the privs of all NPC. NPC need privs for some dangerous things like executing lua code.| - | `privs grant ` | grant NPC `` the priv ``| - | `privs revoke ` | revoke priv `` for NPC ``| - | `force_restore_npc []` | Restore an NPC that got lost. Only for emergencies.| - | `generic list` | list all NPC that provide generic dialogs| - | `generic add ` | add NPC `` as a new provider of generic dialogs| - | `generic remove ` | remove NPC `` as a provider of generic dialogs| - | `generic reload` | reload data regarding generic dialogs| - - -* Most commands need extra privs. Only `style `, `list`, `debug []` and `force_edit` are available to all players. - -* `/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. - -* The diffrent npc talk styles are: - | Style | Useful for | - | ---------- | ----------- | - | `/npc_talk style 1` | Very rudamentary. Not recommended. Only use with really ancient clients.| - | `/npc_talk style 2` | Shows additional buttons for up and down. Might help users of mobile clients. If they report problems, recommend them this option.| - | `/npc_talk style 3` | Default (recommended) version. Scroll via mouse wheel between the options. | - -* 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. - -* The `force_restore_npc` is rarely needed. You only need it if the NPC entity and its spawn egg got lost. It may have got lost due to someone having misplaced its egg. Or it might have been killed somehow.
The optional parameter `` 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. +1. [For players: How to use it as a player](#for-players) + 1. [1.1 Terminology](#terminology) + 1. [1.2 How it works](#how-it-works) + 1. [1.3 How to configure NPC and add dialogs](#how-to-configure) + 1. [1.4 Skin](#skin) + 1. [1.5 Mute](#mute) + 1. [1.6 Chat Commands for players](#chat-commands-players) + 1. [1.7 Simple replacements (NPC name, player name etc)](#simple-variables) + 1. [1.8 Alternate Text](#alternate_text) + 1. [1.9 Autoselect/Autoanswer](#autoselect_autoanswer) + 1. [1.10 Random Dialogs](#random_dialogs) + 1. [1.11 Maximum recursion depth](#max_recursion_depth) + 1. [1.12 Changing the start dialog](#start_dialog) + 1. [1.13 Special dialogs](#special-dialogs) + 1. [1.14 Trading (simple)](#trading-simple) + 1. [1.15 Quest items](#quest-items) + 1. [1.16 Entering Passwords](#quest-passwords) + 1. [1.17 Giving things to the NPC](#npc_wants) + 1. [1.18 Quests](#quests) + 1. [1.19 Properties](#properties) + 1. [1.20 Logging](#logging) + +2. [For moderators: Generic NPCs](#for-moderators) + 1. [2.1 Generic behaviour](#generic_behaviour) + 1. [2.2 Chat Commands for moderators](#chat-commands-moderators) + +3. [For server owners: What to consider as a server owner](#server-owners) + 1. [3.1 Tutorial](#tutorial) + 1. [3.2 The privs](#privs) + 1. [3.3 Chat Commands for server owners](#chat-commands-owners) + 1. [3.4 Reload mod without server restart](#hotreload) + 1. [3.5 Restoring a lost NPC](#npc_restore) + 1. [3.6 Tools](#tools) + 1. [3.7 Configuration](#configuration) + 1. [3.8 Adding local overrides for your server](#server_overrides) + 1. [3.9 Data saved in modstorage](#modstorage) + 1. [3.10 Files generated in world folder](#files_generated) + 1. [3.11 Additional custom replacements (in addition to NPC name, player name etc)](#add-simple-variables) + 1. [3.12 Custom Preconditions, Actions and Effects](#precon_action_effect) + 1. [3.13 Integration into your own NPC/mob mods](#integration) + +4. [Future](#future) +## 1. For players: How to use it as a player -### 3. Terminology - | Word used | What it means | - | -------------- | ------------- | - | 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. The player selects one by clicking on it.| - | precondition/
prerequirement | All listed preconditions have to be true in order for the NPC to offer an 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. The action happens after the option is selected by the player.| - | 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.| - | 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.| +You need: +* the `npc_talk_owner` [priv](#privs) +* 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_`] | + | option | A reply/answer to the text the NPC said. The player selects one by clicking on it. [`o_`] | + | precondition/
prerequirement | All listed preconditions have to be true in order for the NPC to offer an option. [`p_`] | + | 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_`] | + | 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_`]| + | 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 - +### 1.2 How it works + -In general, dialogs follow the naming schem `d_`. However, some few have a -special meaning: - | Dialog | Meaning | - | ---------------- | ------- | - | `d_` | 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.| +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. *Note:* As a player, you have no influence on this. +* [Autoselect/Autoanswer](#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](#random_dialogs), 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](#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)) +* execute Lua code (requires `npc_master` [priv](#privs)) - 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](#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 +* _deal_ (accept or refuse) an item the player offered to the NPC - [the last thing the player gave to the NPC](#npc_wants)) +* 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. -### 5. How to configure NPC and add dialogs +### 1.3 How to configure NPC and add dialogs -Just talk to them and click on the `"I am your owner"`-Dialog. This opens up +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. -Hint: The command `/npc_talk debug ` allows you to get debug +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 ` 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 - +### 1.4 Skin + - | 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| +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](#integration). -### 7. Tools - - -There are no more tools (=staffs) provided. You can do all you could do -with them by just talking to the NPC. The staffs are deprecated. - - -### 8. Mute +### 1.5 Mute When you edit an NPC, you might want to stop it from talking to other players @@ -180,13 +188,23 @@ option in the talk menu after having started edit mode by claiming to be the NPC's owner. -### 9. Skin - +### 1.6 Chat Commands for players + -The skin and what the NPC wields can be changed via the `"Edit Skin"` button. +In general, chat commands used by this mod have the form `/npc_talk []`. + + | Command | Description | + | ------- | ----------- | + | `style ` | Allows to select the formspec version with `` beeing 1, 2 or 3. Important for very old clients.| + | `list` | Shows a list of all your NPC and where they are.| + | `debug []` | Toggle debug mode for NPC ``. 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](#chat-commands-server) that require [further privs](#privs) for some special functionality (i.e. [generic NPC behaviour](#generic_behaviour)). -### 10. Simple variables +### 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 @@ -202,22 +220,93 @@ in the options the player can select from: | `$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"`)| -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. +Servers can define [additional custom replacements](#add-simple-variables). -### 11. Trading (simple) + +### 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_"]:"` 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](#generic_behaviour). 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_`. However, some few have a +special meaning: + | Dialog | Meaning | + | ---------------- | ------- | + | `d_` | Normal dialog. They are automaticly numbered. | + | `d_end` | End the conversation (i.e. after teleporting the player). | + | `d_got_item` | The NPC [got something](#npc_wants) and is trying to decide what to do with it. | + | `d_trade` | [Trade](#trading-simple)-specific options. I.e. crafting new items when stock is low.| + + +### 1.14 Trading (simple) The NPC can trade item(stacks) with other players. @@ -242,30 +331,16 @@ 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 +### 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. +[Quest](#quests) 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 +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). @@ -279,130 +354,289 @@ 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 +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* +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 +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). +is _not_ a quest item). -### 14. Entering Passwords +### 1.16 Entering Passwords -Another useful method for quests is the *text_input* action. It allows the +Another useful method for [quests](#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 +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 +### 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 +* [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 - or whichever priv you set in config.lua as `yl_speak_up.npc_privs_priv`). +* 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. -
In order to activate this functionality, just enter edit mode and select the option +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 +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 + +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.. + +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"`. -### 21. Configuration + +### 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](#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. + + + + + +## 2. For moderators: Generic NPCs + + +You need: +* the `npc_talk_admin` [priv](#privs) + +With this priv you can edit and maintain NPC that show [generic behaviuor](#geeric_behaviour) +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](#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 + + +In general, chat commands used by this mod have the form `/npc_talk []`. + +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 ` | add NPC `` as a new provider of generic dialogs| + | `generic remove ` | remove NPC `` 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 + `/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](#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 | Description | + | ------- | ----------- | + | `privs list` | List the privs of all NPC. NPC need privs for some dangerous things like executing lua code.| + | `privs grant ` | grant NPC `` the priv ``| + | `privs revoke ` | revoke priv `` for NPC ``| + +* 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](#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 + + +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 []` + +The optional parameter `` 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 @@ -413,14 +647,14 @@ 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 +_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 +### 3.8 Adding local overrides for your server * You can override and add config values by creating and adding a file @@ -439,10 +673,10 @@ in the mod folder of this mod. It will be executed at startup and each time `/np ``` local_server_do_once_on_startup.lua ``` -which will be executed only *once* after server start and *not* when `/npc_talk_reload` is executed. +which will be executed only _once_ after server start and _not_ when `/npc_talk_reload` is executed. -### 23. Data saved in modstorage +### 3.9 Data saved in modstorage | Variable | Usage | @@ -452,7 +686,7 @@ which will be executed only *once* after server start and *not* when `/npc_talk_ | `generic_npc_list` | List of NPC ids whose dialogs shall be used as generic dialogs. | -### 24. Files generated in world folder +### 3.10 Files generated in world folder | Path/File name | Content | @@ -465,64 +699,46 @@ which will be executed only *once* after server start and *not* when `/npc_talk_ | `yl_speak_up.player_vars_save_file` | JSON file containing information about quest progress and quest data for individual players. | -### 25. Properties - +### 3.11 Additional custom replacements (in addition to NPC name, player name etc) + -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. +In addition to the [simple replacements (NPC name, player name etc)](#simple-variables), +a server owner can add server-specific replacements as needed. -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 +In order to do this, add the following in your own mod: +```lua +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` -You can also react to or limit normal property changes this way. +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. -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. +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. -### 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 `npc_talk_admin` 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 +### 3.13 Integration into your own NPC/mob mods In order to talk to NPC, you need to call -``` +```lua if(minetest.global_exists("yl_speak_up") and yl_speak_up.talk) then yl_speak_up.talk(self, clicker) return @@ -537,7 +753,13 @@ You also need to make sure that the textures of your mob can be edited. In order * add an entry in `yl_speak_up.mob_skins[] = {"skin1.png", "skin2.png", "another_skin.png"}` * call `table.insert(yl_speak_up.emulate_orders_on_rightclick, )` 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. -### 28. Future + + + + +## 4. Future Creating quests is possible but not very convincing yet. It is too tedious and errorprone. I'm working on a better mechanism. + +