This API wraps the functionality of the component robot to allow more intuitive interaction with the robot.
This is the api you are using when in your lua code you call
local robot_api = require("robot") robot_api.forward()
As opposed to using the robot component api directly, via the component interface
local component = require("component") local robot_component_api = component.robot -- if using openos, else component.proxy(component.list("robot")()) robot_component_api.move(sides.front)
While the component robot has more generic functions like move([side: number])
or drop([side: number])
, this API has more intuitive and failsafe functions like turnRight
, dropDown
, forward
. Which one you use is up to you, you can even use both at the same time.
Note that a Robot is an OpenComputer like any other with just an additional robot component included, so the normal APIs are available as usual.
See Robot Block for additional information on the actual Robot.
Slot indexes do not match between the robot's internal and external view of its inventory
When a robot interacts with its own inventory it is using its internal view. You access the inventory of another robot via its external view.
The reason for this distinction is to separate the two inventory spaces: the main inventory and the tool belt inventory. Internally, the robot selects slots only in its inventory space, and not its toolbelt. It can equip
or unequip items from its toolbelt. However, externally, an observer interacts with a single inventory that includes both the toolbelt as well as the main inventory.
The Robot's GUI displays the slots of a robot aligned from top-left to bottom-right. So for example the slot at index 1 is displayed in the top-left corner, the slot at index 2 is the next to the right and the first slot on the 2nd row is index 5.
These are the slot indexes a robot uses on it self (for its own main inventory, an interview view).
How many slots a robot has available depends on it's setup. If a slot is specified in a function that exceeds the amount of slots a robot has available an error is thrown.
The robot can select
, place
, drop
, compare
(etc) items from its main inventory using these slot indexes as they represent the internal perspective of its inventory.
Slot indexes of a robot's inventory to an outside observer will be offset by 4. To an outside observer, slots 1 through 4 refer to slots in the robot toolbelt. The first slot of the main inventory is slot 1 from inside the robot (internal view), but is thus slot 5 to an outside observer. Yes, this can be confusing at first. This design choice was made so that, to an outside observer, [slot 1] always indicated the first toolbelt slot regardless of the robot inventory size, and [slot 5] was always the first main inventory slot.
The robot inventory, again to an external observer, is sided inventory. The robot will not share all its inventory to all sides. Slot indexes do not change to these different sides. Slot 1, therefore, always refers to the first toolbelt slot, even when inaccessible to a side.
Robots are capable of complex movements, but some you may want to understand some nuances.
Robots have a flight-height limitation. The general movement rules for robots go like this:
flightHeight
above a solid block are valid (limited flight capabilities, default is 8).
Violating these rules will result in a the error impossible move
to be returned
You can install hover upgrades to increase (tier 1) and pretty much circumvent (tier 2) this limitation. Or you can disable this in the config, by setting limitFlightHeight
to 256 or so.
The name of a Robot is set initially during it's creation and cannot be changed programmatically. However you can change it using an anvil if you want.
robot.name(): string
Detects what is directly in front of the robot and returns if the robot could move through it as well as a generic description.
robot.detect(): boolean, string
true
if the robot if whatever is in front of the robot would prevent him from moving forward (a block or an entity) (Note: Drones return true
even if the block is passable
), false
otherwise. The second parameter describes what is in front in general and is one of either entity
, solid
, replaceable
, liquid
, passable
or air
.
As robot.detect()
except that it scans the block directly above the robot.
robot.detectUp(): boolean, string
As robot.detect()
except that it scans the block directly below the robot.
robot.detectDown(): boolean, string
Selects the given inventory slot (if specified) and returns the current inventory slot.
robot.select([slot: number]): number
Information on inventory size.
To get the number of inventory upgrades use: x = robot.inventorySize() / 16
.
robot.inventorySize(): number
Returns the amount of items currently in the specified or selected slot.
robot.count([slot: number]): number
Determines the amount of items that can still be added to the specified slot until it is filled up.
This function helps to determine how many items of a type can be added to a specific slot. While for example cobblestone can pile up to 64 items per slot, empty buckets can only stack up to 16 and other blocks like doors can only take 1 item per slot.
robot.space([slot: number]): number
Moves all or up to count items from the currently selected slot to the specified slot.
robot.transferTo(slot: number[, count: number]): boolean
true
if exchanging the content between those slots was successful, false
otherwise.
Compares the item of the currently selected slot to the item of the slot specified and returns whether they are equal or not.
Two items are considered the 'same' if their item type and metadata are the same. Stack size or any additional mod-specific item informations (like for example the content of two floppy disks) are not checked.
robot.compareTo(slot: number): boolean
true
if the item type in the specified slot and the currently selected slot are equal, false
otherwise.
Compares the block in front of the robot with the item in the currently selected slot and returns whether they are the same or not.
Blocks are considered the 'same' if their type and metadata are the same. Stack size or any additional informations (like for example the inventory of a container) are not checked.
Note that empty space in front of the robot is considered an 'air block' by the game, which cannot be put into an inventory slot and therefore compared by normal means. An empty slot and an air block are not the same. You can use robot.detect()
beforehand to determine if there is actually a block in front of the robot.
Also keep in mind that blocks that drop items need to be compared to the actual same block that is in the world. For example stone blocks drop as cobblestone and diamond ores drop diamond items, which are not the same for this function. Use silk-touch items to retrieve the actual block in the world for comparison.
robot.compare(): boolean
As robot.compare
just for the block directly above the robot.
robot.compareUp(): boolean
As robot.compare
just for the block directly below the robot.
robot.compareDown(): boolean
Tries to drop items from the currently selected inventory slot in front of the robot. Note that if you are trying to drop items into an inventory below you, this is the wrong method. Use dropDown
for that case. This method, drop
, will drop the items to the front.
This function cannot interact with non-item inventories (like for example fluid tanks) and will not consider them an inventory and therefore items will be thrown into the world instead. You need to use the robot.use
function to interact with those types of blocks.
robot.drop([count: number]): boolean
true
if at least one item was dropped, false
otherwise.
As robot.drop
just for the block directly above the robot.
robot.dropUp(): boolean
As robot.drop
just for the block directly below the robot.
robot.dropDown(): boolean
Tries to pick up items from directly in front of the robot and puts it into the selected slot or (if occupied) first possible slot.
This is basically the inverse of robot.drop
and will interact with item inventories in the same way. However this will only take the first item available in that inventory. For more precise inventory management you need to install an inventory controller upgrade into the robot.
robot.suck([count: number]): boolean
true
if at least one item was picked up, false otherwise.false
.
As robot.suck
except that it tries to pick up items from directly above the robot.
robot.suckUp([count: number]): boolean
As robot.suck
except that it tries to pick up items from directly below the robot.
robot.suckDown([count: number]): boolean
Tries to place the block in the currently selected inventory slot in front of the robot.
A robot can only place blocks to the side of another solid block, they cannot place blocks “into the air” without an Angel upgrade. This can be changed in the config file.
robot.place([side: number[, sneaky: boolean]]): boolean[, string]
true
the robot will simulate a sneak-placement (like if the player would be using shift during placement), which is usually not necessary and only included for compatibility to other mods.true
if an item could be placed, false
otherwise. If placement failed, the secondary return parameter will describe why the placement failed.
As robot.place
except that the robot tries to place the item into the space directly above it.
robot.placeUp([side: number[, sneaky: boolean]]): boolean[, string]
As robot.place
except that the robot tries to place the item into the space directly below it.
robot.placeDown([side: number[, sneaky: boolean]]): boolean[, string]
The durability of the currently used item.
robot.durability(): number, number, number or nil, string
nil
and an error message describing why no durability could be returned. The error message is one of no tool equipped
or tool cannot be damaged
.
Makes the robot use the item currently in the tool slot against the block or space immediately in front of the robot in the same way as if a player would make a left-click.
This can be used to mine blocks or fight entities in the same way as if the player did a left-click. Note that tools and weapons do lose durability in the same way as if a player would use them and need to be replaced eventually. Items mined or dropped of mobs will be put into the inventory if possible, otherwise they will be dropped to the ground.
robot.swing([side: number, [sneaky:boolean]]): boolean[, string]
As robot.swing
except that the block or entity directly above the robot will be the target.
robot.swingUp([side: number, [sneaky:boolean]]): boolean[, string]
As robot.swing
except that the block or entity directly below the robot will be the target.
robot.swingDown([side: number, [sneaky:boolean]]): boolean[, string]
Attempts to use the item currently equipped in the tool slot in the same way as if the player would make a right-click.
This function has a very broad use as the robot can simulate right-clicks with most items. The only difference to players is that the robot cannot use items that specifically require the user to be an entity as the robot is a block. So drinking potions, eating food or throwing an ender pearl will fail.
robot.use([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]
true
the robot will simulate a sneak-right-click (like if the player would be using shift during a right-click). Some items (like buckets) will behave differently if this is set to true.block_activated
- a block was activated (like levers, switches or doors).item_interacted
- the equipped tool interacted with the world, for example sheers when used on a sheep.item_placed
- something was placed into the world. This is not only caused by placeable blocks, but as well by items that cause blocks or entities to appear in the world (like flint and stone or mob eggs).item_used
- the equipped was activated, like a splash-potion.air
- the equipped item requires a target but there was none. Note that if your robot has an Angel upgrade, this will never be returned, however some actions might still cause no effect.
As robot.use
except that the item is used aiming at the area above the robot.
robot.useUp([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]
As robot.use
except that the item is used aiming at the area below the robot.
robot.useDown([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]
Tries to move the robot forward.
robot.forward(): boolean[, string]
Returns: true
if the robot successfully moved, nil
otherwise. If movement fails a secondary result will be returned describing why it failed, which will either be 'impossible move', 'not enough energy' or the description of the obstacle as robot.detect
would return.
As robot.forward()
except that the robot tries to move backward.
robot.back(): boolean[, string]
As robot.forward()
except that the robot tries to move upwards.
robot.up(): boolean[, string]
As robot.forward()
except that the robot tries to move downwards.
robot.down(): boolean[, string]
Turns the robot 90° to the left.
Note that this can only fail if the robot has not enough energy to perform the turn but has not yet shut down because of it.
robot.turnLeft()
As robot.turnLeft
except that the robot turns 90° to the right.
robot.turnRight()
This is the same as calling robot.turnRight
twice.
robot.turnAround()
Deprecated since OC 1.3 use component.experience.level()
instead (only available if the experience upgrade is installed).
Returns the current level of the robot, with the fractional part being the percentual progress towards the next level. For example, if this returns 1.5
, then the robot is level one, and 50% towards achieving level two.
robot.level(): number
The number of tanks installed in the robot.
robot.tankCount():number
Select the specified tank. This determines which tank most operations operate on.
robot.selectTank(tank)
The the current fluid level in the specified tank, or, if none is specified, the selected tank.
robot.tankLevel([tank:number]):number
The the remaining fluid capacity in the specified tank, or, if none is specified, the selected tank.
robot.tankSpace():number
Tests whether the fluid in the selected tank is the same as in the specified tank.
robot.compareFluidTo(tank:number):boolean
Transfers the specified amount of fluid from the selected tank into the specified tank. If no volume is specified, tries to transfer 1000 mB.
robot.transferFluidTo(tank:number[, count:number]):boolean
Tests whether the fluid in the selected tank is the same as in the world or the tank in front of the robot.
robot.compareFluid():boolean
Like compareFluid
, but operates on the block above the robot.
robot.compareFluidUp():boolean
Like compareFluid
, but operates on the block below the robot.
robot.compareFluidDown():boolean
Extracts the specified amount of fluid from the world or the tank in front of the robot. When no amount is specified, will try to drain 1000 mB. When the drained fluid is in the world and it cannot be fully stored in the selected tank, the operation fails, i.e. no fluid is lost.
robot.drain([count:number]):boolean
Like drain
, but operates on the block above the robot.
robot.drainUp([count:number]):boolean
Like drain
, but operates on the block below the robot.
robot.drainDown([count:number]):boolean
Injects the specified amount of fluid from the selected tank into the the world or the tank in front of the robot. When no amount is specified, will try to eject 1000 mB. When there is not enough fluid to fill a block, or the target tank does not have enough room, the operation fails, i.e. no fluid is lost.
robot.fill([count:number]):boolean
Like fill
, but operates on the block above the robot.
robot.fillUp([count:number]):boolean
Like fill
, but operates on the block below the robot.
robot.fillDown([count:number]):boolean