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

后端对接文档（Unity 前端）

版本：V1.6
日期：2026-06-18
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 = "自定义", Model = "DJI-M3", Description = "小型四旋翼", 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 sc = scenario.CreateScenario("我的想定", "");
scenario.SaveScene(sc.Id, new CombatScene { WindSpeed = 5, WindDirection = (int)WindDirection.E });
scenario.SaveScenarioDrone(sc.Id, new ScenarioDrone {
    WaveId = "w1", Model = "Shahed-136", Description = "活塞巡飞弹",
    Quantity = 1, DroneType = (int)DroneType.FixedWing,
    TypicalSpeed = 200, TypicalAltitude = 500
});
scenario.SaveRoute(sc.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(sc.Id, new List<ScenarioUnit> {
    new() { EquipmentRole = 1, PlatformType = 1, Quantity = 1,
            PositionX = 5000, AerosolType = 0, MunitionCount = 8,
            Description = "地面轻型平台" }
});
scenario.SaveCloud(sc.Id, new CloudDispersal { AerosolType = 0, DisperseHeight = 500 });
scenario.UpdateStep(sc.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.CreateScenario(name, number) / mgr.DeleteScenario(id)
mgr.Search(kw, from, to, page, size)
mgr.SaveScene / SaveScenarioDrone / 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) → 文件路径
rm.Export(reportId, "D:\\MyReports")  // 支持指定导出路径

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, DroneType, 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()

---

七、核心模型

7.1 数据库表

模型	SQLite 表	说明
Scenario	Scenario	想定任务
CombatScene	CombatScene	作战环境
ScenarioDrone	ScenarioDrone	无人机批次参数
ScenarioUnit	ScenarioUnit	装备部署
CloudDispersal	CloudDispersal	云团抛撒配置
RoutePlan	RoutePlan	航路规划
Waypoint	Waypoint	航路点
ControlZone	ControlZone	管控区域
SimulationReport	SimulationReport	仿真报告
AmmunitionSpec	AmmunitionSpec	弹药基础参数
DroneSpec	DroneSpec	无人机基础模板
FireUnitSpec	FireUnitSpec	火力单元基础模板
SensorSpec	SensorSpec	传感器基础模板
EnvironmentSpec	EnvironmentSpec	环境基础模板
FormationTemplate	FormationTemplate	编队基础模板
RouteTemplate	RouteTemplate	航线基础模板
ModelInfo	ModelInfo	3D 模型元数据

7.2 关键属性

模型	属性	类型	说明
ScenarioDrone	Model	string	型号
ScenarioDrone	Description	string	描述/用途
ScenarioDrone	DroneType	DroneType	Rotor / FixedWing / HighSpeed
ScenarioDrone	PowerType	PowerType	Electric / Piston / Jet
ScenarioDrone	TypicalSpeed	double	典型速度 (km/h)
ScenarioDrone	TypicalAltitude	double	典型高度 (m)
Scenario	ScenarioNumber	string	想定编号（唯一）
Scenario	Description	string	想定描述
ScenarioUnit	Description	string	部署备注
ScenarioUnit	MuzzleVelocity	double?	初速 (m/s)
ScenarioUnit	CruiseSpeed	double?	巡航速度 (m/s)，空基专用
DroneSpec	Model	string	型号
DroneSpec	Description	string	描述/用途
FireUnitSpec	Description	string	描述/用途

---

八、默认数据

首次运行自动种子，含 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
测试状态	238 测试，11 秒（全部通过）