basil
/
vampire-like
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
vampire-like/skills/simulation-development/references/SimulationDevelopmentSkill.md

11 KiB
Raw Blame History

SimulationWorld Architecture Specification

文档定位

本文件是 SimulationWorld 的架构规范与扩展开发约束。

用途分为两部分：

  • 作为当前 SimulationWorld 实现的架构总览，说明模块职责、依赖边界、运行链路和数据所有权。
  • 作为后续扩展、重构、性能优化和回归修复时的约束文档，防止破坏核心不变量。

文档与实现冲突时，当前分支源码优先；提交前必须同步修正文档。

适用范围

  • Assets/GameMain/Scripts/Simulation/*
  • Assets/GameMain/Scripts/Procedure/Game/GameStateBattle.cs
  • Assets/GameMain/Scripts/Procedure/Game/ProcedureGame.cs
  • Assets/GameMain/Scripts/Utility/AIUtility.cs
  • Assets/Tests/Simulation/EditMode/*
  • Assets/Tests/Simulation/PlayMode/*

架构目标

  • 将战斗中的敌人、投射物、掉落物运行时状态收口到统一仿真容器。
  • 将热路径逻辑与 Unity 表现层解耦，避免在仿真阶段直接读写 Transform。
  • 为 Job/Burst 提供稳定的数据通道、生命周期管理和主线程结算收口点。
  • 保持 SimulationWorld 对外是单一战斗调度入口，而不是分散的业务入口集合。
  • 保证扩展新仿真对象或新碰撞规则时，能够沿着既有管线接入，而不是旁路修改。

非目标

  • 不负责完整战斗规则定义。伤害公式、碰撞业务语义仍由 AIUtility 和实体逻辑承担。
  • 不负责实体创建策略。实体创建与隐藏仍由外部流程和 Entity 系统负责。
  • 不追求全局 ECS 化。本模块仍以 SimulationWorld + partial + Native 容器 为中心组织。
  • 不在 Job 中直接驱动表现层、事件系统或 Unity 对象生命周期。

外部依赖与系统边界

SimulationWorld 处于战斗流程中层，位于 GameStateBattle 和具体实体逻辑之间。

上游依赖：

  • GameStateBattle.OnUpdate 驱动每帧 Tick。
  • GameEntry.Event 提供实体显示/隐藏事件，用于同步仿真容器生命周期。
  • GameEntry.Entity 提供实体查询、隐藏和表现事件消费。

下游协作：

  • AIUtility 负责伤害与碰撞业务结算。
  • Enemy/Projectile/Drop 实体提供初始化所需运行时数据。
  • Presentation 子模块负责把仿真结果写回表现层。

边界要求：

  • 外部业务代码不得直接增删 _enemies、_projectiles、_pickups。
  • 外部业务代码不得绕过 SimulationWorld 直接维护仿真索引。
  • SimulationWorld 不直接拥有实体生成权，只消费实体生命周期事件。

模块结构

SimulationWorld 使用 partial 拆分，职责按以下边界划分：

  • SimulationWorld.cs
    • 核心组件入口、主状态容器、基础依赖、Unity 生命周期入口。
  • SimulationWorld.SimEntityState.cs
    • 敌人、投射物、掉落物的仿真态创建、更新、删除和清空。
  • SimulationWorld.EntitySync.cs
    • 监听实体 show/hide 事件，将实体生命周期映射到仿真容器。
  • DataChannel/SimulationWorld.JobDataChannel.cs
    • Native 容器持有、初始化、清理、容量准备、仿真数据到 Job 数据的转换。
  • Jobs/SimulationWorld.EnemyJobs.cs
    • 每帧仿真主编排、敌人移动与互斥分离 Job 调度。
  • Jobs/SimulationWorld.ProjectileJobs.cs
    • 投射物移动、寿命处理、越界回收。
  • Jobs/SimulationWorld.CollisionPipeline.cs
    • 投射物与区域碰撞查询构建、候选筛选、主线程命中结算。
  • SimulationWorld.TargetSelectionSpatialIndex.cs
    • 敌人目标选择空间索引。
  • Presentation/SimulationWorld.TransformSync.cs
    • LateUpdate 表现写回。
  • Presentation/SimulationWorld.HitPresentation.cs
    • 命中事件的表现消费桥。

核心数据所有权

主容器

  • _enemies
  • _projectiles
  • _pickups

这些容器是真实仿真态所有者。Job 输入输出缓冲只是当前帧的镜像通道，不是持久源数据。

绑定关系

  • EntityBinding 维护 EntityId <-> SimulationIndex 双向映射。
  • 容器删除使用 swap-back。
  • 发生尾元素覆盖时，必须同步 RemapIndex。
  • 删除完成后再 Unbind，避免索引悬挂。

Native 容器

  • Job 通道一律使用 Allocator.Persistent。
  • 生命周期由 InitializeJobDataChannels / DisposeJobDataChannels 集中管理。
  • 帧间复用时使用 Clear，不允许用临时重建替代正常复用。
  • Job 数据与主容器数据之间的转换必须集中在 JobDataChannel 侧完成。

生命周期模型

实体进入仿真

统一由 EntitySync 监听实体显示事件后触发：

  • Enemy group -> RegisterEnemyLifecycle
  • Drop group -> RegisterPickupLifecycle
  • Bullet / Projectile / EnemyProjectile group -> RegisterProjectileLifecycle

实体退出仿真

统一由 EntitySync 监听实体隐藏事件后触发：

  • Enemy -> UnregisterEnemyLifecycle
  • Drop -> UnregisterPickupLifecycle
  • Projectile 相关 group -> UnregisterProjectileLifecycle

清场

ClearSimulationState 负责：

  • 清空主容器
  • 清空投射物回收与结算缓存
  • 清空区域碰撞请求与命中缓存
  • 清空 Job 通道
  • 清空全部 EntityBinding

运行时执行链路

帧级入口

  1. GameStateBattle.OnUpdate
  2. _enemyManager.OnUpdate(...)
  3. SimulationWorld.Tick(...)
  4. SimulationWorld.LateUpdate()

Tick 总流程

SimulationWorld.Tick 是战斗仿真的唯一主入口。

约束：

  • 当 UseSimulationMovement == false 时，直接返回。
  • Tick 只负责逻辑仿真与结算，不直接写 Transform。

每帧仿真管线

当前实现的标准顺序为：

  1. Early Return
    • DeltaTime <= 0 时只清理碰撞临时通道和统计。
  2. BuildInput
    • 将 _enemies / _projectiles 同步为 Job 输入。
    • 准备敌人输出、投射物输出、碰撞查询缓冲。
  3. StateUpdate
    • 调度敌人移动 Job。
    • 调度投射物移动 Job。
  4. Schedule
    • 按需调度敌人互斥分离 Job。
    • 合并敌人与投射物 Job 依赖。
  5. Complete
    • 等待本帧仿真 Job 完成。
  6. Collision
    • 构建碰撞查询。
    • 构建敌人碰撞桶。
    • 生成候选并统计。
  7. WriteBack
    • 把输出写回主容器。
    • 在主线程结算碰撞与伤害。
    • 回收失效投射物。

LateUpdate

LateUpdate 只做表现写回，不做逻辑判定：

  • 敌人位置/朝向写回
  • 投射物位置/朝向写回

线程模型与边界

Job/Burst 允许做的事

  • 读取 Job 输入缓冲
  • 写入 Job 输出缓冲
  • 写入 NativeHashMap / NativeList 等碰撞与分桶数据
  • 执行纯数据计算

Job/Burst 禁止做的事

  • 读写 Transform
  • 操作 GameObject / Entity 生命周期
  • 调用事件系统
  • 直接调用 AIUtility.PerformCollision
  • 进行托管分配、LINQ、装箱

主线程必须做的事

  • 应用输出到仿真主容器
  • 命中结算与伤害计算
  • 投射物失效回收
  • 命中表现事件派发
  • LateUpdate 表现写回

子系统约束

敌人仿真

固定接入点：

  • BuildInput
  • Movement
  • Separation
  • WriteBack

约束：

  • 敌人状态必须以 EnemySimData 为中心流动。
  • 互斥与移动结果必须先写入输出缓冲，再统一提交。
  • 与目标选择相关的空间索引脏标记必须在主容器变更时维护。

投射物仿真

固定接入点：

  • BuildInput
  • Movement
  • Collision Query
  • Resolve
  • Recycle

约束：

  • 投射物生命周期状态必须由 ProjectileSimData.Active 和 State 共同表达。
  • 投射物实际隐藏与移除只能在主线程回收阶段完成。

碰撞管线

职责：

  • 构建投射物查询和区域查询
  • 生成 broad-phase 候选
  • 在主线程做最终业务结算

约束：

  • Broad-phase 只能筛候选，不能替代最终命中判定。
  • Area Query 必须保留 SourceWasActiveAtQueryTime 快照语义。
  • 候选去重与区域命中去重只能在主线程收口。

目标选择空间索引

职责：

  • 提供按位置查询最近敌人的能力。

约束：

  • 仅在仿真启用时对外提供结果。
  • 敌人主容器变更后必须标记脏。
  • 索引是缓存，不是源数据；源数据仍是 _enemies。

Presentation

职责：

  • 将仿真层结果写回表现层。
  • 消费命中表现事件。

约束：

  • Presentation 只消费仿真结果，不反向修改仿真逻辑状态。
  • 任何新增表现都应接在 Presentation 子模块，而不是接回 Job 或业务结算热路径。

不可破坏的不变量

生命周期单入口

仿真容器的增删必须只经过 EntitySync 和 SimEntityState。

数据单一事实来源

主容器是持续态事实来源，Job 缓冲只是帧级副本。

逻辑与表现分离

逻辑阶段不写 Transform，表现阶段不做业务结算。

索引一致性

任何 swap-back 删除都必须同步 remap，否则视为架构级错误。

主线程结算收口

伤害、事件派发、实体隐藏和回收必须回到主线程。

空间索引与碰撞桶是缓存

它们可以重建，不可被外部业务当作持久数据依赖。

扩展开发流程

Step 0：判定接入位置

先判断新需求属于：

  • 新仿真态字段
  • 新执行阶段逻辑
  • 新碰撞查询类型
  • 新表现桥接

不要一开始就直接改 Tick 主流程。

Step 1：扩状态

先补 SimData、必要的 Job 输入输出结构和转换逻辑。

Step 2：接生命周期

如果是新实体类型，先定义 show/hide 到仿真态的映射，再进入执行阶段。

Step 3：接执行管线

优先复用已有阶段；只有确实无法收纳时才新增阶段，并补可观测的 profiler 标记。

Step 4：接主线程结算

需要业务判定、伤害、事件派发、实体隐藏时，一律回主线程收口。

Step 5：接表现

视觉写回、命中反馈、临时特效都放在 Presentation 侧。

Step 6：补测试

至少覆盖：

  • 正常行为
  • 空容器和边界条件
  • 删除后的索引稳定性
  • 碰撞去重或快照语义
  • 与旧路径一致的关键行为

Step 7：更新文档

修改模块边界、数据契约、不变量或执行阶段时，必须同步更新本文件。

回归关注点

  • ClearSimulationState 是否把主容器、缓存和 binding 一并清干净。
  • 删除路径是否保持 swap-back + remap 一致。
  • Job Native 容器是否有泄漏或容量管理回退。
  • 是否在热路径引入托管分配。
  • 是否让表现逻辑重新侵入仿真逻辑。
  • 是否破坏 Area Query 快照语义。
  • 是否破坏碰撞候选与命中去重。

测试建议

至少保留并持续扩展以下类型的测试：

  • Tick 行为正确性
  • 主线程与 Job 管线一致性
  • 最近敌查询正确性
  • 投射物候选上限与玩家候选覆盖
  • Area Query 快照语义
  • 清场和 Battle 循环稳定性

维护原则

如果未来需要继续扩展为多模式仿真开关、更多 Job 管线层级或新的仿真对象类型，应优先维护以下三点：

  • Tick 仍然只有一个主入口
  • 仿真态生命周期仍然只有一个注册/反注册入口
  • 主线程结算与表现写回边界不被打穿