Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
api:robot [2015/10/04 17:33]
sangar add sneaky arg for .swing
api:robot [2024/01/19 06:18] (current)
bioscreeper Grammar Improvements
Line 1: Line 1:
 ====== Robot API ====== ====== Robot API ======
 This API wraps the functionality of the **component** [[component:​robot|robot]] to allow more intuitive interaction with the robot. 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. 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. 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-rightSo for example the slot at index 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 flight-height limitationThe 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`  ​ - `robot.name():​ string`  ​
Line 48: Line 79:
 **count** - if specified only up to this many items are moved, otherwise the entire stack is moved.  ​ **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.  ​ **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. 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`  ​ - `robot.compareTo(slot:​ number): boolean`  ​
Line 65: Line 96:
 As `robot.compare` just for the block directly below the robot. As `robot.compare` just for the block directly below the robot.
 - `robot.drop([count:​ number]): boolean`  ​ - `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.  ​ **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.  ​ **Returns** `true` if at least one item was dropped, `false` otherwise.  ​
Line 179: Line 210:
 - `robot.fillDown([count:​number]):​boolean`  ​ - `robot.fillDown([count:​number]):​boolean`  ​
   Like `fill`, but operates on the block below the robot.   Like `fill`, but operates on the block below the robot.
-  ​+
 Contents Contents
 ----------- -----------
 {{page>​api:​contents&​noheader&​noeditbutton&​nouser&​nofooter}} {{page>​api:​contents&​noheader&​noeditbutton&​nouser&​nofooter}}