whosit/yl_speak_up
2
0
Fork 0
forked from Sokomine/yl_speak_up
Code Pull Requests Activity

improved README.md: added chapter local overrides for your server; added table of content; reformatted for markdown format

Browse Source
This commit is contained in:
Sokomine 2023-01-28 23:02:34 +01:00
parent af250b2a77
commit 359664b4ef
1 changed files with 212 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

324
README.md
View File

@ -1,47 +1,84 @@
# 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.
Tutorial
========
Original author: AliasAlreadyTaken/Bastrabun
Massive rewrite/extension: Sokomine
## 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)
### 1. Tutorial
<a name="tutorial"></a>
There is an NPC that explains a few things and adds as a tutuor.
His savefile is: n_1.json
His savefile is: `n_1.json`
Copy that file to the folder
<your wold folder>/yl_speak_up_dialogs/n_1.json
(replace the 1 with a higher number if you already have some NPC defined)
The first NPC in your world will become a tutor (after you spawned it
and set its name).
Chat commands
=============
/npc_talk_style Allows to select the formspec version:
1: Very rudamentary. Not recommended.
2: Shows additional buttons for up and down.
3: Default (recommended) version. Scroll via mouse wheel.
### 2. Chat commands
<a name="chat-commands"></a>
/npc_talk_debug Allows to debug dialogs.
#### `/npc_talk_style` Allows to select the formspec version:
* 1: Very rudamentary. Not recommended.
* 2: Shows additional buttons for up and down.
* 3: Default (recommended) version. Scroll via mouse wheel.
/npc_talk_privs grant, revoke or list the privs of NPC. NPC need privs for
#### `/npc_talk_debug` Allows to debug dialogs.
#### `/npc_talk_privs` grant, revoke or list the privs of NPC. NPC need privs for
some dangerous things like executing lua code. Examples:
/npc_talk_privs list lists the privs of all NPC
/npc_talk_privs grant n_3 effect_exec_lua
`/npc_talk_privs list` lists the privs of all NPC
`/npc_talk_privs grant n_3 effect_exec_lua`
grants NPC n_3 the right to execute
lua code as an effect/result
Note: If a precondition or effect originates from a generic
NPC, the priv will be considered granted if either the
executing NPC or the the generic NPC has the priv.
/npc_talk_generic Add or remove NPC from the list of generic dialog providers.
/npc_talk_generic list Lists all generic NPC
/npc_talk_generic add n_3 Adds the dialog from NPC as a
generic dialog.
/npc_talk_generic add n_3 Removes the dialog from NPC as a
generic dialog.
#### `/npc_talk_generic` Add or remove NPC from the list of generic dialog providers.
`/npc_talk_generic list` Lists all generic NPC
`/npc_talk_generic add n_3` Adds the dialog from NPC as a
generic dialog.
`/npc_talk_generic add n_3` Removes the dialog from NPC as a
generic dialog.
Requires the privs priv.
/npc_talk_reload Reload almost all of the code of this mod.
#### `/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.
@ -49,8 +86,10 @@ Chat commands
server will crash - so please test on a test server first!
Requires the privs priv.
Terminology
===========
### 3. Terminology
<a name="terminology"></a>
dialog A text said by the NPC, with diffrent replys the player can
select from.
@ -71,17 +110,20 @@ alternate text Text shown instead of the normal dialog text. This is useful
player to be able to easily select the next question without
having to create a new dialog for each option.
Special dialogs
===============
### 4. Special dialogs
<a name="special-dialogs"></a>
In general, dialogs follow the naming schem "d_<nr>". However, some few have a
special meaning:
d_end End the conversation (i.e. after teleporting the player).
d_got_item The NPC got something and is trying to decide what to do with it.
`d_end` End the conversation (i.e. after teleporting the player).
`d_got_item` The NPC got something and is trying to decide what to do with it.
### 5. How to configure NPC and add dialogs
<a name="how-to-configure"></a>
How to configure NPC and add dialogs
====================================
There are two ways:
1. Just talk to them and click on the "I am your owner"-Dialog. This opens up
a menu where you can edit most things.
@ -89,49 +131,52 @@ There are two ways:
NPC you want to change. This is much more powerful. Lua code can be
entered and later executed by the NPC.
Hint: The command "/npc_talk_debug <npc_id>" allows you to get debug
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
off with `/npc_talk_debug off`. The NPC ID can be seen in the
setup dialog for preconditions and effects.
The privs
=========
npc_talk_owner will allow players to edit their *own* NPC by talking to them.
Does *not* include usage of the staffs!
Ought to be given to all players.
### 6. The privs
<a name="privs"></a>
`npc_talk_owner` will allow players to edit their *own* NPC by talking to them.
Does *not* include usage of the staffs!
Ought to be given to all players.
npc_talk_master allows players to edit *any* NPC supported by this mod.
Does *not* include usage of the staffs!
Ought to be given to selected trusted players who want to
help others with their NPC configuration and/or support
NPCs owned by the server.
`npc_talk_master` allows players to edit *any* NPC supported by this mod.
Does *not* include usage of the staffs!
Ought to be given to selected trusted players who want to
help others with their NPC configuration and/or support
NPCs owned by the server.
npc_master allows players to edit *any* NPC supported by this mod.
*Does* include usage of the staffs.
This is very powerful and allows to enter and execute lua
code without restrictions.
Only grant this to staff members you really trust.
`npc_master` allows players to edit *any* NPC supported by this mod.
*Does* include usage of the staffs.
This is very powerful and allows to enter and execute lua
code without restrictions.
Only grant this to staff members you really trust.
privs Necessary for the commands
npc_talk_privs - grant NPC privs like e.g. execute lua
npc_talk_generic - add or remove an NPC from the list of
generic dialog providers
`privs` Necessary for the commands
`npc_talk_privs` - grant NPC privs like e.g. execute lua
`npc_talk_generic` - add or remove an NPC from the list of
generic dialog providers
NPC can have privs as well. The NPC...
precon_exec_lua ..is allowed to excecute lua code as a precondition
`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_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_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_take_item` ..can accept and destroy items given to it by a player
effect_move_player ..can move the player to another position
`effect_move_player` ..can move the player to another position
Tools
=====
### 7. Tools
<a name="tools"></a>
There are diffrent staffs for diffrent functionality:
Staff of.. does:
..I-said-so edit what the NPC says (extremly powerful)
@ -144,8 +189,10 @@ Be careful: With the staffs, you can add more than one result of the type
"dialog" - which will confuse the NPC and lead to unexpected results. Use
the staffs only with care!
Mute
====
### 8. Mute
<a name="mute"></a>
When you edit an NPC, you might want to stop it from talking to other players
and spoiling unifinished texts/options to the player.
@ -153,28 +200,31 @@ For this case, the NPC can be muted. This works either with the staff or by
selecting the appropriate option in the talk menu after having started edit
mode by claiming to be the NPC's owner.
Skin
====
### 9. Skin
<a name="skin"></a>
The skin and what the NPC wields can be changed via the "Edit Skin" button.
Simple variables
================
### 10. Simple variables
<a name="simple-variables"></a>
If you want to let your NPC greet the player by name, you can do so. Some
variables/texts are replaced appropriately in the text the NPC says and
the player can reply:
$MY_NAME$ will be replaced by the name of the NPC
$NPC_NAME$ same as above
$OWNER_NAME$ will be replaced by the name of the owner of the NPC
$PLAYER_NAME$ will be replaced by the name of the player talking to the NPC
$GOOD_DAY$ will be replaced by "Good morning", "Good afternoon" or
"Good evening" - depending on the ingame time of day
$good_DAY$ same as above, but starts with a lowercase letter (i.e.
"good morning")
`$MY_NAME$` will be replaced by the name of the NPC
`$NPC_NAME$` same as above
`$OWNER_NAME$` will be replaced by the name of the owner of the NPC
`$PLAYER_NAME$` will be replaced by the name of the player talking to the NPC
`$GOOD_DAY$` will be replaced by "Good morning", "Good afternoon" or
"Good evening" - depending on the ingame time of day
`$good_DAY$` same as above, but starts with a lowercase letter (i.e.
"good morning")
Note: If you want to extend this, you can do the following in your own mod:
```
local old_function = yl_speak_up.replace_vars_in_text
yl_speak_up.replace_vars_in_text = function(text, dialog, pname)
-- do not forget to call the old function
@ -184,12 +234,13 @@ yl_speak_up.replace_vars_in_text = function(text, dialog, pname)
-- do not forget to return the new text
return text
end
```
The replacements will not be applied in edit mode.
Trading (simple)
================
### 11. Trading (simple)
<a name="trading-simple"></a>
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.
@ -213,8 +264,9 @@ 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.
Logging
=======
### 12. Logging
<a name="logging"></a>
The trade list view provides access to a log file where all changes to the
NPC, inventory movements and purchases are logged.
@ -223,8 +275,9 @@ The log shows the date but not the time of the action. Players can view the
logs of their own NPC.
Quest items
===========
### 13. Quest items
<a name="quest-items"></a>
Quest items can be *created* to some degree as part of the *action* of an
*option* through the edit options menu.
@ -236,7 +289,7 @@ apples).
A new description alone may also be set by the player with the engraving
table (provided that mod is installed):
https://forum.minetest.net/viewtopic.php?t=17482
<a href="https://forum.minetest.net/viewtopic.php?t=17482">See Minetest Forum Engraving Table Topic</a>
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
@ -258,29 +311,35 @@ 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).
Entering Passwords
==================
### 14. Entering Passwords
<a name="quest-passwords"></a>
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.
Custom Preconditions, Actions and Effects
=========================================
### 15. Custom Preconditions, Actions and Effects
<a name="precon_action_effect"></a>
You can define custom actions and provide up to ten parameters. The file
custom_functions_you_can_override.lua
`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 ]
`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.
Alternate Text
==============
### 16. Alternate Text
<a name="alternate_text"></a>
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
@ -298,8 +357,10 @@ 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.
Autoselect/Autoanswer
=====================
### 17. Autoselect/Autoanswer
<a name="autoselect_autoanswer"></a>
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
@ -310,8 +371,10 @@ once it hits an option where selecting has been set to "automaticly" and all oth
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.
Random Dialogs
==============
### 18. Random Dialogs
<a name="random_dialogs"></a>
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.
@ -320,39 +383,45 @@ anymore, and neither are the texts of the options/answers shown. Whenever your N
ends up at this dialog, he'll automaticly choose one of the options/answers randomly
and continue there!
Maximum recursion depth
=======================
### 19. Maximum recursion depth
<a name="max_recursion_depth"></a>
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
`yl_speak_up.max_allowed_recursion_depth`
and usually set to 5.
Giving things to the NPC
========================
### 20. Giving things to the NPC
<a name="npc_wants"></a>
There are several ways of giving items to the NPC: trade, using an action where the
NPC wants a more or less special item, or an effect/result where the NPC just removes
the item from the player's inventory and thrashes it (requires npc_master priv).
the item from the player's inventory and thrashes it (requires `npc_master` priv).
Using an action might work in many situations. There may be situations where it
would be far more convenient for the player to just give the items to the NPC and let
it deal with it.
In order to activate this functionality, just enter edit mode and select the option
"I want to give you something.".
A new dialog named "d_got_item" will be created and an option shown to players in the
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
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
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.
Configuration
=============
### 21. Configuration
<a name="configuration"></a>
Please make sure that the tables
yl_speak_up.blacklist_effect_on_block_<type> with <type>:
<interact|place|dig|punch|right_click|put|take>
@ -366,16 +435,43 @@ Note: The best way to deal with local adjustments may be to create your
for i.e. adding your own textures or doing configuration. You can
then still update the mod without loosing local configuration.
Data saved in modstorage
========================
### 22. Adding local overrides for your server
<a name="server_overrides"></a>
You can override and add config values by creating and adding a file
local_server_config.lua
in the mod folder of this mod. It will be executed after the file
config.lua
has been executed. This happens at startup and each time after the command
/npc_talk_reload has been given.
If you want to add or override existing functions (i.e. functions from/for
custom_functions_you_can_override.lua), you can create a file named
local_server_do_on_reload.lua
in the mod folder of this mod. It will be executed at startup and each time
/npc_talk_reload is executed.
Note: If you want to register things (call minetest.register_-functions),
you have to do that in the file
local_server_do_once_on_startup.lua
which will be executed only *once* after server start and *not* when
/npc_talk_reload is executed.
### 23. Data saved in modstorage
<a name="modstorage"></a>
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.
Files generated in world folder
===============================
### 24. Files generated in world folder
<a name="files_generated"></a>
yl_speak_up.path/ Folder containing the JSON files containing the
stored dialogs of the NPC.
yl_speak_up.inventory_path/ Folder containing the detatched inventories of
@ -385,8 +481,9 @@ yl_speak_up.player_vars_save_file JSON file containing information about
quest progress and quest data for individual
players.
Properties
==========
### 25. Properties
<a name="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
@ -412,8 +509,10 @@ Properties are also extremyl important for generic behaviour. Depending
on the properties of the NPC, a particular generic behaviour might fit
or not fit to the NPC.
Generic behaviour
=================
### 26. Generic behaviour
<a name="generic_behaviour"></a>
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
@ -462,8 +561,9 @@ The chat command /npc_talk_generic (requires privs priv) is used to list,
add or remove NPC from the list of generic dialog/behaviour providers.
Integration into your own NPC/mob mods
======================================
### 27. Integration into your own NPC/mob mods
<a name="integration"></a>
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)