Actions & Schedules (WIP)

Dev_Actions_Schedules.md

@@ -0,0 +1,35 @@
+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:
+      - ``
+ -  `PLACE`:
+ -  `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`
+ -  `USE_BED`
+ -  `USE_SITTABLE`
+ -  `WALK_TO_POS`