tian/CounterDroneBackend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
b23b19e4e9
CounterDroneBackend/docs/对接文档_Unity前端.md

13 KiB
Raw Blame History

后端对接文档（Unity 前端）

版本：V1.8
日期：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 });

// 无人机：引用 DroneSpec (基础数据) + 想定特有字段
scenario.SaveScenarioDrone(sc.Id, new ScenarioDrone {
    DroneSpecId = "shahed", WaveId = "w1", Quantity = 3
});

// 部署：引用 FireUnitSpec (基础数据) + 想定特有字段
scenario.SaveDeployment(sc.Id, new List<ScenarioUnit> {
    new() { FireUnitSpecId = "ground-light", Quantity = 2,
            PositionX = 5000, PositionY = 0, PositionZ = 50,
            AerosolType = 0, MunitionCount = 8, Description = "地面轻型平台" }
});

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.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() / GetAmmo() / DeleteAmmo()
mgr.DataService.GetAllFireUnits() / SaveFireUnit() / GetFireUnit() / DeleteFireUnit()
mgr.DataService.GetAllDrones() / SaveDrone() / GetDrone() / DeleteDrone()
mgr.DataService.GetAllSensors() / SaveSensor() / GetSensor() / DeleteSensor()
mgr.DataService.GetAllEnvironments() / SaveEnvironment() / GetEnvironment() / DeleteEnvironment()
mgr.DataService.GetAllFormations() / SaveFormation() / GetFormation() / DeleteFormation()
mgr.DataService.GetAllRoutes() / SaveRoute() / GetRoute() / DeleteRoute()

// 想定 CRUD
mgr.CreateScenario(name, number) / mgr.UpdateScenario(s) / mgr.DeleteScenario(id)
mgr.Search(kw, from, to, page, size) / mgr.GetDetail(id) → ScenarioConfig

// CombatScene
mgr.SaveScene(id, s) / mgr.GetScene(id)

// ControlZone
mgr.SaveControlZones(id, zones) / mgr.GetControlZones(id) / mgr.DeleteControlZone(id)

// ScenarioDrone
mgr.SaveScenarioDrone(id, d) / mgr.AddScenarioDrone(id, d) / mgr.UpdateScenarioDrone(d)
mgr.DeleteScenarioDrone(id) / mgr.GetScenarioDrones(id)

// ScenarioUnit
mgr.SaveDeployment(id, units) / mgr.AddDeploymentUnit(id, u) / mgr.UpdateDeploymentUnit(u)
mgr.DeleteDeploymentUnit(id) / mgr.GetDeploymentUnits(id)

// Detection
mgr.AddDetection(id, d) / mgr.DeleteDetection(id) / mgr.GetDetections(id)

// CloudDispersal
mgr.SaveCloud(id, c) / mgr.GetCloud(id) / mgr.DeleteCloud(id)

// Route & Waypoint
mgr.SaveRoute(id, waveId, r, wps) / mgr.GetRoutes(id) / mgr.DeleteRoute(id)
mgr.GetWaypoints(id) / mgr.GetWaypointsByWave(id, waveId) / mgr.DeleteWaypoint(id)

// Misc
mgr.UpdateStep(id, step)
mgr.GetEnums() → EnumMetadata  // 所有枚举中英文对照（下拉框数据源）
// EnumMetadata 每个字段是 List<EnumItem>
//   EnumItem: { Name(英文), ChineseName(中文), Value(int) }
// 覆盖: DroneType, PowerType, PlatformType, AerosolType,
//   WeatherType, WindDirection, SceneType, FormationMode,
//   TriggerMode, ReleaseMode, EquipmentRole

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)
ModelId string? 3D 模型 ID（Unity 实例化用）

六、实体属性速查

实体 关键属性
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, TargetX/Y/Z, HasArrived
PlatformEntity Id, PosX/Y/Z, CurrentVelocity, State, MunitionCount, Cooldown, MuzzleVelocity, CruiseSpeed, ReleaseAltitude, TargetX/Y/Z, FlightDistance
DetectionEntity Id, PosX/Y/Z, Source, IsInRange(), IsDetected()

七、核心模型

7.1 数据分层

基础数据（全局模板）              想定数据（归属 ScenarioId）
─────────────────              ──────────────────────────
DroneSpec                       ScenarioDrone (DroneSpecId FK)
FireUnitSpec                    ScenarioUnit  (FireUnitSpecId / SensorSpecId FK)
SensorSpec
AmmunitionSpec
EnvironmentSpec
FormationTemplate
RouteTemplate
ModelInfo

7.2 数据库表

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

7.3 关键属性

模型 属性 类型 说明
ScenarioDrone DroneSpecId string FK → DroneSpec
ScenarioDrone WaveId string 批次 ID
ScenarioDrone Quantity int 数量
ScenarioUnit FireUnitSpecId string FK → FireUnitSpec（发射平台）
ScenarioUnit SensorSpecId string FK → SensorSpec（探测设备）
ScenarioUnit PositionX/Y/Z double 部署位置
ScenarioUnit AerosolType int? 挂载弹药类型
ScenarioUnit MunitionCount int? 弹药数量
ScenarioUnit Description string 部署备注
DroneSpec Model string 型号名称（非 3D 模型，3D 模型见 ModelId）
DroneSpec Description string 描述/用途
DroneSpec ModelId string 3D 模型 FK → ModelInfo
DroneSpec DroneType DroneType Rotor / FixedWing / HighSpeed
DroneSpec PowerType PowerType Electric / Piston / Jet
DroneSpec TypicalSpeed double 典型速度 (km/h)
DroneSpec TypicalAltitude double 典型高度 (m)
FireUnitSpec Description string 描述/用途
FireUnitSpec ModelId string 3D 模型 FK → ModelInfo
FireUnitSpec MuzzleVelocity double 初速 (m/s)
FireUnitSpec CruiseSpeed double 巡航速度 (m/s)
FireUnitSpec RadarRange double 雷达距离 (m)
ModelInfo EntityType int 实体类型 0=Drone 1=Platform 2=DetectionEquip
ModelInfo FilePath string 模型文件路径
Scenario ScenarioNumber string 想定编号（唯一）
Scenario Description string 想定描述
SimulationReport DroneCount int 无人机总数
SimulationReport UnitCount int 装备总数

八、默认数据

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