From 4c2c18cfccee8aae7277661a0d892b4ddcd5b689 Mon Sep 17 00:00:00 2001 From: tian <11429339@qq.com> Date: Wed, 17 Jun 2026 15:57:41 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=E5=AF=B9=E6=8E=A5?= =?UTF-8?q?=E6=96=87=E6=A1=A3=20=E2=80=94=20=E4=BA=94=E6=AD=A5=E5=AE=8C?= =?UTF-8?q?=E6=95=B4=E5=B7=A5=E4=BD=9C=E6=B5=81=EF=BC=88=E5=9F=BA=E7=A1=80?= =?UTF-8?q?=E6=95=B0=E6=8D=AE=E2=86=92=E6=83=B3=E5=AE=9A=E2=86=92=E4=BB=BF?= =?UTF-8?q?=E7=9C=9F=E2=86=92=E6=8A=A5=E5=91=8A=E2=86=92=E5=9B=9E=E6=94=BE?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/对接文档_Unity前端.md | 333 +++++++++++++++++-------------------- 1 file changed, 150 insertions(+), 183 deletions(-) diff --git a/docs/对接文档_Unity前端.md b/docs/对接文档_Unity前端.md index b76fbb6..05f74f4 100644 --- a/docs/对接文档_Unity前端.md +++ b/docs/对接文档_Unity前端.md @@ -27,207 +27,187 @@ src/Unity/Assets/Scripts/Managers/ ← 桥接脚本 2. 创建空 GameObject，挂 `SimulationBootstrap` 3. 运行 — 自动种子数据库，选一个 `[Demo]` 想定，启动仿真 -> `SimulationBootstrap` 是前端开发的参考模板，展示预设模式（一行代码）和自定义模式（用 DefaultData 预设组装）两种路径。 - -> 如需验证全部模块，挂 `ManagerVerification` → Inspector 右键 `Run Full Verification`。 +> `SimulationBootstrap` 是前端开发的参考模板，展示预设模式（一行代码）和自定义模式两种路径。 --- -## 三、核心流程（使用预设想定） +## 三、完整工作流（5 步） -### 3.1 列出预设想定 - -```csharp -var scenario = GetComponent(); -var demos = scenario.Search("Demo", null, null, 1, 100); -// → 返回 6 个预设想定： -// [Demo] 无防御-无人机抵达目标 -// [Demo] 管控区域侵入 -// [Demo] 活塞拦截-西风5ms -// [Demo] 喷气式拦截-活性材料 -// [Demo] 空基拦截-东风5ms -// [Demo] 3架空基编队拦截 +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌──────────┐ ┌──────────┐ +│ 基础数据 CRUD │ → │ 创建想定 │ → │ 运行仿真 │ → │ 生成报告 │ → │ 回放 │ +│ DataService │ │ ScenarioMgr │ │ SimRunner │ │ ReportMgr │ │ Replay │ +└─────────────┘ └─────────────┘ └─────────────┘ └──────────┘ └──────────┘ ``` -### 3.2 启动仿真（一行代码） - -```csharp -var runner = GetComponent(); - -// 选一个预设想定，直接运行（引擎自动调用 Planner 生成发射计划） -runner.LoadAndStart(demos.Items[0].Id); // 例如：活塞拦截-西风5ms -runner.Engine.TimeScale = 4f; // 加速 - -// 订阅事件 -runner.Engine.OnMunitionLaunched += m => Instantiate(shellPrefab, ToVector3(m.PosX, m.PosY, m.PosZ)); -runner.Engine.OnCloudGenerated += c => SpawnCloud(c.PosX, c.PosY, c.PosZ, c.Radius); -runner.Engine.OnDroneDestroyed += d => PlayExplosion(d.PosX, d.PosY, d.PosZ); -runner.Engine.OnTargetDetected += (d, det) => ShowDetectionMark(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(); -``` - -### 3.3 自定义想定（高级） - -```csharp -var scenario = GetComponent(); -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 -{ - 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(); -runner.LoadAndStart(task.Id); -``` - -### 3.3 仿真事件一览 - -| 事件 | 参数 | 触发时机 | -|------|------|------| -| `OnTargetDetected` | `DroneEntity`, `DetectionEntity` | 无人机首次进入探测设备 3D 球冠范围（离开后再次进入会重新触发） | -| `OnMunitionLaunched` | `MunitionEntity` | 发射计划时间到达 | -| `OnCloudGenerated` | `CloudEntity` | 弹药到达释放高度 | -| `OnDroneDestroyed` | `DroneEntity` | HP ≤ 0 | -| `OnDroneReachedTarget` | `DroneEntity` | 到达最后航路点 | -| `OnZoneIntruded` | `DroneEntity`, `ControlZoneEntity` | 进入管控区 | -| `OnSimulationEnded` | 无 | 所有无人机状态 ≠ Flying | - ---- - -## 四、Manager API - -### ScenarioManager +### 3.1 步骤 1：管理基础数据 ```csharp var mgr = GetComponent(); -SimTask task = mgr.CreateTask("任务名", ""); // 空字符串 = 自动编号 SIM-yyyyMMdd-xxx -mgr.SaveScene(id, combatScene); -mgr.SaveTarget(id, targetConfig); -mgr.SaveDeployment(id, equipmentList); -mgr.SaveCloud(id, cloudDispersal); -mgr.SaveRoute(id, "default", routePlan, waypoints); -TaskFullConfig detail = mgr.GetDetail(id); -PagedResult result = mgr.Search("关键词", from, to, page, pageSize); +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 ``` -### SimulationRunner +### 3.2 步骤 2：创建想定 + +```csharp +var scenario = GetComponent(); + +// 方式 A：预设想定（最快） +var demos = scenario.Search("Demo", null, null, 1, 100); +var taskId = 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 TargetConfig { WaveId = "w1", Quantity = 1, TypicalSpeed = 200, TypicalAltitude = 500 }); +scenario.SaveRoute(task.Id, "w1", new RoutePlan(), new List { + new() { PosX = 0, PosY = 500, PosZ = 0, Speed = 200 }, + new() { PosX = 10000, PosY = 500, PosZ = 0, Speed = 200 } +}); +scenario.SaveDeployment(task.Id, new List { + 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：运行仿真 ```csharp var runner = GetComponent(); -runner.Engine.SetFireSchedule(fireEvents); // 从推荐方案取 runner.LoadAndStart(taskId); runner.Engine.TimeScale = 4f; -runner.Engine.State / Drones / Clouds / Munitions / Platforms / DetectionEntities / Events -runner.DataService // 基础数据 CRUD（见第五节） -runner.Stop(); + +// 事件 +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... + } +} ``` -### ReportManager +### 3.4 步骤 4：生成报告 ```csharp -var mgr = GetComponent(); -var config = scenario.GetDetail(taskId); -var report = mgr.Generate(taskId, config, runner.Engine.Events.ToList(), - runner.Engine.Drones[0].Status.ToString(), - runner.Engine.SimulationTime); -string path = mgr.Export(report.Id); // → persistentDataPath/reports/xxx.md +var rm = GetComponent(); +var detail = scenario.GetDetail(taskId); +var report = rm.Generate(taskId, detail, runner.Engine.Events.ToList(), + runner.Engine.Drones[0].Status.ToString(), runner.Engine.SimulationTime); +string path = rm.Export(report.Id); ``` -### ReplayController +### 3.5 步骤 5：回放 ```csharp var replay = GetComponent(); replay.LoadReplay(taskId); -// replay.TotalFrames / replay.GetFrame(frameIndex) +for (int i = 0; i < replay.TotalFrames; i++) { + var frame = replay.GetFrame(i); + // frame.SimulationTime, frame.EntitySnapshots... +} ``` -### EntitySnapshot（每帧推送） +--- + +## 四、Manager API 速查 + +### ScenarioManager — 基础数据 + 想定 + +```csharp +var mgr = GetComponent(); + +// 基础数据 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) → TaskFullConfig +``` + +### SimulationRunner — 仿真执行 + +```csharp +var runner = GetComponent(); +runner.LoadAndStart(taskId); +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(); +rm.Generate(taskId, detail, events, status, duration) → SimulationReport +rm.Export(reportId) → 文件路径 +``` + +### ReplayController — 回放 + +```csharp +var replay = GetComponent(); +replay.LoadReplay(taskId); +replay.TotalFrames / replay.GetFrame(index) +``` + +--- + +## 五、EntitySnapshot（每帧推送） | 字段 | 类型 | 说明 | |------|------|------| | `EntityId` | string | 实体唯一 ID | -| `EntityType` | enum | Drone/Platform/Munition/Cloud/DetectionEquip | +| `EntityType` | enum | Drone / Platform / Munition / Cloud / DetectionEquip | | `PosX/Y/Z` | float | 三维位置 | | `VelX/Y/Z` | float | 瞬时速度 (m/s) | | `Hp` | float | 无人机血量 (0~1) | -| `DamageStage` | int | 损伤阶段 (0~N) | -| `PlatformStateStr` | string | 平台状态 (Idle/FlyingToTarget/ReadyToRelease) | +| `DamageStage` | int | 损伤阶段 | +| `PlatformStateStr` | string | Idle / FlyingToTarget / ReadyToRelease | | `CloudRadius` | float | 云团有效半径 | -| `CloudOpacity` | float | 云团不透明度 (0~1) | -| `CloudPhase` | int | 云团扩散阶段 (1/2/3) | -| `CloudElapsed` | float | 云团已存在时间 (s) | +| `CloudOpacity` | float | 不透明度 (0~1) | +| `CloudPhase` | int | 扩散阶段 (1/2/3) | +| `CloudElapsed` | float | 已存在时间 (s) | -### 实体属性（直接访问） +--- + +## 六、实体属性速查 | 实体 | 关键属性 | |------|------| -| **DroneEntity** | Id, PosX/Y/Z, Hp, Status, ExposureTime, TargetType, PowerType, Wingspan, CruiseSpeed, Route, TraveledArc, TotalArc, Progress | -| **CloudEntity** | Id, PosX/Y/Z, Radius, Density, Phase, Elapsed, IsDissipated, AerosolType | -| **MunitionEntity** | Id, PosX/Y/Z, Velocity, StartX/Y/Z, LaunchTime, ElapsedTime, LaunchAngle, Azimuth, MuzzleVelocity, FlightDuration, TargetX/Y/Z, ReleaseAltitude, HasArrived | -| **PlatformEntity** | Id, PosX/Y/Z, CurrentVelocity, State, MunitionCount, Cooldown, MuzzleVelocity, CruiseSpeed, ReleaseAltitude, TargetX/Y/Z, FlightDistance | +| **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() | --- -## 五、基础数据 CRUD（DataService） - -`SimulationRunner.DataService` 提供 7 类基础数据的增删改查： - -```csharp -var ds = runner.DataService; - -// 弹药 -var ammo = ds.GetAllAmmo(); -ds.SaveAmmo(new AmmunitionSpec { Id = "custom", ... }); -ds.DeleteAmmo("custom"); - -// 火力单元规格 -ds.GetAllFireUnits(); -ds.SaveFireUnit(spec); -ds.DeleteFireUnit(id); - -// 无人机规格 -ds.GetAllDrones(); -ds.SaveDrone(spec); -ds.DeleteDrone(id); - -// 传感器规格 -ds.GetAllSensors(); -ds.SaveSensor(spec); -ds.DeleteSensor(id); - -// 环境规格 -ds.GetAllEnvironments(); -ds.SaveEnvironment(spec); -ds.DeleteEnvironment(id); - -// 编队模板 -ds.GetAllFormations(); -ds.SaveFormation(spec); -ds.DeleteFormation(id); - -// 航线模板 -ds.GetAllRoutes(); -ds.SaveRoute(spec); -ds.DeleteRoute(id); -``` - -### 规格类命名对照 +## 七、规格类命名对照 | 旧名 | 新名 | SQLite 表 | |------|------|------| @@ -241,48 +221,35 @@ ds.DeleteRoute(id); --- -## 六、默认数据 +## 八、默认数据 -首次运行 `DatabaseManager.OpenMainDb()` 自动从 `data/defaults.json` 种子数据库： +首次运行自动种子，含 6 个 `[Demo]` 预设想定： -| 类别 | 内容 | 示例 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` | - -所有默认数据名称含 `[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); -``` +| 类别 | 示例 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 -# 覆盖 Assets/Plugins/CounterDrone.Core/ 下所有 DLL ``` --- -## 八、参考 +## 十、参考 | 文档 | 位置 | |------|------| | 架构设计 | `docs/design/architecture/总体架构设计.md` | | 实体事件映射 | `docs/design/technical/仿真器实体与事件映射.md` | -| 任务跟踪 | `docs/implementation/tasks/实施计划与任务跟踪.md` | -| 测试报告 | `test/reports/`（每次集成测试自动生成） | | 测试状态 | **243 测试，11 秒（全部通过）** |