Skip to content
All projects

distributed-quarry

Runs any number of mining turtles on one quarry in CC:Tweaked, without GPS, and recovers cleanly when any of them reboot.

Role
Sole author
Period
2026-08 → now
Status
maintained
Stack
Lua, CC:Tweaked, Rednet

Overview#

CC:Tweaked is a Minecraft mod that adds programmable computers and small mining robots called turtles. distributed-quarry digs a rectangular quarry with as many turtles as you give it. One controller computer keeps the map of the quarry and hands out sections to the turtles over Rednet, the mod's wireless network. Each turtle mines its section and reports back to the controller. Turtles never talk to each other.

Most of the work went into recovery. Turtles reboot, chunks unload and the server restarts, and a turtle can disappear halfway through a section. The system has to keep going through all of that without GPS and without two turtles digging into the same blocks.

Problem#

A turtle keeps its program state in memory, and CC:Tweaked restarts computers when their chunk unloads or the server restarts. A simple quarry script loses track of where it is after a restart and digs in the wrong place. With several turtles you also get collisions and overlapping work. GPS would solve the position problem, but it needs extra hardware in the world and many servers don't have it.

Constraints#

  • No GPS, no geo scanners, no external storage and no HTTP at runtime.
  • Any machine can reboot at any moment, including while moving or saving.
  • Turtles can join or leave while the quarry is running.
  • A player should be able to install it with three wget commands.

Architecture#

There are three programs. The selector is used once to mark the corners and depth of the quarry. The controller splits the area into sections, 8 by 8 blocks by default, with the edge sections cut to fit. It tracks each turtle with heartbeats and decides which turtle gets which section. The miners register with the controller, take a section, and mine it one layer at a time in back-and-forth rows, reporting progress as they go.

Turtles work out their position by counting every successful move from a known starting dock, and they save that position after each move. They travel to and from their sections along a clear layer above the quarry, so they don't cut through another turtle's section.

Technical decisions#

Only the controller decides who mines what#

When a turtle reboots, it asks the controller whether its saved section is still assigned to it, and it only carries on if the controller agrees. If it can't reach the controller, it waits. It never picks a new section by itself.

Sections are released only after a timeout#

A turtle that misses heartbeats is marked STALE, and later OFFLINE. Its section goes back into the pool only once it has been offline for longer than jobReleaseTimeout. A turtle that is just slow keeps its section, and a section is never assigned to two turtles at once.

Stop on a failed move#

If a turtle can't move, it switches to an ERROR state and stops. It doesn't attack or dig whatever is in its way, because that could be another turtle.

Trade-offs#

The quarry has to be a rectangle. There is no ore detection, no cave pathfinding and no routing around obstacles, because each of those adds new ways for a turtle to lose track of where it is. The controller is a single point of coordination. If it goes down, the turtles wait until it comes back.

Implementation details#

Every state file is written to a temporary file first and then moved into place, with a backup in between. If a turtle reboots in the middle of a save, the old state file is still intact.

shared/persistence.lua (excerpt)
function M.save(path, value)
  ensure(path); local tmp=path..".tmp"; local backup=path..".bak"; local h=fs.open(tmp,"w")
  if not h then return false,"cannot open "..tmp end
  h.write(textutils.serialize(value)); h.close()
  if fs.exists(backup) then fs.delete(backup) end
  if fs.exists(path) then
    local backedUp, backupErr = pcall(fs.move, path, backup)
    if not backedUp or not fs.exists(backup) then return false, backupErr or ("cannot back up "..path) end
  end
  local moved, err = pcall(fs.move, tmp, path)
  if not moved or not fs.exists(path) then
    if fs.exists(backup) and not fs.exists(path) then pcall(fs.move, backup, path) end
    return false, err or ("cannot replace "..path)
  end
  if fs.exists(backup) then fs.delete(backup) end
  return true
end

Each turtle saves which block it will mine next after every block it mines. When its fuel runs low or its inventory fills up, it moves back along the travel layer to its dock, unloads, refuels, and returns to the same spot in its section.

Outcomes#

The quarry works with several turtles. The README has a ten-step test checklist for the failure cases. It covers rebooting a turtle mid-section, rebooting the controller, removing a turtle until its section is released, running low on fuel, a full inventory, clipped edge sections, and pausing and resuming. I haven't measured mining speed.

The installer only downloads the program for the role you pick plus the shared modules. Re-running it updates the programs and keeps your existing configuration.