Actions and Schedules

The interesting part of Advanced NPC is its ability to simulate realistic behavior in NPCs. Realistic behavior is defined simply as being able to perform tasks at a certain time of the day, like usually people do. This allow the NPC to go to bed, sleep, get up from it, sit in benches, etc. But how all of this is simulated? The answer is: tasks and scheduling.

The implementation resembles a rough OS process scheduling algorithm where only one process is allowed at a time. The processes or tasks are held in 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.

Actions and Tasks

Actions are "atomic" executable actions the NPC can perform. Tasks are sequences of actions that are common enough to be supported by default. Advanced NPC supports 16 actions and tasks by default which can be used together to simulate tasks that players can do. Each action or task is wrapped on a Lua table which tells the action/task to be executed and the arguments to be used. However, this is encapsulated to the user in the following two functions:

npc.add_action(action, args)
npc.add_task(task, args)

For both of the above, action/task is a constant defined in npc.actions.cmd, and args is a Lua table specific to each action/task. The following is a list of the 16 actions/tasks supported by default:

SET_INTERVAL: This action sets the interval at which the action/tasks are executed. The default is 1 second.
- Arguments:
  - interval: A decimal number, in seconds
  - freeze: Boolean, if true, mobs_redo API will not execute until interval is set
FREEZE: This action allows to stop/execute mobs_redo API. This is good for stopping the NPC from fighting, wandering, etc.
- Arguments:
  - freeze: Boolean, if true, mobs_redo API will not execute.
DIG: Digs a node as a player would do. The NPC will use mining animation and the node's dug sound will be played if enabled. It is also possible to respect or bypass protection.
- Arguments:
  - pos: Position where to dig
  - add_to_inventory: Boolean, if true, adds the first defined drop to the NPC's inventory. Note: This doesn't uses Minetest's drop system. It will take only the first item defined in the drops table.
  - bypass_protection: Boolean, if true, protection will not be respected and NPC will dig node anyways.
  - play_sound: Boolean, if true, node's dug sound will be played. Default is true.
PLACE: Places a node as a player would do.
- Arguments:
  - pos: The position where the node will be placed
  - node: A string containing the name of the node to be placed
  - source: Specifies where the node will be sourced. There are three options:
    - take_from_inventory: The node will be taken from NPC's inventory. If not present, no node will be placed.
    - take_from_inventory_forced: The node will be taken from the inventory if present, and if not present, it will place it anyways.
    - force_place: The node will be placed and not taken from the NPC's inventory.
  - bypass_protection: Boolean, if set to true, the node will be placed regardless of protection.
  - play_sound: Boolean, if set to true, node's place sound will be played
ROTATE: Rotates a NPC to one of 8 possible directions.
- Arguments:
  - dir: One of the 8 directions in the enum npc.direction. The options are:
    - North, northeast, east, southeast, south, southwest, west, northwest
  - start_pos: If given, the dir argument is ignored. It will calculate the direction from start_pos to end_pos. Requires end_pos.
  - end_pos: If given, the dir argument is ignored. It will calculate the direction from start_pos to end_pos. Requires start_pos.
WALK_STEP: Walks one step looking into specified direction.
- Arguments:
  - dir: Can be either:
    - One of the 8 directions to look at and walk to. Can be found in enum npc.direction, or;
    - "random", "random_orthogonal", "random_all", which will give a random direction as specified by the parameter. Requires start_pos
  - speed: Double number specifying the speed that the NPC will be moved. Three pre-defined speeds exists at npc.actions.one_nps_speed, npc.actions.one_half_nps_speed, npc.actions.two_nps_speed.
  - target_pos: Position that specifies where the NPC should be at the end of moving.
  - start_pos: Position where the NPC is before executing movement. Required to calculate random direction. Requires dir.
STAND: NPC's animation is changed to stand and velocity is set to 0. This is usually required to stop the NPC after it was walking.
- Arguments:
  - pos: If given, NPC will stand at the given position.
  - dir: If given, NPC will stand and look at dir.
SIT: NPC's animation is changed to sit and velocity is set to 0.
- Arguments:
  - pos: If given, NPC will sit at the given position.
  - dir: If given, NPC will sit and look at dir.
LAY: The NPC's animation is changed to lay and velocity is set to 0.
- Arguments:
  - pos: If given, NPC will lay at the given position.
  - dir: If given, NPC will lay and look at dir.
PUT_ITEM: Puts an item into an external (to the NPC) inventory. Supports either a player or node's inventory. The items are taken from the NPC's inventory. If the NPC doesn't have the item or the amount specified this function does nothing.
- Arguments:
  - player: String containing the name of the player whose inventory will be used. Set to nil if using node's inventory
  - pos: Position of the node whose inventory will be used. Set to nil if using player's inventory.
  - inv_list: A string specifying the inventory list where the item will be placed.
  - item_name: A string containing the item's name
  - count: An integer specifying how much items will be placed
  - is_furnace: A boolean, if set to true, it will start its timer. Note: Currently only supports default furnaces.
TAKE_ITEM: Takes an item from an external (to the NPC) inventory. Supports either a player or node's inventory. The items are taken from the external inventory. If the external inventory doesn't have the item or the amount specified this function does nothing.
- Arguments:
  - player: String containing the name of the player whose inventory will be used. Set to nil if using node's inventory
  - pos: Position of the node whose inventory will be used. Set to nil if using player's inventory.
  - inv_list: A string specifying the inventory list where the item will be placed.
  - item_name: A string containing the item's name
  - count: An integer specifying how much items will be taken
CHECK_ITEM: Simple function that checks if an external inventory contains an specified item in specific amounts. Works with both players and nodes' inventories.
- Arguments:
  - player: String containing the name of the player whose inventory will be used. Set to nil if using node's inventory
    - pos: Position of the node whose inventory will be used. Set to nil if using player's inventory.
    - inv_list: A string specifying the inventory list where the item will be placed.
    - item_name: A string containing the item's name to be searched
    - count: An integer specifying amount of the item to be searched
USE_OPENABLE: Action to open/close any supported openable node like a door, fence gate, etc.
- Arguments:
  - pos: Position of the openable node
  - action: Whether to open or close. Defined in npc.actions.const.doors.action
  - dir: Direction in which the NPC is looking. Defined in npc.direction
USE_FURNACE: Task. Sequence of actions that allows a NPC to use a furnace. Fuels and cookable items are taken from the NPC's inventory. If there's not enough of any, the task will not be performed. Fuels are limited to leaves, tree trunks, coalblocks and straw.
- Arguments:
  - pos: Position of the furnace to use
  - item: Item that will be cooked/smelt in furnace
  - freeze: Whether to freeze or not the NPC while the furnace is working
USE_BED: Task. Sequence of actions that allows the NPC to use a bed. Currently supports MTG beds and cottages' beds.
- Arguments:
  - pos: Position of bed to be used.
  - action: Whether to get up or lay on bed. Defined in npc.actions.const.beds.action.
USE_SITTABLE: Task. Sequence of actions that allows the NPC to use a sittable node. Currently supports cottages' benches and to some extend, MTG stairs.
- Arguments:
  - pos: Position of sittable node to be used.
  - action: Whether to get up or sit on bed. Defined in npc.actions.const.sittable.action.
WALK_TO_POS: Task. 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.
- Arguments:
  - end_pos: Destination position to reach
  - walkable: An array of node names to consider as walkable nodes for finding the path to the end_pos
  - use_access_node: 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: Boolean, if true and no path is found from the NPC's position to the end_pos, the NPC will be teleported to the end_pos (or, if use_access_node == true it will teleport to the "accessible" node)

Home
Concepts

Developer Documentation