Differences

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

--- component:agent:zh [2023/11/26 16:43]
hfsr [机器人组件API]
+++ component:agent:zh [2023/11/30 09:01] (current)
hfsr
@@ Line 1: / Line 1: @@
-====物品栏控制器API====
+====物品栏控制器特性API====
 - `inventorySize():number`
@@ Line 19: / Line 19: @@
   将指定数量的物品从当前选定槽位中移动到指定槽位。如果未指定数量，则移动整个物品堆。
-====WorldControl Trait API====
+====世界控制特性API====
 - `detect(side:number):boolean`
-  检测给定面相对于机器人的方块，并返回机器人是否可以移动到方块中，以及方块的描述。如果方块会阻挡机器人向前移动，则返回 true，否则返回 false。即使该方块是可通过的，机器人也会返回true。
+  检测相对机器人的给定方向处的方块，并返回机器人是否可以移动到该方块中，以及方块的大致描述。若方块会阻挡机器人向前移动，则返回`true`，否则返回`false`。无人机即使在方块为可穿越（passable）时也会返回`true`。
+**side** - 请参阅[[api:sides:zh|sides(方向) API]]以获取可能的方向列表。
- **side** - 请参阅 [[api:sides:zh|sides API]] 以获取可能的面列表。
+====世界储罐控制器特性API====
-====TankWorldControl Trait API====
+- `compareFluid(side:number):boolean`
+  将当前选定储罐（需要[[item:tank_upgrade:zh|储罐升级]]）中的流体与机器人指定方向处世界中或外部储罐中的流体进行比较。
-- `compareFluid(side:number):boolean`
+\\
-  将选定储罐中的液体（需要 [[item:tank_upgrade:zh|储罐升级]]）与世界上的流体或机器人指定一侧的外部储罐中的流体进行比较。
 - `drain(side:number[, count:number]):boolean`
-  令机器人通过指定面在世界或储罐中提取一定数量的流体。如果未指定数量，机器人将尝试提取 1000mB。如果储罐无法存储指定数量的流体，则操作将会执行失败（该过程不会损失流体）。
+  令机器人从指定方向抽取在世界中或储罐中的一定数量流体。若未指定数量，机器人将尝试抽取1000mB。若储罐无法存储指定数量的流体，则操作将失败（该过程不会损失流体）。
 - `fill(side:number[, count:number]):boolean`
-  从选定的储罐（需要 [[item:tank_upgrade:zh|储罐升级]]）中将指定量的流体填充到世界或机器人前面的储罐中。如果未指定数量，机器人将尝试用 1000mB 的液体填充目标储罐。如果没有足够的流体来填充方块或者目标储罐没有足够的空间，则该操作将执行失败且流体不会损失。
+  从当前选定储罐（需要[[item:tank_upgrade:zh|储罐升级]]）中抽取指定量流体，向指定方向填充到世界中或储罐中。若未指定数量，机器人将尝试用1000mB 的液体填充目标储罐。若没有足够的流体来填充方块或者目标储罐没有足够的空间，则操作将失败，且流体不会损失。
-====Agent Trait API====
+====硬件实体特性API====
 - `name():string`
   获取机器人的名称。
+\\
 - `swing(side:number):boolean[, string]`
-  让机器人使用当前自身工具栏装备的物品来与与正前方的方块、空气（空间）交互。如果成功则返回 `true`（可能需要时间，具体时间取决于与其交互的方块——例如黑曜石需要一些时间来挖掘）。如果执行失败则返回 `false` 同时返回失败的原因。
+  让机器人使用当前工具槽位装备的物品与正前方的方块或空间交互。如果成功则返回 `true`（可能需要时间，具取决于与其交互的方块，例如黑曜石需要一些时间来挖掘）。如果执行失败则返回`false`以及失败原因。
+\\
 - `use(side: number[, sneaky: boolean[, duration: number]]): boolean[, string]`
-  尝试以玩家相同的方式：右键（单击）来使用当前装备在工具栏中的物品。
+  尝试以与玩家右键单击相同的方式使用当前装备在工具槽位的物品。
-**side** - 如果指定该值，则机器人尝试仅在指定面上单击右键，否则机器人会尝试所有面，请查阅 [[api:sides:zh|Sides API]] 以获取可能的面列表。
+**side** - 若给定，则机器人仅尝试在指定面上“右键单击”，否则机器人会尝试所有可能的面。请查阅[[api:sides:zh|sides(方向) API]]以获取可能的方向列表。
-**sneaky** - 如果设置为true，机器人将会模拟玩家的“潜行右击”。如果设置为true，则某些物品（例如桶）的行为会有所不同。
+**sneaky** - 若设置为true，机器人将会模拟玩家的潜行右键单击（如同玩家在右键单击时按住shift键一样）。若设置为true，某些物品（例如桶）的行为会有所不同。
-**duration** - 使用该物品的时间。这在使用弓等持续使用物品时很有用。
+**duration** - 使用该物品的时间。这在使用弓等需要蓄力的物品时很有用。
-**返回值：**如果机器人可以与它前面的方块交互，则返回 `true`，否则返回 `false`。如果成功，第二个参数将会描述机器人与之交互的内容，并且将是 `block_activated`、`item_placed`、`item_used`、`item_interacted`、`air` 之一。
+**返回值：**若机器人可以与其前面的方块或实体交互，则返回 `true`，否则返回 `false`。若成功，会有第二个返回值，代表机器人交互的内容，可能取值为下列之一：`block_activated`（激活方块）、`item_placed`（放置物品）、`item_used`（使用物品）、`item_interacted`（与物品互动）、`air`（空气）。
-此函数用途非常广泛，因为机器人可以模拟大多数物品的单击右键。与玩家的唯一区别是机器人不能使用特别要求用户是实体的物品，因为机器人是一个方块。所以喝药水、吃食物或扔末影珍珠都会失败。
+此函数用途非常广泛，因为机器人可以模拟右键单击大多数物品。在这方面机器人与玩家的唯一区别是机器人不能使用明确要求用户是实体的物品，因为机器人是方块。所以喝药水、吃食物或扔末影珍珠都会失败。
-这个函数的次要返回值可以用来判断右键单击的结果是什么造成的。返回项目结果并不总是很明显，需要事先进行一些测试。另请注意，虽然机器人不受有害药水的影响，但它们可能会被爆炸摧毁，因此在使用此功能放置、投掷或激活任何形式的炸药时要小心。第二个返回值的可能值：
+此函数的第二个返回值可用来判断右键单击的结果。有时候不一定能明显看出一个物品会返回哪个值，因此需要事先测试。还需注意，虽然机器人不受有害药水的影响，但它们可能会被爆炸摧毁，因此在使用此函数放置、投掷或激活任何形式的炸药时要小心。
-  - `block_activated` - 一个被激活的方块（例如拉杆、开关、门）
+第二个返回值的可能值有：
-  - `item_interacted` - 用装备的工具与世界互动，例如在羊上使用剪刀。
+  - `block_activated` - 某个方块被激活（例如拉杆、开关以及门）
-  - `item_placed` - 某个东西被放置在世界中。这不仅仅是有可放置的方块引起的，但也可以通过方块或实体出现在世界中的物品（例如燧石或刷怪蛋）。
+  - `item_interacted` - 装备的工具与世界进行了互动，例如在羊身上使用剪刀。
-  - `item_used` - 装备物品被激活，如同喷溅药水一样。
+  - `item_placed` - 某个物品被放置到了世界中。此返回值不一定由可放置的方块触发，其他会导致方块或实体出现在世界上的物品也会触发（例如燧石或刷怪蛋）。
-  - `air` - 当前装备的物品（包括空手）需要对着一个目标物体才能使用。请注意如果你的机器人有天使方块升级，这个值将永远不会被返回，但是一些操作可能仍然无效果。
+  - `item_used` - 装备的物品被激活，例如喷溅式药水。
+  - `air` - 当前装备的物品需要目标才能使用，但并不存在。请注意如果你的机器人有天使升级，此返回值将永远不会出现，但一些操作可能仍然无效果。
+\\
 - `place(side: number[, sneaky: boolean]): boolean[, string]`
-  尝试将物品栏中已选定格子的方块放置在指定面（如果支持这面）如果 `sneaky` 设置为`true`，那么机器人将会模拟潜行放置（Shift+点击）。如果成功放置，则返回 `true`。
+  尝试将物品栏中前选定槽位中的方块放置在机器人的指定方向（若支持此方向）。若`sneaky`设置为`true`，那么机器人将会模拟潜行放置（按住shift点击）。若成功放置则返回 `true`，若操作失败则返回 `false`。若使用不支持的值作为参数，则操作将会失败，并返回失败原因。
-如果操作执行失败，则返回 `false`。如果使用一个不被支持的值作为参数，则操作将会执行失败并说明失败的原因。
+\\
 - `getLightColor():number`
-  获取襟翼或状态活动灯的颜色，并用整数编码 RGB 值（0xRRGGBB）形式表示。
+  获取当前活动指示灯（机器人）或机翼灯（无人机）设定的颜色，形式为整数编码RGB值（0xRRGGBB）。
+\\
 - `setLightColor(value:number):number`
-  将活动或襟翼灯的颜色设置为指定的整数编码 RGB 值 (0xRRGGBB)。
+  将活动指示灯（机器人）或机翼灯（无人机）的颜色设定为给定的整数编码RGB值（0xRRGGBB）。
-====TankControl Trait API====
+====储罐控制器特性API====
 - `tankCount():number`
-  返回机器人中安装的储罐升级数量。
+  返回机器人中安装的储罐数量。
+\\
 - `selectTank(tank:number)`
-  选择指定的储罐（如果机器人包含多个 [[item:tank_upgrade:zh|储罐升级]]）。任何储罐运行时都会使用这个储罐。
+  选定指定储罐（如果机器人包含多个[[item:tank_upgrade:zh|储罐升级]]）。任何储罐操作都会使用这个储罐。
+\\
 - `tankLevel([tank:number]):number`
-  返回指定储罐中的液位。如果未指定储罐，则返回选定储罐中的液位（使用 `selectTank()`）。
+  返回指定储罐中的流体存量。若未指定储罐，则返回当前选定储罐（使用 `selectTank()`）中的流体存量。
+\\
 - `tankSpace([tank:number]):number`
-  返回指定储罐中的剩余液体容量（剩余空间）。如果未指定储罐，则返回选定储罐中的剩余容量。
+  返回指定储罐中的剩余流体容量（剩余空间）。若未指定储罐，则返回当前选定储罐的剩余容量。
+\\
 - `compareFluidTo(tank:number):boolean`
-  测试所选储罐（机器人存储空间）是否与指定储罐中的流体相同（需要 [[item:tank_upgrade:zh|储罐升级]]）。
+  检查（机器人物品栏）当前选定槽位中储罐所存流体是否与指定储罐中的相同（需要[[item:tank_upgrade:zh|储罐升级]]）。
+\\
 - `transferFluidTo(tank:number[, count:number]):boolean`
-  将选定储罐中的指定量流体转移到指定储罐。如果未指定储罐，机器人将尝试传输 1000mB。
+  从当前选定储罐中转移指定量流体到指定储罐。若未指定转移量，机器人将尝试传输 1000mB。
-====InventoryWorldController trait API====
+====世界物品栏控制器特性API====
 - `compare(side:number[, fuzzy:boolean=false]):boolean`
-  将机器人指定侧的方块与当前选择的格子中的物品进行比较，并返回它们是否相同。如果二者元数据匹配，则认为方块（物品）相同；不检查其他 ItemStack 信息。空气被视为空气方块，不能与物品栏中的空格子进行比较；`detect()` 函数可用于确定机器人前面是否有块。
+  将机器人指定方向处的方块与当前选定槽位中的物品进行比较，返回它们是否相同。方块相同的条件是类型和元数据相同，不检查额外物品堆信息。空方块被视为空气方块，不能与物品栏的空槽位进行比较。`detect()` 函数可用于确定机器人前面是否有方块。
-对于掉落不同物品的方块，`compare()` 方法将不能工作（例如：钻石矿石掉落钻石）；对于这些情况，请使用精准采集来获取方块进行比较。
+对于掉落不同物品而非本身的方块，`compare()`方法不起作用（例如：钻石矿石掉落钻石物品）；对这种情况，请使用精准采集获取原方块进行比较。
+\\
 - `drop(side:number[, count:number]):boolean`
-  从当前选定的物品栏格子中丢弃指定数量的物品。如果丢弃了至少一个物品，则返回 `true`，否则返回 `false`。如果机器人前面的方块是容器，机器人会尝试把物品放入容器中。
+  从物品栏的当前选定槽位中提取并丢弃指定数量的物品。若丢弃了至少一个物品，则返回 `true`，否则返回 `false`。若机器人前面的方块为物品容器，机器人会尝试把物品放入容器中。
-如果该容器不能接收该物品，则该物品不会被丢弃在世界中（操作将会执行失败并返回 `false`）。机器人本身被视为容器（方块），并且可以使用 `drop()` 函数将物品移入其中。`drop()` 函数不适用非物品容器，例如流体储罐（`use()` 函数适用于这些情况）。
+若该容器不能接收该物品，物品**不会**被丢弃在世界中（操作将会执行失败并返回 `false`）。机器人本身被视为带物品栏的方块，并且可以使用`drop()`函数将物品移入其中。`drop()` 函数不适用非物品容器，例如流体储罐（`use()` 函数适用于这些情况）。
+\\
 - `suck(side:number[, count:number]):boolean`
-  尝试拾取指定数量的物品并将其置于选定的格子中。如果选定的格子被占用，则物品将被置于第一个可用格子中。会返回拾取的物品数量，否则返回 `false`。
+  尝试拾取指定数量的物品并将其置于当前选定槽位中。若当前选定槽位被占用，则物品将被置于第一个可用槽位中。返回值为拾取的物品数量，其他情况返回`false`。
 ====机器人组件API====
@@ Line 97: / Line 109: @@
 \\
 - `turn(clockwise:boolean):boolean`
   向指定方向旋转。
-====Drone Component API====
+====无人机组件API====
 - `getStatusText():string`
-  获取当前在 GUI 中显示的状态文字（文本）。
+  获取当前在GUI中显示的状态文本。
+\\
 - `setStatusText(value:string):string`
-  设置在 GUI 显示的状态文字（文本），并返回一个新的值。
+  设置在GUI中显示的状态文本，返回新设定的值。
+\\
 - `move(dx:number, dy:number, dz:number)`
-  通过指定的位移量移动到目标位置。
+  以给定偏移量修改目标位置。
+\\
 - `getOffset():number`
-  获取到当前目标位置的距离。
+  获取当前到目标位置的距离。
+\\
 - `getVelocity():number`
-  获取目标的当前速度。（单位：m/s)
+  获取当前速度，单位m/s。
+\\
 - `getMaxVelocity():number`
-  获取到目标的最大速度。（单位：m/s)
+  获取最大速度，单位m/s。
+\\
 - `getAcceleration():number`
-  获取到当前设置的加速度。
+  获取当前设置的加速度。
+\\
 - `setAcceleration(value:number):number`
-  尝试把加速设置到指定值并返回新的加速度的值。
+  尝试将加速度设置为给定值，返回新的加速度值。