ComputerCraft

Turtle — automatic mining

Program a Turtle to move, dig, and collect resources on its own. Start with the basics and build a full mining script from scratch.

Category: ComputerCraft Difficulty: Intermediate Time: ~25 min

What you will end up with

A Turtle that digs a straight tunnel of any length, collects everything it mines, and returns to the starting position with a full inventory. From here you can expand to branch mining, staircase mining, or quarry patterns.

What you need

A Mining Turtle (crafted from a Turtle + a pickaxe)
Fuel in its inventory — coal, lava buckets, or any burnable item
Space underground or in a flat area for the Turtle to dig

Turtles consume fuel for every movement. Check current fuel level with turtle.getFuelLevel(). Refuel by placing fuel items in slot 1 and running turtle.refuel() from the terminal.

Turtle movement basics

Turtles move one block at a time. All movement functions return true on success or false, "reason" on failure (e.g. blocked).

turtle.forward() / turtle.back() — move forward or back
turtle.up() / turtle.down() — move up or down
turtle.turnLeft() / turtle.turnRight() — rotate 90°
turtle.dig() — mine the block in front
turtle.digUp() / turtle.digDown() — mine above or below
turtle.detect() — returns true if there is a block in front

Step 1 — Fuel up the Turtle

Right-click the Mining Turtle to open its inventory.
Place coal (or any fuel) in slot 1.
Open the terminal (click the screen icon or right-click while sneaking) and run:
turtle.refuel() print(turtle.getFuelLevel())
You should see a number above 0.

Step 2 — Simple straight tunnel

Place the Turtle facing into a wall. Create a new program:

edit mine.lua

Type the following:

-- mine.lua
-- Digs a straight tunnel of the specified length

local LENGTH = 20  -- change this to set tunnel length

for i = 1, LENGTH do
  -- Dig forward (handles gravel/sand falling)
  while turtle.detect() do
    turtle.dig()
    os.sleep(0.3)
  end
  turtle.forward()

  -- Also clear above (2-block-tall tunnel)
  turtle.digUp()
end

print("Tunnel complete. Returning...")

Save, exit, and run:

mine

The while turtle.detect() loop handles falling blocks like gravel and sand — it keeps digging until the path is clear before moving forward.

Step 3 — Return to start

After mining, the Turtle needs to come back. Extend mine.lua with a return function after the mining loop:

-- After the mining loop, turn around and walk back
turtle.turnLeft()
turtle.turnLeft()

for i = 1, LENGTH do
  while turtle.detect() do
    turtle.dig()
    os.sleep(0.3)
  end
  turtle.forward()
end

turtle.turnLeft()
turtle.turnLeft()
print("Back at start.")

Step 4 — Check the inventory

After returning, inspect what was collected with this snippet in the terminal:

for slot = 1, 16 do
  local item = turtle.getItemDetail(slot)
  if item then
    print(slot, item.name, item.count)
  end
end

Full mine.lua — complete script

-- mine.lua — digs a tunnel and returns to start

local LENGTH = 20

-- Dig forward
for i = 1, LENGTH do
  while turtle.detect() do
    turtle.dig()
    os.sleep(0.3)
  end
  turtle.forward()
  turtle.digUp()
end

print("Tunnel done. Returning...")

-- Turn around
turtle.turnLeft()
turtle.turnLeft()

-- Walk back
for i = 1, LENGTH do
  while turtle.detect() do
    turtle.dig()
    os.sleep(0.3)
  end
  turtle.forward()
end

turtle.turnLeft()
turtle.turnLeft()
print("Done. Check inventory with: turtle.getItemDetail(slot)")

Useful Turtle API methods

turtle.getFuelLevel() — current fuel amount
turtle.refuel(count) — consume items from selected slot as fuel
turtle.getItemCount(slot) — number of items in a slot
turtle.getItemDetail(slot) — item name and count for a slot
turtle.drop(count) — drop items from selected slot in front
turtle.select(slot) — set the active inventory slot (1–16)

Troubleshooting

Turtle does not move — check fuel level. Run turtle.refuel() with coal in slot 1.
Inventory full, items lost — add a check inside the loop: if turtle.getItemCount(16) > 0 (last slot has items), return early to empty the inventory.
Turtle stuck in lava/water — add turtle.place() with a bucket or use turtle.inspect() to detect liquid before moving.

← Back to Tutorials