nalc/advanced_npc
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Api doc update (#31)

Browse Source 
* Update api.md

* Add schedules
* Add occupation
* Update places map
* Fix `step` and `initialize`

* Add schedule commands

* Add WALK_TO_POS task

* orthographic correction
This commit is contained in:
BrunoMine 2017-12-20 17:40:36 -02:00 committed by Hector Kio
parent c7fad7d6c6
commit 2dc2400b38
2 changed files with 296 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
doc/actions_and_tasks.md
View File

@ -31,9 +31,48 @@ Tasks (`add_task`)
Sequence of actions that allows the NPC to use a bed.
{
pos = {x=0,y=0,z=0}, -- Position of bed to be used.
pos = {x=0,y=0,z=0}, --[[
^ Position of bed to be used.
^ Can be a coordinate x,y,z.
^ Can be a place name of the NPC place map.
Example: "bed_primary" ]]
action = action, --[[
^ Whether to get up or lay on bed
^ Defined in npc.actions.const.beds.action
^ Example: npc.actions.const.beds.action.LAY ]]
^ Available options:
* npc.actions.const.beds.LAY : lay
* npc.actions.const.beds.GET_UP : get up
}
#### `WALK_TO_POS`
NPC will walk to the given position. This task uses the pathfinder to calculate the nodes
in the path that the NPC will walk through, then enqueues walk_step actions, combined with
correct directional rotations and opening/closing of doors on the path.
{
end_pos = {x=0,y=0,z=0}, --[[
^ Destination position to reach.
^ Can be a coordinate x,y,z.
^ Can be a place name of the NPC place map.
The position must be walkable for the npc to stop in,
or in the access position of the place.
Example: "home_inside" ]]
walkable = {}, --[[
^ An array of node names to consider as walkable nodes
for finding the path to the destination. ]]
use_access_node = true, --[[
^ Boolean, if true, when using places, it will find path
to the "accessible" node (empty or walkable node around
the target node) instead of to the target node.
^ Default is true. ]]
enforce_move = true, --[[
^ Boolean, if true and no path is found from the NPC's
position to the end_pos, the NPC will be teleported
to the destination (or, if use_access_node == true it will
teleport to the access position)
^ Default is true. ]]
}

262
doc/api.md
View File

@ -25,10 +25,13 @@ a controled behavior.
* `npc.initialize(entity, pos, is_lua_entity, npc_stats, occupation_name)` : Initialize a NPC
The simplest way to start a mob (of mobs_redo API) is by using the `on_spawn` function
Note: currently this call is unduly repeated (mobs_redo problem), so you should check if npc has already been initialized.
on_spawn = function(self)
npc.initialize(self, self.object:getpos(), true)
self.tamed = false
if self.initialized == nil then
npc.initialize(self, self.object:getpos(), true)
self.tamed = false
end
end
Or after add in the world
@ -48,7 +51,7 @@ and return the freeze state, which is used for stop mobs_redo behavior.
Example:
on_step = function(self, dtime)
npc.on_step(self)
npc.step(self, dtime)
end
Mobs of Mobs_Redo API uses `do_custom` function instead of `on_step` callback
@ -60,7 +63,7 @@ Here is a recommended code.
-- Here is my "do_custom" code
-- Process the NPC action and return freeze state
return npc.on_step(self)
return npc.step(self, dtime)
end
@ -112,15 +115,133 @@ a queue, where they are executed one at a time in queue fashion.
Interruptions are allowed, and the interrupted action is re-started once
the interruption is finished.
### Schedule commands
Schedule commands are an array of actions and tasks that the NPC.
There are 4 possible commands:
* action
```
{
action = action, -- Is a constant defined in `npc.actions.cmd`
args = {} -- action arguments
}
```
* task
```
{
task = task, -- Is a constant defined in `npc.actions.cmd`
args = {} -- task arguments
}
```
* Property change
```
{
???
}
```
* Schedule query/check
```
   {
schedule query/check definition
   }
```
### Schedule time
Only integer value 0 until 23
* 0: 0/24000 - 999
* 1: 1000 - 1999
* 2: 2000 - 2999
* ...
* 22: 22000 - 22999
* 23: 23000 - 23999
### Schedule Type
* "generic" : Returns nil if there are already seven schedules, one for each
day of the week or if the schedule attempting to add already exists.
The date parameter is the day of the week it represents as follows:
Note: Currently only one schedule is supported, for day 0
1: Monday
2: Tuesday
3: Wednesday
4: Thursday
5: Friday
6: Saturday
7: Sunday
* "date_based" : The date parameter should be a string of the format "MM:DD".
If it already exists, function retuns nil
### Methods
* `npc.create_schedule(luaentity, schedule_type, day)` : Create a schedule for a NPC
* `npc.delete_schedule(luaentity, schedule_type, date)` : Delete a schedule for a NPC
* `npc.add_schedule_entry(luaentity, schedule_type, date, time, check, commands)` : Add a schedule entry for a time
* `npc.get_schedule_entry(luaentity, schedule_type, date, time)` : Get a schedule entry
* `npc.update_schedule_entry(luaentity, schedule_type, date, time, check, commands)` : Update a schedule entry
### Examples
-- Schedule entry for 7 in the morning
npc.add_schedule_entry(self, "generic", 0, 7, nil, {
-- Get out of bed
[1] = {
task = npc.actions.cmd.USE_BED,
args = {
pos = "bed_primary",
action = npc.actions.const.beds.GET_UP
}
},
-- Allow mobs_redo wandering
[2] = {
action = npc.actions.cmd.FREEZE,
args = {
freeze = false
}
}
})
Occupations
-----------
NPCs need an occupation or job in order to simulate being alive.
This functionality is built on top of the schedules functionality.
Occupations are essentially specific schedules, that can have slight
random variations to provide diversity and make specific occupations
less predictable. Occupations are associated with textures, dialogues,
specific initial items, type of building (and surroundings) where NPC
lives, etc.
### Methods
* `npc.occupations.register_occupation(occupation_name, {occupation definition})` : Register an occupation
* `npc.occupations.initialize_occupation_values(luaentity, occupation_name)` : Initialize an occupation for a NPC
Places Map
----------
Places map define which NPCs can access which places.
Places are separated into different types.
### Place types
Current place types
* `bed_primary` : the bed of a NPC
* `sit_primary`
* `sit_shared`
* `furnace_primary`
* `furnace_shared`
* `storage_primary`
* `storage_shared`
* `home_entrance_door`
* `schedule_target_pos` : used in the schedule actions
* `calculated_target_pos`
* `workplace_primary`
* `workplace_tool`
* `home_plotmarker`
* `home_inside`
* `home_outside`
### Methods
* `npc.places.add_owned(luaentity, place_name, place_type, pos, access_node)` : Add owned place.
* `npc.places.add_owned(luaentity, place_name, place_type, pos, access_pos)` : Add owned place.
`luaentity` npc owner.
`place_name` a specific place name.
`place_type` place typing.
`pos` is a position of a node to be owned.
`access_pos` is a position of a node to be accessed.
`access_pos` is the coordinate where npc must be to initiate the access.
Place is added for the NPC.
* `npc.places.add_shared(luaentity, place_name, place_type, pos, access_node)` : Add shared place
@ -147,7 +268,91 @@ The flags or marks of the dialogue text. Tags can be used for ....
Definition tables
-----------------
### Dialogue Definition (`register_dialogue`)
### Occupation definition (`register_occupation`)
{
dialogues = {
enable_gift_item_dialogues = true, --[[
^ This flag enables/disables gift item dialogues.
^ If not set, it defaults to true. ]]
type = "", -- The type can be "given", "mix" or "tags"
data = {}, --[[
^ Array of dialogue definitions. This will have dialogue
if the type is either "mix" or "given" ]]
tags = {}, --[[
^ Array of tags to search for. This will have tags
if the type is either "mix" or "tags" ]]
},
textures = {}, --[[
^ Textures are an array of textures, as usually given on
an entity definition. If given, the NPC will be guaranteed
to have one of the given textures. Also, ensure they have sex
as well in the filename so they can be chosen appropriately.
^ If left empty, it can spawn with any texture. ]]
walkable_nodes = {}, -- Walkable nodes
building_types = {}, --[[
^ An array of string where each string is the type of building
where the NPC can spawn with this occupation.
^ Example: building_type = {"farm", "house"}
^ If left empty or nil, NPC can spawn in any building ]]
surrounding_building_types = {}, --[[
^ An array of string where each string is the type of building
that is an immediate neighbor of the NPC's home which can also
be suitable for this occupation. Example, if NPC is farmer and
spawns on house, then it has to be because there is a field
nearby.
^ If left empty or nil, surrounding buildings doesn't matter. ]]
workplace_nodes = {}, --[[
^ An array of string where each string is a node the NPC works with.
^ These are useful for assigning workplaces and work work nodes. ]]
initial_inventory = {}, --[[
^ An array of entries like the following:
{name="", count=1} -- or
{name="", random=true, min=1, max=10}
^ This will initialize the inventory for the NPC with the given
items and the specified count, or, a count between min and max
when the entry contains random=true
^ If left empty, it will initialize with random items. ]]
initial_trader_status = "", --[[
^ String that specifies initial trader value.
^ Valid values are: "casual", "trader", "none" ]]
schedules_entries = {},
^ This is a table of tables in the following format:
{
[<time number>] = {
[<command number>] = {
command
}
}
}
^ Example:
{
[1] = {
[1] = schedule command
},
[13] = {
[1] = schedule command,
[2] = schedule command
},
[23] = {
[1] = schedule command
}
}
The numbers, [1], [13] and [23] are the times when the entries
corresponding to each are supposed to happen. The tables with
[1], [1],[2] and [1] actions respectively are the entries that
will happen at time 1, 13 and 23. ]]
}
### Dialogue definition (`register_dialogue`)
{
text = "Hello.", --[[
@ -159,6 +364,49 @@ Definition tables
^ The object can be excluded. ]]
}
### Schedule query/check definition (schedule command)
{
check = true, -- Indicates that this is a schedule query/check
range = 2, -- Range of checked area in blocks.
count = 20, -- How many checks will be performed.
random_execution_times = true, --[[
^ Randomizes the number of checks that will be performed.
^ min_count and max_count is required ]]
min_count = 20, -- minimum of checks
max_count = 25, -- maximum of checks
nodes = {"itemstring1", "itemstring2"}, --[[
^ Nodes to be found for the actions.
^ When a node is found, it is add in the npc place map
with the place name "schedule_target_pos"
prefer_last_acted_upon_node = true, -- If prefer to act on nodes already acted upon
walkable_nodes = {"itemstring1", "itemstring2"}, -- Walkable nodes
actions = { --[[
^ Table where index is a itemstring of the node to be found,
and value is an array of actions and tasks to be performed
when found the node. ]]
["itemstring1"] = {
[1] = action or task in schedule command format,
[2] = action or task in schedule command format,
[3] = action or task in schedule command format
},
["itemstring2"] = {
[1] = action or task in schedule command format,
[2] = action or task in schedule command format
}
},
}
Examples:
Syntax example 1: