Differences

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

--- api:robot:zh [2023/11/27 04:14]
hfsr [API 特有方法]
+++ api:robot:zh [2023/11/30 08:27]
hfsr [悬停]
@@ Line 3: / Line 3: @@
 此API封装了[[component:robot:zh|机器人]]**组件**的功能，允许与机器人实现更直观的互动。
-使用如下方式在你的 Lua 代码中调用这个 API：
+若你在Lua代码中这样写，那么你调用的就是此API：
 ```lua
@@ Line 10: / Line 10: @@
 ```
-不推荐直接访问机器人组件API，虽然可以通过组件接口这么做：
+与之相对的是通过组件接口，直接使用机器人组件API：
 ```lua
 local component = require("component")
-local robot_component_api = component.robot -- 如果你使用 OpenOS 可以这么写，否则要写 component.proxy(component.list("robot")())
+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`。使用哪一种由你自己决定，甚至可以混用二者。
+虽然机器人组件提供了更通用的功能，比如`move([side: number])`和`drop([side: number])`，但是此API提供了更直观、更安全的函数，比如`turnRight`、`dropDown`、`forward`。使用哪一种由你自己决定，甚至可以混用二者。
-请注意机器人本身就是一台开放式电脑，和其它电脑一样，只是多了一个机器人组件，所以一般的[API](api:zh)仍然可用。
+请注意机器人本身就是一台OC模组的电脑，和其它电脑一样，只是多了一个机器人组件，所以一般的[API](api:zh)仍然可用。
 查看[方块：机器人](:block:robot:zh)以获取更多有关机器人本身的信息。
@@ Line 28: / Line 28: @@
 ## 移动
-机器人能够灵活移动，但你应该了解一点细节。
+机器人能够灵活移动，但你可能会想了解一些细节。
 ### 悬停
@@ Line 34: / Line 34: @@
 机器人有飞行高度限制。机器人移动的基本规则是这样的：
-- 1. 机器人只有在起点和目标点均可用时才会移动（例如用于建桥）。
+- 1. 机器人只有在起点或目标点为可用（下图绿色区域）时才会移动（此特性可用于建桥等）。
-- 2. 机器人下方一定可用（一定可以向下移动）。
+- 2. 机器人下方位置一定为可用（一定可以向下移动）。
-- 3. 固体方块上至多`flightHeight`格是可用的（飞行能力有限，默认为8）
+- 3. 固体方块（图中棕色区域）上方的`flightHeight`格为可用区域（飞行能力有限，默认为8）。
-- 4. 任何紧贴着实心面的位置都是可用的（机器人可以“爬墙”）。
+- 4. 紧贴实心面的位置均为可用区域（机器人可以“爬墙”）。
 此处为一张可视化展示上述规则的图片（忽略了第二条规则，这会使图片变得混乱）
@@ Line 170: / Line 170: @@
 \\
 - `robot.use([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]`
-尝试以玩家点击右键的方式对着前方使用当前工具栏里的工具。
+尝试使用当前工具槽位中的物品，与玩家单击右键相同。
-**side** - 如果给定，机器人只会尝试“右键”指定的面，否则机器人会尝试右键所有可能的面。参见 [方向控制（sides） API](api:sides:zh) 来获得可能的面的列表。
+**side** - 若给定，机器人只会尝试“右键单击”指定方向的面，否则机器人会尝试所有可能的方向。参见[sides(方向) API](api:sides:zh)以获取可用方向的列表。
-**sneaky** - 如果设置为 `true`，机器人会模拟潜行点击右键（如同玩家按住 Shift 时点击右键）。某些物品（例如桶）在这时会有不同的行为。
+**sneaky** - 若设置为 `true`，机器人会模拟潜行右键单击（如同玩家按住shift时点击右键）。某些物品（例如桶）在这时会有不同的行为。
-**duration** - 这个物品被使用多长时间。这在使用例如弓之类的蓄力物品时很有用。
+**duration** - 物品被使用多长时间。这在使用例如弓之类的蓄力物品时很有用。
-**返回值**： 如果机器人可以和它面前的方块或实体互动返回真，否则返回假。如果成功，第二个返回值会描述机器人和什么东西互动了，它会是“方块*已激活*”、“*物品*已放置”、“和物品*互动*”或者“*物品*已使用”之一。
+**返回值：**若机器人可以和它面前的方块或实体互动返回`true`，否则返回`false`。如果执行成功，第二个返回值表示机器人和什么东西互动了，可能的取值为下列之一：`block_activated`（激活方块）、`item_placed`（放置物品）、`item_interacted`（与物品互动）、`item_used`（使用物品）。
-这个函数有很广泛的应用，因为机器人能由此模拟右键点击大部分物品。和玩家唯一的不同在于机器人不能使用要求使用者必须是实体的物品，因为机器人是方块。所以喝药水、吃食物或者扔末影珍珠会失败。
+此函数用途非常广泛，因为机器人可以模拟右键单击大多数物品。在这方面机器人与玩家的唯一区别是机器人不能使用明确要求用户是实体的物品，因为机器人是方块。所以喝药水、吃食物或扔末影珍珠都会失败。
-这个函数的第二个返回值可以被用于右键点击造成的结果。有些物品返回的结果并不总是明显的，它们需要事先测试。同样请注意尽管机器人不会被有害的药水伤害，它们仍然可以被爆炸炸毁，所以在你使用这个函数放置、扔出或激活任何爆炸物时，请务必小心。可能的第二个返回值是以下这些：
+ 此函数的第二个返回值可用以判断右键单击的结果。有时候不一定能明显看出一个物品会返回哪个值，因此需要事先测试。还需注意，虽然机器人不受有害药水的影响，但它们可能会被爆炸摧毁，因此在使用此函数放置、投掷或激活任何形式的炸药时要小心。
+第二个返回值的可能取值有：
-  - `block_activated` - 一个方块被激活了（例如拉杆、按钮或门）。
+  - `block_activated` - 某个方块被激活（例如拉杆、开关以及门）。
-  - `item_interacted` - 装备的工具与世界互动了，例如用剪刀剪羊毛。
+  - `item_interacted` - 装备的工具与世界进行了互动，例如在羊身上使用剪刀。
-  - `item_placed` - 某些东西被放置在世界上了。这不仅仅由可放置的方块造成，还会由可以创造方块或实体的物品造成（例如打火石或刷怪蛋)。
+  - `item_placed` - 某个物品被放置到了世界中。此返回值不一定由可放置的方块触发，其他会导致方块或实体出现在世界上的物品也会触发（例如燧石或刷怪蛋）。
-  - `item_used` - 装备的物品被激活了，例如喷溅型药水。
+  - `item_used` - 装备的物品被激活，例如喷溅式药水。
-  - `air` - 装备的物品要求有一个目标但是却没有。请注意，如果你的机器人有一个天使方块升级，这个值永远不会被返回，但是一些动作仍然不会有效果。
+  - `air` - 当前装备的物品需要目标才能使用，但并不存在。请注意如果你的机器人有天使升级，此返回值将永远不会出现，但一些操作可能仍然无效果。\\
+\\
 - `robot.useUp([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]`
-和 `robot.use()` 一样，只是这个会瞄准机器人头顶的位置。
+和`robot.use()`一样，但此函数会瞄准机器人上方区域。
+\\
 - `robot.useDown([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]`
-和 `robot.use()` 一样，只是这个会瞄准机器人脚底的位置。
+和`robot.use()`一样，只是这个会瞄准机器人下方区域。
+\\
 - `robot.forward(): boolean[, string]`
 尝试将机器人向前移动。
-**返回值**：返回 `true`，如果机器人成功移动了，否则返回 `nil`。如果移动失败，第二个返回值会描述为什么失败，它会是“不可能的移动”、“没有足够能量”或者是 `robot.detect` 返回的障碍描述之一。
+**返回值：**若机器人成功移动了则返回`true`，否则返回 `nil`。若移动失败，会出现第二个返回值，代表为什么失败，可能的取值为：`impossible move`（不可行的移动方式）、`not enough energy`（能量不足）或与`robot.detect`返回值相同的障碍描述。
-返回值“没有足够能量”是极少见的，因为缺少能量通常会让机器人在那之前就关机了。
+返回值`impossible move`很少见，因为缺少能量通常会让机器人在此前就关机了。
-返回值“不可能的移动”是一种回落（fall-back）结果，而且会在诸如机器人试图进入一片未加载区域等场合返回。
+返回值`impossible move`是一种回退结果，会在机器人试图进入未加载区域等情况下返回。
+\\
 - `robot.back(): boolean[, string]`
-和 `robot.forward()` 一样，只是这个会让机器人尝试向后移动。
+和`robot.forward()`一样，但此函数会让机器人尝试向后移动。
+\\
 - `robot.up(): boolean[, string]`
-和 `robot.forward()` 一样，只是这个会让机器人尝试向上移动。
+和`robot.forward()`一样，但此函数会让机器人尝试向上移动。
+\\
 - `robot.down(): boolean[, string]`
-和 `robot.forward()` 一样，只是这个会让机器人尝试向下移动。
+和`robot.forward()`一样，但此函数会让机器人尝试向下移动。
+\\
 - `robot.turnLeft()`
-将机器人左转 90°。
+将机器人左转90°。
-请注意，它只会在机器人没有足够能量左转但还没有关机时失败。
+请注意，此函数只会在机器人没有足够能量左转但还没有关机时执行失败。
+\\
 - `robot.turnRight()`
-和 `robot.turnLeft() ` 一样，只是这个会让机器人右转 90°。
+和`robot.turnLeft() `一样，但此函数会让机器人右转90°。
+\\
 - `robot.turnAround`
-这和调用两次 `robot.turnRight()` 是一样的。
+此函数与调用两次`robot.turnRight()`是一样的。
+\\
 - <del>` robot.level(): number `</del>
-**自 OC 1.3 起已弃用。**
+**自 OC 1.3 起已弃用。**请使用`component.experience.level()`代替（只能在安装了[[item:experience_upgrade:zh|经验升级]]的前提下可用）。
-译者注：由于该 API 被弃用且暂无恢复计划，故略过不译，有需要者请自行查看英文文档。
+返回机器人的当前等级，其小数部分为到达下一等级的百分比进度。例如，若此函数返回了`1.5`，代表机器人为1级，且已经完成了升到2级所需进度的50%。
+\\
 - `robot.tankCount(): number`
-机器人安装的液体储罐数量（number）。
+机器人安装的流体储罐数量。
+\\
 - `robot.selectTank(tank)`
-选择指定的液体储罐。这决定了大多数操作在哪个液体储罐上进行。
+选定指定的流体储罐。这决定了大多数操作在哪个流体储罐上进行。
+\\
 - `robot.tankLevel([tank:number]): number`
-返回指定液体储罐的等级，如果没有指定，则返回当前液体储罐的等级。
+返回指定流体储罐的流体存量，若不指定，则返回选定流体储罐的流体存量。
+\\
 - `robot.compareFluidTo(tank: number): boolean`
-测试当前选定的液体储罐中的液体与给定的液体储罐中的液体是否相同。
+检查选定流体储罐中的液体与指定流体储罐中的是否相同。
+\\
 - `robot.transferFluidTo(tank: number[, count: number]): boolean`
-从当前选定的液体储罐转移指定数量的液体到给定的液体储罐。如果不指定数量，就会尝试转移 1000 mB。
+从选定流体储罐转移指定数量的流体到指定流体储罐。若不指定数量，则尝试转移1000 mB。
+\\
 - `robot.compareFluid(): boolean`
-测试当前选定的液体储罐中的液体与机器人面前的液体储罐中的液体是否相同。
+检查选定流体储罐中的流体与机器人面前世界中或流体储罐中的流体是否相同。
+\\
 - `robot.compareFluidUp(): boolean`
-和 `robot.compareFluid()` 一样，只是这个会比较机器人头顶的液体储罐。
+和`robot.compareFluid()`一样，但此函数作用于机器人上方的方块。
+\\
 - `robot.compareFluidDown(): boolean`
-和 `robot.compareFluid()` 一样，只是这个会比较机器人脚底的液体储罐。
+和`robot.compareFluid()`一样，但此函数作用于机器人下方的方块。
+\\
 - `robot.drain([count: number]): boolean`
-从机器人面前的液体储罐抽取指定数量的液体到选定的液体储罐中。当不指定数量时，会尝试转移 1000 mB。当抽取的液体是直接存在于世界上并且不能被完全储存于选定的液体储罐时，操作失败。没有液体会损失。
+从机器人面前的世界中或流体储罐中抽取指定数量的流体。若不指定数量，会尝试转移1000 mB。若抽取的流体是直接存在于世界中，且不能被完全储存于选定流体储罐时，操作会失败，但不会损失流体。
+\\
 - `robot.drainUp([count: number]): boolean`
-和 `robot.drain()` 一样，只是这个会抽取机器人头顶的液体。
+和`robot.drain()`一样，但此函数作用于机器人上方的方块。
+\\
 - `robot.drainDown([count: number]): boolean`
-和 `robot.drain()` 一样，只是这个会抽取机器人脚底的液体。
+和`robot.drain()`一样，但此函数作用于机器人下方的方块。
+\\
 - `robot.fill([count: number]): boolean`
-从选定的液体储罐中注入指定数量的液体到机器人面前的液体储罐。当不指定数量时，会尝试转移 1000 mB。当没有足够的液体来填充一个方块。或者目标储罐没有足够的空间，操作失败。没有液体会损失。
+从选定流体储罐抽取指定数量的液体，填充到机器人面前的世界或流体储罐中。若不指定数量，会尝试转移1000 mB。若没有足够流体填满一个方块，或者目标储罐空间不足，操作将会失败，但不会损失流体。
+\\
 - `robot.fillUp([count: number]): boolean`
-和 `robot.fill()` 一样，只是这个会向机器人头顶注入液体。
+和`robot.fill()`一样，但此函数作用于机器人上方的方块。
+\\
 - `robot.fillDown([count: number]): boolean`
-和 `robot.fill()` 一样，只是这个会向机器人脚底注入液体。
+和`robot.fill()`一样，但此函数作用于机器人下方的方块。