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

# RockDebris

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

## 枚举：`RockDebrisModelSourceType`

- 作用：落石模型来源类型

| 枚举项 | 值 | 说明 |
| --- | --- | --- |
| `GENERATED` | `"GENERATED"` | 使用程序内置的几何体生成落石 |
| `URL` | `"URL"` | 使用传入 URL 的模型生成落石 |

## 接口：`RockDebrisOptions`

- 作用：RockDebrisOptions 的结构定义。

### 字段

| 字段名 | 类型 | 必填 | 作用 |
| --- | --- | --- | --- |
| `count` | `number` | 否 | 生成数量 |
| `size` | `[number, number]` | 是 | 随机大小范围 [min, max] |
| `office` | `[number, number]` | 是 | XZ 平面随机偏移范围 [min, max] |
| `speed` | `number` | 是 | 掉落速度 (units/s) |
| `startPosition` | `THREE.Vector3` | 是 | 开始位置 |
| `mesh` | `THREE.Mesh` | 是 | 碰撞 mesh |
| `modelSourceType` | `RockDebrisModelSourceType` | 否 | URL 模型来源类型 |
| `modelUrls` | `string[]` | 否 | URL 模型地址列表 |

## 类：`RockDebris`

- 作用：岩爆碎片效果

### 构造函数

#### `new RockDebris(options: RockDebrisOptions)`

- 作用：创建 RockDebris 实例。

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `options` | `RockDebrisOptions` | 是 | 当前功能对应的配置项。 |

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

### 属性

| 属性名 | 可见性 | 类型 | 作用 |
| --- | --- | --- | --- |
| `options` | `public` | `Required<RockDebrisOptions>` | 用于保存 `options` 对应的数据。 |
| `rocks` | `public` | `RockData[]` | 用于保存 `rocks` 的集合数据。 |
| `active` | `public` | `boolean` | ------ 落石URL模型支持 结束------ |
| `updateBound` | `public` | `((data: RenderEventData) => void) \| null` | 用于保存 `updateBound` 对应的数据。 |
| `_matrix` | `public readonly` | `THREE.Matrix4` | 用于保存 `_matrix` 对应的数据。 |
| `_raycaster` | `public readonly` | `THREE.Raycaster` | 用于保存 `_raycaster` 对应的数据。 |
| `_rayDirection` | `public readonly` | `THREE.Vector3` | 用于保存 `_rayDirection` 对应的数据。 |
| `SPAWN_MAX_RETRY` | `public readonly` | `20` | 单个落石生成点的最大重采样次数，防止射线检测陷入无限循环 |
| `SPAWN_MIN_RAY_DISTANCE` | `public readonly` | `0.05` | 判定“靠墙”时的最小射线距离下限 |
| `FALL_LIMIT` | `public readonly` | `50` | 超出起始点以下多少距离视为未命中，直接回收 |

### 方法

#### `spawn(): Promise<void>`

- 作用：执行 spawn 相关逻辑。

- 入参：无

- 出参：`Promise<void>`
- 返回说明：返回 Promise，解析结果类型为 `void`。

#### `start(): void`

- 作用：------ 落石落点射线重采样优化 结束------

- 入参：无

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

#### `stop(): void`

- 作用：执行 stop 相关逻辑。

- 入参：无

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

#### `update(data: RenderEventData): void`

- 作用：更新 update。

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `RenderEventData` | 是 | 输入数据。 |

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

#### `clear(): void`

- 作用：清理 clear。

- 入参：无

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

#### `dispose(): void`

- 作用：释放资源并销毁当前实例。

- 入参：无

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

#### `init(): void`

- 作用：执行 init 初始化逻辑。

- 入参：无

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

## 构造示例

- 来源：`packages/demo/src/disasterFormationPanel/TunnelScene/RockBurstPanel.vue`

```ts
  if (!archMesh){
    return;
  }
  debris = new RockDebris({
    count: 10,
    size: [0.05, 0.1],
    office: [-0.3, 0.3],
    speed: 3,
    startPosition: ROCK_BURST_START_POSITION.clone(),
    mesh: archMesh,
    // modelSourceType: RockDebrisModelSourceType.URL,
    modelSourceType: RockDebrisModelSourceType.GENERATED
  });
  debrisReady.value = true;
}
```

## 函数示例

### `RockDebris.spawn`

- 来源：`packages/demo/src/disasterFormationPanel/TunnelScene/RockBurstPanel.vue`

```ts
const spawn = () => {
  ensureDebris();
  ensureRockBurstLabel();
  debris?.spawn();
};
```

## Demo 参考

### `RockDebrisModelSourceType`

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

- `packages/demo/src/disasterFormationPanel/TunnelScene/RockBurstPanel.vue`

### `RockDebris`

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

- `packages/demo/src/disasterFormationPanel/TunnelScene/RockBurstPanel.vue`