Api doc update (#31)
* 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
Hector Kio
parent
c7fad7d6c6
commit
2dc2400b38
|
|
@ -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
262
doc/api.md
|
|
@ -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:
|
||||
|
|
|
|||
Loading…
Reference in New Issue