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

@@ -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. ]]
     }

doc/api.md

@@ -25,11 +25,14 @@ 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)
+        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: