CounterDroneBackend/docs/对接文档_Unity前端.md

后端对接文档（Unity 前端）

版本：V1.5
日期：2026-06-17
Unity 版本：2022.3.62f3c1

---

一、交付物

从仓库取以下内容，拖入 Unity 项目：

src/Unity/Assets/Plugins/              ← DLL（Core + sqlite + JSON）
src/Unity/Assets/Scripts/Managers/     ← 桥接脚本

将以下文件放到 Unity 项目 Assets/StreamingAssets/ 目录下：
  data/defaults.json                    ← 默认数据（首次运行自动复制到 persistentDataPath）
  data/planner_config.json              ← 规划器配置（同上）

---

二、快速开始

1. 将 defaults.json 和 planner_config.json 放到 Assets/StreamingAssets/
2. 创建空 GameObject，挂 SimulationBootstrap
3. 运行 — 自动种子数据库，选一个 [Demo] 想定，启动仿真

SimulationBootstrap 是前端开发的参考模板，展示预设模式（一行代码）和自定义模式两种路径。

---

三、完整工作流（5 步）

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌──────────┐    ┌──────────┐
│ 基础数据 CRUD │ → │  创建想定    │ → │  运行仿真    │ → │  生成报告  │ → │  回放    │
│ DataService  │    │ ScenarioMgr │    │ SimRunner   │    │ ReportMgr │    │ Replay   │
└─────────────┘    └─────────────┘    └─────────────┘    └──────────┘    └──────────┘

3.1 步骤 1：管理基础数据

var mgr = GetComponent<ScenarioManager>();
var ds = mgr.DataService;

// 列出所有
var drones = ds.GetAllDrones();
var ammo = ds.GetAllAmmo();
var units = ds.GetAllFireUnits();

// 新增
ds.SaveDrone(new DroneSpec { Id = "custom", Name = "自定义", TypicalSpeed = 100, ... });
// 删除
ds.DeleteDrone("custom");

// 7 类全覆盖：DroneSpec / FireUnitSpec / SensorSpec / EnvironmentSpec
//               FormationTemplate / RouteTemplate / AmmunitionSpec

3.2 步骤 2：创建想定

var scenario = GetComponent<ScenarioManager>();

// 方式 A：预设想定（最快）
var demos = scenario.Search("Demo", null, null, 1, 100);
var scenarioId = demos.Items[0].Id;

// 方式 B：自定义
var task = scenario.CreateTask("我的想定", "");
scenario.SaveScene(task.Id, new CombatScene { WindSpeed = 5, WindDirection = (int)WindDirection.E });
scenario.SaveTarget(task.Id, new DroneProfile { WaveId = "w1", Quantity = 1, TypicalSpeed = 200, TypicalAltitude = 500 });
scenario.SaveRoute(task.Id, "w1", new RoutePlan(), new List<Waypoint> {
    new() { PosX = 0, PosY = 500, PosZ = 0, Speed = 200 },
    new() { PosX = 10000, PosY = 500, PosZ = 0, Speed = 200 }
});
scenario.SaveDeployment(task.Id, new List<EquipmentDeployment> {
    new() { EquipmentRole = 1, PlatformType = 1, Quantity = 1, PositionX = 5000, AerosolType = 0, MunitionCount = 8 }
});
scenario.SaveCloud(task.Id, new CloudDispersal { AerosolType = 0, DisperseHeight = 500 });
scenario.UpdateStep(task.Id, 5);

3.3 步骤 3：运行仿真

var runner = GetComponent<SimulationRunner>();
runner.LoadAndStart(scenarioId);
runner.Engine.TimeScale = 4f;

// 事件
runner.Engine.OnMunitionLaunched += m => { };
runner.Engine.OnCloudGenerated   += c => { };
runner.Engine.OnDroneDestroyed   += d => { };
runner.Engine.OnSimulationEnded  += () => { };

// 逐帧
void Update() {
    var result = runner.Engine.Tick(Time.deltaTime);
    foreach (var snap in result.EntitySnapshots) {
        // snap.EntityType, PosX/Y/Z, VelX/Y/Z, Hp, CloudRadius...
    }
}

3.4 步骤 4：生成报告

var rm = GetComponent<ReportManager>();
var detail = scenario.GetDetail(scenarioId);
var report = rm.Generate(scenarioId, detail, runner.Engine.Events.ToList(),
    runner.Engine.Drones[0].Status.ToString(), runner.Engine.SimulationTime);
string path = rm.Export(report.Id);

3.5 步骤 5：回放

var replay = GetComponent<ReplayController>();
replay.LoadReplay(scenarioId);
for (int i = 0; i < replay.TotalFrames; i++) {
    var frame = replay.GetFrame(i);
    // frame.SimulationTime, frame.EntitySnapshots...
}

---

四、Manager API 速查

ScenarioManager — 基础数据 + 想定

var mgr = GetComponent<ScenarioManager>();

// 基础数据 CRUD（7 类）
mgr.DataService.GetAllAmmo() / SaveAmmo() / DeleteAmmo()
mgr.DataService.GetAllFireUnits() / GetAllDrones() / GetAllSensors()
mgr.DataService.GetAllEnvironments() / GetAllFormations() / GetAllRoutes()

// 想定 CRUD
mgr.CreateTask(name, "") / mgr.DeleteTask(id) / mgr.Search(kw, from, to, page, size)
mgr.SaveScene / SaveTarget / SaveDeployment / SaveCloud / SaveRoute / UpdateStep
mgr.GetDetail(id) → ScenarioConfig

SimulationRunner — 仿真执行

var runner = GetComponent<SimulationRunner>();
runner.LoadAndStart(scenarioId);
runner.Engine.TimeScale = 4f;
runner.Engine.State / Drones / Clouds / Munitions / Platforms / DetectionEntities / Events
runner.Engine.Tick(dt) → SimulationFrameResult { EntitySnapshots, NewEvents }
runner.Engine.OnMunitionLaunched / OnCloudGenerated / OnDroneDestroyed / ...
runner.Stop();

ReportManager — 报告

var rm = GetComponent<ReportManager>();
rm.Generate(scenarioId, detail, events, status, duration) → SimulationReport
rm.Export(reportId) → 文件路径

ReplayController — 回放

var replay = GetComponent<ReplayController>();
replay.LoadReplay(scenarioId);
replay.TotalFrames / replay.GetFrame(index)

---

五、EntitySnapshot（每帧推送）

字段	类型	说明
EntityId	string	实体唯一 ID
EntityType	enum	Drone / Platform / Munition / Cloud / DetectionEquip
PosX/Y/Z	float	三维位置
VelX/Y/Z	float	瞬时速度 (m/s)
Hp	float	无人机血量 (0~1)
DamageStage	int	损伤阶段
PlatformStateStr	string	Idle / FlyingToTarget / ReadyToRelease
CloudRadius	float	云团有效半径
CloudOpacity	float	不透明度 (0~1)
CloudPhase	int	扩散阶段 (1/2/3)
CloudElapsed	float	已存在时间 (s)

---

六、实体属性速查

实体	关键属性
DroneEntity	Id, PosX/Y/Z, Hp, Status, Type, Wingspan, CruiseSpeed, Route, TraveledArc, TotalArc, Progress
CloudEntity	Id, PosX/Y/Z, Radius, Density, Phase, Elapsed, IsDissipated
MunitionEntity	Id, PosX/Y/Z, Velocity, Start, LaunchTime, ElapsedTime, LaunchAngle, Azimuth, MuzzleVelocity, FlightDuration, Target, HasArrived
PlatformEntity	Id, PosX/Y/Z, CurrentVelocity, State, MunitionCount, Cooldown, MuzzleVelocity, CruiseSpeed, ReleaseAltitude, Target, FlightDistance
DetectionEntity	Id, PosX/Y/Z, Source, IsInRange(), IsDetected()

---

七、规格类命名对照

旧名	新名	SQLite 表
TargetPreset	DroneSpec	DroneSpec
DetectionPreset	SensorSpec	SensorSpec
WeatherPreset	EnvironmentSpec	EnvironmentSpec
FireUnitTemplate	FireUnitSpec	FireUnitSpec
RoutePreset	RouteTemplate	RouteTemplate
FormationTemplate	不变	FormationTemplate
AmmunitionSpec	不变	AmmunitionSpec

---

八、默认数据

首次运行自动种子，含 6 个 [Demo] 预设想定：

类别	示例 ID
弹药	inert / active / fuel
编队	single / line-3 / swarm-10
航线	5km-h500 / 10km-h500 / 20km-h500
火力单元	ground-light / air-standard
无人机	shahed / quadcopter / cruise-missile
传感器	radar-mr / eo-station
环境	sunny-calm / fog / night

---

九、更新后端

cd src/CounterDrone.Core
dotnet publish -c Release -o ../../unity_plugins

---

十、参考

文档	位置
架构设计	docs/design/architecture/总体架构设计.md
实体事件映射	docs/design/technical/仿真器实体与事件映射.md
测试状态	243 测试，11 秒（全部通过）