Movement and travel.
The movement functions track position, handle gravel and mobs, wait for other turtles, and never dig chests, machines, other turtles or bedrock. Prefer them over raw turtle.forward loops.
Where am I.
The current position and facing. A fresh table each call.
Returns{ x, y, z, facing }
Turn to face 0 north, 1 east, 2 south or 3 west, taking the shortest turn.
Returnstrue when facing that way.
Moving.
Move one block "forward" (the default), "up" or "down", digging or attacking whatever is in the way. Falling gravel is handled by retrying. Another turtle in the way is waited for, briefly. A dig the server refuses (a land claim, spawn protection, an unbreakable block) is remembered, so later routes go around it.
Returnstrue, or false, err: "Out of fuel", "turtle in the way", "protected block (name)", the refused dig's reason, or "blocked".
td.clear("up" | "down" | "forward"): dig in that direction until nothing falls back in, for gravel and sand columns. Leaves protected blocks alone.
Straight-line travel that digs its way: y first, then x, then z.
Returnstrue, or false, err.
Smart travel. Known open cells are preferred, unseen ones are worth a try, solid ones are only used when digging is allowed and protected ones never. It steers around other turtles.
On 1.19.1 and later, trips of 6 blocks or more are planned by the relay over the whole map of your account: everything any of your turtles has seen, including tunnels they dug, and the routes other turtles are taking right now. Something in the way that the map did not know about (a block placed since, a mob) is gone round with what the turtle sees, reported to the map, and the relay plans the rest again. When the relay is away, and for shorter trips, the turtle plans on its own over what it has seen since it started.
Returnstrue, or false, err: "no route", "Out of fuel", "gave up" or why the goal itself could not be entered.
td.goTo options.
digfalse | true | "fallback"default "fallback"falsenever digs.truedigs freely."fallback"digs only when no clear route exists (or after several attempts keep bumping into unseen blocks).knowntrueOnly move through cells known to be open: seen, or taught withtd.learn. Never digs, whateverdigsays.
Teaching the route planner.
Teach the route planner corridors somebody else dug: a list of boxes { x0, y0, z0, x1, y1, z1 } of open cells. Pair it with { known = true } to travel only through them.
Returnsthe number of cells taught (at most 6000 per call).
Home.
Home is a parking spot. Jobs return to it, but do not unload there: see Where jobs unload.
The saved home.
Returnsthe saved home { x, y, z, facing }, or nil if none is set.
Remember the current spot and facing as home. If a chest touches the turtle there, its contents are read so the deck can show them.
Returnstrue
Travel home with td.goTo and face the home direction. Takes the same opts as td.goTo.
Returnsok, err. err is "No home set" when there is no home.