Skip to content

1.20.1 Mod API

Stefano Manca edited this page Oct 16, 2026 · 2 revisions

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

Registering a task

RegisterWorkerTasksEvent is fired once on every mod bus during common setup:

public MyAddon(FMLJavaModLoadingContext context) {
    context.getModEventBus().addListener((RegisterWorkerTasksEvent e) -> e.register(new ChopTask()));
}

WorkerTask

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.

TaskContext

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

WorkerInput

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.

Example

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.

Other entry points

  • WorkerTaskRegistry.INSTANCE.get(id), .all().
  • WorkerEntity: skills(), needs(), inventory(), runner(), input(), supply(), gainXp(amount, task), pickupItems(radius).

Clone this wiki locally