Updated Dev_Actions_Schedules (markdown)

Dev_Actions_Schedules.md

@@ -2,7 +2,6 @@
 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)`
@@ -18,18 +17,51 @@ For both of the above, action/task is a constant defined in `npc.actions.cmd`, a
       - `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:
-      - ``
- -  `PLACE`:
+      - `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.
- -  `WALK_STEP`:
- -  `STAND`:
- -  `SIT` = 5,
- -  `LAY` = 6,
- -  `PUT_ITEM` = 7,
- -  `TAKE_ITEM` = 8,
- -  `CHECK_ITEM`
- -  `USE_OPENABLE`
- -  `USE_FURNACE`
+    - 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`:
+ -  `TAKE_ITEM`:
+ -  `CHECK_ITEM`:
+ -  `USE_OPENABLE`: Task. NPC will open/close any supported openable node like a door, fence gate, etc.
+ -  `USE_FURNACE`:
  -  `USE_BED`
  -  `USE_SITTABLE`
- -  `WALK_TO_POS`
+ -  `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.