An API (Application Programming Interface) is a fairly large block of code inserted or called into a program to ease on the coder. An example is a game development API that adds in features that make game development easier. APIs can be used in one of 3 ways. They can be inserted directly into the code, called in through means of running it at the same time as the other code or it can be run all the time by the BIOS. So far however, there are no APIs that run straight from the BIOS, that's just a theory. APIs tend to be ~200 lines of code. Some APIs may be used as databases or memory storage for people. Some may be serial encoders/decoders, and some may be to assist in other forms of coding. Currently there are 20 default API's that come with ComputerCraft: bit, color, colour (same as colors), coroutine, disk, fs, help, http, io, math, OS, parallel, rednet, redstone, rs (shortened redstone), shell, string, table, term, and textutils. Users can also use their own API's. Users can view all the currently enabled API's by entering 'api' in their terminal.
The Bit API is for manipulating bits of variables.
The Colors API allows you to mess with colors. For the British just replace 'color' with 'colour' and it will use the other API, colours, which is just a British version.
Its functions are:
- colors.combine( color1, color2, color3, so on) - combines the colors
- colors.subtract( colors, color1, color2, so on) - subtracts the given colors
- colors.test( colors, color ) - <no description given>
The Disk API allows you to manipulate disk drives.
- isPresent(string side ) - Checks the given side for a disk
- hasData(string side ) - Checks the disk for data
- getMountPath(string side ) - Returns the directory path on which the disk on side has been mount (ex. /disk)
- setLabel(string side ) - Sets the label
- getLabel(string side ) - Finds label
- hasAudio(string side ) - Checks if the disk is a music disk
- getAudioTitle(string side ) - Returns the audio title on the disk
- playAudio(string side ) - Plays the audio
- stopAudio(string side ) - Stops the audio
- eject(string side ) - Ejects the disk.
The FS API allows you to manipulate the filesystem.
- fs.list( path ) - Shows all files and folders at path.
- fs.exists( path ) - Checks if the given path exists.
- fs.isDir( path ) - Checks if the given path is a directory.
- fs.isReadOnly( path ) - Checks if you can only read to a directory.
- fs.getName( path ) - <no description given>
- fs.getDrive( path ) - <no description given>
- fs.makeDir( path ) - Makes a directory.
- fs.move( path, path ) - Moves path 1 to path 2.
- fs.copy( path, path ) - Copies path 1 to path 2.
- fs.delete( path ) - Deletes the given path.
- fs.combine( path, localpath ) - Adds the given path and the local path together to make a new path. For example, if localpath is C\ and path is programs\, it will make C\programs\ and return it.
- fs.open( path, mode ) - Opens the given path. Modes: "r" (read), "w" (write), "a" (append), "rb" (read binary), "wb" (write binary), "ab" (append binary). Meaning: <no description given>
The Help API allows you to manipulate the help files.
- path() - Returns the path the help api has been set to
- setPath(string path ) - Sets the path of the api to path
- lookup(string topic ) - Looks up the help file for topic
- topic() - Returns a table of valid help topics
The HTTP API allows interfacing with websites and downloading from them. Due to CraftOS's nature, images cannot be downloaded.
- http.request( url )
- http.get( url )
The HTTP API must be enabled in mod_ComputerCraft.cfg before being used. A period of time after a http.request() call is made, a "http_success" or "http_failure" event will be raised to os.pullEvent(). Arguments are the URL and a file handle if successful. http.get() blocks until this event is fired.
The redstone API contains methods to control attached RedPower cables/bundled cables.
Note: Currently the redstone API has issues in SMP in some circumstances where the Minecraft server is running Linux. This appears to occur when the RedPower mod loads after ComputerCraft on the server. It is currently confirmed to occur on Ubuntu 11.10 but may occur on other systems as well. Some users have suggested changing the names of the RedPower .zip files to include an "a" at the beginning but this does not work in all cases.
The parameters of the type String, requires quotation marks. For example: redstone.setOutput("left", true). Also note that the parameter 'color' requires an int or one of the 'color.<color_name>' fields.
- rs.getBundledInput(string side) - Returns the state of a redpower wire inside a bundle connected to side
- rs.getBundledOutput(string side) - Returns the set of redpower wires inside a bundle on side that are being driven high by the local console (not those that are driven high by another device on the bundle but not driven high by the local console)
- rs.setBundledOutput(string side, int color) - Sets one or multiple colored signals in a redpower bundled wire connected to Side
- rs.testBundledInput(string side, int color) - Returns true or false whether or not a colored signal is active in a redpower bundled wire connected to Side
- rs.getInput(string side) - Returns the current redstone signal state on side
- rs.getSides() - Returns an array of possible sides
- rs.setOutput(string side, boolean value) - Set or reset a redstone signal on side
The rednet API provides a simple computer networking model over RedPower bundled cables. With the table below, 'side' refers to a string that represents a side of the computer ("front", "back", "left", "right", "bottom", "top"). All message sent with rednet are and must be strings.
- rednet.open( side ) - Tells the computer that the side can be used for networking.
- rednet.close( side ) - Tells the computer that the side can no longer be used for networking.
- rednet.announce() - Broadcasts an empty rednet message.
- rednet.send( receiverID, message ) - Sends a message to the computer using the opened sides. The receiver ID is the ID (number, not string) of the computer you're sending the message to.
- rednet.broadcast( message ) - Sends the message to ALL connected and open computers.
- rednet.receive( timeout ) - Sets an amount of time to wait for a rednet message input. If you wanted to have the computer wait for an input for 5 seconds, then the code would be: rednet.receive( 5 )
You can also handle the "rednet_message" event to receive messages without calling receive(), the arguments are the same as the receive() return values.
The shell APIEdit
The shell API allows you to interface with the shell.
- shell.exit() - Exits the program
- shell.dir() - Returns the directory
- shell.setDir( path ) - Sets the directory
- shell.path() - Returns the path
- shell.setPath( path ) - Sets the path
- shell.resolve( localpath ) - <no description given>
- shell.resolveProgram( name ) - <no description given>
- shell.aliases() - Returns aliases.
- shell.setAlias( alias, command ) - Sets an alias.
- shell.clearAlias( alias, command ) - Clears an alias.
- shell.programs() - Returns programs.
- shell.run( program, arguments ) - Runs a program.
The Terminal API provides functions for ASCII graphics.
- term.write( text ) - Writes text to the screen.
- term.clear() - Clears the entire screen
- term.clearLine() - Clears the line the cursor is on
- term.getCursorPos() - Returns position of the cursor
- term.setCursorPos( x, y ) - Sets the cursor's position.
- term.setCursorBlink( b ) - Disables the blinking or turns it on.
- term.getSize() - Gets the size of the screen. (Good for if you're making something to be compatible with both Turtles and Consoles.)
- term.scroll( n ) - Scrolls the terminal.
Text utilities is used to manipulate text.
- textutils.slowPrint( text ) - Slowly prints the text.
- textutils.slowWrite( text ) - Slowly writes the text.
- textutils.tabulate( table, table2, so on) - <no description given>
- textutils.formatTime( time, bTwentyFourHour) - Put a time into it, and it spews it out in a different format.
The Turtle API is used to Work with your Turtles.
Only these need fuel to be done.
- turtle.forward() - Let the Turtle move forward
- turtle.back() - Let the Turtle move back
- turtle.up() - Let the Turtle move up
- turtle.down() - Let the Turtle move down
- turtle.turnLeft() - The Turtle turns left
- turtle.turnRight() - The Turtle turns right
- turtle.getFuelLevel() - Returns How much Fuel is left in the Turtle. (Fuel only needed to move)
- turtle.refuel( quantity ) - Attempts to burn (quantity) item(s) in selected slot to add to Fuel Level.
Item Mangement CommandsEdit
- turtle.select( slotNum ) - The Turtle selects the given Slot (1 is top left, 9 is bottom right)
- turtle.getItemCount( slotNum ) - Counts how many items are in the given Slot
- turtle.getItemSpace( slotNum ) - Counts how many items you need to fill the stack in the given Slot
- turtle.compare() - Compares item in selected slot with space in front of turtle.
- turtle.compareUp() - Compares item in selected slot with space above turtle.
- turtle.compareDown() - Compares item in selected slot with space in below turtle.
- turtle.compareTo( slotNum ) - Compares item in selected slot with item in Slot number slotNum
- turtle.transferTo (slotNum, quantity) - Transfers (quantity) of item in selected slot to Slot number slotNum
- turtle.drop() - Drops everything of the selected slot to an inventory in front.
- turtle.dropUp() - Drops everything of the selected slot to an inventory in front.
- turtle.dropDown() - Drops everything of the selected slot to an inventory in front.
- turtle.suck() - Pulls from an inventory in front of Turtle.
- turtle.suckUp() - Pulls from an inventory above Turtle.
- turtle.suckDown() - Pulls from an inventory below Turtle.
World Interaction CommandsEdit
- turtle.dig() - Breaks the Block in front (Digging an Air block above dirt with the Farming Turtle will turn the dirt into farmland)
- turtle.digUp() - Breaks the Block above
- turtle.digDown() - Breaks the Block below
- turtle.place() - Places a Block of the selected Slot in front
- turtle.placeUp() - Places a Block of the selected Slot above
- turtle.placeDown() - Places a Block of the selected Slot below
- turtle.attack() - Attacks the space in front. (range of 1) (Melee only)
- turtle.attackUp() - Attacks the space above. (range of 1) (Melee only)
- turtle.attackDown() - Attacks the space below. (range of 1) (Melee only)
- turtle.detect() - Detects if there is a Block in front
- turtle.detectUp() - Detects if there is a Block above
- turtle.detectDown() - Detects if there is a Block below
- turtle.craft( quantity ) (only on Crafty Turtles) Attempts to craft ( quantity ) items based on what is in Slots 1,2,3,5,6,7,9,10 and 11. If (quantity) is left blank it will try to make all it can.