Mobs: Document core microtask templates
This commit is contained in:
Wuzzy
parent
01e01991f3
commit
012f79b36d
@ -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)`
|
||||
|
||||
137
mods/rp_mobs/API_templates.md
Normal file
137
mods/rp_mobs/API_templates.md
Normal file
@ -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.
|
||||
|
||||
|
||||
@ -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",
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user