Differences

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

--- api:robot:zh [2023/11/30 08:27]
hfsr [悬停]
+++ api:robot:zh [2023/11/30 08:58] (current)
hfsr [API 特有方法]
@@ Line 52: / Line 52: @@
 - `robot.name(): string`
 返回机器人的名字。
-机器人的名字在它被创造时会自动赋予，并且不能通过程序修改。但如果你想，可以用铁砧修改。
+机器人的名字在它被创造时会自动设定，且不能通过程序修改。但如果你想，可以用铁砧修改。
 \\
 - `robot.detect(): boolean, string`
-探测机器人正前方的物体并且返回机器人是否能移动过去，同时返回面前物体的描述。
+探测机器人正前方的物体，并且返回机器人是否能移动过去，同时返回面前物体的描述。
-**返回值：**若机器人面前的物体会阻碍其移动（方块或者实体）则返回 `true`，否则返回 `false`（注意：即使面前的方块为`passable`，代表可穿越，无人机也会返回`true`）。第二个返回值大体描述前面的物体是什么，可能取值为；`entity`、`solid`、`replaceable`、`liquid`、`passable`或者`air`。
+**返回值：**若机器人面前的物体会阻碍其移动（方块或者实体）则返回 `true`，否则返回 `false`（注意：即使面前的方块为`passable`，代表可穿越，无人机也会返回`true`）。第二个返回值大体描述了前面的物体是什么，可能取值为；`entity`、`solid`、`replaceable`、`liquid`、`passable`或者`air`。
 \\
 - `robot.detectUp(): boolean, string`
-和`robot.detect()`一样，但此函数探测机器人正上方的物体。
+和`robot.detect()`一样，但此函数探测机器人正上方的方块。
 \\
 - `robot.detectDown(): boolean, string`
-和`robot.detect()`一样，但此函数探测机器人正下方的物体。
+和`robot.detect()`一样，但此函数探测机器人正下方的方块。
 \\
 - `robot.select([slot: number]): number`
-选定给定物品栏槽位（若指定），并返回当前选定物品栏槽位。
+选定给定的物品栏槽位（若指定），并返回物品栏当前的选定槽位。
 **slot** - 要选定的物品栏槽位。若此参数省略，那么不会改动当前选定槽位。
-**返回值：**当前选定物品栏槽位。可能是给定物品栏槽位（若选择成功）或先前选定的物品栏槽位。
+**返回值：**物品栏当前的选定槽位。可能为给定的物品栏槽位（若选择成功）或先前选定的物品栏槽位。
 \\
 - `robot.inventorySize(): number`
@@ Line 73: / Line 73: @@
 \\
 - `robot.count([slot: number]): number`
-返回物品栏当前选定槽位或指定槽位里面物品栏的个数。
+返回物品栏的指定槽位或选定槽位中的物品个数。
 **slot** - 指定要获取物品数的槽位。若省略则会对当前选定槽位的物品计数。
 **返回值：**指定槽位中物品的数量，或当前选定槽位中物品的数量（若没有指定槽位）。
@@ Line 81: / Line 81: @@
 **slot** - 指定要计算物品数的槽位。若省略则计算当前选定槽位。
 **返回值：**给定槽位或当前选定槽位在装满前还能装入多少物品。
-此函数还能判断某种物品在单个槽位中的堆叠上限。例如圆石在每个槽位中能放64个，但是空桶在每个槽位中只能放16个，而有些方块，比如门，在每个槽位中只能放一个。
+此函数还有助于判断某种物品在单个槽位中的堆叠上限。例如圆石在每个槽位中能放64个，但是空桶在每个槽位中只能放16个，而有些方块，比如门，在每个槽位中只能放一个。
 \\
 - `robot.transferTo(slot: number[, count: number]): boolean`
@@ Line 88: / Line 88: @@
 **count** - 若指定此参数，则最多移动此参数个物品，否则移动整个物品堆。
 **返回值：**若成功交换两个槽位中的物品则返回`true`，否则返回 `false`。
-若指定槽位中有物品，此函数会尝试交换两个槽位中的物品。只有将当前选定槽位中的所有物品都移走或当前选中槽位本来就是空的才会成功。
+若指定槽位中有物品，此函数会尝试交换两个槽位中的物品。只有将选定槽位中的所有物品都移走，或以其他任意方式清空选定槽位，交换才会成功。
-注意，若两个槽位中的物品相同或者两个格子都是空的，返回值一定是`true`，即使实际上没有移动任何东西。
+注意，若两个槽位中的物品相同，或者两个槽位都是空的，返回值一定是`true`，即使实际上没有移动任何东西。
 \\
 - `robot.compareTo(slot: number):boolean`
-比较物品栏当前选定槽位中的方块与给定槽位中的是否相同。
+比较物品栏当前选定槽位中的物品与给定槽位中的是否相同。
 **slot** - 指定要与当前选定槽位比较的槽位。
 **返回值：**若两个槽位中的物品种类相同则返回`true`，否则返回`false`。
@@ Line 99: / Line 99: @@
 - `robot.compare(slot: number):boolean`
 比较机器人正前方的方块与物品栏当前选定槽位中的方块，并返回它们是否相同。
-若两个方块的种类和元数据相同，那么它们就被认定为“相同”。物品堆大小（物品数量）或其它额外信息（例如容器的物品栏）不会检查。
+若两个方块的类型和元数据相同，那么它们就被认定为“相同”。物品堆大小（物品数量）或其它额外信息（例如容器的物品栏）不会检查。
 请注意，机器人前方如果是空的则会被游戏认为是“空气方块”，这种方块不能被放进物品栏，因此也不能使用一般方法比较。物品栏的空槽位与空气方块**不同**。你可以先使用`robot.detect()`来确认机器人前方是否真的有方块。
-还请记住，会掉落其它物品的方块应当和真正出现在世界上的方块比较（而非掉落物）。例如，石头方块掉落圆石，钻石矿石掉落钻石，对于这个函数来说它们并不相同。需要使用精准采集的工具开采实际的方块用于比较。
+还请记住，会掉落其它物品的方块应当和真正出现在世界上的方块比较（而非掉落物）。例如，石头方块会以圆石形式掉落，钻石矿石掉落钻石物品。对于这个函数来说它们并不相同。需要使用精准采集的工具开采实际的方块用于比较。
 \\
 - `robot.compareUp(): boolean`
@@ Line 112: / Line 112: @@
 尝试从内部物品栏的当前选定槽位提取物品，并丢弃在机器人**前方**。注意，此方法不可用于将物品丢入机器人下方的物品容器，这种情况下需要使用`dropDown`方法。 此方法会将物品丢在**面前**。
 **count** - 指定丢出多少物品。若省略此参数或其值超过了物品的数量，则所有物品都会被丢出。
-**返回值：**若至少丢除了一个物品则返回`true`，否则返回`false`。
+**返回值：**若至少丢出了一个物品则返回`true`，否则返回`false`。
-如果机器人正前方的实体或方块有可访问的物品栏（例如箱子或运输矿车），机器人会尝试将物品放进物品栏中而不是丢弃到世界中。若面前的方块的确有物品栏，但是因为某种原因物品无法被放入其中，则此函数返回`false`且不会移动任何物品。物品被放置的位置取决于物品容器自身，以及机器人面对容器的哪个面。例如，熔炉从上方接收待烧炼物品。还请注意，其它机器人也会被认为是“带物品栏的方块”，所以物品也能被移入其它机器人的物品栏槽位，就像移入别的物品容器一样。
+若机器人正前方的实体或方块有可访问的物品栏（例如箱子或运输矿车），机器人会尝试将物品放进物品栏中而不是丢弃到世界中。若面前的方块的确有物品栏，但是因为某种原因物品无法被放入其中，则此函数返回`false`，且不会移动任何物品。物品被放置的位置取决于物品容器自身，以及机器人面对容器的哪个面。例如，熔炉从上方接收待烧炼物品。还请注意，其它机器人也会被认为是“带物品栏的方块”，所以物品也能被移入其它机器人的物品栏槽位，就像移入别的物品容器一样。
-此函数不能与非物品类型的容器互动（例如液体储罐），也不会将它们当作物品容器，因此物品会被扔到世界中。你需要使用`robot.use`函数与这些种类的方块互动。
+此函数不能与非物品类型的容器互动（例如流体储罐），也不会将它们当作物品容器，因此物品会被扔到世界中。你需要使用`robot.use`函数与这些种类的方块互动。
 请注意若物品栏的当前选定槽位是空的，那么返回值一定为`false`。
 \\
@@ Line 124: / Line 124: @@
 \\
 - `robot.suck([count: number]): boolean`
-尝试从正前方拾起掉落物，并将其放入指定物品栏槽位或者（若槽位被占用）第一个可用的物品栏槽位。
+尝试从正前方拾起掉落物，并将其放入物品栏的选定槽位或者（若槽位被占用）第一个可用的槽位。
 **count** - 拾起掉落物的数量上限。若省略，则会捡起最多一个物品堆。
 **返回值：**若捡起了至少一个物品则返回`true`，否则返回`false`。
@@ Line 139: / Line 139: @@
 - `robot.place([side: number[, sneaky: boolean]]): boolean[, string]`
 尝试将物品栏选定槽位中的方块放置在机器人面前。
-**side** - 若指定，此参数决定机器人会尝试将方块放到哪个方向。例如，将火把放在特定表面上。若省略，机器人会尝试所有可能的方向。参见[sides(方向) API](api:sides:zh)以获取可能的方向列表。
+**side** - 若指定，此参数决定机器人会尝试将方块放到哪个面上。例如，可用于将火把放在特定表面上。若省略，机器人会尝试所有可能的方向。参见[sides(方向) API](api:sides:zh)以获取可能的方向列表。
 **sneaky** - 若设置为 `true`，机器人会模拟潜行放置方块（和玩家在放置时按住shift的效果相同）。这种操作通常没有必要，只是为了保证和其它模组的兼容性。
 **返回值：**若物品可以放置则返回 `true`，否则返回 `false`。若放置失败，第二个返回值会描述失败原因。
@@ Line 153: / Line 153: @@
 - `robot.durability(): number, number, number or nil, string`
 返回工具槽位中物品的耐久度剩余比例（小数）、当前耐久、最大耐久。
-若未装备物品或物品没有耐久值，此函数会返回`nil`以及一条描述为何不能返回耐久值的信息。报错信息可能为：`no tool equipped`（未装备物品）或`tool cannot be damaged`（物品不会损坏）。
+若未装备物品或物品没有耐久值，此函数会返回`nil`以及一条描述为何不能返回耐久值的信息。报错信息可能为：`no tool equipped`（未装备工具）或`tool cannot be damaged`（工具不会损坏）。
 \\
 - `robot.swing([side: number[, sneaky: boolean]]): boolean[, string]`
@@ Line 174: / Line 174: @@
 **sneaky** - 若设置为 `true`，机器人会模拟潜行右键单击（如同玩家按住shift时点击右键）。某些物品（例如桶）在这时会有不同的行为。
 **duration** - 物品被使用多长时间。这在使用例如弓之类的蓄力物品时很有用。
-**返回值：**若机器人可以和它面前的方块或实体互动返回`true`，否则返回`false`。如果执行成功，第二个返回值表示机器人和什么东西互动了，可能的取值为下列之一：`block_activated`（激活方块）、`item_placed`（放置物品）、`item_interacted`（与物品互动）、`item_used`（使用物品）。
+**返回值：**若机器人可以和它面前的方块或实体互动返回`true`，否则返回`false`。若执行成功，第二个返回值表示机器人互动的对象是什么，可能的取值为下列之一：`block_activated`（激活方块）、`item_placed`（放置物品）、`item_interacted`（与物品互动）、`item_used`（使用物品）。
 此函数用途非常广泛，因为机器人可以模拟右键单击大多数物品。在这方面机器人与玩家的唯一区别是机器人不能使用明确要求用户是实体的物品，因为机器人是方块。所以喝药水、吃食物或扔末影珍珠都会失败。
  此函数的第二个返回值可用以判断右键单击的结果。有时候不一定能明显看出一个物品会返回哪个值，因此需要事先测试。还需注意，虽然机器人不受有害药水的影响，但它们可能会被爆炸摧毁，因此在使用此函数放置、投掷或激活任何形式的炸药时要小心。