# Robot(机器人) API

此API封装了[[component:robot:zh|机器人]]**组件**的功能，允许与机器人实现更直观的互动。

若你在Lua代码中这样写，那么你调用的就是此API：

```lua
local robot_api = require("robot")
robot_api.forward()
```

与之相对的是通过组件接口，直接使用机器人组件API：

```lua
local component = require("component")
local robot_component_api = component.robot -- 如果你使用OpenOS那么可以这么写，否则要写 component.proxy(component.list("robot")())
robot_component_api.move(sides.front)
```

虽然机器人组件提供了更通用的功能，比如`move([side: number])`和`drop([side: number])`，但是此API提供了更直观、更安全的函数，比如`turnRight`、`dropDown`、`forward`。使用哪一种由你自己决定，甚至可以混用二者。

请注意机器人本身就是一台OC模组的电脑，和其它电脑一样，只是多了一个机器人组件，所以一般的[API](api:zh)仍然可用。

查看[方块：机器人](:block:robot:zh)以获取更多有关机器人本身的信息。

## 槽位排列
{{page>component:inventory_slots:zh&noheader&nofooter}}
## 移动

机器人能够灵活移动，但你可能会想了解一些细节。

### 悬停

机器人有飞行高度限制。机器人移动的基本规则是这样的：

- 1. 机器人只有在起点或目标点为可用（下图绿色区域）时才会移动（此特性可用于建桥等）。
- 2. 机器人下方位置一定为可用（一定可以向下移动）。
- 3. 固体方块（图中棕色区域）上方的`flightHeight`格为可用区域（飞行能力有限，默认为8）。
- 4. 紧贴实心面的位置均为可用区域（机器人可以“爬墙”）。  
此处为一张可视化展示上述规则的图片（忽略了第二条规则，这会使图片变得混乱）

{{:api:robot_flight.png}}

违反这些规则会导致机器人返回`impossible move`错误。

你可以安装悬浮升级以提升（1级）乃至很大程度上规避（2级）这个限制。或者你也可以在模组配置文件中禁用这个限制，只要将`limitFlightHeight`设置为256或更高即可。

[来源](https://github.com/MightyPirates/OpenComputers/issues/1113#issuecomment-97731965)（英文）

## API 特有方法

- `robot.name(): string`  
返回机器人的名字。 
机器人的名字在它被创造时会自动设定，且不能通过程序修改。但如果你想，可以用铁砧修改。  
\\
- `robot.detect(): boolean, string`  
探测机器人正前方的物体，并且返回机器人是否能移动过去，同时返回面前物体的描述。  
**返回值：**若机器人面前的物体会阻碍其移动（方块或者实体）则返回 `true`，否则返回 `false`（注意：即使面前的方块为`passable`，代表可穿越，无人机也会返回`true`）。第二个返回值大体描述了前面的物体是什么，可能取值为；`entity`、`solid`、`replaceable`、`liquid`、`passable`或者`air`。  
\\
- `robot.detectUp(): boolean, string`  
和`robot.detect()`一样，但此函数探测机器人正上方的方块。  
\\
- `robot.detectDown(): boolean, string`  
和`robot.detect()`一样，但此函数探测机器人正下方的方块。  
\\
- `robot.select([slot: number]): number`  
选定给定的物品栏槽位（若指定），并返回物品栏当前的选定槽位。  
**slot** - 要选定的物品栏槽位。若此参数省略，那么不会改动当前选定槽位。  
**返回值：**物品栏当前的选定槽位。可能为给定的物品栏槽位（若选择成功）或先前选定的物品栏槽位。  
\\
- `robot.inventorySize(): number`  
**返回值：**可选定的物品栏槽位数量。想要获取安装的物品栏升级个数，可以使用这个公式：x = robot.inventorySize() / 16。  
\\
- `robot.count([slot: number]): number`  
返回物品栏的指定槽位或选定槽位中的物品个数。  
**slot** - 指定要获取物品数的槽位。若省略则会对当前选定槽位的物品计数。  
**返回值：**指定槽位中物品的数量，或当前选定槽位中物品的数量（若没有指定槽位）。  
\\
- `robot.space([slot: number]):number`  
返回在给定槽位装满之前还能装入多少物品。 
**slot** - 指定要计算物品数的槽位。若省略则计算当前选定槽位。  
**返回值：**给定槽位或当前选定槽位在装满前还能装入多少物品。
此函数还有助于判断某种物品在单个槽位中的堆叠上限。例如圆石在每个槽位中能放64个，但是空桶在每个槽位中只能放16个，而有些方块，比如门，在每个槽位中只能放一个。  
\\
- `robot.transferTo(slot: number[, count: number]): boolean`  
从当前选定槽位移动所有或是至多`count`个物品到指定槽位。  
**slot** - 指定承接物品的槽位。  
**count** - 若指定此参数，则最多移动此参数个物品，否则移动整个物品堆。  
**返回值：**若成功交换两个槽位中的物品则返回`true`，否则返回 `false`。  
若指定槽位中有物品，此函数会尝试交换两个槽位中的物品。只有将选定槽位中的所有物品都移走，或以其他任意方式清空选定槽位，交换才会成功。  
注意，若两个槽位中的物品相同，或者两个槽位都是空的，返回值一定是`true`，即使实际上没有移动任何东西。  
\\
- `robot.compareTo(slot: number):boolean`  
比较物品栏当前选定槽位中的物品与给定槽位中的是否相同。  
**slot** - 指定要与当前选定槽位比较的槽位。  
**返回值：**若两个槽位中的物品种类相同则返回`true`，否则返回`false`。  
若两个物品的种类和元数据相同，那么它们就被认定为“相同”。物品堆大小（物品数量）或其它额外信息（例如容器的物品栏）不会检查。  
\\
- `robot.compare(slot: number):boolean`  
比较机器人正前方的方块与物品栏当前选定槽位中的方块，并返回它们是否相同。  
若两个方块的类型和元数据相同，那么它们就被认定为“相同”。物品堆大小（物品数量）或其它额外信息（例如容器的物品栏）不会检查。  
请注意，机器人前方如果是空的则会被游戏认为是“空气方块”，这种方块不能被放进物品栏，因此也不能使用一般方法比较。物品栏的空槽位与空气方块**不同**。你可以先使用`robot.detect()`来确认机器人前方是否真的有方块。  
还请记住，会掉落其它物品的方块应当和真正出现在世界上的方块比较（而非掉落物）。例如，石头方块会以圆石形式掉落，钻石矿石掉落钻石物品。对于这个函数来说它们并不相同。需要使用精准采集的工具开采实际的方块用于比较。  
\\
- `robot.compareUp(): boolean`  
和`robot.compare()`一样，但此函数比较机器人正上方的方块。  
\\
- `robot.compareDown(): boolean`  
和`robot.compare()`一样，但此函数比较机器人正下方的方块。  
\\
- `robot.drop([count: number]): boolean`  
尝试从内部物品栏的当前选定槽位提取物品，并丢弃在机器人**前方**。注意，此方法不可用于将物品丢入机器人下方的物品容器，这种情况下需要使用`dropDown`方法。 此方法会将物品丢在**面前**。  
**count** - 指定丢出多少物品。若省略此参数或其值超过了物品的数量，则所有物品都会被丢出。  
**返回值：**若至少丢出了一个物品则返回`true`，否则返回`false`。  
若机器人正前方的实体或方块有可访问的物品栏（例如箱子或运输矿车），机器人会尝试将物品放进物品栏中而不是丢弃到世界中。若面前的方块的确有物品栏，但是因为某种原因物品无法被放入其中，则此函数返回`false`，且不会移动任何物品。物品被放置的位置取决于物品容器自身，以及机器人面对容器的哪个面。例如，熔炉从上方接收待烧炼物品。还请注意，其它机器人也会被认为是“带物品栏的方块”，所以物品也能被移入其它机器人的物品栏槽位，就像移入别的物品容器一样。  
此函数不能与非物品类型的容器互动（例如流体储罐），也不会将它们当作物品容器，因此物品会被扔到世界中。你需要使用`robot.use`函数与这些种类的方块互动。  
请注意若物品栏的当前选定槽位是空的，那么返回值一定为`false`。  
\\
- `robot.dropUp(): boolean`  
和`robot.drop()`一样，但此函数把物品丢在机器人正上方。  
\\
- `robot.dropDown(): boolean`  
和`robot.drop()`一样，但此函数把物品丢在机器人正下方。  
\\
- `robot.suck([count: number]): boolean`  
尝试从正前方拾起掉落物，并将其放入物品栏的选定槽位或者（若槽位被占用）第一个可用的槽位。  
**count** - 拾起掉落物的数量上限。若省略，则会捡起最多一个物品堆。  
**返回值：**若捡起了至少一个物品则返回`true`，否则返回`false`。  
此函数基本就是`robot.drop`的反向版，而且也会以相同的方式和物品容器互动。但是它只会拿走物品栏中的第一个可用物品。想要实现更精准的物品栏管理，你需要为机器人安装[物品栏控制器升级](item:inventory_controller_upgrade:zh)。   
若机器人面前有多个掉落物，则会根据距离远近捡起掉落物。此操作会跳过因为任意原因无法捡起的掉落物，并且在返回`false`之前先尝试捡起其它掉落物。  
若物品栏的当前选定槽位中有和机器人捡起的掉落物不同的物品，机器人会尝试将物品放在这个槽位**之后**的第一个可用槽位，要么是空槽位，要么是包含相同物品并且尚未达到堆叠上限的槽位。若必要，它会将拾起的物品分配到不同的槽位中。若当前选定槽位后没有可用槽位，此函数会执行失败，即使在选定槽位**前**有能装下这些物品的槽位也是如此。  
\\
- `robot.suckUp([count: number]): boolean`  
和`robot.suck()`一样，但此函数会尝试捡起正上方的物品。  
\\
- `robot.suckDown([count: number]): boolean`  
和`robot.suck()`一样，但此函数尝试捡起正下方的物品。  
\\
- `robot.place([side: number[, sneaky: boolean]]): boolean[, string]`  
尝试将物品栏选定槽位中的方块放置在机器人面前。  
**side** - 若指定，此参数决定机器人会尝试将方块放到哪个面上。例如，可用于将火把放在特定表面上。若省略，机器人会尝试所有可能的方向。参见[sides(方向) API](api:sides:zh)以获取可能的方向列表。  
**sneaky** - 若设置为 `true`，机器人会模拟潜行放置方块（和玩家在放置时按住shift的效果相同）。这种操作通常没有必要，只是为了保证和其它模组的兼容性。  
**返回值：**若物品可以放置则返回 `true`，否则返回 `false`。若放置失败，第二个返回值会描述失败原因。  
机器人只能将方块放置到另一个固体方块的某个面上，而不能“放在空气中”，除非有[天使升级](item:angel_upgrade:zh)。此特性可在配置文件中修改。  
请注意若物品栏槽位是空的，那么操作一定会失败。  
\\
- `robot.placeUp([side: number[, sneaky: boolean]]): boolean[, string]`  
和`robot.place()`一样，但此函数会尝试在正上方放置方块。  
\\
- `robot.placeDown([side: number[, sneaky: boolean]]): boolean[, string]`  
和`robot.place()`一样，但此函数会尝试在正下方放置方块。  
\\
- `robot.durability(): number, number, number or nil, string`  
返回工具槽位中物品的耐久度剩余比例（小数）、当前耐久、最大耐久。  
若未装备物品或物品没有耐久值，此函数会返回`nil`以及一条描述为何不能返回耐久值的信息。报错信息可能为：`no tool equipped`（未装备工具）或`tool cannot be damaged`（工具不会损坏）。  
\\
- `robot.swing([side: number[, sneaky: boolean]]): boolean[, string]`  
让机器人用当前在工具槽位中的物品对正前方的方块或空间交互，与玩家左键单击相同。  
**side** - 若指定，机器人只会尝试左键单击给定方向处的面，否则机器人会尝试单击所有可能的方向。参见[sides(方向) API](api:sides:zh)以获取可能方向的列表。  
**返回值：**若机器人可以和面前的方块或实体互动，返回`true`，否则返回`false`。若执行成功，第二个返回值代表机器人和什么东西互动了，取值可能为`entity`（实体）、`block`（方块）或`fire`（火）。  
此函数可用于开采方块或者攻击实体，就像玩家点击左键一样。请注意工具和武器会像被玩家使用一样减少耐久度，且最终需要被替换掉。如果可能，开采的方块或实体的掉落物会被放进机器人的物品栏中，否则会掉在地上。  
请注意，虽然动作会立刻完成（如方块被摧毁），这个函数还是会适当地等待一会来模拟玩家操作所需的时间。如果你尝试开采黑曜石，这个现象会很明显：它们立即就被破坏并且放入机器人的物品栏中，但函数还会等待几秒。  
如果此函数被用于开采方块，那么装备的工具必须足以开采机器人面前的方块。例如，如果用木镐开采黑曜石，函数会返回`false`。任何东西（包括空槽位）都能用于与生物战斗，但是伤害会基于所使用的物品。同样所有东西都能被用来灭火，且有耐久的工具也不会减少耐久值。  
\\
- `robot.swingUp([side: number[, sneaky: boolean]]): boolean[, string]`  
和`robot.swing()`一样，但此函数会将正上方的方块或实体当作目标。  
\\
- `robot.swingDown([side: number[, sneaky: boolean]]): boolean[, string]`  
和`robot.swing()`一样，但此函数会将正下方的方块或实体当作目标。  
\\
- `robot.use([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]`  
尝试使用当前工具槽位中的物品，与玩家单击右键相同。  
**side** - 若给定，机器人只会尝试“右键单击”指定方向的面，否则机器人会尝试所有可能的方向。参见[sides(方向) API](api:sides:zh)以获取可用方向的列表。  
**sneaky** - 若设置为 `true`，机器人会模拟潜行右键单击（如同玩家按住shift时点击右键）。某些物品（例如桶）在这时会有不同的行为。
**duration** - 物品被使用多长时间。这在使用例如弓之类的蓄力物品时很有用。  
**返回值：**若机器人可以和它面前的方块或实体互动返回`true`，否则返回`false`。若执行成功，第二个返回值表示机器人互动的对象是什么，可能的取值为下列之一：`block_activated`（激活方块）、`item_placed`（放置物品）、`item_interacted`（与物品互动）、`item_used`（使用物品）。
此函数用途非常广泛，因为机器人可以模拟右键单击大多数物品。在这方面机器人与玩家的唯一区别是机器人不能使用明确要求用户是实体的物品，因为机器人是方块。所以喝药水、吃食物或扔末影珍珠都会失败。  
 此函数的第二个返回值可用以判断右键单击的结果。有时候不一定能明显看出一个物品会返回哪个值，因此需要事先测试。还需注意，虽然机器人不受有害药水的影响，但它们可能会被爆炸摧毁，因此在使用此函数放置、投掷或激活任何形式的炸药时要小心。  
第二个返回值的可能取值有：  
  - `block_activated` - 某个方块被激活（例如拉杆、开关以及门）。
  - `item_interacted` - 装备的工具与世界进行了互动，例如在羊身上使用剪刀。
  - `item_placed` - 某个物品被放置到了世界中。此返回值不一定由可放置的方块触发，其他会导致方块或实体出现在世界上的物品也会触发（例如燧石或刷怪蛋）。
  - `item_used` - 装备的物品被激活，例如喷溅式药水。
  - `air` - 当前装备的物品需要目标才能使用，但并不存在。请注意如果你的机器人有天使升级，此返回值将永远不会出现，但一些操作可能仍然无效果。\\
\\
- `robot.useUp([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]`  
和`robot.use()`一样，但此函数会瞄准机器人上方区域。  
\\
- `robot.useDown([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]`  
和`robot.use()`一样，只是这个会瞄准机器人下方区域。  
\\
- `robot.forward(): boolean[, string]`  
尝试将机器人向前移动。  
**返回值：**若机器人成功移动了则返回`true`，否则返回 `nil`。若移动失败，会出现第二个返回值，代表为什么失败，可能的取值为：`impossible move`（不可行的移动方式）、`not enough energy`（能量不足）或与`robot.detect`返回值相同的障碍描述。  
返回值`impossible move`很少见，因为缺少能量通常会让机器人在此前就关机了。  
返回值`impossible move`是一种回退结果，会在机器人试图进入未加载区域等情况下返回。  
\\
- `robot.back(): boolean[, string]`  
和`robot.forward()`一样，但此函数会让机器人尝试向后移动。  
\\
- `robot.up(): boolean[, string]`  
和`robot.forward()`一样，但此函数会让机器人尝试向上移动。  
\\
- `robot.down(): boolean[, string]`  
和`robot.forward()`一样，但此函数会让机器人尝试向下移动。  
\\
- `robot.turnLeft()`  
将机器人左转90°。  
请注意，此函数只会在机器人没有足够能量左转但还没有关机时执行失败。  
\\
- `robot.turnRight()`  
和`robot.turnLeft() `一样，但此函数会让机器人右转90°。  
\\
- `robot.turnAround`  
此函数与调用两次`robot.turnRight()`是一样的。  
\\
- <del>` robot.level(): number `</del>  
**自 OC 1.3 起已弃用。**请使用`component.experience.level()`代替（只能在安装了[[item:experience_upgrade:zh|经验升级]]的前提下可用）。  
返回机器人的当前等级，其小数部分为到达下一等级的百分比进度。例如，若此函数返回了`1.5`，代表机器人为1级，且已经完成了升到2级所需进度的50%。  
\\
- `robot.tankCount(): number`  
机器人安装的流体储罐数量。  
\\
- `robot.selectTank(tank)`  
选定指定的流体储罐。这决定了大多数操作在哪个流体储罐上进行。  
\\
- `robot.tankLevel([tank:number]): number`  
返回指定流体储罐的流体存量，若不指定，则返回选定流体储罐的流体存量。  
\\
- `robot.compareFluidTo(tank: number): boolean`  
检查选定流体储罐中的液体与指定流体储罐中的是否相同。  
\\
- `robot.transferFluidTo(tank: number[, count: number]): boolean`  
从选定流体储罐转移指定数量的流体到指定流体储罐。若不指定数量，则尝试转移1000 mB。  
\\
- `robot.compareFluid(): boolean`  
检查选定流体储罐中的流体与机器人面前世界中或流体储罐中的流体是否相同。  
\\
- `robot.compareFluidUp(): boolean`  
和`robot.compareFluid()`一样，但此函数作用于机器人上方的方块。  
\\
- `robot.compareFluidDown(): boolean`  
和`robot.compareFluid()`一样，但此函数作用于机器人下方的方块。  
\\
- `robot.drain([count: number]): boolean`  
从机器人面前的世界中或流体储罐中抽取指定数量的流体。若不指定数量，会尝试转移1000 mB。若抽取的流体是直接存在于世界中，且不能被完全储存于选定流体储罐时，操作会失败，但不会损失流体。  
\\
- `robot.drainUp([count: number]): boolean`  
和`robot.drain()`一样，但此函数作用于机器人上方的方块。  
\\
- `robot.drainDown([count: number]): boolean`  
和`robot.drain()`一样，但此函数作用于机器人下方的方块。  
\\
- `robot.fill([count: number]): boolean`  
从选定流体储罐抽取指定数量的液体，填充到机器人面前的世界或流体储罐中。若不指定数量，会尝试转移1000 mB。若没有足够流体填满一个方块，或者目标储罐空间不足，操作将会失败，但不会损失流体。  
\\
- `robot.fillUp([count: number]): boolean`  
和`robot.fill()`一样，但此函数作用于机器人上方的方块。  
\\
- `robot.fillDown([count: number]): boolean`  
和`robot.fill()`一样，但此函数作用于机器人下方的方块。  


目录
-----------
{{page>api:contents:zh&noheader&noeditbutton&nouser&nofooter}}