docs: 前端对接文档更新到 V1.3（预设想定一键运行）
交付物简化: defaults.json + planner_config.json（替代 default_ammo.json） 核心流程: 列出[Demo]想定→LoadAndStart→订阅事件，无需手写配置或调用Planner 新增: 自定义想定示例（使用 DefaultData 预设快速组装） 默认数据表: 弹药/编队/航线/火力单元/无人机/探测/天气/预设想定 8类
This commit is contained in:
parent
235c111a75
commit
5b6ccccba6
@ -1,6 +1,6 @@
|
||||
# 后端对接文档（Unity 前端）
|
||||
|
||||
> **版本**：V1.2
|
||||
> **版本**：V1.3
|
||||
> **日期**：2026-06-15
|
||||
> **Unity 版本**：2022.3.62f3c1
|
||||
|
||||
@ -11,66 +11,84 @@
|
||||
从仓库取以下内容，拖入 Unity 项目：
|
||||
|
||||
```
|
||||
src/Unity/Assets/Plugins/ ← 16 个 DLL（Core + sqlite + JSON）
|
||||
src/Unity/Assets/Plugins/ ← DLL（Core + sqlite + JSON）
|
||||
src/Unity/Assets/Scripts/Managers/ ← 桥接脚本
|
||||
data/default_ammo.json ← 默认弹药参数（放到 persistentDataPath 下）
|
||||
data/defaults.json ← 默认数据（弹药/航线/火力单元/无人机/天气，放到 persistentDataPath 下）
|
||||
data/planner_config.json ← 规划器配置（放到 persistentDataPath 下）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、快速验证
|
||||
|
||||
1. 拖入上述目录，等 Unity 编译
|
||||
1. 将上述文件拖入 Unity 项目，等编译
|
||||
2. 创建空 GameObject，挂 `ManagerVerification`
|
||||
3. Inspector 右键 → `Run Full Verification`
|
||||
4. Console 看到 7 行 OK
|
||||
|
||||
> 首次运行自动种子 6 个 `[Demo]` 预设想定到数据库，含完整配置。
|
||||
|
||||
---
|
||||
|
||||
## 三、核心流程
|
||||
## 三、核心流程（使用预设想定）
|
||||
|
||||
### 3.1 创建想定 & 获取推荐方案
|
||||
### 3.1 列出预设想定
|
||||
|
||||
```csharp
|
||||
var scenario = GetComponent<ScenarioManager>();
|
||||
var task = scenario.CreateTask("拦截活塞式无人机", "");
|
||||
scenario.SaveScene(task.Id, new CombatScene { WindSpeed = 3 });
|
||||
scenario.SaveTarget(task.Id, new TargetConfig { WaveId = "default", PowerType = (int)PowerType.Piston, ... });
|
||||
scenario.SaveRoute(task.Id, "default", routePlan, waypoints);
|
||||
|
||||
// 推荐方案（DefensePlanner 五步流水线）
|
||||
var detail = scenario.GetDetail(task.Id);
|
||||
var ammoCatalog = db.Table<AmmunitionSpec>().ToList(); // DatabaseManager 已种子
|
||||
var fireUnits = new List<FireUnit> { /* 从 EquipmentDeployment 构建 */ };
|
||||
var threats = new List<DroneWave> { new DroneWave { WaveId = "default", Target = detail.Targets[0], Route = detail.Routes[0], Waypoints = detail.WaypointGroups["default"] } };
|
||||
var plan = new DefensePlanner(ammoCatalog, PlannerConfig.Load(paths)).Plan(fireUnits, threats, detail.Scene, new List<DetectionSource>());
|
||||
|
||||
// 应用到想定（发射计划传给引擎，部署方案保存到配置）
|
||||
var mergedSchedule = plan.Best.MergedSchedule;
|
||||
// 部署火力单元到 EquipmentDeployment...
|
||||
scenario.SaveCloud(task.Id, new CloudDispersal { /* 从 plan.Best.Assignments 推算云团参数 */ });
|
||||
scenario.SaveDeployment(task.Id, equips);
|
||||
var demos = scenario.Search("[Demo]", null, null, 1, 100);
|
||||
// → 返回 6 个预设想定：
|
||||
// [Demo] 无防御-无人机抵达目标
|
||||
// [Demo] 管控区域侵入
|
||||
// [Demo] 活塞拦截-西风5ms
|
||||
// [Demo] 喷气式拦截-活性材料
|
||||
// [Demo] 空基拦截-东风5ms
|
||||
// [Demo] 3架空基编队拦截
|
||||
```
|
||||
|
||||
### 3.2 启动仿真（事件驱动）
|
||||
### 3.2 启动仿真（一行代码）
|
||||
|
||||
```csharp
|
||||
var runner = GetComponent<SimulationRunner>();
|
||||
|
||||
// 推荐方案的 FireSchedule 直接传给引擎
|
||||
runner.Engine.SetFireSchedule(plan.Best.MergedSchedule);
|
||||
runner.LoadAndStart(task.Id);
|
||||
// 选一个预设想定，直接运行（引擎自动调用 Planner 生成发射计划）
|
||||
runner.LoadAndStart(demos.Items[0].Id); // 例如：活塞拦截-西风5ms
|
||||
runner.Engine.TimeScale = 4f; // 加速
|
||||
|
||||
// 订阅事件，不需要每帧遍历 NewEvents
|
||||
// 订阅事件
|
||||
runner.Engine.OnMunitionLaunched += m => Instantiate(shellPrefab, ToVector3(m.PosX, m.PosY, m.PosZ));
|
||||
runner.Engine.OnCloudGenerated += c => SpawnCloud(c.Dispersion.Center, c.Dispersion.Radius);
|
||||
runner.Engine.OnDroneDestroyed += d => PlayExplosion(d.PosX, d.PosY, d.PosZ);
|
||||
runner.Engine.OnDroneReachedTarget += d => ShowReached(d.PosX, d.PosY, d.PosZ);
|
||||
runner.Engine.OnZoneIntruded += (d, z) => AlertIntrusion(z.Name);
|
||||
runner.Engine.OnSimulationEnded += () => GenerateReport();
|
||||
```
|
||||
|
||||
// 不需要手动 Tick —— SimulationBootstrap 已封装好了
|
||||
### 3.3 自定义想定（高级）
|
||||
|
||||
```csharp
|
||||
var scenario = GetComponent<ScenarioManager>();
|
||||
var task = scenario.CreateTask("自定义想定", "");
|
||||
|
||||
// 使用默认数据预设快速配置
|
||||
var defaults = DefaultData.Load(new UnityPathProvider());
|
||||
scenario.SaveScene(task.Id, defaults.Weather.First(w => w.Id == "sunny-calm").ToCombatScene());
|
||||
scenario.SaveTarget(task.Id, defaults.Targets.First(p => p.Id == "shahed").ToTargetConfig());
|
||||
scenario.SaveRoute(task.Id, "default",
|
||||
defaults.Formations.First(f => f.Id == "single").ToRoutePlan(),
|
||||
defaults.Routes.First(r => r.Id == "5km-h500").ToWaypoints(200));
|
||||
scenario.SaveDeployment(task.Id, new List<EquipmentDeployment>
|
||||
{
|
||||
defaults.FireUnits.First(f => f.Id == "ground-light")
|
||||
.ToEquipmentDeployment(AerosolType.InertGas, 1, 1500, 0, 50),
|
||||
});
|
||||
scenario.SaveCloudDispersal(task.Id, new CloudDispersal
|
||||
{ AerosolType = (int)AerosolType.InertGas, DisperseHeight = 500 });
|
||||
scenario.UpdateStep(task.Id, 5);
|
||||
|
||||
// 运行
|
||||
var runner = GetComponent<SimulationRunner>();
|
||||
runner.LoadAndStart(task.Id);
|
||||
```
|
||||
|
||||
### 3.3 仿真事件一览
|
||||
@ -134,18 +152,29 @@ replay.LoadReplay(taskId);
|
||||
|
||||
---
|
||||
|
||||
## 五、默认弹药
|
||||
## 五、默认数据
|
||||
|
||||
首次运行 `DatabaseManager.OpenMainDb()` 会检查 `persistentDataPath/default_ammo.json`。如果存在且 `AmmunitionSpec` 表为空，自动导入。
|
||||
首次运行 `DatabaseManager.OpenMainDb()` 自动从 `data/defaults.json` 种子数据库：
|
||||
|
||||
当前默认参数（`data/default_ammo.json`）：
|
||||
| 类别 | 内容 | 示例 ID |
|
||||
|------|------|------|
|
||||
| 弹药 | 3 种 | `inert` / `active` / `fuel` |
|
||||
| 编队 | 6 种 | `single` / `line-3` / `swarm-10` |
|
||||
| 航线 | 6 条 | `3km-h300` / `5km-h500` / `10km-h500` / `20km-h500` |
|
||||
| 火力单元 | 4 种 | `ground-light` / `ground-standard` / `ground-heavy` / `air-standard` |
|
||||
| 无人机 | 6 种 | `quadcopter` / `shahed` / `cruise-missile` |
|
||||
| 探测设备 | 4 种 | `radar-mr` / `eo-station` |
|
||||
| 天气 | 6 种 | `sunny-calm` / `fog` / `night` |
|
||||
| 预设想定 | 6 个 | `[Demo] 活塞拦截-西风5ms` |
|
||||
|
||||
| 参数 | 惰性气体弹 | 活性材料弹 | 活性燃料弹 |
|
||||
|------|------|------|------|
|
||||
| 药剂质量 | 10 kg | 12 kg | 10 kg |
|
||||
| 爆发药 TNT | 1.5 kg | 4.0 kg | 1.5 kg |
|
||||
| 初始半径 R₀ | 3.75 m | 5.14 m | 3.75 m |
|
||||
| 扩散模型 | 三阶段（爆轰→湍流→高斯） | | |
|
||||
所有默认数据名称含 `[Demo]` 前缀，UI 中可识别。预设可通过 API 直接获取：
|
||||
|
||||
```csharp
|
||||
var defaults = DefaultData.Load(new UnityPathProvider());
|
||||
var ammo = defaults.Ammunition.First(a => a.Id == "inert");
|
||||
var route = defaults.Routes.First(r => r.Id == "5km-h500").ToWaypoints(200);
|
||||
var unit = defaults.FireUnits.First(f => f.Id == "ground-light").ToEquipmentDeployment(AerosolType.InertGas, 1, 1500, 0, 50);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@ -167,4 +196,4 @@ dotnet publish -c Release -o ../../unity_plugins
|
||||
| 实体事件映射 | `docs/design/technical/仿真器实体与事件映射.md` |
|
||||
| 任务跟踪 | `docs/implementation/tasks/实施计划与任务跟踪.md` |
|
||||
| 测试报告 | `test/reports/`（每次集成测试自动生成） |
|
||||
| 测试状态 | **204 测试，95.4% 行覆盖率，63 秒** |
|
||||
| 测试状态 | **191 测试，24 秒（集成）** |
|
||||
|
||||
Loading…
Reference in New Issue
Block a user