The Robot API
Connecting to your Robot
username = "username"
server_address = "server.address.net"
robot = Robot(username, server_address)
This connects to your robot on the Minecraft server and lets you start sending commands through the robot object.
Moving, Turning and Mining
These are all the possible directions that you can use for the various actions. Some are relative to the way the robot is facing (see the face of the pumpkin) and some are absolute compass directions.
Dir.UP
Dir.DOWN
Dir.LEFT
Dir.RIGHT
Dir.FORWARD
Dir.BACKWARD
Dir.NORTH
Dir.SOUTH
Dir.EAST
Dir.WEST
Robot.move(direction)
robot.move(Dir.LEFT)
Moves the robot in the given direction, and returns a boolean whether the move succeeded or not (fails if there's a solid block in the way).
Robot.turn(direction)
robot.turn(Dir.LEFT)
Turns the robot to face the given direction, and returns a boolean if successful. Turning always succeeds, except if turning UP/DOWN which is impossible.
Robot.mine(direction)
robot.mine(Dir.LEFT)
Mines away the adjacent block in the given direction, and returns a boolean if successful.
All mines are done as though the robot is holding a Diamond Pickaxe. If the block cannot be broken with a diamond pickaxe (e.g. Water) then the mine action will fail (return False). Whatever the result of the break is (e.g. COAL_ORE -> COAL) is spawned as an item, automatically picked up by the robot and added to the inventory.
Block Types
The BlockType enum lists all available block types in Minecraft, any types missing from this list are likely to be sub-types of one of the types. This gets confusing, but I don't have a good solution for it just yet. For example granite is a subtype of STONE, so there is no granite type in the list.
The complete list of supported block types.
Robot.place(direction, block_type)
robot.place(Dir.LEFT, BlockType.DIRT)
Places a block of the given type, adjacent to the robot in the given direction, and reduces it from the inventory. Returns True if the place succeeds, and False otherwise
Placing a block will fail if there is none of that type in the inventory or if there is a solid block in the way. If there are multiple items in the inventory matching the block type, then the first match is used. When the place is successful, the placed type is deducted from the inventory.
Robot.get_block_type(direction)
robot.get_block_type(Dir.LEFT)
Returns the BlockType of the adjancent block in the given direction.
Robot.is_block_solid(direction)
robot.is_block_solid(Dir.LEFT)
Returns True if the block is solid, False if it can be moved through.
Inventory
Robot.get_inventory()
robot.get_inventory()
Returns a list of tuples (pairs) where each pair contains the BlockType and the count of how many of that block type are in the inventory.
Block types which take up multiple spaces in the inventory will return multiple results, they are not aggregated together.
Note: The robot has an infinite supply of DIRT and COBBLESTONE, since these are the normal products of mining. The robot will not pick up additional dirt or cobblestone and placing dirt or cobblestone does not reduce the inventory.
Location
A Location object is a 3D coordinate in the Minecraft world, same as the coordinates used in the game.
The Location object has a few useful methods for finding distances and navigating.
loc = Location(4, 10, 1)
Constructs a new location with the given X, Y, Z coordinate values.
Location.distance(location)
loc.distance(Location(3, -23, 80))
Returns the distance from this location to another location as a float.
Location.direction(location)
loc.direction(Location(2, 24, -23))
Returns the direction or Dir (UP/DOWN/NORTH/SOUTH/EAST/WEST) that best fits the direction from this location to the given location.
Robot and owner locations
robot.get_location()
Returns the location of the robot as a Location object.
robot.get_owner_location()
Returns the location of the robot's onwer (you) as a Location object.
Searching
Robot.find_type_nearby(block_type)
robot.find_type_nearby(BlockType.DIAMOND_ORE)
Returns a list of Locations near to the robot which match the given block type.
The search has a limit of 5 blocks in every direction by Manhattan Distance, and the results are sorted by distance with the nearest locations first in the list.
Robot.find_path(location)
robot.find_path(Location(4, 29, 0))
Extremely basic path-finding tool. Out of the non-solid blocks adjacent to the robot, this function selects the one closest to the target location and returns the direction for the robot to move.
Note that this only uses the blocks immediately surrounding the Robot, this is not enough information to accurately find a path and the Robot will get stuck pretty often.
Sending chat messages
Robot.message_owner(str)
robot.message_owner("Hey, I finished mining!")
Sends an in-game chat message to you, the owner of the robot only.
Robot.message_all(str)
robot.message_all("Hi everyone!")
Sends an in-game chat message to everyone on the server, use with caution and please don't spam everyone.