ExplosionEffect & EntityDetectEffect 特效系统

特效系统提供爆炸粒子效果和实体探测/雷达扫描效果，分别基于 Cesium ParticleSystem 和 EllipsoidGraphics 实现。

---

ExplosionEffect 爆炸特效

ExplosionEffect 封装了火焰粒子 + 烟雾粒子的二阶段爆炸动画，通过 installExplosionEffect() 混入（mixin）挂载到 Viewer 上使用。

installExplosionEffect

installExplosionEffect(viewer: Viewer): void

调用后 viewer 会获得 extensions.createExplosion 和 extensions.createExplosionAtCoordinates 两个工厂方法。

参数	类型	描述
viewer	Cesium.Viewer	Cesium Viewer 实例

viewer.extensions.createExplosion

createExplosion(options: ExplosionOptions): ExplosionEffect

在指定 Cartesian3 位置创建爆炸。

viewer.extensions.createExplosionAtCoordinates

createExplosionAtCoordinates(
  longitude: number,
  latitude: number,
  height?: number,
  config?: ExplosionConfig
): ExplosionEffect

通过经纬度坐标创建爆炸，内部调用 Cartesian3.fromDegrees 转换。

ExplosionOptions & ExplosionConfig

interface ExplosionOptions {
  position: Cartesian3;
  config?: ExplosionConfig;
}

interface ExplosionConfig {
  duration?: number;       // 持续时间（秒），默认 8.0
  particleCount?: number;  // 粒子数量，默认 200
  scale?: number;          // 缩放比例，默认 1.0
  color?: Color;           // 基础颜色，默认 Color.ORANGE
  explosionSize?: number;  // 爆炸体积，默认 50.0
  gravity?: number;        // 模拟重力，默认 -9.8
  windSpeed?: Cartesian3;  // 风速，默认 (0,0,0)
  smokeColor?: Color;      // 烟雾颜色，默认 GRAY alpha 0.8
  fireColor?: Color;       // 火焰颜色，默认 ORANGE
}

配置项	类型	默认值	描述
duration	number	8.0	爆炸总持续时间（秒），到期自动销毁
particleCount	number	200	火焰粒子发射数量，烟雾粒子取其一半
scale	number	1.0	全局缩放倍率，影响粒子速度、大小和发射区域
color	Color	Color.ORANGE	爆炸整体基调颜色
explosionSize	number	50.0	SphereEmitter 半径（米），控制爆炸扩散范围
gravity	number	-9.8	重力加速度，负值使粒子上升
windSpeed	Cartesian3	(0,0,0)	风速向量，影响粒子飘散方向
smokeColor	Color	GRAY(0.8)	烟雾粒子颜色
fireColor	Color	ORANGE	火焰粒子颜色

ExplosionEffect.destroy()

destroy(): void

主动销毁爆炸效果，清理粒子系统、纹理和定时器。

代码示例

基础爆炸

import { installExplosionEffect } from '@air-stack/gis-cesium';

// 混入爆炸特效
installExplosionEffect(viewer);

// 在指定位置创建爆炸
const position = Cesium.Cartesian3.fromDegrees(116.3, 39.9, 500);
const explosion = viewer.extensions.createExplosion({ position });

自定义配置

const explosion = viewer.extensions.createExplosion({
  position: Cesium.Cartesian3.fromDegrees(121.4, 31.2, 0),
  config: {
    duration: 5.0,
    particleCount: 300,
    scale: 1.5,
    explosionSize: 80,
    gravity: -5.0,
  },
});

// 手动销毁
setTimeout(() => {
  explosion.destroy();
}, 3000);

使用经纬度快捷方法

const explosion = viewer.extensions.createExplosionAtCoordinates(
  116.3,   // longitude
  39.9,    // latitude
  1000,    // height（可选，默认 0）
  {
    particleCount: 150,
    scale: 0.8,
  }
);

多爆炸演示

// 在多个坐标点同时爆破
const positions = [
  [116.3, 39.9, 200],
  [116.4, 40.0, 200],
  [116.5, 39.8, 200],
];

positions.forEach(([lon, lat, height]) => {
  viewer.extensions.createExplosionAtCoordinates(lon, lat, height, {
    duration: 6,
    particleCount: 100,
    explosionSize: 40,
  });
});

---

EntityDetectEffect 实体探测效果

EntityDetectEffect 基于 EllipsoidGraphics 实现扇形探测体，自动朝向目标并检测目标是否进入探测范围，适用于雷达扫描、传感器视锥、目标锁定等场景。

构造函数

constructor(options: EntityDetectEffectOptions)

interface EntityDetectEffectOptions {
  source: Entity;   // 雷达源实体（探测发起方）
  target: Entity;   // 目标实体（被探测对象）
  radius?: number;  // 探测半径（米），默认 500000
}

参数	类型	默认值	描述
source	Entity	—	探测发起方实体，必须含 position
target	Entity	—	被探测目标实体，必须含 position
radius	number	500000	探测半径，单位米

方法

on(collection, fn?)

on(collection: EntityCollection, fn?: (inRange: boolean) => void): void

将探测体添加到指定实体集合中，并注册范围检测回调。当目标进入或离开探测半径时触发 fn。

参数	类型	描述
collection	EntityCollection	实体集合，通常传 viewer.entities
fn	(inRange: boolean) => void	可选回调，true 表示目标进入范围

off(collection)

off(collection: EntityCollection): void

从实体集合中移除探测体，停止效果但不销毁实例。

destroy(collection)

destroy(collection: EntityCollection): void

关闭效果并释放内部引用。调用后实例不再可用。

代码示例

基础雷达探测

import { EntityDetectEffect } from '@air-stack/gis-cesium';

// 创建源实体（雷达站）
const radar = viewer.entities.add({
  id: 'radar_station',
  position: Cesium.Cartesian3.fromDegrees(116.3, 39.9, 100),
  point: { pixelSize: 8, color: Cesium.Color.CYAN },
});

// 创建目标实体（飞行器）
const target = viewer.entities.add({
  id: 'aircraft_01',
  position: Cesium.Cartesian3.fromDegrees(116.5, 40.0, 5000),
  point: { pixelSize: 6, color: Cesium.Color.RED },
});

// 创建探测效果
const effect = new EntityDetectEffect({
  source: radar,
  target: target,
  radius: 300000,
});

// 启用探测并监听范围变化
effect.on(viewer.entities, (inRange) => {
  if (inRange) {
    console.log('目标进入探测范围！');
  } else {
    console.log('目标离开探测范围！');
  }
});

多目标监测

const targets = ['target_01', 'target_02', 'target_03'];

targets.forEach((targetId) => {
  const targetEntity = viewer.entities.getById(targetId);
  if (!targetEntity) return;

  const effect = new EntityDetectEffect({
    source: radarEntity,
    target: targetEntity,
    radius: 200000,
  });

  effect.on(viewer.entities, (inRange) => {
    updateRadarDisplay(targetId, inRange);
  });

  // 存储引用以便后续销毁
  activeEffects.push({ targetId, effect });
});

销毁探测效果

// 关闭单个探测
effect.off(viewer.entities);

// 销毁并释放引用
effect.destroy(viewer.entities);

探测体表现说明

• 扇形范围：默认 minimumClock=135、maximumClock=225、minimumCone=70、maximumCone=110，构成前方 90 度扇形探测体。
• 颜色变化：目标在范围外时显示绿色，进入范围内变为蓝色，视觉反馈直观。
• 自动跟踪：探测体通过 Quaternion.lerp 平滑插值朝向目标，旋转有缓动效果。
• 位置绑定：探测体位置绑定到 source.position，随源实体移动。

---

注意事项

1. ExplosionEffect 会自动管理生命周期，到达 duration 后自动销毁并释放 Canvas 纹理。也可通过 destroy() 提前销毁。
2. ExplosionEffect 使用纹理管理器（单例模式）缓存火焰和烟雾 Canvas 纹理，减少重复创建开销。
3. EntityDetectEffect 的 on() 方法可多次调用注册多个回调，off() 仅移除探测体，不销毁回调列表。
4. EntityDetectEffect 的 destroy() 会清空内部引用，调用后不可复用在新的集合上，需重新构造。
5. 两个特效都依赖实体拥有 position 属性，确保使用前已正确定位。