diff --git a/mods/rp_mobs/API.md b/mods/rp_mobs/API.md index 3625acdb..711ee203 100644 --- a/mods/rp_mobs/API.md +++ b/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)` diff --git a/mods/rp_mobs/API_templates.md b/mods/rp_mobs/API_templates.md new file mode 100644 index 00000000..3b224ef3 --- /dev/null +++ b/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. + + diff --git a/mods/rp_mobs/task_templates.lua b/mods/rp_mobs/task_templates.lua index 98ee58cb..a8a71d26 100644 --- a/mods/rp_mobs/task_templates.lua +++ b/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",