A collection of practical CC:Tweaked turtle programs with a Basalt user interface.
Turtle Toolbox is in early development. The Basalt launcher, shared turtle runtime, persistent job system, tracked movement, and the first executable turtle programs are available.
The available programs are:
- Room Digger — room excavation using length, width, and height settings.
- Excavate+ — downward area excavation using length and width, optional depth, and inventory filtering.
- Tunnel Digger — configurable tunnels with an optional unlimited length.
- Branch Miner — a main tunnel with regularly spaced left and right branches.
- Staircase Digger — a straight or switchback descending passage with configurable width and walking height.
- Vein Miner — connected 3D mining for the block directly in front of the turtle.
- Tree Harvester — stationary whole-tree axe harvesting with nearby drop collection and replanting.
- Crop Farm — continuous mature-crop harvesting and replanting across a rectangular field.
Running jobs can be paused, resumed, or cancelled from the dashboard. Progress, relative position, heading, runtime phase, movement count, and mined blocks are saved throughout the job. Jobs that were safely between movements continue automatically after a restart.
- CC:Tweaked
- A turtle with the tools required by the selected program
- HTTP access enabled for automatic dependency installation
Basalt will be installed automatically when it is required and not already available.
Run this once on a fresh turtle:
wget run https://raw.githubusercontent.com/Pyroxenium/turtle-toolbox/refs/heads/main/install.luaThe installer downloads the repository manifest and every required runtime file
with http.get. Repository-only files such as the README and license are not
copied to the turtle. Downloads are staged in a temporary folder, so an
interrupted download does not leave a partial installation behind.
The turtle is configured with:
/startup.lua— starts Turtle Toolbox automatically after a reboot./turtle-toolbox/— contains the launcher, jobs, and shared runtime modules.
For safety, the installer refuses to overwrite an existing /startup.lua or
/turtle-toolbox/ installation.
Run the launcher immediately after installation:
startupAfter a reboot, /startup.lua launches it automatically. The launcher can also
be started directly with turtle-toolbox/main.
On first launch, Turtle Toolbox checks for /basalt.lua. When it is missing,
the official Basalt installer is run with:
wget run https://basalt.madefor.cc/2.5/install.lua minifiedSelect Blacklist in the launcher sidebar to manage the shared inventory filter.
Enter a full block ID such as create:limestone, or enter a vanilla path such as
stone and the editor will store it as minecraft:stone. Select an existing
entry and use Remove block to stop filtering it.
Changes are saved immediately in /.turtle-toolbox/block-filters.json. The file
contains a version and a sorted array of block IDs. It is stored outside the
installed program directory so a later Toolbox update does not overwrite the
user's choices. All jobs configured with Drop filtered blocks use this one
shared list.
Place the turtle directly outside the lower-left corner of the planned room and
point it into the room. The configured volume extends forward, to the turtle's
right, and upward. The dimensions are Length × Width × Height: length extends
forward, width extends to the right, and height extends upward. This placement is
the origin at (0, 0, 0). The first mined block is directly ahead at (0, 0, 1).
When Chest behind is selected, place a chest directly behind the turtle at the origin. The shared runtime returns through already excavated cells, turns around at home, and unloads into that chest. Drop behind drops items at the same location without requiring a chest, while Keep items pauses when the inventory is full.
Before every work step, the runtime reserves enough fuel for the known safe route home plus the configured fuel buffer. Coal, charcoal, and coal blocks in the turtle inventory are consumed one item at a time only when the current fuel level is too low. If onboard fuel still is not sufficient, the turtle returns home before continuing and waits there for more fuel. After service, it navigates back to its saved work position and continues the same job.
The job pauses when service needs user attention or movement remains blocked. Resolve the issue and select Resume. Do not move or turn the turtle manually while a saved job is active, because recovery uses its tracked relative position and heading.
Every movement is journaled before it is attempted. If a server restart occurs during the exact moment of a movement, Turtle Toolbox marks the job as requiring manual recovery instead of guessing whether the movement completed. This avoids continuing from coordinates that may be incorrect.
Active job state is stored in /.turtle-toolbox/active-job.json.
Place the turtle on the upper-left corner of the area to excavate and point it
along the configured length. The dimensions are Length × Width: length
extends forward and width extends to the right. The first excavation cell is
directly ahead of the turtle at (0, 0, 1), so the starting level is included
as the first layer. The turtle only descends after completing that entire layer.
Saved Excavate+ jobs created with the previous layout that started below the
turtle are marked as incompatible and must be cancelled instead of being
resumed with incorrect coordinates.
Set Depth to a positive number to excavate exactly that many layers. Set it
to 0 to make depth optional: the turtle continues downward until it encounters
bedrock or another known unbreakable block. Reaching an unbreakable block is a
successful completion condition, not an error.
The Drop filtered blocks option discards inventory items listed in the shared block-filter configuration while the job runs. The default list contains common terrain blocks, while ores and unknown or modded blocks are kept unless the user adds them explicitly.
Excavate+ uses the same home service as Room Digger. With Chest behind
selected, place the output chest directly behind the turtle at (0, 0, -1).
Fuel checks, selective auto-refueling, unloading, restart continuation, and the
return to the saved work position are handled by the shared runtime.
Place the turtle at the lower-left entrance of the planned tunnel and point it
forward. The configured dimensions are Length × Width × Height. Length
extends forward, width extends to the right, and height extends upward. The
first excavation cell is directly ahead at (0, 0, 1).
Set Length to 0 for an unlimited tunnel. In this mode the turtle continues
until it reaches bedrock or another known unbreakable block. Set a positive
length to excavate an exact tunnel volume. Wider and taller tunnels are cleared
one complete cross-section at a time, using only cleared cells for service trips
back to the origin.
Place the turtle at the entrance and point it along the planned main tunnel. The Branch Miner digs a one-block-wide main tunnel with the configured height. At every Branch spacing interval it creates side branches with the configured length and height, then returns to the junction before continuing forward.
Branch sides can be set to both sides, left only, or right only. Left and right are relative to the turtle's starting direction. The saved action index allows a paused or restarted job to continue in the same main tunnel or side branch without rebuilding a large route in memory.
Both programs support the shared block filter and all shared runtime
features. When Chest behind is selected, place the chest directly behind the
turtle at (0, 0, -1).
Place the turtle at the top entrance and point it in the direction the staircase should descend. Every configured step moves one block forward and one block down. Width extends to the turtle's right, and walking height controls the clear vertical space at every step. The program excavates the passage but does not place stair blocks.
Set Turn interval to 0 for a straight staircase. A positive interval adds a
full-width landing after that many steps, shifts the next flight to the right,
and continues downward in the opposite direction. For example, Steps = 32
and Turn interval = 16 creates two parallel 16-step flights.
The turtle finishes each level on the lower walking surface. Its safe route home climbs the already excavated staircase in reverse, including from a partially cleared wide step. Common-block filtering and all shared service options are available.
Place the turtle directly in front of the first block in the vein and point the turtle at it. The inspected block ID becomes the target. The miner follows blocks with that exact ID in all six directions; diagonally touching blocks are not considered connected.
Maximum blocks is a safety limit rather than an expected vein size. The job finishes when the complete connected vein has been explored or that limit has been reached. Its saved depth-first path provides a known route through mined blocks for fuel service, unloading, and restart continuation. If no starting block is present, the job pauses with an English error instead of mining an arbitrary neighboring block.
Place the turtle on the ground directly in front of a supported tree trunk and point it at the lowest log. Equip it with an axe or tool whose single dig action fells the complete tree. The turtle never leaves its starting position. Oak, spruce, birch, jungle, acacia, dark oak, mangrove, cherry, pale oak, crimson, and warped trees are recognized.
When Replant tree is enabled, put at least one matching sapling, propagule, or fungus into the turtle before starting. One planting item is retained during automatic unloading and placed in the original trunk position after harvesting. The optional output chest remains behind the turtle at the starting position.
After felling, the turtle repeatedly collects drops in front, to both sides, above, and below for the configured collection time. The rear side is skipped when using chest or drop output so the turtle cannot pull items from its output or collect them again. With Keep items, the rear side is collected as well.
The default Continuous mode waits at home for the next tree, harvests it, replants it, unloads the logs, and repeats indefinitely. Check interval controls how often the block ahead is inspected. Use Single cycle for one tree only. The sapling reserve is retained between automatic unloading trips.
Place the turtle one block above the first crop in a uniform rectangular field, facing along its length. Width extends to the turtle's right. Put at least one matching seed item into the inventory and place the optional output chest behind the turtle at the same height.
The farm detects wheat, carrots, potatoes, beetroot, nether wart, or torchflower from the crop below its starting position. It follows a serpentine route, skips missing or immature plants, harvests mature plants, and replants them immediately. The configured seed reserve is kept during service trips and unloaded after the job ends. In the default Continuous mode, the turtle returns home and unloads after every field pass, waits for the configured check interval, and starts the next pass. Use Single cycle to process the field once and stop.
After every harvest, the turtle performs the configured number of collection passes below, on all safe horizontal sides, and above before replanting. At the starting cell, the rear side is skipped for chest and drop output. If the inventory fills during collection, the turtle unloads and returns to the same field position before continuing.
Job implementations provide their work sequence and a safe route planner back to the origin. The shared runtime owns fuel checks, selective auto-refueling, inventory service, home and work return trips, movement journaling, checkpoints, and restart continuation. New turtle programs can reuse those guarantees without implementing their own fuel or recovery logic.
Licensed under the MIT License.