Repixture/mods/rp_mobs/API_TEMPLATES.md

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). If not noted otherwise, the microtask finishes successfully.

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, jump_clear_height, stop_at_object_collision, max_timer)

Walk in a straight horizontal line (on the XZ plane), will jump if hitting a node obstacle and jump~=nil.

It's recommended the mob is subject to gravity.

NOTE: You MUST call rp_mobs.scan_environment in the entity's on_step function every step for this to work.

Parameters:

• walk_speed: How fast to walk
• yaw: walk direction in radians
• jump: jump strength if mob needs to jump or nil if no jumping
• jump_clear_height: how many nodes to jump up at most
• stop_at_object_collision: stop walking if colliding with object
• max_timer: automatically finish microtask after this many seconds (nil = infinite)

Finish condition: If the time runs out (if set with max_timer) or collides with and object if stop_at_object_collision is true.

rp_mobs.microtasks.walk_straight_towards(walk_speed, target_type, target, set_yaw, reach_distance, jump, jump_clear_height, stop_at_reached, stop_at_object_collision, max_timer)

Walk in a straight horizontal line (on the XZ plane) towards a position or object, will jump if hitting node obstacle and jump~=nil.

It's recommended the mob is subject to gravity.

NOTE: You MUST call rp_mobs.scan_environment in the entity's on_step function every step for this to work.

Parameters:

• walk_speed: How fast to walk
• 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, stop walking. If nil, has no effect
• max_distance: If mob is further away from target than this distance, stop walking. If nil, has no effect
• jump: jump strength if mob needs to jump or nil if no jumping
• jump_clear_height: how many nodes to jump up at most
• stop_at_reached: stop walking and finish if within reach_distance of target
• stop_at_object_collision: stop walking and finish if colliding with object
• max_timer: automatically finish microtask after this many seconds (nil = infinite)

Finish condition: If any of the following is true:

• When the time runs out (if max_timer was set)
• Target is within reach_distance of the mob and stop_at_reached is true
• Target is further away than max_distance
• When colliding with object if stop_at_object_collision is true

This microtask finishes successfully unless there is an error.

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.follow_path(path, walk_speed, jump_strength, set_yaw, can_jump, finish_func)

Make the mob follow along a path, i.e. a sequence of positions by walking. This assumes the mob is bound to gravity along the whole path and the entire path is walkable. Jumping and falling is supported, but not climbing or swimming. Note: This function does not check the nodes along the path for validity.

Parameters:

• path: List of positions to follow. Can alternatively be set to nil, in which case the path will be read from mob._temp_custom_state.follow_path when the microtask starts
• walk_speed: How fast to walk
• jump_strength: How strong to jump (must be able to clear a height of max_jump at least)
• set_yaw: If true, mob will automatically set the yaw to face towards the next path position (default: false)
• can_jump: If true, mob will jump to increase height (default: true)
• finish_func: Optional function called every step with arguments self, mob to force microtask to finish early. self is the microtask reference, mob the mob reference. Returns <stop>, <success>. If stop is true, microtask will finish. with the given success (success = true/false; true is default).

Finish condition: There are multiple reasons for finishing:

• When the mob has reached the final position (within a small tolerance) (considered success)
• When mob was stuck and unable to continue to walk for a few seconds (considered failure)
• When finish_func is has returned true for its 1st return value

rp_mobs.microtasks.follow_path_climb(path, walk_speed, climb_speed, set_yaw, finish_func, anim_walk, anim_climb, anim_idle)

Make the mob follow along a path, i.e. a sequence of positions by climbing. The difference from rp_mobs.microtask.follow_path is that the mob climbs instead of walks. The path must exclusively consist of nodes that are considered 'climbable'.

This assumes the mob is not bound to gravity while climbing and the entire path consists of climbable (or equivalent) nodes from the viewpoint of the mob.

This function could also be used to follow a path through nodes with liquid physics.

Parameters:

• path: See rp_mobs.microtasks.follow_path
• walk_speed: Horizontal movement speed
• climb_speed: Vertical movement speed
• set_yaw: See rp_mobs.microtasks.follow_path
• finish_func: See rp_mobs.microtasks.follow_path
• anim_walk: Mob animation name for horizontal movement (default: "walk")
• anim_climb: Mob animation name for vertical movement (default: "idle")
• anim_idle: Mob animation name when idling (default: "idle")