Skip to content

API Robot

Jump to bottom
Vexatos edited this page Jul 13, 2014 · 6 revisions

For those that don't like images: the wiki has moved to a new place, http://ocdoc.cil.li/.
This wiki will no longer be updated.

This API abstracts the computer component of a robot to allow more intuitive interaction with it. This means it is really just a very thin wrapper. This API is only available when the computer is actually a robot.

  • robot.level(): number
    Gets the current level of the robot, with the fractional part being the percentual progress towards the next level. For example, if this is 1.5, then the robot is level one, and 50% towards achieving level two.
  • robot.name(): string
    Gets the current name of the robot (can be changed using an anvil).
  • robot.detect(): boolean, string
    Tests if there is something in front of the robot. Returns true if there is something that would block the robot's movement, false otherwise. The second returned value specifies what it is that is in front of the robot and can be one of the following: entity, solid, replaceable, liquid and air. The first two will block the robots movement, the latter won't.
    In case of an entity it will either be some living entity, such as a player or monster, or some kind of minecart.
  • robot.detectUp(): boolean, string
    Like robot.detect, but for the block above the robot.
  • robot.detectDown(): boolean, string
    Like robot.detect, but for the block below the robot.
  • robot.select([slot: number]): number
    Selects the inventory slot with the specified index, which is an integer in the interval [1, 16]. Numbering starts at the top left, and goes left to right, then top to bottom. So the top left inventory slot is 1, top right is 4, bottom left is 13, bottom right is 16. Throws an error if an invalid index is specified. Returns the newly selected slot. Can be called without arguments to get the index of the currently selected slot.
  • robot.count([slot: number]): number
    Gets the number of item in the specified inventory slot. If no slot is specified returns the number of items in the selected slot.
  • robot.space([slot: number]): number
    Gets how many more items can be put into the specified slot, which depends on the item already in the slot (for example, buckets only stack up to 16, so if there are 2 buckets in the slot this will return 14). If no slot is specified gets the available space in the selected slot.
  • robot.compareTo(slot: number): boolean
    Compares the item in the currently selected slot to the item in the specified slot. Returns true if the items are equal (i.e. the stack size does not matter), false otherwise.
  • robot.transferTo(slot: number[, count: number]): boolean
    Moves items from the selected slot into the specified slot. If count is specified only moves up to this number of items. Returns true if one or more items were moved (but not necessarily all of them!), false if no items could be moved.
    Note that if the target slot is not empty, and the number of items to move is unspecified or larger or equal to the number items in the selected slot, this will result in a swap.
  • robot.compare(): boolean
    Compares the item in the currently selected inventory slot to the block in front of the robot. Returns true if the block is equivalent to the item at the selected slot, false otherwise.
  • robot.compareUp(): boolean
    Like robot.compare, but for the block above the robot.
  • robot.compareDown(): boolean
    Like robot.compare, but for the block below the robot.
  • robot.drop([count: number]): boolean
    Drops items from the selected inventory slot. If count is specified only drops up to that number of items. If the robot faces a block with an inventory, such as a chest, it will try to insert the items into that inventory. If there is nothing in front of the robot it will drop the items into the world. Returns true if one or more items were dropped, false otherwise. If an inventory is full, this will return false and the items will not be dropped.
    Also checks for minecarts with an inventory, such as minecarts with chests and hoppers on them.
  • robot.dropUp([count: number]): boolean
    Like robot.drop, but drops into inventories or the block above the robot.
  • robot.dropDown([count: number]): boolean
    Like robot.drop, but drops into inventories or the block below the robot.
  • robot.place([side: number[, sneaky: boolean]]): boolean
    Places a block from the selected inventory slot in front of the robot. Returns true on success, false otherwise.
    The side parameter determines the "surface" on which to try to place the block. If it is omitted the robot will try all surfaces. This allows more control when placing blocks that can have an orientation. For example, when placing a torch, specifying sides.left will place it to the left "wall" in front of the robot (if possible), sides.right to the one on the right.
    The sneaky parameter determines whether the robot should be sneaking while placing the block, which may be necessary for some mods.
    Important: per default, there must at least be one solid side (aside the robot!) in the cube in front of the robot so that a block can be placed, i.e. robots cannot place blocks in thin air, they need some kind of "reference", like players do, too. If you would like robots to be able to place blocks in thin air (like ComputerCraft turtles can) check the config, there's a setting for that.
  • robot.placeUp([side: number[, sneaky: boolean]]): boolean
    Like robot.place, but for placing blocks above the robot.
  • robot.placeDown([side: number[, sneaky: boolean]]): boolean
    Like robot.place, but for placing blocks below the robot.
  • robot.suck([count: number]): boolean
    Sucks at maximum one stack into the selected slot, or the first free slot after the selected slot. Returns true if one or more items were picked up, false otherwise.
    If there is a block with an inventory in front of the robot, such as a chest, this will try to take some items from that inventory. If count is specified it will only take up that amount of items. Also works for minecarts with inventories.
    If there is no inventory in front of the robot, it will try to pick up items lying around in the world, in which case the count parameter is ignored.
  • robot.suckUp([count: number]): boolean
    Like robot.suck, but for inventories or items lying above the robot.
  • robot.suckDown([count: number]): boolean
    Like robot.suck, but for inventories or items lying below the robot.
  • robot.durability(): number or nil, string
    If the robot has a tool equipped, this can be used to check the remaining durability of that tool. Returns the remaining durability, if the tool has durability, nil and a reason otherwise.
  • robot.swing([side: number]): boolean[, string]
    Makes the robot perform a "left click", using the currently equipped tool, if any. The result of this action depends on what is in front of the robot. Returns true and a descriptor if something was hit, false and possibly a reason otherwise.
    The side parameter determines the "surface" towards which to try to click. If it is omitted the robot will try all sides. This allows more control over the direction of the click, when needed.
    The returned string can be one of the following:
    • entity, in which case the robot attacked an entity.
    • block in which case the robot tried to break a block.
    • fire if the robot extinguished some flames.
    • air if there was nothing there.
  • robot.swingUp([side: number]): boolean[, string]
    Like robot.swing, but towards the area above the robot.
  • robot.swingDown([side: number]): boolean[, string]
    Like robot.swing, but towards the area below the robot.
  • robot.use([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]
    Makes the robot perform a "right click", using the currently equipped tool, if any. The result on this action depends on what is in front of the robot. Returns true if something happened, false otherwise.
    The side parameter determines the "surface" towards which to click. If it is omitted the robot will try all sides. This allows more control over the direction of the click, when needed. For example, this can be used to tweak the direction in which an arrow is shot when using a bow.
    The sneaky parameter determins whether the robot should be sneaking while using the item. This can be necessary when trying to place blocks on items that would otherwise be used (e.g. by opening a GUI).
    The duration parameter can be used to control for how long to use an item, in seconds. For example, this can be used to specify a draw time when using a bow. Note that this also influences the pause enforced after the call, i.e. when using an item for 10 seconds, the robot will be paused for seconds.
    The returned string may be one of the following:
    • block_activated, if the block in front of the robot was activated, for example a lever was flipped or a button was pushed.
    • item_placed, if the selected item was "placed" into the world. This can either mean a block was placed, but it can also mean the item was used on an existing block, for example bone meal.
    • item_interacted, if the selected tool was used on an entity, for example shears on sheep.
    • item_used, if the selected tool was used without a target, for example shooting a bow.
    • air, if there was nothing to use in that direction and the tool cannot be used without a target.
  • robot.useUp([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]
    Like robot.use, but towards the area above the robot.
  • robot.useDown([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]
    Like robot.use, but towards the area below the robot.
  • robot.forward(): boolean[, string]
    Makes the robot try to move into the block in front of it. Returns true if the robot moved successfully, nil and a reason otherwise. The reason string will be one of the blocking results from the robot.detect function.
  • robot.back(): boolean[, string]
    Like robot.forward, but makes the robot try to move into the block behind it.
  • robot.up(): boolean[, string]
    Like robot.forward, but makes the robot try to move into the block above it.
  • robot.down(): boolean[, string]
    Like robot.forward, but makes the robot try to move into the block below it.
  • robot.turnLeft()
    Makes the robot turn by 90 degrees to its left.
  • robot.turnRight()
    Makes the robot turn by 90 degrees to its right.
  • robot.turnAround()
    Makes the robot turn around by 180 degrees.
Clone this wiki locally