This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
api:robot:zh [2022/08/11 10:11] fight_xing [API 特有的方法] |
api:robot:zh [2023/11/30 08:58] (current) hfsr [API 特有方法] |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | 翻译不保证完全准确。 | + | # Robot(机器人) API |
- | # 机器人 API | + | 此API封装了[[component:robot:zh|机器人]]**组件**的功能,允许与机器人实现更直观的互动。 |
- | 这个 API 打包了机器人组件的功能,允许与机器人实现更直观的互动。 | + | 若你在Lua代码中这样写,那么你调用的就是此API: |
- | + | ||
- | 使用如下方式在你的 Lua 代码中调用这个 API: | + | |
```lua | ```lua | ||
Line 12: | Line 10: | ||
``` | ``` | ||
- | 直接访问机器人组件 API 是不推荐的,虽然可以通过组件接口这么做: | + | 与之相对的是通过组件接口,直接使用机器人组件API: |
```lua | ```lua | ||
local component = require("component") | 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) | robot_component_api.move(sides.front) | ||
``` | ``` | ||
- | 机器人组件 API 提供了更通用的功能,比如说 `move([方向:数字])` 或者 `drop([方向:数字])`,而这个 API(译者注:指机器人 API,这里的指代如此混乱是因为各种组件有一套单独的 API,这套单独的 API 中也包含了用于控制机器人的 API,下文的所有 API 指的都是机器人 API 而不是组件机器人 API)提供更直观、更安全的功能,比如说 `turnRight`, `dropDown`, `forward`。使用哪一种由你自己决定,甚至可以混用二者。 | + | 虽然机器人组件提供了更通用的功能,比如`move([side: number])`和`drop([side: number])`,但是此API提供了更直观、更安全的函数,比如`turnRight`、`dropDown`、`forward`。使用哪一种由你自己决定,甚至可以混用二者。 |
- | 请注意机器人本身就是一台开放式电脑,和其它电脑一样,只是多了一套机器人 API,所以 [一般的 API](api:zh) 仍然可用。 | + | 请注意机器人本身就是一台OC模组的电脑,和其它电脑一样,只是多了一个机器人组件,所以一般的[API](api:zh)仍然可用。 |
- | 查看 [方块:机器人](:block:robot:zh) 获得更多有关机器人本身的信息。 | + | 查看[方块:机器人](:block:robot:zh)以获取更多有关机器人本身的信息。 |
- | ## 物品栏格子的对应方法 | + | ## 槽位排列 |
- | + | {{page>component:inventory_slots:zh&noheader&nofooter}} | |
- | **译者注:本段的原文引用了组件-物品栏部分的内容,当该部分翻译完成后,这里会自动被翻译。** | + | |
- | {{page>component:inventory_slots&noheader&nofooter}} | + | |
## 移动 | ## 移动 | ||
- | 机器人能够灵活移动,但你应该了解一点细节。 | + | 机器人能够灵活移动,但你可能会想了解一些细节。 |
### 悬停 | ### 悬停 | ||
Line 38: | Line 34: | ||
机器人有飞行高度限制。机器人移动的基本规则是这样的: | 机器人有飞行高度限制。机器人移动的基本规则是这样的: | ||
- | 1. 机器人只有在起点和目标点都是可用的(也就是可以建造)时才会移动 | + | - 1. 机器人只有在起点或目标点为可用(下图绿色区域)时才会移动(此特性可用于建桥等)。 |
- | 2. 机器人总是可以向下移动 | + | - 2. 机器人下方位置一定为可用(一定可以向下移动)。 |
- | 3. 距离脚下的固体方块 `flightHigh` 格以上的位置是不可用的(限制飞行能力,默认是 8) | + | - 3. 固体方块(图中棕色区域)上方的`flightHeight`格为可用区域(飞行能力有限,默认为8)。 |
- | 4. 任何紧贴着一个实心方块(译者注:也就是不能穿过的方块)的位置都是可用的(机器人可以“爬墙”)。这里有一张可视化表现机器人能移动位置的图片(忽略了第二条规则,这会使图片变得混乱) | + | - 4. 紧贴实心面的位置均为可用区域(机器人可以“爬墙”)。 |
+ | 此处为一张可视化展示上述规则的图片(忽略了第二条规则,这会使图片变得混乱) | ||
{{:api:robot_flight.png}} | {{:api:robot_flight.png}} | ||
- | 违反这些规则会导致机器人返回 `impossible move` 错误。 | + | 违反这些规则会导致机器人返回`impossible move`错误。 |
- | 你可以安装悬浮升级提升(tire 1)乃至规避(tire 2)这个限制。或者你也可以在模组配置文件中禁用这个限制,只要把 `limitFlightHeight` 设置到 256 或者更高就行。 | + | 你可以安装悬浮升级以提升(1级)乃至很大程度上规避(2级)这个限制。或者你也可以在模组配置文件中禁用这个限制,只要将`limitFlightHeight`设置为256或更高即可。 |
- | [这一段的来源](https://github.com/MightyPirates/OpenComputers/issues/1113#issuecomment-97731965) | + | [来源](https://github.com/MightyPirates/OpenComputers/issues/1113#issuecomment-97731965)(英文) |
- | ## API 特有的方法 | + | ## API 特有方法 |
- | + | ||
- | (译者注:为了保证程序员友好,原文中的专有名词不做翻译,仅在这段末尾附上对照表) | + | |
- `robot.name(): string` | - `robot.name(): string` | ||
返回机器人的名字。 | 返回机器人的名字。 | ||
- | 机器人的名字在它被创造时会自动赋予,并且不能通过程序修改。但如果你想,可以用铁砧改掉。 | + | 机器人的名字在它被创造时会自动设定,且不能通过程序修改。但如果你想,可以用铁砧修改。 |
+ | \\ | ||
- `robot.detect(): boolean, string` | - `robot.detect(): boolean, string` | ||
- | 探测机器人面前的东西并且返回机器人是否能移动过去,同时返回面前东西的描述。 | + | 探测机器人正前方的物体,并且返回机器人是否能移动过去,同时返回面前物体的描述。 |
- | **返回值:** 如果机器人面前有东西阻碍它过去(方块或者实体),返回 `true`(提示:即使面前的方块是 `passable`,机器人也会返回 `true`),否则返回 `false`。第二个返回的参数粗略地描述前面的是什么,这个参数将会是 `entity`, `solid`, `replaceable`, `liquid`, `passable` 或者是 `air`。 | + | **返回值:**若机器人面前的物体会阻碍其移动(方块或者实体)则返回 `true`,否则返回 `false`(注意:即使面前的方块为`passable`,代表可穿越,无人机也会返回`true`)。第二个返回值大体描述了前面的物体是什么,可能取值为;`entity`、`solid`、`replaceable`、`liquid`、`passable`或者`air`。 |
+ | \\ | ||
- `robot.detectUp(): boolean, string` | - `robot.detectUp(): boolean, string` | ||
- | 和 `robot.detect()` 一样,只是这个探测机器人头顶的东西。 | + | 和`robot.detect()`一样,但此函数探测机器人正上方的方块。 |
+ | \\ | ||
- `robot.detectDown(): boolean, string` | - `robot.detectDown(): boolean, string` | ||
- | 和 `robot.detect()` 一样,只是这个探测机器人脚踩的东西。 | + | 和`robot.detect()`一样,但此函数探测机器人正下方的方块。 |
+ | \\ | ||
- `robot.select([slot: number]): number` | - `robot.select([slot: number]): number` | ||
- | 选择给定的物品栏格子(如果指定了)并且返回当前的物品栏格子。 | + | 选定给定的物品栏槽位(若指定),并返回物品栏当前的选定槽位。 |
- | **slot** - 要选择的物品栏格子。如果这个参数省略,那么不会新选择任何格子。 | + | **slot** - 要选定的物品栏槽位。若此参数省略,那么不会改动当前选定槽位。 |
- | **返回** 当前的物品栏格子。返回给定的物品栏格子(如果选择成功)或者先前选择的物品栏格子。 | + | **返回值:**物品栏当前的选定槽位。可能为给定的物品栏槽位(若选择成功)或先前选定的物品栏槽位。 |
+ | \\ | ||
- `robot.inventorySize(): number` | - `robot.inventorySize(): number` | ||
- | **返回** 可以选择的物品栏格子的数量。如果想要知道安装的物品栏升级个数,使用这个公式:x = robot.inventorySize() / 16。 | + | **返回值:**可选定的物品栏槽位数量。想要获取安装的物品栏升级个数,可以使用这个公式:x = robot.inventorySize() / 16。 |
+ | \\ | ||
- `robot.count([slot: number]): number` | - `robot.count([slot: number]): number` | ||
- | 返回当前选定的物品栏格子里物品的个数或者指定格子里面物品栏的个数。 | + | 返回物品栏的指定槽位或选定槽位中的物品个数。 |
- | **slot** - 指定格子来获取里面物品的个数。如果省略这个参数就会对当前选定的格子里的物品计数。 | + | **slot** - 指定要获取物品数的槽位。若省略则会对当前选定槽位的物品计数。 |
- | **返回** 指定格子里面物品的数量,或者当前格子里面物品的数量(如果没有指定格子) | + | **返回值:**指定槽位中物品的数量,或当前选定槽位中物品的数量(若没有指定槽位)。 |
+ | \\ | ||
- `robot.space([slot: number]):number` | - `robot.space([slot: number]):number` | ||
- | 返回仍然能叠加到指定格子里面的物品的个数。 | + | 返回在给定槽位装满之前还能装入多少物品。 |
- | **slot** - 指定格子来计算还能叠加多少物品。如果省略就计算当前格子。 | + | **slot** - 指定要计算物品数的槽位。若省略则计算当前选定槽位。 |
- | **返回** 仍然能叠加到指定格子或者当前格子的物品数量。 | + | **返回值:**给定槽位或当前选定槽位在装满前还能装入多少物品。 |
- | 这个函数帮助决定多少同种物品能叠加到一个格子上。例如对于圆石每个格子能放 64 个,但是空桶每个格子只能放 16 个,而有些方块,比如门<sup>原文如此</sup>,每个格子只能放一个。 | + | 此函数还有助于判断某种物品在单个槽位中的堆叠上限。例如圆石在每个槽位中能放64个,但是空桶在每个槽位中只能放16个,而有些方块,比如门,在每个槽位中只能放一个。 |
+ | \\ | ||
- `robot.transferTo(slot: number[, count: number]): boolean` | - `robot.transferTo(slot: number[, count: number]): boolean` | ||
- | 从当前格子移动所有的或者是最多 *count* 数量的物品到指定的格子。 | + | 从当前选定槽位移动所有或是至多`count`个物品到指定槽位。 |
- | **slot** - 指定要把物品移动到的格子。 | + | **slot** - 指定承接物品的槽位。 |
- | **count** - 如果指定这个参数,那么最多有这些数量的物品会被移动,不指定则会移动全部物品。 | + | **count** - 若指定此参数,则最多移动此参数个物品,否则移动整个物品堆。 |
- | **返回** `true`,如果交换两个格子的物品成功了,否则返回 `false`。 | + | **返回值:**若成功交换两个槽位中的物品则返回`true`,否则返回 `false`。 |
- | 如果指定的格子里面有物品,这个函数就会尝试交换两个格子的物品。只有当你将当前格子的所有物品都移动过去或者当前格子是空的时才会成功。 | + | 若指定槽位中有物品,此函数会尝试交换两个槽位中的物品。只有将选定槽位中的所有物品都移走,或以其他任意方式清空选定槽位,交换才会成功。 |
- | 请注意如果两个格子里的物品相同或者两个格子都是空的,返回值总会是真,即使事实上没有移动任何东西。 | + | 注意,若两个槽位中的物品相同,或者两个槽位都是空的,返回值一定是`true`,即使实际上没有移动任何东西。 |
+ | \\ | ||
- `robot.compareTo(slot: number):boolean` | - `robot.compareTo(slot: number):boolean` | ||
- | 比较机器人面前的方块与当前选择的物品栏格子中的方块是否相同。 | + | 比较物品栏当前选定槽位中的物品与给定槽位中的是否相同。 |
- | 如果方块的种类和元数据(meatdata)相同,那么它们就被认定为相同。栈(stack)大小或者其它附加信息(例如容器的物品栏)不会被比较。 | + | **slot** - 指定要与当前选定槽位比较的槽位。 |
- | 请注意机器人前方如果是空的则会被游戏认为是“空气方块”,不能被放进物品栏,因此也不能进行一般意义上的比较。物品栏的空格子和空气方块是**不**相同的。你可以先使用 `robot.detect()` 来确认机器人面前是否真的有方块。 | + | **返回值:**若两个槽位中的物品种类相同则返回`true`,否则返回`false`。 |
- | 同样请记住会掉落其它物品的方块应当和真正摆放在世界上的方块比较。举个例子,石头方块掉落圆石,钻石矿石掉落钻石,对于这个函数来说它们并不相同。使用精准采集的工具开采实际的方块用于作比较。 | + | 若两个物品的种类和元数据相同,那么它们就被认定为“相同”。物品堆大小(物品数量)或其它额外信息(例如容器的物品栏)不会检查。 |
+ | \\ | ||
+ | - `robot.compare(slot: number):boolean` | ||
+ | 比较机器人正前方的方块与物品栏当前选定槽位中的方块,并返回它们是否相同。 | ||
+ | 若两个方块的类型和元数据相同,那么它们就被认定为“相同”。物品堆大小(物品数量)或其它额外信息(例如容器的物品栏)不会检查。 | ||
+ | 请注意,机器人前方如果是空的则会被游戏认为是“空气方块”,这种方块不能被放进物品栏,因此也不能使用一般方法比较。物品栏的空槽位与空气方块**不同**。你可以先使用`robot.detect()`来确认机器人前方是否真的有方块。 | ||
+ | 还请记住,会掉落其它物品的方块应当和真正出现在世界上的方块比较(而非掉落物)。例如,石头方块会以圆石形式掉落,钻石矿石掉落钻石物品。对于这个函数来说它们并不相同。需要使用精准采集的工具开采实际的方块用于比较。 | ||
+ | \\ | ||
- `robot.compareUp(): boolean` | - `robot.compareUp(): boolean` | ||
- | 和 `robot.compare()` 一样,只是这个比较机器人头顶的方块。 | + | 和`robot.compare()`一样,但此函数比较机器人正上方的方块。 |
+ | \\ | ||
- `robot.compareDown(): boolean` | - `robot.compareDown(): boolean` | ||
- | 和 `robot.compare()` 一样,只是这个比较机器人脚踩的方块。 | + | 和`robot.compare()`一样,但此函数比较机器人正下方的方块。 |
+ | \\ | ||
- `robot.drop([count: number]): boolean` | - `robot.drop([count: number]): boolean` | ||
- | 尝试将当前所选的物品栏中的物品丢在面前。注意,如果你尝试将物品丢进脚下的容器里面,这是错误的方法。使用 `dropDown` 来做这个。这个方法,` drop `,会将东西丢在面前。 | + | 尝试从内部物品栏的当前选定槽位提取物品,并丢弃在机器人**前方**。注意,此方法不可用于将物品丢入机器人下方的物品容器,这种情况下需要使用`dropDown`方法。 此方法会将物品丢在**面前**。 |
- | **count** - 指定丢多少物品。如果省略这个参数或者它的值超过了物品的数量,所有物品都会被丢出去。 | + | **count** - 指定丢出多少物品。若省略此参数或其值超过了物品的数量,则所有物品都会被丢出。 |
- | **返回** `true`,如果有至少一个物品被丢出去,反之返回 `false`。 | + | **返回值:**若至少丢出了一个物品则返回`true`,否则返回`false`。 |
- | 如果机器人面前的实体或方块有物品栏(例如箱子或者运输矿车),机器人会尝试将物品放进物品栏中而不是丢在世界上。如果面前的方块的确有物品栏但是要丢出去的物品因为某种原因没法放进去,那么这个函数返回假并且不会移动任何物品。物品被放置的位置取决于物品栏和机器人面对方块的方向。举例来说,熔炉会冶炼上方放进来的物品。同样请注意其它机器人也会被认为成“带有物品栏的方块”,所以物品也能被移入其它机器人的物品栏格子,就像移入别的物品栏一样。 | + | 若机器人正前方的实体或方块有可访问的物品栏(例如箱子或运输矿车),机器人会尝试将物品放进物品栏中而不是丢弃到世界中。若面前的方块的确有物品栏,但是因为某种原因物品无法被放入其中,则此函数返回`false`,且不会移动任何物品。物品被放置的位置取决于物品容器自身,以及机器人面对容器的哪个面。例如,熔炉从上方接收待烧炼物品。还请注意,其它机器人也会被认为是“带物品栏的方块”,所以物品也能被移入其它机器人的物品栏槽位,就像移入别的物品容器一样。 |
- | 这个函数不能和不储存物品的物品栏互动(比如说液体储罐),也不会认为它们带有物品栏,所以物品会被扔到世界上。你需要使用 `robot.use` 函数来和这些方块互动。 | + | 此函数不能与非物品类型的容器互动(例如流体储罐),也不会将它们当作物品容器,因此物品会被扔到世界中。你需要使用`robot.use`函数与这些种类的方块互动。 |
- | 请注意如果当前选定的物品栏格子是空的,那么返回值总会是假。 | + | 请注意若物品栏的当前选定槽位是空的,那么返回值一定为`false`。 |
+ | \\ | ||
- `robot.dropUp(): boolean` | - `robot.dropUp(): boolean` | ||
- | 和 `robot.drop()` 一样,只是这个把物品丢在机器人头顶。 | + | 和`robot.drop()`一样,但此函数把物品丢在机器人正上方。 |
+ | \\ | ||
- `robot.dropDown(): boolean` | - `robot.dropDown(): boolean` | ||
- | 和 `robot.drop()` 一样,只是这个把物品丢在机器人脚底。 | + | 和`robot.drop()`一样,但此函数把物品丢在机器人正下方。 |
+ | \\ | ||
- `robot.suck([count: number]): boolean` | - `robot.suck([count: number]): boolean` | ||
- | 尝试从面前捡起掉落物并把它放入指定的物品栏格子或者(如果省略这个参数)第一个可能的物品栏格子。 | + | 尝试从正前方拾起掉落物,并将其放入物品栏的选定槽位或者(若槽位被占用)第一个可用的槽位。 |
- | **count** - 限制最多捡起掉落物的数量。如果省略,将会捡起一个格子能装下的最多物品。 | + | **count** - 拾起掉落物的数量上限。若省略,则会捡起最多一个物品堆。 |
- | **返回** `true`,如果捡起了至少一个物品,否则返回 `false`。 | + | **返回值:**若捡起了至少一个物品则返回`true`,否则返回`false`。 |
- | 这基本就是 `robot.drop` 的反向,而且也会以相同的方式和物品栏互动。但是它只会拿走物品栏中第一个可用的物品。想要更精确的物品栏管理,你需要为机器人安装 [物品栏控制器升级](item:inventory_controller_upgrade:zh)。 | + | 此函数基本就是`robot.drop`的反向版,而且也会以相同的方式和物品容器互动。但是它只会拿走物品栏中的第一个可用物品。想要实现更精准的物品栏管理,你需要为机器人安装[物品栏控制器升级](item:inventory_controller_upgrade:zh)。 |
- | 如果机器人面前有多个掉落物,它会根据距离捡起掉落物。这会跳过因为某些原因无法捡起的掉落物并且在返回 `false` 之前尝试捡起其它掉落物。 | + | 若机器人面前有多个掉落物,则会根据距离远近捡起掉落物。此操作会跳过因为任意原因无法捡起的掉落物,并且在返回`false`之前先尝试捡起其它掉落物。 |
- | 如果当前选择的物品栏格子包含和机器人捡起的掉落物不同的物品,机器人会尝试将物品放在这个格子*之后*第一个可用的格子,要么是空的,要么是包含相同物品并且在放入机器人捡起的物品后小于等于最大堆叠上限的。如果必要,它会将物品分割到不同的格子中。如果在选定的格子之后没有可用的格子,这个函数就会失败,即使在选定的格子*之前*有能装下这些物品的格子。 | + | 若物品栏的当前选定槽位中有和机器人捡起的掉落物不同的物品,机器人会尝试将物品放在这个槽位**之后**的第一个可用槽位,要么是空槽位,要么是包含相同物品并且尚未达到堆叠上限的槽位。若必要,它会将拾起的物品分配到不同的槽位中。若当前选定槽位后没有可用槽位,此函数会执行失败,即使在选定槽位**前**有能装下这些物品的槽位也是如此。 |
+ | \\ | ||
- `robot.suckUp([count: number]): boolean` | - `robot.suckUp([count: number]): boolean` | ||
- | 和 `robot.suck()` 一样,只是这个尝试捡起头顶的物品。 | + | 和`robot.suck()`一样,但此函数会尝试捡起正上方的物品。 |
+ | \\ | ||
- `robot.suckDown([count: number]): boolean` | - `robot.suckDown([count: number]): boolean` | ||
- | 和 `robot.suck()` 一样,只是这个尝试捡起脚踩的物品。 | + | 和`robot.suck()`一样,但此函数尝试捡起正下方的物品。 |
+ | \\ | ||
- `robot.place([side: number[, sneaky: boolean]]): boolean[, string]` | - `robot.place([side: number[, sneaky: boolean]]): boolean[, string]` | ||
- | 尝试将当前选定的物品栏里面的方块放置在机器人面前。 | + | 尝试将物品栏选定槽位中的方块放置在机器人面前。 |
- | **side** - 这个参数会决定机器人尝试将方块放在哪个面上,举例来说,将火把放在特定的面上。如果省略,机器人会尝试所有可能的面。参见 [方向控制(sides) API](api:sides:zh) 来获得可能的面的列表。 | + | **side** - 若指定,此参数决定机器人会尝试将方块放到哪个面上。例如,可用于将火把放在特定表面上。若省略,机器人会尝试所有可能的方向。参见[sides(方向) API](api:sides:zh)以获取可能的方向列表。 |
- | **sneaky** - 如果设置为 `true`,机器人会模拟潜行时放置方块(如同一个按住 Shift 放置方块的玩家),这一般不是必要的,只是为了保持和其它模组的兼容性。 | + | **sneaky** - 若设置为 `true`,机器人会模拟潜行放置方块(和玩家在放置时按住shift的效果相同)。这种操作通常没有必要,只是为了保证和其它模组的兼容性。 |
- | **返回值**:如果一个物品可以被放置返回 `true`,否则返回 `false`。如果放置失败,第二个返回值会描述为什么放置失败。 | + | **返回值:**若物品可以放置则返回 `true`,否则返回 `false`。若放置失败,第二个返回值会描述失败原因。 |
- | 一个机器人只能在紧邻着其它固体方块的地方放置方块,它们不能将方块“放在空中”,除非有 [天使方块升级](item:angel_upgrade:zh)。这可以在配置文件中修改。 | + | 机器人只能将方块放置到另一个固体方块的某个面上,而不能“放在空气中”,除非有[天使升级](item:angel_upgrade:zh)。此特性可在配置文件中修改。 |
- | 请注意,如果物品栏格子是空的,放置方块总是会失败。 | + | 请注意若物品栏槽位是空的,那么操作一定会失败。 |
+ | \\ | ||
- `robot.placeUp([side: number[, sneaky: boolean]]): boolean[, string]` | - `robot.placeUp([side: number[, sneaky: boolean]]): boolean[, string]` | ||
- | 和 `robot.place()` 一样,只是这个尝试在头顶放置方块。 | + | 和`robot.place()`一样,但此函数会尝试在正上方放置方块。 |
+ | \\ | ||
- `robot.placeDown([side: number[, sneaky: boolean]]): boolean[, string]` | - `robot.placeDown([side: number[, sneaky: boolean]]): boolean[, string]` | ||
- | 和 `robot.place()` 一样,只是这个尝试在脚底放置方块。 | + | 和`robot.place()`一样,但此函数会尝试在正下方放置方块。 |
+ | \\ | ||
- `robot.durability(): number, number, number or nil, string` | - `robot.durability(): number, number, number or nil, string` | ||
- | 返回当前工具栏中物品耐久值的百分比(小数形式),以及它当前的耐久,以及它的最大耐久。 | + | 返回工具槽位中物品的耐久度剩余比例(小数)、当前耐久、最大耐久。 |
- | 如果工具栏中没有工具或者工具栏中的物品没有耐久值,它会返回 `nil` 以及一条描述为何不能返回耐久值的消息。错误信息要么是 `no tool equipped`,要么是 `too connot be damaged`。 | + | 若未装备物品或物品没有耐久值,此函数会返回`nil`以及一条描述为何不能返回耐久值的信息。报错信息可能为:`no tool equipped`(未装备工具)或`tool cannot be damaged`(工具不会损坏)。 |
+ | \\ | ||
- `robot.swing([side: number[, sneaky: boolean]]): boolean[, string]` | - `robot.swing([side: number[, sneaky: boolean]]): boolean[, string]` | ||
- | 让机器人立即以玩家点击左键的方式对着面前的方块或空间使用工具栏里装备的物品。 | + | 让机器人用当前在工具槽位中的物品对正前方的方块或空间交互,与玩家左键单击相同。 |
- | **side** - 如果指定,机器人只会尝试左键点击给定的面,否则机器人会尝试点击所有可能的面。参见 [方向控制(sides) API](api:sides:zh) 来获得可能的面的列表。 | + | **side** - 若指定,机器人只会尝试左键单击给定方向处的面,否则机器人会尝试单击所有可能的方向。参见[sides(方向) API](api:sides:zh)以获取可能方向的列表。 |
- | **返回值**:如果机器人可以和面前的方块或实体互动,返回真,否则返回假。如果成功,第二个返回值会描述机器人和什么东西互动了,它会是“实体”、“方块”或“火”之一。 | + | **返回值:**若机器人可以和面前的方块或实体互动,返回`true`,否则返回`false`。若执行成功,第二个返回值代表机器人和什么东西互动了,取值可能为`entity`(实体)、`block`(方块)或`fire`(火)。 |
- | 这可以被用于开采方块或者攻击实体,就像玩家点击左键一样。请注意工具和武器会像被玩家使用一样掉耐久,而且最终需要被替换掉。如果可能,开采的方块或实体的掉落物会被放进机器人的物品栏中,否则就会掉在地上。 | + | 此函数可用于开采方块或者攻击实体,就像玩家点击左键一样。请注意工具和武器会像被玩家使用一样减少耐久度,且最终需要被替换掉。如果可能,开采的方块或实体的掉落物会被放进机器人的物品栏中,否则会掉在地上。 |
- | 请注意,即使某个动作会被立刻完成(例如方块被摧毁),这个函数也会适当地等待一会来模拟一名玩家做这个操作所需的时间。如果你尝试开采黑曜石,这会很明显,因为它们立即就被破坏并且放入了机器人的物品栏中,但函数还要再等几秒。 | + | 请注意,虽然动作会立刻完成(如方块被摧毁),这个函数还是会适当地等待一会来模拟玩家操作所需的时间。如果你尝试开采黑曜石,这个现象会很明显:它们立即就被破坏并且放入机器人的物品栏中,但函数还会等待几秒。 |
- | 如果它被用于开采方块,那么装备的工具必须满足机器人面前方块的挖掘等级。举例来说,如果一把木镐被用于开采黑曜石,它会返回假。任何东西(包括空的工具栏)都能被用于战斗,但是伤害会基于使用的物品。 | + | 如果此函数被用于开采方块,那么装备的工具必须足以开采机器人面前的方块。例如,如果用木镐开采黑曜石,函数会返回`false`。任何东西(包括空槽位)都能用于与生物战斗,但是伤害会基于所使用的物品。同样所有东西都能被用来灭火,且有耐久的工具也不会减少耐久值。 |
- | 同样所有东西都能被用来熄灭火,而有耐久的工具也不会掉耐久。 | + | \\ |
- `robot.swingUp([side: number[, sneaky: boolean]]): boolean[, string]` | - `robot.swingUp([side: number[, sneaky: boolean]]): boolean[, string]` | ||
- | 和 `robot.swing()` 一样,只是这个会将头顶的方块或实体当作目标。 | + | 和`robot.swing()`一样,但此函数会将正上方的方块或实体当作目标。 |
+ | \\ | ||
- `robot.swingDown([side: number[, sneaky: boolean]]): boolean[, string]` | - `robot.swingDown([side: number[, sneaky: boolean]]): boolean[, string]` | ||
- | 和 `robot.swing()` 一样,只是这个会将脚底的方块或实体当作目标。 | + | 和`robot.swing()`一样,但此函数会将正下方的方块或实体当作目标。 |
+ | \\ | ||
- `robot.use([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]` | - `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.useUp([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]` | ||
- | 和 `robot.use()` 一样,只是这个会瞄准机器人头顶的位置。 | + | 和`robot.use()`一样,但此函数会瞄准机器人上方区域。 |
+ | \\ | ||
- `robot.useDown([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]` | - `robot.useDown([side: number[, sneaky: boolean[, duration: number]]]): boolean[, string]` | ||
- | 和 `robot.use()` 一样,只是这个会瞄准机器人脚底的位置。 | + | 和`robot.use()`一样,只是这个会瞄准机器人下方区域。 |
+ | \\ | ||
- `robot.forward(): boolean[, string]` | - `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.back(): boolean[, string]` | ||
- | 和 `robot.forward()` 一样,只是这个会让机器人尝试向后移动。 | + | 和`robot.forward()`一样,但此函数会让机器人尝试向后移动。 |
+ | \\ | ||
- `robot.up(): boolean[, string]` | - `robot.up(): boolean[, string]` | ||
- | 和 `robot.forward()` 一样,只是这个会让机器人尝试向上移动。 | + | 和`robot.forward()`一样,但此函数会让机器人尝试向上移动。 |
+ | \\ | ||
- `robot.down(): boolean[, string]` | - `robot.down(): boolean[, string]` | ||
- | 和 `robot.forward()` 一样,只是这个会让机器人尝试向下移动。 | + | 和`robot.forward()`一样,但此函数会让机器人尝试向下移动。 |
+ | \\ | ||
- `robot.turnLeft()` | - `robot.turnLeft()` | ||
- | 将机器人左转 90°。 | + | 将机器人左转90°。 |
- | 请注意,它只会在机器人没有足够能量左转但还没有关机时失败。 | + | 请注意,此函数只会在机器人没有足够能量左转但还没有关机时执行失败。 |
+ | \\ | ||
- `robot.turnRight()` | - `robot.turnRight()` | ||
- | 和 `robot.turnLeft() ` 一样,只是这个会让机器人右转 90°。 | + | 和`robot.turnLeft() `一样,但此函数会让机器人右转90°。 |
+ | \\ | ||
- `robot.turnAround` | - `robot.turnAround` | ||
- | 这和调用两次 `robot.turnRight()` 是一样的。 | + | 此函数与调用两次`robot.turnRight()`是一样的。 |
+ | \\ | ||
- <del>` robot.level(): number `</del> | - <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` | - `robot.tankCount(): number` | ||
- | 机器人安装的液体储罐数量(number)。 | + | 机器人安装的流体储罐数量。 |
+ | \\ | ||
- `robot.selectTank(tank)` | - `robot.selectTank(tank)` | ||
- | 选择指定的液体储罐。这决定了大多数操作在哪个液体储罐上进行。 | + | 选定指定的流体储罐。这决定了大多数操作在哪个流体储罐上进行。 |
+ | \\ | ||
- `robot.tankLevel([tank:number]): number` | - `robot.tankLevel([tank:number]): number` | ||
- | 返回指定液体储罐的等级,如果没有指定,则返回当前液体储罐的等级。 | + | 返回指定流体储罐的流体存量,若不指定,则返回选定流体储罐的流体存量。 |
+ | \\ | ||
- `robot.compareFluidTo(tank: number): boolean` | - `robot.compareFluidTo(tank: number): boolean` | ||
- | 测试当前选定的液体储罐中的液体与给定的液体储罐中的液体是否相同。 | + | 检查选定流体储罐中的液体与指定流体储罐中的是否相同。 |
+ | \\ | ||
- `robot.transferFluidTo(tank: number[, count: number]): boolean` | - `robot.transferFluidTo(tank: number[, count: number]): boolean` | ||
- | 从当前选定的液体储罐转移指定数量的液体到给定的液体储罐。如果不指定数量,就会尝试转移 1000 mB。 | + | 从选定流体储罐转移指定数量的流体到指定流体储罐。若不指定数量,则尝试转移1000 mB。 |
+ | \\ | ||
- `robot.compareFluid(): boolean` | - `robot.compareFluid(): boolean` | ||
- | 测试当前选定的液体储罐中的液体与机器人面前的液体储罐中的液体是否相同。 | + | 检查选定流体储罐中的流体与机器人面前世界中或流体储罐中的流体是否相同。 |
+ | \\ | ||
- `robot.compareFluidUp(): boolean` | - `robot.compareFluidUp(): boolean` | ||
- | 和 `robot.compareFluid()` 一样,只是这个会比较机器人头顶的液体储罐。 | + | 和`robot.compareFluid()`一样,但此函数作用于机器人上方的方块。 |
+ | \\ | ||
- `robot.compareFluidDown(): boolean` | - `robot.compareFluidDown(): boolean` | ||
- | 和 `robot.compareFluid()` 一样,只是这个会比较机器人脚底的液体储罐。 | + | 和`robot.compareFluid()`一样,但此函数作用于机器人下方的方块。 |
+ | \\ | ||
- `robot.drain([count: number]): boolean` | - `robot.drain([count: number]): boolean` | ||
- | 从机器人面前的液体储罐抽取指定数量的液体到选定的液体储罐中。当不指定数量时,会尝试转移 1000 mB。当抽取的液体是直接存在于世界上并且不能被完全储存于选定的液体储罐时,操作失败。没有液体会损失。 | + | 从机器人面前的世界中或流体储罐中抽取指定数量的流体。若不指定数量,会尝试转移1000 mB。若抽取的流体是直接存在于世界中,且不能被完全储存于选定流体储罐时,操作会失败,但不会损失流体。 |
+ | \\ | ||
- `robot.drainUp([count: number]): boolean` | - `robot.drainUp([count: number]): boolean` | ||
- | 和 `robot.drain()` 一样,只是这个会抽取机器人头顶的液体。 | + | 和`robot.drain()`一样,但此函数作用于机器人上方的方块。 |
+ | \\ | ||
- `robot.drainDown([count: number]): boolean` | - `robot.drainDown([count: number]): boolean` | ||
- | 和 `robot.drain()` 一样,只是这个会抽取机器人脚底的液体。 | + | 和`robot.drain()`一样,但此函数作用于机器人下方的方块。 |
+ | \\ | ||
- `robot.fill([count: number]): boolean` | - `robot.fill([count: number]): boolean` | ||
- | 从选定的液体储罐中注入指定数量的液体到机器人面前的液体储罐。当不指定数量时,会尝试转移 1000 mB。当没有足够的液体来填充一个方块。或者目标储罐没有足够的空间,操作失败。没有液体会损失。 | + | 从选定流体储罐抽取指定数量的液体,填充到机器人面前的世界或流体储罐中。若不指定数量,会尝试转移1000 mB。若没有足够流体填满一个方块,或者目标储罐空间不足,操作将会失败,但不会损失流体。 |
+ | \\ | ||
- `robot.fillUp([count: number]): boolean` | - `robot.fillUp([count: number]): boolean` | ||
- | 和 `robot.fill()` 一样,只是这个会向机器人头顶注入液体。 | + | 和`robot.fill()`一样,但此函数作用于机器人上方的方块。 |
+ | \\ | ||
- `robot.fillDown([count: number]): boolean` | - `robot.fillDown([count: number]): boolean` | ||
- | 和 `robot.fill()` 一样,只是这个会向机器人脚底注入液体。 | + | 和`robot.fill()`一样,但此函数作用于机器人下方的方块。 |
- | + | ||
- | |名词|翻译|解释| | + | |
- | |blloean|布尔值|只有真`true`和假`false`两个值| | + | |
- | |number|数字|在 Lua 中为双精度浮点数| | + | |
- | |string|字符串|OC 的中文编码有问题,请避免使用| | + | |
- | + | ||
- | ## 目录 | + | |
- | {{page>api:contents:zh&noheader&noeditbutton&nouser&nofooter}} | ||
目录 | 目录 |