---
outline: [2, 3]
---

# MiningRobot

- 源文件：`packages/sdk/src/robot/MiningRobot.ts`
- 文档位置：`packages/docs/api/robot/MiningRobot.md`

## 接口：`ICSGTargetConfig`

- 作用：CSG 目标对象配置

### 字段

| 字段名 | 类型 | 必填 | 作用 |
| --- | --- | --- | --- |
| `mesh` | `THREE.Mesh` | 是 | 目标网格对象 |
| `operationType` | `CSGOperationType` | 是 | CSG 操作类型 |
| `enabled` | `boolean` | 否 | 是否启用 |

## 接口：`IMiningRobotOptions`

- 作用：回采机器人配置

### 字段

| 字段名 | 类型 | 必填 | 作用 |
| --- | --- | --- | --- |
| `size` | `number` | 否 | 机器人尺寸 |
| `color` | `number` | 否 | 机器人颜色 |
| `widthRatio` | `number` | 否 | 主体宽度系数 |
| `heightRatio` | `number` | 否 | 主体高度系数 |
| `depthRatio` | `number` | 否 | 主体深度系数 |

## 接口：`IMiningAnimationOptions`

- 作用：挖掘动画配置

### 字段

| 字段名 | 类型 | 必填 | 作用 |
| --- | --- | --- | --- |
| `duration` | `number` | 否 | 移动持续时间（秒） |
| `csgFrequency` | `number` | 否 | CSG 执行频率系数，1.0 表示每移动切割头尺寸距离执行一次，0.5 表示每移动切割头尺寸一半距离执行一次 |
| `onComplete` | `() => void` | 否 | 完成回调 |
| `onProgress` | `(progress: number) => void` | 否 | 进度回调 |

## 类：`MiningRobot`

- 作用：回采机器人 用于模拟矿体回采过程

### 构造函数

#### `new MiningRobot(options: IMiningRobotOptions = {})`

- 作用：创建回采机器人

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `options` | `IMiningRobotOptions` | 否 | - 机器人配置选项 |

- 出参：`MiningRobot`
- 返回说明：返回当前类实例。

### 属性

| 属性名 | 可见性 | 类型 | 作用 |
| --- | --- | --- | --- |
| `group` | `public` | `THREE.Group` | 用于保存 `group` 对应的数据。 |
| `mainBody` | `public` | `THREE.Mesh` | 用于保存 `mainBody` 对应的数据。 |
| `cuttingHead` | `public` | `THREE.Mesh` | 用于保存 `cuttingHead` 对应的数据。 |
| `connector` | `public` | `THREE.Mesh` | 用于保存 `connector` 对应的数据。 |
| `frontIndicator` | `public` | `THREE.Mesh` | 用于保存 `frontIndicator` 对应的数据。 |
| `options` | `public` | `Required<IMiningRobotOptions>` | 用于保存 `options` 对应的数据。 |
| `animationId` | `public` | `number \| null` | 用于保存 `animationId` 对应的数据。 |
| `isMining` | `public` | `boolean` | 用于标记 `isMining` 的启用状态。 |

### 方法

#### `addCSGTarget(mesh: THREE.Mesh, operationType: CSGOperationType, enabled: boolean = true): void`

- 作用：添加 CSG 目标对象

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `mesh` | `THREE.Mesh` | 是 | - 目标网格对象 |
| `operationType` | `CSGOperationType` | 是 | - CSG 操作类型 |
| `enabled` | `boolean` | 否 | - 是否启用（默认为 true） |

- 出参：`void`
- 返回说明：无返回值。

#### `removeCSGTarget(mesh: THREE.Mesh): void`

- 作用：移除 CSG 目标对象

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `mesh` | `THREE.Mesh` | 是 | - 要移除的网格对象 |

- 出参：`void`
- 返回说明：无返回值。

#### `clearCSGTargets(): void`

- 作用：清空所有 CSG 目标对象

- 入参：无

- 出参：`void`
- 返回说明：无返回值。

#### `getCSGTargets(): ICSGTargetConfig[]`

- 作用：获取所有 CSG 目标对象

- 入参：无

- 出参：`ICSGTargetConfig[]`
- 返回说明：返回数组结果，元素类型为 `ICSGTargetConfig`。

#### `setCSGTargetEnabled(mesh: THREE.Mesh, enabled: boolean): void`

- 作用：设置 CSG 目标对象的启用状态

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `mesh` | `THREE.Mesh` | 是 | - 目标网格对象 |
| `enabled` | `boolean` | 是 | - 是否启用 |

- 出参：`void`
- 返回说明：无返回值。

#### `setPosition(position: THREE.Vector3): void`

- 作用：设置机器人位置

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `position` | `THREE.Vector3` | 是 | - 位置向量 |

- 出参：`void`
- 返回说明：无返回值。

#### `setDirection(direction: THREE.Vector3): void`

- 作用：设置机器人朝向

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `direction` | `THREE.Vector3` | 是 | - 方向向量 |

- 出参：`void`
- 返回说明：无返回值。

#### `updateSize(size: number): void`

- 作用：更新机器人尺寸

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `size` | `number` | 是 | - 新的基础尺寸 |

- 出参：`void`
- 返回说明：无返回值。

#### `startMining(viewer: Viewer, startPosition: THREE.Vector3, endPosition: THREE.Vector3, options: IMiningAnimationOptions = {}): void`

- 作用：开始挖掘动画

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `viewer` | `Viewer` | 是 | - Viewer 实例 |
| `startPosition` | `THREE.Vector3` | 是 | - 起始位置 |
| `endPosition` | `THREE.Vector3` | 是 | - 结束位置 |
| `options` | `IMiningAnimationOptions` | 否 | - 动画配置选项 |

- 出参：`void`
- 返回说明：无返回值。

#### `executeCSGOperation(): void`

- 作用：执行 CSG 操作

- 入参：无

- 出参：`void`
- 返回说明：无返回值。

#### `stopMining(): void`

- 作用：停止挖掘动画

- 入参：无

- 出参：`void`
- 返回说明：无返回值。

#### `getIsMining(): boolean`

- 作用：获取是否正在挖掘

- 入参：无

- 出参：`boolean`
- 返回说明：返回布尔结果。

#### `dispose(): void`

- 作用：销毁机器人资源

- 入参：无

- 出参：`void`
- 返回说明：无返回值。

## 构造示例

- 来源：`packages/demo/src/panels/GoldMineScene/DevelopmentMiningPanel.vue`

```ts
  if (miningRobot) {
    miningRobot.dispose();
  }

  miningRobot = new MiningRobot({
    size: 0.075,
    color: 0xff6600,
    widthRatio: 1.5,
    heightRatio: 1.2,
    depthRatio: 2
  });
  miningRobot.group.position.set(0, 0, -0.55);
  // 添加机器人到场景
  viewer.scene.add(miningRobot.group);
```

- 来源：`packages/demo/src/panels/GoldMineScene/ExplorationMiningPanel.vue`

```ts
  if (!viewer) return;

  const robot = new MiningRobot({
    size: 1,
    color: miningParams.value.color,
  });
```

## 函数示例

### `MiningRobot.startMining`

- 来源：`packages/demo/src/panels/GoldMineScene/ExplorationMiningPanel.vue`

```ts
  robots.push(robot);

  // 开始挖掘动画
  robot.startMining(startPosition, endPosition, rockSample, {
    speed: miningParams.value.speed,
    cutterSize: 0.5,
    cutterSegments: 16,
    csgInterval: 0.1,
    onComplete: () => {
      isMining.value = false;
      console.log('挖掘完成');
    },
    onProgress: (progress) => {
      // 可以在这里添加进度显示逻辑
    }
  });
```

### `MiningRobot.dispose`

- 来源：`packages/demo/src/panels/GoldMineScene/ExplorationMiningPanel.vue`

```ts
  if (robots.length > 0) {
    robots.forEach(robot => {
      robot.dispose();
    });
```

## Demo 参考

### `MiningRobot`

以下示例文件中可以看到该 API 的实际调用方式：

- `packages/demo/src/panels/GoldMineScene/DevelopmentMiningPanel.vue`
- `packages/demo/src/panels/GoldMineScene/ExplorationMiningPanel.vue`