This is a guide which attempts to impart the basics of programming to someone who is not familiar with programming languages or used a ComputerCraft Turtle. The first thing you need to know when programming in ComputerCraft is how to use the text interface in a Turtle.
The Turtle's text interface is accessed by right-clicking on a Turtle that is placed in the world. A GUI will appear that greets the player with the message, "TurtleOS 1.4" followed by an angle bracket and a blinking cursor. This is the text interface with which you will be working with and this particular screen is known as the "command line".
Giving the turtle a name: Naming turtles is very important, without a name a turtle will forget its fuel level and any programs upon breaking it. To name a turtle simply type
label set Bob
Where "Bob" is what you want to call the turtle.
Running a Program: To run a program, type the name of the program you want to run and any input the program will need (if any) separated by a single space. For example, typing "tunnel 100" will make a Mining Turtle dig a 2 high by 3 wide by 100 long tunnel.
Creating a program: To create a program of your own, type
Where <program> is the name of the program you wish to create (example: "edit turnAround"). It's important to note that the program name cannot contain any spaces. If we tried to use a space in our example and typed
edit turn around
We would end up with a program named "turn".
The name of a program must be a single string of characters. Multiple words may be placed together if needed but it is suggested that the first letter of each subsequent word be capitalized. This is commonly called camel-case notation in programming as the capital letters look like the humps on the back of a camel.
Save your program: To save your program you will need to make a disk drive and a floppy disk. Place your disk drive next to your computer, and put in your floppy.Then type
copy <program> diskWhere <program> is the name of the program you wish to save.
Access a program on a floppy disk:To access a program on a disk you will need to first change the directory you are in to the disk directory. To do so type
cd diskNow all you have to do is type the name of your program and any inputs it needs. Alternatively, you can type
disk/<program>Where <program> is the name of the program in the disk directory.
The most basic program you can create with a computer is known as the Hello world program. This program makes the Turtle speak in the screen "Hello, world".
For now we will create a program which does something slightly more useful. This program will make a Mining Turtle branch mine for you.
First type "edit mine" to create a new program titled "mine". You will now see a blank window where we will type our program. Pressing the control key allows you to access the menu which lets you save, exit, or print. Use your arrow keys to change which option you have selected and enter to do that option. For now, just press the control key again to close the menu.
Making a startup script Edit
Startup scripts are very useful for relaying important data(e.g.: Name, ID, Fuel...) When a turtle turns on it checks for a file called "startup", and if one is present it will run it. to make the startup script type
Now you will be in a window where you can make your program. Now for the code:
print("Name: "..os.getComputerLabel()) print("ID: "..os.getComputerID()) print("Fuel: "..turtle.getFuelLevel())
Now press <L Ctrl> and release it, then press <Enter>. this will save the program into your turtle.
Restart your turtle(hold <L Ctrl> + <R> for 1 second)
Name: Bob ID: 2 Fuel: 47
note: any text used in programs as a "string" value must be surrounded by a pair of quotation marks. the ".." means to join multiple strings together, example:
would make this appear on the turtles screen:
Using The Turtle API Edit
To make your turtle do something you will need to call a function from its API (Application Programming Interface). A function is basically a bit of code which can be run multiple times. I will get into more about how to make one later, but for now that is all you need to know.
The first thing you will want your turtle to do as it starts mining is to dig the block in front of it. To make it do this, type "turtle.dig()" (without the quotes) and then press enter. The Turtle won't actually mine the block in front of it right now as we are writing the program, not running it.
We also want to have the turtle dig above and below it. Type "turtle.digUp()" and press enter, then type "turtle.digDown()" and press enter.
Next we will want our turtle to move forward. To make your turtle move forward, type "turtle.forward()".
At this point your code should look like this:
turtle.dig() turtle.digUp() turtle.digDown() turtle.forward()
It is important that your code has the same captialization as what is written above. Ensure that your code matches the above text exactly before before proceeding.
Now, save your program by pressing the control key, navigating to the save button on the menu with the arrow keys, and then pressing enter. You should see a message at the bottom which says "Saved to mine". Your program is now saved to the Turtle.
To run our program, we will need to exit the editor and get back to the command line. To do this, press the control key to access the menu again but this time navigate to the exit button and press enter.
Now that we're back at the command line you may type the name of our program and press enter to run it. Simply type "mine" and your turtle will dig in front, above, and below itself before moving forward one block.
As we have it right now, the turtle may waste a lot of time, since it digs without checking if there is something to dig. To make the turtle check to see if there's a block in-front of it, you will need to use an if statement.
The syntax for an if statement is as follows:
if [condition] then
[code to run when the condition is true]
For our program, edit mine add an if statement using the turtle.detect() function in the condition. your code should look like this:
if turtle.detect() then turtle.dig() turtle.forward() end
We should do the same to check if there is a block above using turtle.detectUp() and bellow with turtle.detectDown()
After you add these if statements our code should look like this:
if turtle.detect() turtle.dig() end if turtle.detectUp() then turtle.digUp() end if turtle.detectDown() then turtle.digDown() end turtle.forward()
Before we talk about the loops, we should spend a moment to learn about variables. A variable stores information specified by the programmer. This information may be a numeric value, a Boolean value (true or false) or a string (a collection) of characters (letters, numbers, symbols). A variable is declared(when you tell the computer that it exists, its name, and value) using this syntax:
[a single word name that starts with a letter] = [the value or contents of variable]
For example if we wanted a variable to hold the value of how far we want our turtle to dig, we would make a variable like this:
length = 100
It is usually helpful for variables to be placed at the top of your code, unless they are temporary. A temporary variable (known as local) only exists within the body of a specific element of code. For instance, if you made your variable in an if statement, it probably would not be defined after the end.
You should now add "length = 100" above your code in mine, so that it looks like this:
length = 100
if turtle.detect() turtle.dig() end if turtle.detectUp() then : turtle.digUp() end if turtle.detectDown() then : turtle.digDown() end turtle.forward()
Our turtle can now dig a block in front of it, if there is one, and then move forward once, but as it is we would have to rewrite those two commands over and over to get it to repeat. Instead of doing this we can use a loop to have the computer repeat those lines of code as many times as we need.There are at least two kinds of loops in Lua. We want the turtle to move and mine a predefined number of times ahead so we want to use a counting loop, which is known as a for loop.
A for loop's syntax is as follows:
for [variable]=[numerical start value], [numerical end value], [value to count by] do
[code to loop]
For our for loop, we will want to have it start at 1 and end at length. The following is an example of how to do this:
for i=1, length, 1 do
[code to repeat]
This loop will first check to see if the counter is equal to the end value, and if it is not then it adds one and does whatever is within the body of the loop(between the do and end)
At this point your code should look something like this:
length = 100
for i=1,length,1 do
if turtle.detect() then
if turtle.detectUp() then
if turtle.detectDown() then
When we run the program as is, you will find that there is a problem which will make the end result unpredictable. If the turtle runs into falling sand or gravel, its likely that it will cause the turtle to behave in a way we don't want, because the tunnel will be shorter than we planned. To account for this we can replace the if conditions with another kind of loop, so that before moving ahead the turtle will check if there's a new obstacle.
This loop is called a while loop. This is a while loops syntax:
while [condition statement] do
[code to loop]
For an example of how we can use a while loop, we can replace the if condition in our program with a while loop. We will also want to make the turtle wait a second after digging to account for the time it takes for a block to fall. To do so we use the sleep(1) function.
Your while loop should look like this:
while turtle.detect() do
You should go ahead and also replace the if condition for checking if there's a block above the turtle with a while loop, but it is not necessary to do so with the down.
So far, we have used a few different functions in our code without really knowing what they are. A function is a segment of code which you can call from somewhere else in our program as many times as you want. The following is the syntax for a function:
function [name of function in a single word]()
--code to make the turtle dig away every block touching it function digAround() turtle.digUp() turtle.digDown() for i = 1, 4, 1 do turtle.dig() turtle.turnRight() end end
to call the digAround() function in code we would use
Using functions in your code has a few benefits. The first is that you can make a more complicated action then easily repeat it.
In our program we will create a function called dig, which will allow you to perform the dig forward, dig up, and dig down from our current code by calling the function instead of repeating all that code.
Putting it all togetherEdit
Now that we have learned all this lets make a simple program that will chop down Redwood and Fir trees:
First we need to initialise any variables, in this program we need to keep track of how far up the tree we have come so we know how far to come back down:
local height = 0
Now we need to make some functions, one for chopping its way up the tree, one for moving over at the top, and one more for coming back down on the other side of the tree:
function chopUp() turtle.digUp() turtle.up() turtle.dig() height = height + 1 end function moveOver() turtle.turnLeft() turtle.dig() turtle.forward() turtle.turnRight() turtle.dig() end function chopDown() turtle.digDown() turtle.down() turtle.dig() end
Now that we have our functions and variables declared we can start writing the main script that tells the turtle when to use its functions:
turtle.dig() turtle.forward() turtle.dig()
That puts the turtle "in" the tree
while turtle.detectUp() == true do chopUp() end
This will continue to make the turtle dig its way up the tree until there isn't a block directly above it.
moveOver() for i = 1, height, 1 do chopDown() end
Finally we should add a line of code that returns it to its starting position.
shell.run("go right forward left back")
shell.run() is a very handy piece of code, it allows you to use other programs in the turtle as functions. The go program comes with the turtle.
Click here for the pastebin version of this program You can also use this command to do all the hard work for you:
pastebin get MMgKbqSu <program name>