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).

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.