tian
537671ab3a
- 模型表: ScenarioDrone(原DroneProfile) / ScenarioUnit(原EquipmentDeployment) - ScenarioConfig.Equipment→Units - 数据库旧表清理 + scenariosVersion 4→5 - 238 测试全过
295 lines
10 KiB
Markdown
295 lines
10 KiB
Markdown
# 后端对接文档（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：管理基础数据
|
||
|
||
```csharp
|
||
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：创建想定
|
||
|
||
```csharp
|
||
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：运行仿真
|
||
|
||
```csharp
|
||
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：生成报告
|
||
|
||
```csharp
|
||
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：回放
|
||
|
||
```csharp
|
||
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 — 基础数据 + 想定
|
||
|
||
```csharp
|
||
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 — 仿真执行
|
||
|
||
```csharp
|
||
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 — 报告
|
||
|
||
```csharp
|
||
var rm = GetComponent<ReportManager>();
|
||
rm.Generate(scenarioId, detail, events, status, duration) → SimulationReport
|
||
rm.Export(reportId) → 文件路径
|
||
rm.Export(reportId, "D:\\MyReports") // 支持指定导出路径
|
||
```
|
||
|
||
### ReplayController — 回放
|
||
|
||
```csharp
|
||
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` |
|
||
|
||
---
|
||
|
||
## 九、更新后端
|
||
|
||
```bash
|
||
cd src/CounterDrone.Core
|
||
dotnet publish -c Release -o ../../unity_plugins
|
||
```
|
||
|
||
---
|
||
|
||
## 十、参考
|
||
|
||
| 文档 | 位置 |
|
||
|------|------|
|
||
| 架构设计 | `docs/design/architecture/总体架构设计.md` |
|
||
| 实体事件映射 | `docs/design/technical/仿真器实体与事件映射.md` |
|
||
| 测试状态 | **238 测试，11 秒（全部通过）** |
|