deep-engine-demo/packages/docs/api/effect/FractureEffect.md

outline
2 3

FractureEffect

• 源文件：packages/sdk/src/effect/FractureEffect.ts
• 文档位置：packages/docs/api/effect/FractureEffect.md

接口：FractureEffectOptions

• 作用：FractureEffectOptions 的结构定义。

字段

字段名	类型	必填	作用
points	THREE.Vector3[]	是	用于保存 points 的集合数据。
curveType	'catmullrom' | 'linear'	否	用于保存 curveType 对应的数据。
tension	number	否	用于保存 tension 对应的数据。
closed	boolean	否	用于标记 closed 的启用状态。
spacing	number	否	用于保存 spacing 对应的数据。
bufferRatio	number	否	用于保存 bufferRatio 对应的数据。
minRadius	number	否	用于保存 minRadius 对应的数据。
maxRadius	number	否	用于保存 maxRadius 对应的数据。
animationDuration	number	否	用于保存 animationDuration 对应的数据。
sphereAnimDuration	number	否	用于保存 sphereAnimDuration 对应的数据。
sphereOpacity	number	否	用于保存 sphereOpacity 对应的数据。
spheresVisible	boolean	否	用于标记 spheresVisible 的启用状态。
cracksVisible	boolean	否	用于标记 cracksVisible 的启用状态。
colorMode	'random' | 'gradient' | 'fixed'	否	用于保存 colorMode 对应的数据。
fixedColor	number	否	用于保存 fixedColor 对应的数据。
gradientStart	number	否	用于保存 gradientStart 对应的数据。
gradientEnd	number	否	用于保存 gradientEnd 对应的数据。
autoStart	boolean	否	用于标记 autoStart 的启用状态。
crackModelUrls	string[]	否	用于保存 crackModelUrls 的集合数据。

类：FractureEffect

• 作用：压裂效果 沿着一组点生成的曲线生成一系列带弹性动画的球体，模拟压裂过程

构造函数

new FractureEffect(options: FractureEffectOptions)

• 作用：创建 FractureEffect 实例。

• 入参：

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

• 出参：FractureEffect
• 返回说明：返回当前类实例。

属性

属性名	可见性	类型	作用
options	public	Required<FractureEffectOptions>	用于保存 options 对应的数据。
active	public	boolean	用于标记 active 的启用状态。
running	public	boolean	用于标记 running 的启用状态。
spheres	public	FractureSphere[]	用于保存 spheres 的集合数据。
group	public	THREE.Group	用于保存 group 对应的数据。
crackModels	public	THREE.Object3D[]	用于保存 crackModels 的集合数据。
crackModelTemplates	public	THREE.Object3D[]	用于保存 crackModelTemplates 的集合数据。
progressCallback	public	((progress: number) => void) | null	用于保存 progressCallback 对应的数据。
curve	public	THREE.Curve<THREE.Vector3> | null	用于保存 curve 对应的数据。

方法

createCurve(): void

• 作用：根据点数组创建曲线

• 入参：无

• 出参：void

• 返回说明：无返回值。

onProgress(callback: (progress: number) => void): void

• 作用：设置进度回调

• 入参：

参数名	类型	必填	说明
callback	(progress: number) => void	是	回调函数。

• 出参：void
• 返回说明：无返回值。

start(): Promise<void>

• 作用：开始压裂动画

• 入参：无

• 出参：Promise<void>

• 返回说明：返回 Promise，解析结果类型为 void。

stop(): void

• 作用：停止动画

• 入参：无

• 出参：void

• 返回说明：无返回值。

clear(): void

• 作用：清除所有球体和裂缝模型

• 入参：无

• 出参：void

• 返回说明：无返回值。

showCracks(): void

• 作用：显示裂缝模型

• 入参：无

• 出参：void

• 返回说明：无返回值。

hideCracks(): void

• 作用：隐藏裂缝模型

• 入参：无

• 出参：void

• 返回说明：无返回值。

toggleCracks(): void

• 作用：切换裂缝模型显示

• 入参：无

• 出参：void

• 返回说明：无返回值。

showSpheres(): void

• 作用：显示球体

• 入参：无

• 出参：void

• 返回说明：无返回值。

hideSpheres(): void

• 作用：隐藏球体

• 入参：无

• 出参：void

• 返回说明：无返回值。

toggleSpheres(): void

• 作用：切换球体显示

• 入参：无

• 出参：void

• 返回说明：无返回值。

setOpacity(opacity: number): void

• 作用：设置球体透明度

• 入参：

参数名	类型	必填	说明
opacity	number	是	参数 opacity，类型为 number。

• 出参：void
• 返回说明：无返回值。

updatePoints(points: THREE.Vector3[]): void

• 作用：更新点数组

• 入参：

参数名	类型	必填	说明
points	THREE.Vector3[]	是	参数 points，类型为 THREE.Vector3[]。

• 出参：void
• 返回说明：无返回值。

restart(): Promise<void>

• 作用：重新开始

• 入参：无

• 出参：Promise<void>

• 返回说明：返回 Promise，解析结果类型为 void。

getSphereCount(): number

• 作用：获取球体数量

• 入参：无

• 出参：number

• 返回说明：返回数值结果。

getSpheres(): FractureSphere[]

• 作用：获取球体列表

• 入参：无

• 出参：FractureSphere[]

• 返回说明：返回数组结果，元素类型为 FractureSphere。

dispose(): void

• 作用：销毁

• 入参：无

• 出参：void

• 返回说明：无返回值。

loadCrackModels(): Promise<void>

• 作用：加载裂缝模型模板

• 入参：无

• 出参：Promise<void>

• 返回说明：返回 Promise，解析结果类型为 void。

getRandomHighContrastColor(): THREE.Color

• 作用：生成高对比度随机颜色

• 入参：无

• 出参：THREE.Color

• 返回说明：返回 THREE.Color。

getGradientColor(t: number): THREE.Color

• 作用：根据位置获取渐变颜色

• 入参：

参数名	类型	必填	说明
t	number	是	参数 t，类型为 number。

• 出参：THREE.Color
• 返回说明：返回 THREE.Color。

getSphereColor(t: number): THREE.Color

• 作用：获取球体颜色

• 入参：

参数名	类型	必填	说明
t	number	是	参数 t，类型为 number。

• 出参：THREE.Color
• 返回说明：返回 THREE.Color。

easeOutElastic(x: number): number

• 作用：缓动函数 - easeOutElastic

• 入参：

参数名	类型	必填	说明
x	number	是	参数 x，类型为 number。

• 出参：number
• 返回说明：返回数值结果。

animateSphereIn(sphere: THREE.Mesh): Promise<void>

• 作用：球体弹入动画

• 入参：

参数名	类型	必填	说明
sphere	THREE.Mesh	是	参数 sphere，类型为 THREE.Mesh。

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

calculatePositions(): { position: THREE.Vector3; t: number; index: number; }[]

• 作用：计算球体位置

• 入参：无

• 出参：{ position: THREE.Vector3; t: number; index: number; }[]

• 返回说明：返回数组结果，元素类型为 { position: THREE.Vector3; t: number; index: number; }。

构造示例

• 来源：packages/demo/src/panels/GeothermalScene/DirectionalReservoir.vue

  const points = [
    new THREE.Vector3(1.5, -0.3, 1.5),
    new THREE.Vector3(0,  -0.3, 0)
  ]

  effect = new FractureEffect({
    points: points,
    curveType: 'catmullrom',
    tension: 0.5,
    spacing: 0.1, // 增大间距
    bufferRatio: 0.02,
    closed: false, // 不闭合，形成螺旋
    spheresVisible: showRuptureSpheres.value,
    cracksVisible: showFractures.value
  });

• 来源：packages/demo/src/panels/OilGasScene/FracturingPanel.vue

  const points = generateSpiralPoints();

  effect = new FractureEffect({
    points: points,
    curveType: 'catmullrom',
    tension: 0.5,
    spacing: 0.2, // 增大间距
    bufferRatio: 0.02,
    closed: false, // 不闭合，形成螺旋
    spheresVisible: showRuptureSpheres.value,
    cracksVisible: showFractures.value
  });

函数示例

FractureEffect.onProgress

• 来源：packages/demo/src/panels/GeothermalScene/DirectionalReservoir.vue

  effect = new FractureEffect({
    points: points,
    curveType: 'catmullrom',
    tension: 0.5,
    spacing: 0.1, // 增大间距
    bufferRatio: 0.02,
    closed: false, // 不闭合，形成螺旋
    spheresVisible: showRuptureSpheres.value,
    cracksVisible: showFractures.value
  });

  isRunning.value = true;
  effect.onProgress((progress) => {
    if (progress >= 1) isRunning.value = false;
  });

FractureEffect.showCracks

• 来源：packages/demo/src/panels/GeothermalScene/DirectionalReservoir.vue

  if (effect) {
    if (showFractures.value) effect.showCracks(); else effect.hideCracks();
  }
  isRunning.value = false;
};

FractureEffect.showSpheres

• 来源：packages/demo/src/panels/GeothermalScene/DirectionalReservoir.vue

  if (!effect) return;
  if (val) effect.showSpheres(); else effect.hideSpheres();
});

Demo 参考

FractureEffect

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

• packages/demo/src/panels/GeothermalScene/DirectionalReservoir.vue
• packages/demo/src/panels/OilGasScene/FracturingPanel.vue