mirror of
https://github.com/MightyPirates/OpenComputers.git
synced 2025-08-03 02:56:53 -04:00
Created API/Robot (markdown)
Florian Nücke
parent
79518b57ad
commit
9ff571f26a
96
API-Robot.md
Normal file
96
API-Robot.md
Normal file
@ -0,0 +1,96 @@
|
||||
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 loaded when the computer is actually a robot. Note that it is still in the ROM file system for normal computers, it just isn't automatically loaded.
|
||||
|
||||
- `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.energy(): number`
|
||||
Gets the remaining amount of energy in the robots internal buffer.
|
||||
- `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.
|
||||
- `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.
|
||||
Loading…
x
Reference in New Issue
Block a user