CounterDroneBackend/docs/design/technical/仿真器实体与事件映射.md

仿真器实体与事件映射

实体总览

实体	类	生命周期	主要属性
无人机	DroneEntity	仿真全程	Pos, Hp, Status, Route, ExposureTime, TraveledArc, Progress
发射平台	PlatformEntity	仿真全程	Pos, PlatformType, State（Idle）, AerosolType, MunitionCount, Cooldown, CruiseSpeed, MuzzleVelocity, CurrentVelocity, Target, FlightDistance
飞行弹药	MunitionEntity	发射→到达释放高度	Pos, Velocity, LaunchAngle, Azimuth, MuzzleVelocity, FlightDuration, Start, Target, HasArrived, ElapsedTime
气溶胶云团	CloudEntity	弹药到达→消散	Pos, Radius, Density, Phase, Elapsed, IsDissipated
管控区域	ControlZoneEntity	仿真全程	Vertices, Min/MaxAltitude
探测设备	DetectionEntity	仿真全程	Source（雷达/光电/红外距离+3D球冠参数）, 每无人机探测状态机（Undetected⇄Detected）

事件一览

事件	触发条件	参数	Unity 典型响应
OnTargetDetected	无人机首次进入任一探测设备 3D 球冠范围	DroneEntity, DetectionEntity	显示发现标记 / 3D 球冠 wireframe 高亮
OnMunitionLaunched	发射计划时间到达 + 平台就绪	MunitionEntity	生成炮弹模型，播放发射动画
OnCloudGenerated	弹药到达释放高度	CloudEntity	生成粒子系统，初始半径+颜色
OnDroneDestroyed	毁伤判定 HP ≤ 0	DroneEntity	播放爆炸/坠毁动画
OnDroneReachedTarget	到达最后航路点	DroneEntity	显示"目标抵达"提示
OnZoneIntruded	无人机进入管控区	DroneEntity, ControlZoneEntity	红色警报
OnSimulationEnded	所有无人机状态 ≠ Flying	无	显示结果面板，触发报告生成
PlanningFailed	planner 无法生成拦截方案（引擎发出 SimEvent，无回调）	无（通过 SimEventType.PlanningFailed 事件流传递）	前端显示规划失败原因

实体 × 事件 矩阵

	TargetDetected	MunitionLaunched	CloudGenerated	DroneDestroyed	ReachedTarget	ZoneIntruded	SimEnded	PlanningFailed
DroneEntity	✅			✅	✅	✅
PlatformEntity		✅
MunitionEntity		✅
CloudEntity			✅
ControlZoneEntity						✅
DetectionEntity	✅
全局							✅	✅

数据流

想定配置（ScenarioUnit + ScenarioDrone + RoutePlan + CombatScene）
    │
    ▼
SimulationEngine.Initialize()
    │
    ├─ BuildFireUnits() → List<FireUnit>
    ├─ BuildDroneWaves() → List<DroneWave>
    ├─ IDefensePlanner.Plan() → FireSchedule
    │   └─ MergedSchedule.Count == 0 → PlanningFailed 事件
    │
    ▼
IDefensePlanner.Plan(fireUnits, threats, scene)
    │
    ├─ 五步流水线 → FireSchedule（发射计划）
    │
    ▼
SimulationEngine.Tick()
    │
    ├─ 【地基】时间到达 → PlatformEntity.Release() → MunitionEntity 创建
    │   └─ OnMunitionLaunched ──→ Unity: 炮弹 3D 模型
    │
    ├─ 【空基】时间到达 → PlatformEntity.Release() → MunitionEntity 创建
    │   └─ OnMunitionLaunched ──→ Unity: 空基发射
    │
    ├─ MunitionEntity 飞行 → 到达释放高度
    │   ├─ 地基：抛物线弹道（Kinematics.ParabolicPosition）
    │   └─ 空基：水平初速 + 重力（launchAngle=0, ParabolicPosition）
    │       │
    │       ├─ CloudEntity 创建
    │       ├─ OnCloudGenerated ──→ Unity: 粒子系统
    │       └─ 扩散 → 毁伤判定
    │           ├─ DroneEntity.Hp -= dmg
    │           └─ HP≤0 → OnDroneDestroyed ──→ Unity: 爆炸动画
    │
    ├─ DroneEntity.Update() → 到达终点
    │   └─ OnDroneReachedTarget ──→ Unity: 抵达提示
    │
    ├─ 【实时探测扫描】DetectionEntity × 飞行无人机
    │   ├─ 3D 球冠判定（IsInCoverage）→ 首次进入置 Detected
    │   ├─ 离开范围 → 回退 Undetected（再次进入重新触发）
    │   └─ OnTargetDetected ──→ Unity: 发现标记 / 球冠高亮
    │
    ├─ ControlZone.ContainsPoint()
    │   └─ OnZoneIntruded ──→ Unity: 红色警报
    │
    └─ All drones done
        └─ OnSimulationEnded ──→ Unity: 结果面板 + 报告生成