forked from your-land-mirror/yl_speak_up
further improved README.md
This commit is contained in:
Sokomine
parent
5b1035a19e
commit
c6fef779ac
173
README.md
173
README.md
@ -7,13 +7,27 @@ which most of the time lead to the next dialog.
|
||||
Original author: AliasAlreadyTaken/Bastrabun
|
||||
Massive rewrite/extension: Sokomine
|
||||
|
||||
## Quick installation
|
||||
|
||||
TODO License: comming soon (GPLv3.0 or later planned)
|
||||
|
||||
Reporting bugs: TODO
|
||||
|
||||
Clone via i.e. `git clone https://gitea.your-land.de/Sokomine/yl_speak_up`
|
||||
|
||||
Optional dependency: `mobs_redo` is recommended. You may be able to use other mob mods with manual adjustments as well (This is for very advanced users).
|
||||
|
||||
This mod does not provide any NPC as such. You need a mod that does so.
|
||||
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)
|
||||
5. [How to configure NPC and add dialogs](#how-to-configure)
|
||||
6. [The privs](#privs)
|
||||
7. [Tools](#tools)
|
||||
8. [Mute](#mute)
|
||||
@ -36,6 +50,7 @@ Massive rewrite/extension: Sokomine
|
||||
25. [Properties](#properties)
|
||||
26. [Generic behaviour](#generic_behaviour)
|
||||
27. [Integration into your own NPC/mob mods](#integration)
|
||||
28. [Future](#future)
|
||||
|
||||
|
||||
### 1. Tutorial
|
||||
@ -391,15 +406,16 @@ Else the items will just be offered back to the player.
|
||||
<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>
|
||||
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
|
||||
```
|
||||
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.
|
||||
<br>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
|
||||
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
|
||||
|
||||
* 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.
|
||||
|
||||
@ -407,73 +423,73 @@ Note: The best way to deal with local adjustments may be to create your
|
||||
### 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.
|
||||
* 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.
|
||||
* 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.
|
||||
* 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.
|
||||
| Variable | Usage |
|
||||
| ------------------ | ------- |
|
||||
| `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. |
|
||||
|
||||
|
||||
### 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
|
||||
the NPC.
|
||||
yl_speak_up_npc_privs.data File containing the privs of the NPC.
|
||||
yl_speak_up.player_vars_save_file JSON file containing information about
|
||||
quest progress and quest data for individual
|
||||
players.
|
||||
| Path/File name | Content |
|
||||
| ----------------------------------- | ------- |
|
||||
| `yl_speak_up.path` | Directory containing the JSON files containing the stored dialogs of the NPC. |
|
||||
| `yl_speak_up.inventory_path` | Directory containing the detatched inventories of the NPC. |
|
||||
| `yl_speak_up.log_path` | Directory containing the logfiles of the NPC. |
|
||||
| `yl_speak_up.quest_path` | Directory containing information about quests. |
|
||||
| `yl_speak_up_npc_privs.data` | File containing the privs of the NPC. |
|
||||
| `yl_speak_up.player_vars_save_file` | JSON file containing information about quest progress and quest data for individual players. |
|
||||
|
||||
|
||||
### 25. Properties
|
||||
<a name="properties"></a>
|
||||
|
||||
NPC may have properties. A property is a value a particular NPC has. It
|
||||
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
|
||||
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
|
||||
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
|
||||
`yl_speak_up.custom_property_handler`
|
||||
and
|
||||
custom_functions_you_can_override.lua
|
||||
`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
|
||||
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
|
||||
Example for a property: Mood of the NPC (raises when treated well, gets
|
||||
lowered when treated badly).
|
||||
|
||||
Properties are also extremyl important for generic behaviour. Depending
|
||||
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.
|
||||
|
||||
@ -481,64 +497,47 @@ or not fit to the NPC.
|
||||
### 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
|
||||
dialogs.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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 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.
|
||||
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.
|
||||
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 `"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.
|
||||
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
|
||||
<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)
|
||||
return
|
||||
end
|
||||
in the function that your NPC executes in on_rightclick.
|
||||
Note that capturing and placing of your NPC is *not* handled by yl_speak_up!
|
||||
```
|
||||
in the function that your NPC executes in `on_rightclick`.
|
||||
Note that capturing and placing of your NPC is *not* handled by `yl_speak_up`!
|
||||
Use i.e. the lasso that came with your NPC mod.
|
||||
|
||||
You also need to make sure that the textures of your mob can be edited. In order to do so,
|
||||
* add an entry in `yl_speak_up.mesh_data[<model.b3d>]` for your model
|
||||
* add an entry in `yl_speak_up.mob_skins[<entity_name>] = {"skin1.png", "skin2.png", "another_skin.png"}`
|
||||
* call `table.insert(yl_speak_up.emulate_orders_on_rightclick, <entity_name>)` if your mob is a `mobs_redo` one and can stand, follow (its owner) and walk around randomly. As you override `on_rightclick`, this setting will make sure to add buttons to emulate previous behaviour shown when clicking on the NPC.
|
||||
|
||||
### 28. Future
|
||||
<a name="future"></a>
|
||||
|
||||
Creating quests is possible but not very convincing yet. It is too tedious and errorprone. I'm working on a better mechanism.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user