Repository navigation
1.20.1 Mod API
Version: This guide applies to Minecraft 1.20.1 (Forge).
Another mod can add tasks with their own logic. Add the Rat Worker jar as a compile-only dependency; all API types are in it.ratlab.ratworker.api.
RegisterWorkerTasksEvent is fired once on every mod bus during common setup:
public MyAddon(FMLJavaModLoadingContext context) {
context.getModEventBus().addListener((RegisterWorkerTasksEvent e) -> e.register(new ChopTask()));
}Tasks are stateless singletons. Per-worker data lives in ctx.state(), which is saved with the worker, so a running task survives reloads.
| Method | Default | Meaning |
|---|---|---|
id() |
required | Task id. |
icon() |
required | Icon in the task list. |
title(), description()
|
lang task.<ns>.<path> / .desc
|
Shown in the command screen. |
defaults() |
TaskNumbers.of(1, 1, 1, 16, 1) |
Numbers: hungerCost, thirstCost, speedMultiplier, range, levels, learnXp (30), xpRate (1), plus your own keys via with(key, value). Datapack task files override them. |
branches() |
hunger, thirst | Upgrade branches; add Branch.SPEED if the task reads it. |
isWork() |
true | false = idle drain rate, no XP. |
stageKey() |
null | STAGES mode stage name. |
isUnlocked(player, worker) |
true | Extra condition on top of the unlock mode. |
canStart(ctx) |
OK | Return TaskCheck.fail(reason) with a readable reason. |
start(ctx), tick(ctx), stop(ctx)
|
tick runs every taskTickInterval ticks. Never block, spread scans over ticks. |
Implement InnateTask to make a task known without a manual.
| Method | Meaning |
|---|---|
worker(), level(), owner()
|
Worker, server level, online owner or null. |
state() |
Persistent NBT for this run. |
number(key) |
Resolved number (default, datapack, server config). |
cooldownFactor() |
1, or lowSlowdown while a need is low. Multiply cooldowns by it. |
moveTo(pos, distance), moveTo(entity, distance)
|
ARRIVED, MOVING, FAILED. Call every tick; FAILED after repeated path failures or getting stuck. |
stopTask(reason), setStatus(text)
|
Stop with a reason; status line. |
input() |
WorkerInput, below. |
ticksRunning(), taskLevel()
|
Ticks run; reserved. |
Read upgrade levels with ctx.worker().skills().level(Branch.SPEED, this).
Simulated player input through a Forge fake player that stands on the worker, carries the owner's UUID and holds the worker's item. Vanilla, Forge events and claim mods see a normal player action.
| Method | Meaning |
|---|---|
hold(action, target) / hold(action, target, intervalTicks)
|
Keep pressing USE, ATTACK (mines the block) or SNEAK; USE repeats every interval. |
press(action, target) |
One click. |
release(action), releaseAll(), isHeld(action)
|
Input state. |
useSlot(slot, pos, face) |
Right-click a block with an inventory slot's item; the slot gets the result back. |
breakNow(pos) |
Break a block now with the main-hand tool. |
fakePlayer() |
The fake player itself, for item logic that needs a player. Empty its hands and inventory afterwards. |
Targets: Target.block(pos), Target.entity(e), Target.inFront(). Limits: 4.5 blocks reach, never players, never a container other than the supply, a server-wide budget of interactions per tick. Holds are released when the task stops or pauses, the worker dies or unloads, a need reaches zero, or the target is gone.
public class ChopTask implements WorkerTask {
private static final ResourceLocation ID = ResourceLocation.fromNamespaceAndPath("myaddon", "chop");
@Override public ResourceLocation id() { return ID; }
@Override public ItemStack icon() { return new ItemStack(Items.IRON_AXE); }
@Override public TaskNumbers defaults() { return TaskNumbers.of(1.2, 1.0, 1.0, 12, 1).with("cooldown", 40); }
@Override
public TaskCheck canStart(TaskContext ctx) {
return ctx.worker().getMainHandItem().is(ItemTags.AXES) ? TaskCheck.OK : TaskCheck.fail("myaddon.reason.no_axe");
}
@Override
public void start(TaskContext ctx) {
ctx.state().putLong("Next", 0);
}
@Override
public void tick(TaskContext ctx) {
long now = ctx.level().getGameTime();
if (now < ctx.state().getLong("Next")) return;
BlockPos log = findLog(ctx); // your search, a few blocks per tick
if (log == null) return;
if (ctx.moveTo(log, 2.5) != TaskContext.MoveResult.ARRIVED) return;
ctx.input().breakNow(log);
ctx.worker().pickupItems(4);
ctx.state().putLong("Next", now + Math.round(ctx.number("cooldown") * ctx.cooldownFactor()));
}
}Lang keys: task.myaddon.chop, task.myaddon.chop.desc. Addon tasks have no [tasks.*] config section; tune them with data/myaddon/ratworker/task/chop.json.
-
WorkerTaskRegistry.INSTANCE.get(id),.all(). -
WorkerEntity:skills(),needs(),inventory(),runner(),input(),supply(),gainXp(amount, task),pickupItems(radius).
Rat Worker is released under the MIT license. Author: Stefano Manca.
Guides & Reference
Scripting & Mod API
Version Overviews