Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Why another turtle digging/builder program? Because I wanted a program that met my specific feature requirements, and also I don't care that I am re-inventing the wheel. I code just for fun! I'm providing my turtle dig/build system in case someone else might find it as useful.
The primary focus of this program is for builders. It's designed to dig out a X by Y by Z hole. It can also fill in a X by Y by Z hole with blocks. That's pretty much all it does.
It's possible to use this as a miner, but it's not optimized for that sort of job. For example, it only digs two blocks out at a time, when it should be doing three for large scale work. It also does not care what it is mining or where it puts it; A true mining system should intelligently sort items it acquires or seek out materials.
To guide the turtle, you give it a command like "dig 5 7 2", which will tell it to dig a hole that is 5 blocks wide, 7 blocks tall, and 2 blocks deep. These dimensions can be negative, which will tell the turtle to move in the opposite direction.
For the latest features/changes to REB, check out the changelog.
Table of contents
- How to Install
- Coordinate system used by REB
- Turtle home
- Work zone
- Remote control of Turtle
- Command reference
- Can excavate a 3d area of nearly any size.
- Note: REB is optimized for small digs, <64^3 blocks in size but can be used for larger.
- Will automatically re-dig when moving upwards if it detects sand or gravel has fallen upon it.
- Note this option does slow down the digging, so it is off by default.
- Can build a 3d area of nearly any size.
- REB turtle will utilize all blocks that it finds in its inventory, starting from the left-topmost and working its way down.
- Will build from bottom-to-top and stop once it places the last block.
- Can be configured to do destructive building (replacing every block) or to pause if it runs into a block.
- Smart movement system, will fill in/dig out areas using alternating spirals.
- Turtle can be paused mid-task, in case you need to move something or alter its inventory.
- Turtle can be relocated to new area to begin a new task without having to break/drop turtle.
- Auto-refuel system.
- Auto-refuel system can be configured to accept fuel in first slot only, or any slot.
- Amount of fuel items to burn at once can be configured, to minimize turtle wasting fuel.
- Auto-unload system when excavating.
- If a turtle detects all inventory slots are full, it will automatically return to unload its inventory.
- Will also auto-unload at the end of excavation run.
- Can be disabled for smaller projects when you don't want to place a chest.
- Remote or direct control of turtle.
- Drive the turtle directly from the turtle itself.
- Use a wireless/wired modem via rednet on a remote computer to control the turtle.
- Both programs use the same set of text commands to control the turtle.
- Remote control application that is designed specifically for advanced pocket computers.
- Remote will also work on a normal/advanced computer, but won't look as nice. :)
- Remote program displays turtle status and:
- Fuel amount and status.
- Heart-beat pulse so you know it's working.
- Turtle position and orientation.
- Progress bar for current task.
- Scrollable log of all messages the turtle has sent, for debugging problems.
- Built-in reference navigation system which does not require GPS system.
- Robust but simple packet system, including a "fake" local loop-back system.
- Robust turtle management system with lots of failsafe/error checking.
This program requires at least ComputerCraft v1.5.0. It has been tested extensively under CC 1.6.3.
First, install the github installer created by max96at. It is available in a ComputerCraft forum post.
The server that runs CC will need to make sure that the github.com website is white-listed before you can run this program. If you receive an error of "Bios:500: Domain not allowed", then you cannot proceed until github is added to the ComputerCraft config.
To download and install github, issue this command:
pastebin get wPtGKMam
Once github is installed, install the REB system using this command:
github ChainedLupine ltk-cc-projects /reb reb
This will install REB into the directory named
/reb on your computer. You need to install REB on both the turtle and any computers that you will be using to control the turtle.
Once installed, use this command on the turtle:
This will start the host program on the turtle and it should look something like this:
REB uses its own relative coordinate space, which has nothing to do with Minecraft coordinates. That's important to remember. This might seem confusing at first, but it's quite useful once you are familiar with it.
- X coordinate - Relative to the turtle's front or back. Negative x is back, positive x is forward.
- Y coordinate - Relative to the turtle's left or right. Negative y is left, positive y is right.
- Z coordinate - Relative to the turtle's up or down. Negative z is down, positive z is up.
X/Y/Z is always relative to the turtle's front. If you turn the turtle, the X and Y coordinates will change relative to the Minecraft world. (But X will always refer to the front/back of a turtle, no matter which way it faces.)
Why use this system? Because it's easier to figure out what the turtle will do when you give it orders for builds/digs. If I tell it to dig out a 2 by 2 by 2 area, it will always start digging towards the right while moving forward and up. But again, this is relative to the turtle's front, so having the turtle facing the right direction before giving it a command is important. If I told it to dig a -2 by -2 by -2 area, then it will move to the left, backwards, and down.
To help better visualize this, here's a diagram:
You can also use the manual turtle movement keys to drive the turtle around yourself and get a feel for how it moves.
Note: The turtle uses zero-relative coordinates, but commands are given in an area. So,
dig 2 2 2 will dig an area that is two blocks wide, two tall, and two deep -- starting at the block that the turtle is currently occupying. This means that for
dig 2 2 2, the turtle will move in a region defined by coordinates 0,0,0 and 1,1,1.
Note: While the system supports negative X coordinates, some functions will not work properly if you tell the turtle to move in this direction. For example, the auto-unload command expects a chest to be immediately behind the turtle's home position and issuing a dig command in the negative-x direction will cause the turtle to dig up the chest.
As mentioned, the REB system uses a relative coordinate space for the turtle. This space is defined by the turtle's home position, which is set when the program starts.
You can re-set the move position by issuing the
sethome command at any time. You can also use the
moveto command to move the turtle to a new spot, which will automatically set its home to that spot after it moves.
Note that the home position not only encompasses the turtle's location in the Minecraft world, but also its orientation. If you turn the turtle around, but do not issue a
sethome command, the turtle will still think its facing the other direction.
You can define a zone for the turtle. This zone will be remembered and can be used for issuing future commands.
To define a zone, use the manual movement keys to move the turtle to where you want the end of the zone to be. Issue the
setzone command. The turtle will report the dimensions of this zone.
From then on, if you issue a command with the zone parameter, it will use this zone for the command. For example:
Practicing moving with zones is a good way to get a feel for the relative coordinate system that REB uses. In practical use, zones have little application.
To start the remote control program, issue the command
connect TurtleName. Replace
TurtleName with the name of the turtle you are attempting to connect to.
Once the program has started, you will see the status readout of the turtle, plus a console area. If the status never changes from
Detecting... then you probably have the name of the turtle wrong.
Once in the program, you can press
H to bring up help. This will be an abbreviated list of all commands and keys that are valid.
To enter a console command, press the
T key. This will ask you for a command via the
Cmd> prompt. Enter a command and the turtle will execute it. See Commands for a list of all valid commands and their options.
Once you issue a command, the turtle will begin to execute it. You will see realtime status updates, as long as the turtle remains within range of your remote computer.
Note: The turtle does not require to be in range of the remote computer in order to function. It will continue if communications are lost.
To scroll the log, use the
UP ARROW and
DOWN ARROW keys. You can exit the program at any time by pressing
In the remote program, you can move the turtle manually when it is not executing a task. (ie: It is labeled as Idle.)
The controls are:
D to turn left, move forward, and turn right.
R will move the turtle up, and
F will move it down.
O in the remote program, you can view the options that will be sent to the turtle at every command.
To change what option is selected, use the
UP ARROW and
DOWN ARROW keys.
LEFT ARROW and
RIGHT ARROW changes that option.
Note: These options must be changed before you start a command. If you change the options after a command is given, the changed options will not take effect until you stop the turtle and re-issue the command.
Options currently in the program are:
Auto-unload -- Automatically unloads the turtle once a command is finished. This requires a chest (or some other item which can accept inventory) placed behind the turtle at its home position. Note that currently this option only applies to the
digcommand. Be careful with negative X values for dig commands! The turtle will dig its own chest if told to do so. :)
Refuel slot -- Instructs what slot to use for refueling. By default, the turtle will only refuel for slot number 1 of its inventory, which corresponds to the top-leftmost slot. By setting this to Any, the turtle will use any slot that contains fuel (starting from the top-leftmost).
Destructive moves -- Only applies to
buildcommand. If enabled, this will cause the turtle to destroy every block it encounters, including the block immediately underneath it.
Refuel amount -- When refueling, either in first or any slot mode, it will consume this number of fuel items.
Falling block check -- When digging, the turtle can be instructed to check for blocks which might have fallen upon it. This will let it deal with situations where it digs up into a column of sand and gravel. This option is disabled by default, as the turtle will pause every time it digs for a very short amount of time to verify that nothing is falling. This slows down the overall dig speed.
Here is a list of all commands accepted by the turtle and what their arguments mean.
dig X Y Z -- Will dig out a region defined by X, Y, and Z. X/Y/Z are whole numbers, and can be positive or negative. Note that only X is required. Y and Z will assumed to be 1 if they are not given.
dig zone -- This command is the same as
dig, but it will instead dig out the zone defined by the
build X Y Z -- Will build a region immediately one block below the turtle, of size X/Y/Z. Note that as with the dig command, only the X is required and all other numbers will be assumed to be 1 otherwise. Positive and negative numbers work.
build zone -- This command is the same as
build, but it will instead use the zone defined by the
stop -- Stops all turtle movement and activity. Erases all current tasks.
pause -- Pauses the current task. The turtle can be resumed with the
resume -- Resumes a task in progress.
refuel -- Force a refuel of the turtle.
unload -- Force an unload of the turtle. The turtle will move itself back to coordinates 0,0,0 if necessary.
sethome -- Clears the turtle's current coordinate system and resets it so it is at 0,0,0.
setzone -- Sets a zone. First, move the turtle via the manual control keys to the end of the zone you desire, then issue this command to record that zone region. Note: Do not try to break the turtle and re-place it to define the end of a zone, as this will reset the program.
moveto X Y Z -- Moves the turtle to the coordinates given (relative to the turtle). Once the turtle has moved to these coordinates, it will zero its coordinates back to 0,0,0, as if the
sethomecommand had been issued. It can be used to move a turtle forward when digging a tunnel in sections, without having to break and drop the turtle.
reboot -- Force a reboot of the turtle.
Controlling at Turtle
Note that the turtle
host program also responds to the
T key for entering commands, and you can use the same commands as given in the remote program.
The manual move keys also work.