World actions

Eleven actions that touch the world rather than the client. The editor's World palette also holds farm, described with the other goals.

Five of them accept rel: dig, place_block, use_block, read_sign and write_sign. With rel: true, x/y/z are read as an offset from the client instead of world coordinates, so a loop can say "dig the block in front of me" without knowing where it is standing. Absolute is the default.

dig

Breaks a block.

Needs a suitable tool for the block. Like a player, the client digs only a block within reach, 4.5 blocks from its eyes, that it can see: it never digs through another block. The step fails on a block out of reach, out of sight, unbreakable (bedrock) or on air, and when the block is still not broken after 60 seconds (obsidian by hand). Walk there first with goto, or use dig_nearest, which walks for you.

dig_nearest

Finds the nearest block of a kind, walks to it if needed, and breaks it. The "harvest whatever is around me" primitive that dig cannot be, because a farm loop does not know coordinates.

It breaks the nearest matching block it can reach and see, skipping ones hidden behind other blocks. When none is in reach, it walks up to the nearest one, preferring one it can see. The step fails when no such block is within radius, when the client still cannot reach or see the block after walking, for example ore buried inside stone, or when one block takes longer than 60 seconds to break.

place_block

Places the held block.

Equip the block first with equip or select_slot. The step fails, and the warning says why, when nothing is held, the spot is already taken by a block, the client is standing there, the spot is out of reach (4.5 blocks), or there is no solid block next to it to place against.

use_block

Right-clicks a block: buttons, levers, doors, trapdoors, beds, workstations.

Like a player, the client clicks the face of the block that points at it. The step fails on air and on a block out of reach (4.5 blocks from its eyes).

To open a chest and move items, use container_open instead. It holds the window for the actions that follow.

use_entity

Right-clicks an entity: villager trade windows, NPC shops, item frames, boats.

The step fails when nothing matching is within radius. This plus the menu clicks is how trading works. There was once a dedicated trade action; it never had a working implementation and has been retired.

furnace_smelt

Drives a furnace: open it, load input and fuel, take out whatever is ready. Every field is independent, so one action can smelt, or only collect.

The step fails when there is no furnace, smoker or blast furnace (or the block at x, y, z is something else), or when the input or fuel named is not in the inventory. Fuel goes in only as far as the input in the furnace needs: 32 iron ore takes 4 coal, not the whole stack.

Smelting is not instant. Load in one firing and collect in a later one, for example on a timer, by leaving the smelt fields blank and ticking only the collect box:

fish

Casts a fishing rod once and reels in.

The client puts a fishing rod from its inventory in its hand, and fails if it has none. Like a player it must face water: it turns to the nearest water within 6 blocks that it can see, and fails if there is none. The warning says "no visible water" when water is near but behind a block. It never walks, so stand at the shore. One cast per step; loop it with repeat or while for steady fishing. Each catch fires the item_collected trigger. A fishing loop keeps the rod in hand, and puts the previous item back only if the step fails.

Nothing locks the hand while fishing. eat, use_potion, equip_best and a chase can take the rod away mid-loop, and the next fish step simply takes it back. Do not run equip_best on item_collected in a fishing flow, or every catch swaps the rod for a sword.

sleep

Lies down in the nearest bed.

The client first checks it is night or a thunderstorm, and fails at once otherwise, without walking anywhere. Then it walks to the bed, lies down, and the step stays running until it wakes up: morning, or the server pushing it out of bed. Then the step succeeds. If timeoutMs passes first, it gets up and the step still succeeds, because whether the night skips is the server's sleep rule, not a failure of the step. It fails if the server keeps the client in bed, if there is no bed in range, or if the server refuses (it is not night, monsters are nearby, the bed is taken or blocked); the server's reason is in the warning line.

The walk to the bed is a mover (see attack). Once in bed it is not, but any mover that starts while the client sleeps wakes it first and the sleep step ends as a success. stop_moving does not wake it.

wake

Gets out of bed now.

No fields.

Does nothing, and succeeds, when the client is not in bed. Fails when the server keeps the client in bed.

read_sign

Reads a sign into a variable.

The four lines are saved as plain text, colours and styles removed, joined by line breaks, so a var_matches condition can pick it apart. Fails when there is no sign there.

write_sign

Writes text on a sign.

The client must be within reach, 4.5 blocks, like a player, and does not walk, so goto first. Fails when out of reach. Text is as public as chat, and secrets in it are filled in, exactly as they are in chat. A secret that is not set fails the step and writes nothing.

Before game version 1.20 a sign can only be edited right after the client places it (with place_block). On 1.20 and newer the client right-clicks the sign to open it for editing, so any sign the server lets a player edit works. The side that opens is the one the client faces, so stand on the side you write. The step fails when the server does not open the sign, when the other side opens, or when the client holds a dye, ink sac or honeycomb, which would colour or wax the sign instead. A server keeps a sign closed when it is waxed, protected by a plugin, or within spawn protection: by default 16 blocks around the world spawn, where only operators can edit.