Differences

This shows you the differences between two versions of the page.

--- api:robot [2015/05/28 05:27]
gamax92 rashy stop making incomplete pages
+++ api:robot [2024/01/19 06:18] (current)
bioscreeper Grammar Improvements
@@ Line 1: / Line 1: @@
 ====== Robot API ======
 This API wraps the functionality of the **component** [[component:robot|robot]] to allow more intuitive interaction with the robot.
+This is the api you are using when in your lua code you call
+<code lua>
+local robot_api = require("robot")
+robot_api.forward()
+</code>
+As opposed to using the robot component api directly, via the component interface
+<code lua>
+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)
+</code>
 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 [[:api|APIs]] are available as usual.
+Note that a Robot is also computer like any other with just an additional robot component included, so the normal [[:api|APIs]] are available as usual.
 See [[block:robot|Robot Block]] for additional information on the actual Robot.
-===== Slot alignment =====
+==== Slot alignment ====
-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.
+{{page>component:inventory_slots&noheader&nofooter}}
+==== Movement ====
+Robots are capable of complex movements, but some you may want to understand some nuances.
+=== Hovering ===
+Robots have a flight-height limitation. The general movement rules for robots go like this:
+- 1. Robots may only move if the start or target position is valid (e.g. to allow building bridges).
+- 2. The position below a robot is always valid (can always move down).
+- 3. Positions up to `flightHeight` above a solid block are valid (limited flight capabilities, default is 8).
+- 4. Any position that has an adjacent block with a solid face towards the position is valid (robots can "climb").
+Here's an image visualizing that (minus the second rule, because that'd just clutter it).
+{{:api:robot_flight.png}}
+Violating these rules will result in a the error `impossible move` to be returned
-{{api:robot_slotalign.png}}
+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.
-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.
+[[https://github.com/MightyPirates/OpenComputers/issues/1113#issuecomment-97731965|source]]
-Callbacks:
+==== API Exclusive Methods ====
 - `robot.name(): string`
@@ Line 48: / Line 79: @@
 **count** - if specified only up to this many items are moved, otherwise the entire stack is moved.
 **Returns** `true` if exchanging the content between those slots was successful, `false` otherwise.
-If there are items in the target slot then this function attempts to swap the items in those slots. This only succeeds if you move all slots away from the current slot or if the current slot was empty anyways.
+If there are items in the target slot then this function attempts to swap the items in those slots. This only succeeds if you move all items away from the current slot or if the current slot was empty anyways.
 Note that this will always return true if the specified slot is the same as the currently selected slot, or if both slots are empty, even though no items are effectively moved.
 - `robot.compareTo(slot: number): boolean`
@@ Line 65: / Line 96: @@
 As `robot.compare` just for the block directly below the robot.
 - `robot.drop([count: number]): boolean`
-Tries to drop items from the currently selected inventory slot in front of the robot.
+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**.
 **count** - specifies how many items to drop. If omitted or if count exceeds the amount of items in the currently selected slot, then all items in the currently selected slot are dropped.
 **Returns** `true` if at least one item was dropped, `false` otherwise.
@@ Line 100: / Line 131: @@
 Returns the durability of the item currently in the tool slot, followed by its current durability, followed by its maximum durability.
 If no item is equipped or the item has no durability this returns `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`.
-- `robot.swing([side: number]): boolean[, string]`
+- `robot.swing([side: number, [sneaky:boolean]]): boolean[, string]`
 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.
 **side** - if given the robot will try to 'left-click' only on the surface as specified by side, otherwise the robot will try all possible sides. See the [[api:sides|Sides API]] for a list of possible sides.
@@ Line 107: / Line 138: @@
 Note that even though the action is performed immediately (like a block being destroyed) this function will wait for a while appropriate to the action performed to simulate the time it would take a player to do the same action. This is most noticeable if you try to mine obsidian blocks: they are destroyed and put into the inventory immediately, but the function will wait for a few seconds.
 If this is used to mine blocks, then the tool equipped needs to be sufficient to actually mine the block in front. If for example a wooden pick-axe is used on an obsidian block this will return false. Everything (including an empty slot) can be used to fight mobs, but the damage will be based on the item used. Equally everything can be used to extinguish fire, and items with durability will not lose any if done so.
-- `robot.swingUp([side: number]): boolean[, string]`
+- `robot.swingUp([side: number, [sneaky:boolean]]): boolean[, string]`
 As `robot.swing` except that the block or entity directly above the robot will be the target.
-- `robot.swingDown([side: number]): boolean[, string]`
+- `robot.swingDown([side: number, [sneaky:boolean]]): boolean[, string]`
 As `robot.swing` except that the block or entity directly below the robot will be the target.
 - `robot.use([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]`
@@ Line 179: / Line 210: @@
 - `robot.fillDown([count:number]):boolean`
   Like `fill`, but operates on the block below the robot.
 Contents
 -----------
 {{page>api:contents&noheader&noeditbutton&nouser&nofooter}}