forked from Sokomine/yl_speak_up
297 lines
13 KiB
Markdown
297 lines
13 KiB
Markdown
|
|
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.
|
|
|
|
Chat commands
|
|
=============
|
|
|
|
/npc_talk_style Allows to select the formspec version:
|
|
1: Very rudamentary. Not recommended.
|
|
2: Shows additional buttons for up and down.
|
|
3: Default (recommended) version. Scroll via mouse wheel.
|
|
|
|
/npc_talk_debug Allows to debug dialogs.
|
|
|
|
/npc_talk_privs grant, revoke or list the privs of NPC. NPC need privs for
|
|
some dangerous things like executing lua code. Examples:
|
|
/npc_talk_privs list lists the privs of all NPC
|
|
/npc_talk_privs grant n_3 effect_exec_lua
|
|
grants NPC n_3 the right to execute
|
|
lua code as an effect/result
|
|
Note: If a precondition or effect originates from a generic
|
|
NPC, the priv will be considered granted if the
|
|
executing NPC or the the generic NPC has the priv.
|
|
|
|
Terminology
|
|
===========
|
|
dialog A text said by the NPC, with diffrent replys the player can
|
|
select from.
|
|
|
|
option A reply/answer to the text the NPC said.
|
|
|
|
precondition/ All listed preconditions have to be true in order for the NPC
|
|
prerequirement to offer this option.
|
|
|
|
action An action the player may (or may not) take, i.e. trading,
|
|
taking an item from the NPC, giving the NPC something, entering
|
|
the right password etc.
|
|
|
|
effect/result Further effects (like setting variables, handing out items)
|
|
that take place after the action was successful.
|
|
|
|
alternate text Text shown instead of the normal dialog text.
|
|
|
|
How to configure NPC and add dialogs
|
|
====================================
|
|
There are two ways:
|
|
1. Just talk to them and click on the "I am your owner"-Dialog. This opens up
|
|
a menu where you can edit most things.
|
|
2. Use /giveme to get the staff you want, wield the staff and point it at the
|
|
NPC you want to change. This is much more powerful. Lua code can be
|
|
entered and later executed by the NPC.
|
|
|
|
Hint: The command "/npc_talk_debug <npc_id>" allows you to get debug
|
|
information regarding preconditions and effects. You can turn it
|
|
off with "/npc_talk_debug off". The NPC ID can be seen in the
|
|
setup dialog for preconditions and effects.
|
|
|
|
The privs
|
|
=========
|
|
npc_talk_owner will allow players to edit their *own* NPC by talking to them.
|
|
Does *not* include usage of the staffs!
|
|
Ought to be given to all players.
|
|
|
|
npc_talk_master allows players to edit *any* NPC supported by this mod.
|
|
Does *not* include usage of the staffs!
|
|
Ought to be given to selected trusted players who want to
|
|
help others with their NPC configuration and/or support
|
|
NPCs owned by the server.
|
|
|
|
npc_master allows players to edit *any* NPC supported by this mod.
|
|
*Does* include usage of the staffs.
|
|
This is very powerful and allows to enter and execute lua
|
|
code without restrictions.
|
|
Only grant this to staff members you really trust.
|
|
|
|
|
|
NPC can have privs as well. The NPC...
|
|
|
|
precon_exec_lua ..is allowed to excecute lua code as a precondition
|
|
|
|
effect_exec_lua ..is allowed to execute lua code as an effect
|
|
|
|
effect_give_item ..can give items to the player, created out of thin air
|
|
|
|
effect_take_item ..can accept and destroy items given to it by a player
|
|
|
|
effect_move_player ..can move the player to another position
|
|
|
|
|
|
Tools
|
|
=====
|
|
There are diffrent staffs for diffrent functionality:
|
|
Staff of.. does:
|
|
..I-said-so edit what the NPC says (extremly powerful)
|
|
..shut-up mute the NPC
|
|
..dawai-dawai un-mute the NPC
|
|
..game-over remove the NPC (but not its data)
|
|
..fashion change skin etc.
|
|
|
|
Be careful: With the staffs, you can add more than one result of the type
|
|
"dialog" - which will confuse the NPC and lead to unexpected results. Use
|
|
the staffs only with care!
|
|
|
|
Mute
|
|
====
|
|
When you edit an NPC, you might want to stop it from talking to other players
|
|
and spoiling unifinished texts/options to the player.
|
|
|
|
For this case, the NPC can be muted. This works either with the staff or by
|
|
selecting the appropriate option in the talk menu after having started edit
|
|
mode by claiming to be the NPC's owner.
|
|
|
|
Skin
|
|
====
|
|
The skin and what the NPC wields can be changed via the "Edit Skin" button.
|
|
|
|
|
|
Simple variables
|
|
================
|
|
If you want to let your NPC greet the player by name, you can do so. Some
|
|
variables/texts are replaced appropriately in the text the NPC says and
|
|
the player can reply:
|
|
|
|
$MY_NAME$ will be replaced by the name of the NPC
|
|
$NPC_NAME$ same as above
|
|
$OWNER_NAME$ will be replaced by the name of the owner of the NPC
|
|
$PLAYER_NAME$ will be replaced by the name of the player talking to the NPC
|
|
$GOOD_DAY$ will be replaced by "Good morning", "Good afternoon" or
|
|
"Good evening" - depending on the ingame time of day
|
|
$good_DAY$ same as above, but starts with a lowercase letter (i.e.
|
|
"good morning")
|
|
|
|
Note: If you want to extend this, you can do the following in your own mod:
|
|
|
|
local old_function = yl_speak_up.replace_vars_in_text
|
|
yl_speak_up.replace_vars_in_text = function(text, dialog, pname)
|
|
-- do not forget to call the old function
|
|
text = old_function(text, dialog, pname)
|
|
-- do your own replacements
|
|
text = string.gsub(text, "$TEXT_TO_REPLACE$", "new text")
|
|
-- do not forget to return the new text
|
|
return text
|
|
end
|
|
|
|
The replacements will not be applied in edit mode.
|
|
|
|
|
|
Trading (simple)
|
|
================
|
|
The NPC can trade item(stacks) with other players.
|
|
Only undammaged items can be traded.
|
|
Items that contain metadata (i.e. written books, petz, ..) cannot be traded.
|
|
Dammaged items and items containing metadata cannot be given to the NPC.
|
|
|
|
Trades can either be attached to dialog options (and show up as results there)
|
|
via the edit options dialog or just be trades that are shown in a trade list.
|
|
The trade list can be accessed from the NPC's inventory.
|
|
|
|
Trades cannot be added with the staffs.
|
|
|
|
If there are trades that ought to show up in the general trade list (i.e. not
|
|
only be attached to dialog options), then a button "Let's trade" will be shown
|
|
as option for the first dialog.
|
|
|
|
Trades that are attached to the trade list (and not dialog options) can be
|
|
added and deleted without entering edit mode ("I am your owner. ...").
|
|
|
|
If unsure where to put your trades: If your NPC wants to tell players a story
|
|
about what he sells (or if it is i.e. a barkeeper), put your trades in the
|
|
options of dialogs. If you just want to sell surplus items to other players
|
|
and have the NPC act like a shop, then use the trade list.
|
|
|
|
|
|
Quest items
|
|
===========
|
|
Quest items can be *created* to some degree as part of the *action* of an
|
|
*option* through the edit options menu.
|
|
|
|
MineTest does not allow to create truely new items on a running server on
|
|
the fly. What can be done is giving specific items (i.e. *that* one apple,
|
|
*that* piece of paper, *that* stack of wood, ..) a new description that
|
|
makes it diffrent from all other items of the same type (i.e. all other
|
|
apples).
|
|
|
|
A new description alone may also be set by the player with the engraving
|
|
table (provided that mod is installed):
|
|
https://forum.minetest.net/viewtopic.php?t=17482
|
|
|
|
In order to distinguish items created by your NPC and those created through
|
|
the engraving table or other mods, you can set a special ID. That ID will
|
|
also contain the name of the player to which the NPC gave the item. Thus,
|
|
players can't just take the quest items of other players from their bones
|
|
and solve quests that way.
|
|
|
|
The actions *npc_gives* and *npc_wants* are responsible for handling of
|
|
quest items. They can of course also handle regular items.
|
|
|
|
If an NPC creates a special quest item for a player in the *npc_gives*
|
|
action, it takes the item out of its inventory from a stack of ordinary
|
|
items of that type and applies the necessary modifications (change
|
|
description, set special quest ID, set information which player got it).
|
|
|
|
If the NPC gets such a quest item in an *npc_wants* action, it will check
|
|
the given parameters. If all is correct, it will strip those special
|
|
parameters from the item, call the action a success and store the item
|
|
in its inventory without wasting space (the item will likely stack if it
|
|
is *not* a quest item).
|
|
|
|
Entering Passwords
|
|
==================
|
|
Another useful method for quests is the *text_input* action. It allows the
|
|
NPC to ask for a passwort or the answer to a question the NPC just asked.
|
|
The player's answer is checked against the *expected answer* that you give
|
|
when you set up this action.
|
|
|
|
Custom Preconditions, Actions and Effects
|
|
=========================================
|
|
You can define custom actions and provide a parameter. The function
|
|
yl_speak_up.get_fs_action_custom(player, param)
|
|
gets called when such a function is executed and ought to return a formspec.
|
|
Input ought to be sent to the function
|
|
yl_speak_up.input_fs_action_custom(player, formname, fields)
|
|
which acts as an example of what you need to take care of in your own
|
|
implementation of this function.
|
|
|
|
You can also define custom preconditions and effects. For more information,
|
|
take a look at
|
|
custrom_functions_you_can_override.lua
|
|
In order to add custom functions, you need to be able to edit that file or
|
|
execute Lua code on the server.
|
|
|
|
NPC may need extra privs for some actions.
|
|
|
|
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.
|
|
|
|
Autoselect/Autoanswer
|
|
=====================
|
|
Sometimes you may wish to i.e. greet the player who has been sent on a mission
|
|
or who is well known to the NPC in a diffrent way.
|
|
For that purpose, you can use the option in the edit options menu right next to
|
|
"..the player may answer with this text [dialog option "o_<nr>"]:" and switch that
|
|
from "by clicking on it" to "automaticly".
|
|
When the NPC shows a dialog, it will evaluate all preconditions of all options. But
|
|
once it hits an option where selecting has been set to "automaticly" and all other
|
|
preconditions are true, it will abort processing the current dialog and move on to
|
|
the dialog stated in the automaticly selected option/answer and display that one.
|
|
|
|
Giving things to the NPC
|
|
========================
|
|
There are several ways of giving items to the NPC: trade, using an action where the
|
|
NPC wants a more or less special item, or an effect/result where the NPC just removes
|
|
the item from the player's inventory and thrashes it (requires npc_master priv).
|
|
Using an action might work in many situations. There may be situations where it
|
|
would be far more convenient for the player to just give the items to the NPC and let
|
|
it deal with it.
|
|
In order to activate this functionality, just enter edit mode and select the option
|
|
"I want to give you something.".
|
|
A new dialog named "d_got_item" will be created and an option shown to players in the
|
|
very first dialog where they can tell the NPC that they want to give it something.
|
|
The dialog "d_got_item" can have options like any other dialog - except that autoselect
|
|
will be activated for each option. If there are no options/answers to this dialog or
|
|
none fits, the NPC will offer the items back automaticly.
|
|
Please make sure each option of the dialog "d_got_item" has a precondition that
|
|
inspects what was offered:
|
|
"an item the player offered/gave to the NPC" (precondition)
|
|
and an effect/result that deals with the item:
|
|
"an item the player offered to the NPC" (effect)
|
|
Else the items will just be offered back to the player.
|
|
|
|
Configuration
|
|
=============
|
|
Please make sure that the tables
|
|
yl_speak_up.blacklist_effect_on_block_<type> with <type>:
|
|
<interact|place|dig|punch|right_click|put|take>
|
|
contain all the blocks which do not allow the NPCs this kind of
|
|
interaction.
|
|
You may i.e. set the put and take tables for blocks that do extensive
|
|
checks on the player object which the NPC simply can't provide.
|