FUNCTION REFERENCE

In this reference, you’ll find short descriptions of every function used in this book. The functions are grouped by application programming interface (API), also known as a module. This reference is not a complete list of all the functions in ComputerCraft, but you can read about other available functions in the documentation that ComputerCraft provides at http://computercraft.info/wiki/Category:APIs.

If you want to learn more about Lua, you can use the Lua 5.1 Reference Manual, which is available online at https://www.lua.org/manual/5.1/. Note that ComputerCraft uses Lua 5.1, even though newer versions of Lua are available.

FS (FILE SYSTEM) API

Turtles and in-game Minecraft computers have file systems similar to those your computer has. You can interact with these files using the fs API and the file’s name:

fs.delete(string filename) Deletes a file named filename

fs.exists(string filename) Returns true if a file named filename exists; otherwise returns false

HARE API

You wrote the hare API while reading this book. Unlike the other APIs listed in this reference, hare doesn’t come with ComputerCraft, so you must first run pastebin get wwzvaKuW hare from the CLI shell to download it. Each program you write that uses the hare API must include the code os.loadAPI('hare') in order for the program to call the hare module’s functions:

hare.buildFloor(number length, number width) Builds a floor length blocks long and width blocks wide using items in the turtle’s inventory.

hare.buildRoom(number length, number width, number height) Builds a room length blocks long, width blocks wide, and height blocks tall using items in the turtle’s inventory.

hare.buildWall(number length, number height) Builds a wall length blocks long and height blocks tall using items in the turtle’s inventory.

hare.countInventory() Returns the total number of items in all the turtle’s inventory slots.

hare.digUntilClear() Continues to mine the space in front of the turtle until the space contains no blocks. You use this function when gravel or sand could fall in front of the turtle as it mines the block in front of it.

hare.digUpUntilClear() Similar to hare.digUntilClear() except it clears the space above the turtle.

hare.findBlock(string name) Spins the turtle around and stops if the turtle is facing a block named name. If the turtle can’t find the block, the turtle ends up facing its original direction after the function code finishes running. Returns true if the block was found; otherwise returns false.

hare.selectAndPlaceDown() Selects a nonempty inventory slot and places the item in that slot beneath the turtle.

hare.selectEmptySlot() Selects an empty inventory slot. Returns true if a slot is found; otherwise returns false.

hare.selectItem(string name) Selects an inventory slot containing an item named name. Returns true if the item is found; otherwise returns false.

hare.sweepField(number length, number width, function sweepFunc) Moves the turtle over every space in a rectangular field length blocks long and width blocks wide, calling sweepFunc at each space.

IO (INPUT/OUTPUT) API

When you use the io API, programs can display text on the screen and also accept text from the player via the keyboard. There are several functions in the io API, but the most important function to know is io.read():

io.read() When the player types a response and presses ENTER, this function returns the response as a string value.

MATH API

The math API is part of Lua, and you can call its functions from non-ComputerCraft Lua programs. This API includes the following number and mathematics-related functions:

math.ceil(number num) Returns num rounded up.

math.floor(number num) Returns num rounded down.

math.random(number start, number end) Returns a random whole number between start and end, including start and end. The start and end arguments are optional. If no arguments are passed, the function returns a decimal point number between 0.0 and 1.0. If the start argument is not used, the function returns an integer between 1 and end.

OS (OPERATING SYSTEM) API

The ComputerCraft operating system provides the following functions, which are useable by turtles and in-game computers:

os.getComputerLabel() Returns a string of the turtle’s label (that is, its name).

os.loadAPI(string filename) Loads the program named filename as a module so the current program can call its functions.

os.setComputerLabel(string/nil label) Sets the turtle’s label to label. If label is nil, the function erases the turtle’s label.

os.sleep(number time) Pauses the program for time number of seconds.

SHELL API

Turtles can run commands from the CLI the same way the player can run commands from the CLI. You can run a CLI command in a turtle program using the shell API:

shell.run(string command) Runs command as though the player entered the string at the CLI shell. Returns false if the command terminates because the command doesn’t exist, crashes, or calls error(); otherwise returns true.

STRING API

The string API is part of Lua, and you can call its functions from non-ComputerCraft Lua programs. Although these functions weren’t featured in this book, I’ve included them here because they’re useful:

string.find(string haystack, string needle) Looks for the needle string inside the haystack string and returns two integers: the position where the needle string was found and where this string ends. For example, string.find('hello', 'el') returns 2 and 3, because 'el' is found at the second character in 'hello' and ends at the third character. If the needle string is not in the haystack string, the function returns nil. The needle string can also find text patterns, which are outside the scope of this book. You can learn more about text patterns at https://www.lua.org/manual/5.1/manual.html#5.4.1/.

string.sub(string bigstring, number start, number length) Returns a substring, or portion, of bigstring, starting at the start position and returning the next length characters. The length argument is optional. If length is not passed, the substring starts at start and continues to the end of bigstring. For example, string.sub('hello', 3, 2) returns 'll' and string.sub('hello', 2) returns 'ello'.

TEXTUTILS API

Using textutils, you can make programs display text one character at a time to create a fancy typewriter effect:

textutils.slowPrint(string text, number rate) Similar to print() except it writes the characters in text one character at a time. The rate argument is optional and specifies how many characters are printed per second.

TURTLE API

The turtle API holds all the common functions that your programs could call to make a turtle perform some action. Let’s look at these functions in batches based on the actions the functions can trigger.

BUILDING FUNCTIONS

You can call functions to make turtles build by placing blocks. But the same function can also cause the turtle to perform other actions, depending on the item in the turtle’s current slot:

turtle.place() Performs an action with the item in the turtle’s current slot. For building blocks, this function places the block in the Minecraft world. However, if one of the special items listed in Table 1 is in the current slot, that item will be used in the way specified by Table 1. The function returns false if the turtle is unable to place the block or perform an action on the block.

turtle.placeDown() Similar to turtle.place() but performs the action on the space below the turtle.

turtle.placeUp() Similar to turtle.place() but performs the action on the space above the turtle.

Table 1: Special Items That the place Functions Can Use

Item	Action
Armor	Sets the armor on an armor stand.
Boats	Places the boat on water.
Dyes	Dyes a sheep.
Empty bucket	Collects lava or water. Can also collect milk from a cow.
Fireworks	Launches the fireworks.
Flint and steel	Sets fire to a flammable block or activates a Nether portal.
Minecarts	Places the minecart on tracks.
Saplings, flowers, or seeds	Plants the object in a dirt or grass block.
Shears	Shears a sheep and collects its wool.
Sign	Places a sign with text on it. To write text on the sign, pass the turtle function a string. For example, turtle.place('This\nis a\nsign.').
Spawn eggs	Spawns a mob.

FUELING FUNCTIONS

Turtles use one unit of fuel each time they move, but they can’t move if they run out of fuel. For this reason, refueling the turtle and understanding its fueling functions are important:

turtle.getFuelLevel() Returns the amount of fuel the turtle currently has stored. Returns 'unlimited' if the ComputerCraft.cfg config file has disabled the fuel requirement.

turtle.getFuelLimit() Returns the maximum amount of fuel the turtle can store. For most turtles, the limit is 20,000 units; for other types of turtles, the limit is 100,000 units. Returns 'unlimited' if the ComputerCraft.cfg config file has disabled the fuel requirements.

turtle.refuel(number amount) Consumes amount of fuel items in the current slot. The amount argument is optional. If amount is not given, the function consumes all the items in the current slot by default.

INVENTORY FUNCTIONS

Each turtle has an inventory with 16 numbered slots. You can use various inventory functions to make the turtle perform actions on its inventory. These functions often take a number to indicate which of the numbered slots to perform an action on.

turtle.compareTo(number slot) Returns true if the item in the current slot is the same as the item in slot; otherwise returns false.

turtle.drop(number amount) Drops amount items from the current slot into the space or container in front of the turtle. The amount argument is optional. If amount isn’t given, the function drops all the items in the current slot. Returns true if any items were dropped; otherwise returns false.

turtle.dropDown(number amount) Similar to turtle.drop() except this function drops items into the space or container below the turtle.

turtle.dropUp(number amount) Similar to turtle.drop() except this function drops items into the space or container above the turtle.

turtle.equipLeft() Unequips the tool, if any, on the turtle’s left side and equips the tool in the current slot. Returns true if equipped; otherwise returns false.

turtle.equipRight() Unequips the tool, if any, on the turtle’s right side and equips the tool in the current slot. Returns true if equipped; otherwise returns false.

turtle.getItemCount(number slot) Returns the number of items in slot. Uses the current slot if slot isn’t given.

turtle.getItemDetail(number slot) Returns a table value of information about the item in slot or returns nil if the slot is empty. Uses the current slot if slot isn’t given.

turtle.getItemSpace(number slot) Returns the amount of free space in slot. Uses the current slot if slot isn’t given.

turtle.getSelectedSlot() Returns the slot number (1 to 16) of the current slot.

turtle.select(number slot) Changes the current slot to slot, a number from 1 to 16.

turtle.suck(number amount) Takes amount items from the space or container in front of the turtle, sucking them up like a vacuum cleaner, and places them in either the current slot (if empty) or the first available empty slot. The amount argument is optional. If amount isn’t given, a full stack of items is taken. (A full stack is 64 for most items, although some items like eggs, snowballs, or empty buckets can only stack up to 16.) Returns true if any items were taken; otherwise returns false.

turtle.suckDown(number amount) Like turtle.suck() except this function takes items from the space or container below the turtle.

turtle.suckUp(number amount) Like turtle.suck() except this function takes items from the space or container above the turtle.

turtle.transferTo(number slot, number amount) Transfers amount items from the current slot to slot. The amount argument is optional. If amount isn’t given, the function attempts to transfer all items in the current slot to slot. Returns true if any items were transferred; otherwise returns false.

MOVEMENT FUNCTIONS

Turtles can move in any direction as long as the space they’re attempting to move to is not already occupied by another block. You can use the following functions to tell a turtle to move in various directions. All movement functions return true if the turtle was able to move; otherwise, they return false:

turtle.back() Moves the turtle backward one space

turtle.down() Moves the turtle down one space

turtle.forward() Moves the turtle forward one space

turtle.turnLeft() Turns the turtle to the left; doesn’t use fuel

turtle.turnRight() Turns the turtle to the right; doesn’t use fuel

turtle.up() Moves the turtle up one space

PERCEPTION FUNCTIONS

Turtles can examine blocks one space in front of, above, or below them using the following functions:

turtle.compare() Returns true if the block in front of the turtle is of the same type as the block in the current slot; otherwise returns false.

turtle.compareDown() Similar to turtle.compare() but compares the block below the turtle to the item in the current slot.

turtle.compareUp() Similar to turtle.compare() but compares the block above the turtle to the item in the current slot.

turtle.detect() Returns true if a block is in front of the turtle; otherwise returns false.

turtle.detectDown() Similar to turtle.detect() but checks the block below the turtle.

turtle.detectUp() Similar to turtle.detect() but checks the block above the turtle.

turtle.inspect() Returns two values: true and a table value with information about the block in front of the turtle. If no block is in front of the turtle, returns false.

turtle.inspectDown() Similar to turtle.inspect() but returns information about the block below the turtle.

turtle.inspectUp() Similar to turtle.inspect() but returns information about the block above the turtle.

TOOL-RELATED FUNCTIONS

Turtles can perform actions with the tools they have equipped, and there are corresponding tool-related functions for each action the turtle can perform. You can equip turtles with diamond pickaxes, shovels, axes, swords, hoes, and crafting benches to make the following functions available:

turtle.attack() If equipped with a sword, the turtle attacks anything in front of the turtle. Returns true if a mob was attacked; otherwise returns false if nothing was attacked.

turtle.attackDown() Similar to turtle.attack() but the turtle attacks the space below it.

turtle.attackUp() Similar to turtle.attack() but the turtle attacks the space above it.

turtle.craft(number amount) When you lay out items for a recipe in the turtle’s inventory, this function crafts amount number of items and puts them in the current slot. Requires the turtle to equip a crafting table. The amount argument is optional. If amount isn’t given, the function will craft as many items as possible. Returns true if something was crafted; otherwise returns false when no recipe matches the laid-out items.

turtle.dig() Mines or tills the block in front of the turtle. The turtle must be equipped with a pickaxe for this function to mine blocks. If the turtle has equipped a hoe, the function tills the block in front of the turtle. Returns true if something was mined or hoed; otherwise returns false.

turtle.digDown() Similar to turtle.dig() but mines or tills the block below the turtle.

turtle.digUp() Similar to turtle.dig() but mines the block above the turtle. Note that this function cannot till dirt blocks.

LUA FUNCTIONS

The following functions come with the Lua language, so you don’t need to type a module name before the function name when calling these functions:

error(string message) Terminates the program and displays message, if given. The message argument is optional.

exit() Exits the interactive shell. You can use this only while in the interactive shell.

print(string/number value) Displays value on the screen, followed by a newline. The value argument is optional. If no value is passed, the function only displays a newline.