From 2dc2400b38e41dd5df89cef9c304b666cfe7b6bb Mon Sep 17 00:00:00 2001 From: BrunoMine Date: Wed, 20 Dec 2017 17:40:36 -0200 Subject: [PATCH] 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 --- doc/actions_and_tasks.md | 43 ++++++- doc/api.md | 262 +++++++++++++++++++++++++++++++++++++-- 2 files changed, 296 insertions(+), 9 deletions(-) diff --git a/doc/actions_and_tasks.md b/doc/actions_and_tasks.md index e5d4721..db6ea6c 100644 --- a/doc/actions_and_tasks.md +++ b/doc/actions_and_tasks.md @@ -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. ]] } diff --git a/doc/api.md b/doc/api.md index 84fa99e..bb8779a 100644 --- a/doc/api.md +++ b/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: + { + [