Mobs: Document core microtask templates

mods/rp_mobs/API.md

@@ -288,7 +288,7 @@ The field `_cmi_is_mob=true` will be set automatically for all mobs and can be u
   * `damage`: When mob takes non-fatal damage
   * `punch_no_damage`: When mob was punched but took no damage
   * `eat`: When mob eats something (this has a default sound)
-  * `call`: Occassional mob call (only played manually)
+  * `call`: Occasional mob call (only played manually)
   * `horny`: When mob becomes horny
   * `give_birth`: When mob gives birth to a child
 * `front_body_point`: A point of the front side of the mob. Used by the mob to "see"
@@ -408,7 +408,7 @@ Calling `rp_mobs.restore_state` in `on_activate` is a requirement, but everythin
 
 #### `rp_mobs.init_mob(mob)`
 
-This initializes the mob and does initalization work in order to do things that
+This initializes the mob and does initialization work in order to do things that
 are required for all mobs.
 
 This function **must** be called in `on_activate` before any other mob-related function.
@@ -600,7 +600,7 @@ The function arguments are:
 
 * `task_queue`: Reference to task queue on which the decider is run on.
                 You can modify it at will.
-* `mob`: Refernence to mob object
+* `mob`: Reference to mob object
 * `dtime`: Time in seconds the last time the step decider was called (from `on_step`)
 
 If decider argument is nil, nothing will be done for that event.
@@ -639,6 +639,14 @@ Add the microtask `microtask` to the specified `task`.
 Ends the currently active task in the given `task_queue` of `mob`.
 If the task queue is empty, nothing happens.
 
+
+
+### Task template functions
+
+This mod comes with a number of template functions for common microtasks like walking. See `API_template.md` for a reference.
+
+
+
 ### Breeding functions
 
 #### `rp_mobs.feed_tame_breed(mob, feeder, allowed_foods, food_till_tamed, food_till_horny, add_child_grow_timer, effect, eat_sound)`

mods/rp_mobs/API_templates.md

@@ -0,0 +1,137 @@
+# Repixture Mobs API: Task Templates
+
+This document contains additional information about the Repixture Mobs API.
+It contains task template functions for common use cases so we don't have to
+start from zero for every mob.
+
+See `API.md` for the main document and a general description of the task
+system.
+
+## Microtask templates
+
+A microtask template is a function that returns a microtask that you can
+then use to insert in a task. All microtask templates are part of the
+`rp_mobs.microtasks` table.
+
+### How to use
+
+You simply call one of the template functions with the required parameters
+(if any) to get a microtask returned. You then can insert this microtask
+like any other microtask in a task.
+
+Minimal example for doing nothing for 3 seconds (we assume that `mob`
+is a mob object reference and `task_queue` is a task queue):
+
+```
+local task = rp_mobs.create_task({label="do nothing"})
+local microtask = rp_mobs.microtasks.sleep(3)
+rp_mobs.add_microtask_to_task(mob, task, microtask)
+rp_mobs.add_task_to_task_queue(task_queue, task)
+```
+
+Also, all microtasks come with a 'finish' condition. If this condition is met,
+the microtask is finished and removed from the task, continuing the processing
+with the next microtask (if any).
+
+## Microtask template reference
+
+### `rp_mobs.microtasks.move_straight(move_vector, yaw, drag, max_timer)`
+
+Move in a straight line on any axis.
+
+Parameters:
+
+* `move_vector`: velocity vector to target.
+* `yaw`: look direction in radians
+* `drag`: (optional) if set as a vector, will adjust the velocity smoothly towards the target
+   velocity, with higher axis values leading to faster change. If unset, will set
+   velocity instantly. If drag is 0 or very small on an axis, this axis will see no velocity change
+* `max_timer`: automatically finish microtask after this many seconds (nil = infinite)
+
+Finish condition: If the time runs out (if set with `max_timer`), otherwise does not finish
+on its own.
+
+### `rp_mobs.microtasks.walk_straight(walk_speed, yaw, jump, max_timer)`
+
+Walk in a straight line, jumping if hitting obstacle and `jump~=nil`.
+
+Parameters:
+
+* `yaw`: walk direction in radians
+* `jump`: jump strength if mob needs to jump or nil if no jumping
+* `max_timer`: automatically finish microtask after this many seconds (nil = infinite)
+
+Finish condition: If the time runs out (if set with `max_timer`), otherwise does not finish
+on its own.
+
+### `rp_mobs.microtasks.walk_straight_towards(walk_speed, target_type, target, set_yaw, reach_distance, jump, max_timer)`
+
+Walk in a straight line towards a position or object.
+
+Parameters:
+
+* `walk_speed`: walk speed
+* `target_type`: "pos" (position) or "object"
+* `target`: target, depending on `target_type`: position or object handle
+* `set_yaw`: If true, will set mob's yaw to face target
+* `reach_distance`: If mob is within this distance towards target, finish task
+* `jump`: jump strength if mob needs to jump or nil if no jumping
+* `max_timer`: automatically finish microtask after this many seconds (nil = infinite)
+
+Finish condition: If the target is within `reach_distance` of the mob. Otherwise, when
+the time runs out (if `max_timer` was set)
+
+### `rp_mobs.microtasks.set_yaw(yaw)`
+
+Set mob yaw instantly to `yaw`. Finishes instantly.
+
+### `rp_mobs.microtasks.rotate_yaw_smooth(yaw, time)`
+
+Change mob yaw linearly over time towards a target yaw.
+
+Parameters:
+
+* `yaw`: Target yaw in radians or `"random"` for random yaw
+* `time`: How much time to use until the target yaw is reached (in ms)
+
+Finish condition: When target yaw was reached (within a small tolerance).
+
+### `rp_mobs.microtasks.autoyaw()`
+
+Set the mob yaw based on the current velocity on the XZ coordinate plane.
+If the mob velocity on this plane is zero or near-zero, yaw will
+not be changed.
+
+Finish condition: Finishes instantly.
+
+### `rp_mobs.microtasks.sleep(time)`
+
+Do nothing for the given `time` in seconds, then finishes.
+
+### `rp_mobs.microtasks.set_acceleration(acceleration)`
+
+Instantly set mob acceleration to the given `acceleration` parameter (a vector).
+
+Finish condition: Finishes instantly.
+
+### `rp_mobs.microtasks.pathfind_and_walk_to(target_pos, searchdistance, max_jump, max_drop)`
+
+WARNING: This function isn't very accurate stable. Use at your own risk!
+
+Make the mob find a path (using the A\* algorithm) towards `target_pos`,
+then starts to walk that path.
+This assumes the mob is bound to gravity. Jumping up and falling down a few blocks is
+part of the pathfinding.
+
+Parameters:
+
+* `target_pos`: Target position
+* `searchdistance`: How far (in nodes) from the mob's original position the pathfinder
+  will search before stopping
+* `max_jump`: Maximum allowed jump height (can be 0)
+* `max_drop`: Maximum allowed fall height (can be 0)
+
+Finish condition: When the mob has reached `target_pos` (within a small tolerance).
+Also, finished instantly when no path was found.
+
+

mods/rp_mobs/task_templates.lua

@@ -40,14 +40,12 @@ local random_yaw = function()
 	return (math.random(0, YAW_PRECISION) / YAW_PRECISION) * (math.pi*2)
 end
 
--- Task templates
-
-rp_mobs.tasks = {}
-
 -- Microtask templates
+-- See `API_templates.md` for documentation
 
 rp_mobs.microtasks = {}
 
+-- FIXME: Mob does not walk the path very well, gets stuck a lot
 rp_mobs.microtasks.pathfind_and_walk_to = function(target_pos, searchdistance, max_jump, max_drop)
 	local mtask = {}
 	mtask.label = "pathfind and walk to coordinate"
@@ -110,7 +108,6 @@ rp_mobs.microtasks.pathfind_and_walk_to = function(target_pos, searchdistance, m
 	return rp_mobs.create_microtask(mtask)
 end
 
--- Set yaw instantly
 rp_mobs.microtasks.set_yaw = function(yaw)
 	local label
 	if yaw == "random" then
@@ -142,13 +139,6 @@ local collides_with_wall = function(moveresult, include_objects)
 	return false
 end
 
--- Move in a straight line on any axis
--- * move_vector: velocity vector to target.
--- * yaw: look direction in radians
--- * drag: (optional) if set as a vector, will adjust the velocity smoothly towards the target
---   velocity, with higher axis values leading to faster change. If unset, will set
---   velocity instantly. If drag is 0 or very small on an axis, this axis will see no velocity change
--- * max_timer: automatically finish microtask after this many seconds (nil = infinite)
 rp_mobs.microtasks.move_straight = function(move_vector, yaw, drag, max_timer)
 	local label
 	if max_timer then
@@ -203,10 +193,6 @@ rp_mobs.microtasks.move_straight = function(move_vector, yaw, drag, max_timer)
 	})
 end
 
--- Walk in a straight line, jumping if hitting obstable and jump~=nil
--- * yaw: walk direction in radians
--- * jump: jump strength if mob needs to jump or nil if no jumping
--- * max_timer: automatically finish microtask after this many seconds (nil = infinite)
 rp_mobs.microtasks.walk_straight = function(walk_speed, yaw, jump, max_timer)
 	local label
 	if max_timer then
@@ -293,14 +279,6 @@ rp_mobs.microtasks.walk_straight = function(walk_speed, yaw, jump, max_timer)
 	})
 end
 
--- Walk in a straight line towards a position or object
--- * walk_speed: walk speed
--- * target_type: "pos" (position) or "object"
--- * target: target, depending on target_type: position or object handle
--- * set_yaw: If true, will set mob's yaw to face target
--- * reach_distance: If mob is within this distance towards target, finish task
--- * jump: jump strength if mob needs to jump or nil if no jumping
--- * max_timer: automatically finish microtask after this many seconds (nil = infinite)
 rp_mobs.microtasks.walk_straight_towards = function(walk_speed, target_type, target, set_yaw, reach_distance, jump, max_timer)
 	local label
 	if max_timer then
@@ -431,7 +409,6 @@ rp_mobs.microtasks.walk_straight_towards = function(walk_speed, target_type, tar
 	})
 end
 
--- Rotate yaw linearly over time
 rp_mobs.microtasks.rotate_yaw_smooth = function(yaw, time)
 	local label
 	if yaw == "random" then
@@ -468,7 +445,6 @@ rp_mobs.microtasks.rotate_yaw_smooth = function(yaw, time)
 	})
 end
 
--- Set yaw based on XZ velocity
 rp_mobs.microtasks.autoyaw = function()
 	return rp_mobs.create_microtask({
 		label = "automatically set yaw",
@@ -486,7 +462,6 @@ rp_mobs.microtasks.autoyaw = function()
 	})
 end
 
--- Do nothing for the given time in seconds
 rp_mobs.microtasks.sleep = function(time)
 	return rp_mobs.create_microtask({
 		label = "sleep for "..time.."s",
@@ -502,7 +477,6 @@ rp_mobs.microtasks.sleep = function(time)
 	})
 end
 
--- Instantly set mob acceleration to the given parameter
 rp_mobs.microtasks.set_acceleration = function(acceleration)
 	return rp_mobs.create_microtask({
 		label = "set acceleration",