yl_speak_up/README.md

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