Start here

Getting started.

Programs you run from the deck are plain CC:Tweaked Lua with one extra global, td: the TurtleDeck library. It tracks position, handles gravel, mobs, fuel and full inventories, and never digs chests, machines, other turtles or bedrock. This page covers what a program gets, how it runs, and how to wrap your own work in a job.

The program environment.

The deck sends your code to the turtle, which loads it with load(code, "=name", "t", env) and runs it as a coroutine. The environment falls through to the normal CC:Tweaked globals, so everything you know still works: turtle, peripheral, os, fs, textutils, sleep, gps, rednet and the rest.

  • td is a global. Prefer it over hand-written movement and mining loops.
  • print, write and printError also go to the deck Console (printError as an error line). Use print to report progress and results.
  • Every turtle.* move, turn, dig, place, attack, suck, drop and inventory call is wrapped, so position tracking and the live map keep up with moves your program makes. Do not change position by any other means.
  • There is no keyboard. Do not wait for input with read(): put settings in local variables at the top of the program instead.
  • Programs must be under 100 KB.

Running and stopping.

Open a turtle on the deck, write or paste a program and press Run. The deck shows when it starts and whether it finished, stopped or failed with an error.

The Stop button abandons the program coroutine between turtle actions. It never interrupts a move half way, because the position would be lost. When stopped, the program simply ends where it is: nothing after the current action runs, including the return home of a job.

Custom jobs with td.run.

The built-in mining jobs and td.build all run through the same job wrapper. td.run gives your own work that wrapper.

td.run(name, opts, body)

Runs body(check) as a job: logs "name started" and "name finished" (with fuel left) to the Console, and afterwards travels back to the return point. The return point is home when one is set, otherwise the spot where the job started. Back there, anything in the inventory is unloaded the way jobs unload (see Where jobs unload).

Ordinary Lua errors in the body are not caught: they end the program with an error as usual.

Returnstrue when the body finished, or false, reason when check() had to stop the job.

  • returnHometrue | falsedefault trueGo back afterwards and empty the inventory. Pass false to stay where the job ended.
  • dropJunktrue | falsedefault falseWhen the inventory is full, first drop junk blocks (see td.dropJunk) before unloading.
check()

The function your body receives. Call it before each block of work. It does two things, and stops the job (the body ends, the return home still happens) when it cannot:

  • Fuel reserve. If the fuel level is below the distance back to the return point plus 30, it burns fuel from the inventory up to that plus 200. With nothing to burn it goes to the shared fuel chest set on the deck, if it can still reach it. Otherwise the job stops with "low fuel".
  • Full inventory. With no empty slot it drops junk (when dropJunk is set), then unloads through a carried ender chest, else at the shared unload chest, else into a chest touching the turtle where it stands. With none of those the job stops with "inventory full".

check() does not handle the Stop button. Stop works on its own, between any two turtle actions.

run_skeleton.lualua
td.setHome()local ok, why = td.run("My job", { dropJunk = true }, function(check)  for i = 1, 20 do    check()                      -- fuel reserve and full inventory    assert(td.digMove("forward"))  endend)if not ok then print("Stopped early: " .. why) end

A first program.

This one walks forward digging a 1 wide, 2 high corridor, prints its progress to the Console and comes back. It uses td.digMove, td.clear and td.goHome.

first_corridor.lualua
-- Dig a short 1x2 corridor, report progress, then come back.local LENGTH = 10 td.setHome()for i = 1, LENGTH do  local ok, err = td.digMove("forward")  if not ok then error("stuck after " .. (i - 1) .. " blocks: " .. tostring(err)) end  td.clear("up")  print("Dug " .. i .. " of " .. LENGTH)endassert(td.goHome())print("Back home")

For longer work, wrap the loop in td.run and call check() each step, as in the corridor example. Next, the movement chapter covers position and travel.