- 补充游戏核心逻辑

- 完成 TodOList P0 - 添加游戏内控制台便于调试 - 增加敌人互斥机制提高运算负载 - 优化互斥算法将游戏性能基准线拉到 1k 敌人
2026-02-20 18:08:27 +08:00
parent b4bc8b0445
commit 3742110e9a
196 changed files with 4868 additions and 31326 deletions
@@ -0,0 +1,47 @@
+## 测试机性能
+iQOO Neo8
+
+CPU: 第一代骁龙 8+ 八核
+
+内存: 12 GB
+
+系统: OriginOS 6 (Android 16)
+
+## CPU
+| 怪物数量   | 帧率（原始->优化）                             | Movement_Update 占比                  |
+|--------|----------------------------------------|-------------------------------------|
+| `100`  | `60.3 -> 60.2 fps (16.58 -> 16.59 ms)` | `64.2% -> 13.0% (10.74 -> 2.20 ms)` |
+| `200`  | `21.0 -> 60.3 fps (47.47 -> 16.57 ms)` | `81.1% -> 24.6% (41.54 -> 4.08 ms)` |
+| `300`  | `11.3 -> 60.5 fps (87.90 -> 16.51 ms)` | `88.9% -> 30.3% (89.61 -> 5.00 ms)` |
+| `400`  | `N/A  -> 61.3 fps (inf -> 16.31 ms)`   | `inf -> 33.5% (inf -> 5.47 ms)`     |
+| `500`  | `N/A  -> 59.9 fps (inf -> 16.69 ms)`   | `inf -> 37.7% (inf -> 6.30 ms)`     |
+| `1000` | `N/A  -> 24.6 fps (inf -> 28.90 ms)`   | `inf -> 47.8% (inf -> 13.83 ms)`    |
+| `1500` | `N/A  -> 24.0 fps (inf -> 41.63 ms)`   | `inf -> 52.6% (inf -> 21.91 ms)`    |
+| `2000` | `N/A  -> 16.8 fps (inf -> 59.27 ms)`   | `inf -> 52.9% (inf -> 30.70 ms)`    |
+
+tip:
+1. 60 fps 为 Android 端帧率上限，具体可参考 CPU ms 耗时
+2. 注意 Profiler 里会产生性能损耗的配置（Call Stacks）
+3. `N/A` 和 `inf` 表示 未测试/不可用
+
+### Memory
+| 怪物数量 | GC Used Memory | GC Allocated In Frame |
+|------|----------------|-----------------------|
+| 100  | 6.7 MB         | 15.7 KB               |
+| 200  | 7.5 MB         | 15.7 KB               |
+| 300  | 166.2 KB       | 15.7 KB               |
+
+
+### Render
+| 维度                   | 100 enemies | 200 enemies | 300 enemies |
+|----------------------|-------------|-------------|-------------|
+| SetPass Calls        | 117         | 115         | 119         |
+| Draw Calls           | 120         | 119         | 123         |
+| Batches              | 120         | 119         | 123         |
+| **Static Batching:** |             |             |
+| Batched Draw Call    | 0           | 0           | 0           |
+| Batched              | 0           | 0           | 0           |
+| **Instancing:**      |             |             |
+| Batched Draw Call    | 93          | 196         | 297         |
+| Batched              | 1           | 2           | 4           |
+
@@ -0,0 +1,119 @@
+# 3D 类吸血鬼幸存者项目 Todo（GameMain 侧规划）
+
+> 范围说明：本清单基于当前 `Assets/GameMain` 代码现状制定，未涉及 `Assets/GameFramework` 底层实现。
+
+## 0. 当前代码现状（已确认）
+- [x] 已有完整流程骨架：`Menu -> Game(Battle/LevelUp/Shop)`，以及基础实体系统（Player/Enemy/Weapon/Drop/UI）。
+- [x] 目前仍是传统 `MonoBehaviour + 每实体 OnUpdate` 驱动，暂无 Job System/Burst 实装。
+- [x] 已有一个 Instancing Shader：`Assets/GameMain/Materials/Shaders/SimpleInstancedFlash.shader`，但未接入运行时批量渲染管线。
+- [x] 未发现代码热更新方案接入（如 HybridCLR/ILRuntime/xLua 等）。
+
+## 1. P0 基线修正与性能基准
+- [x] 建立性能基准场景（建议复用 `Game.unity` + 压测参数）：
+  - 指标：`1k / 2k / 3k` 敌人时的 FPS、CPU Main Thread、GC Alloc、Draw Calls。
+  - 输出：一份基线表格（开发机配置 + Unity Profiler 截图）。
+- [x] 修正当前高风险逻辑问题（避免后续优化建立在不稳定行为上）：
+  - `ProcedureGame.OnEnter()` 与 `_hudInitialized` 逻辑中有重复初始化状态机风险（`InitGameState()` 被调用两次）。
+  - `Player.Enable` setter 未更新 `_enable` 字段，状态切换语义不完整。
+  - `PlayerData` 构造中 `MaxHealthBase` 初始化异常（自赋值）。
+  - `AIUtility.PerformCollision()` 武器伤害计算参数里疑似把 `DodgeStat` 传成 `DefenseStat`。
+- [x] 给关键战斗链路加最小回归测试（PlayMode）：
+  - 伤害结算、掉落、回合切换（Battle/LevelUp/Shop）。
+
+**验收标准**
+- 基线数据可复现。
+- 以上问题修正后，核心流程可稳定连续跑 10 分钟无异常日志。
+
+## 2. P1 Simulation 分层（为 Job/Burst 做结构准备）
+- [ ] 新建 `Simulation` 层（建议目录：`Assets/GameMain/Scripts/Simulation`）：
+  - `SimulationWorld`：统一持有敌人/投射物/掉落物的纯数据容器。
+  - `EnemySimData / ProjectileSimData / PickupSimData`：结构化、连续内存友好的数据定义。
+  - `EntityBinding`：维护 `EntityId <-> SimulationIndex` 映射。
+- [ ] 将“逻辑计算”和“表现层（Transform/Animator/特效/UI）”拆离：
+  - 逻辑层输出 position/rotation/state。
+  - 表现层只消费结果做显示。
+- [ ] 先保持现有 GameFramework 实体生命周期不变，仅替换更新路径。
+
+**验收标准**
+- 敌人移动/追踪由 Simulation 统一调度，不再逐个 Enemy MonoBehaviour 执行核心逻辑。
+
+## 3. P2 Job System + Burst 落地（核心性能阶段）
+- [ ] 引入并锁定依赖版本（Unity 2022.3 对应）：
+  - `com.unity.collections`
+  - `com.unity.jobs`
+  - `com.unity.burst`
+  - `com.unity.mathematics`
+- [ ] 第一批 Job 化模块（优先级从高到低）：
+  1. 敌人移动与朝向更新（`IJobParallelFor`）。
+  2. 目标选择加速（空间哈希/网格分桶，减少全量最近邻搜索）。
+  3. 投射物批量移动与寿命回收。
+  4. AOE/碰撞候选筛选（先 broad phase，后精算）。
+- [ ] Burst 编译策略：
+  - 热路径 Job 全部 `[BurstCompile]`。
+  - 禁止在 Job 内使用托管分配、虚调用、LINQ。
+- [ ] 主线程仅做：输入采样、状态切换、UI同步、实体显隐。
+
+**验收标准**
+- 在 3k 敌人规模下，CPU Main Thread 明显下降（目标 >= 30%）。
+- Profiler 中战斗帧 GC Alloc 接近 0（持续帧）。
+
+## 4. P3 GPU Instancing 渲染管线（与 Job 并行推进）
+- [ ] 先做“低风险版”批处理：
+  - 同 Mesh/Material 的敌人分组，使用 `Graphics.DrawMeshInstanced`（每批最多 1023）。
+- [ ] 再升级“高上限版”：
+  - 使用 `Graphics.DrawMeshInstancedIndirect` + `ComputeBuffer` 管理实例矩阵/颜色/状态。
+- [ ] 建立 `InstanceRendererComponent`：
+  - 输入：Simulation 输出的 transform/state。
+  - 输出：按 enemy archetype 的批量绘制。
+- [ ] 将受击闪白、稀有度颜色等通过 `MaterialPropertyBlock` 或实例化属性下发（复用现有 Instanced Shader 思路）。
+- [ ] 与现有碰撞体系解耦：
+  - 逻辑碰撞走 Simulation，渲染不再依赖每敌人独立 GameObject Renderer。
+
+**验收标准**
+- 5k 敌人规模 Draw Calls 显著下降。
+- 渲染主线程耗时可控，且视觉行为（受击、朝向、死亡）与逻辑一致。
+
+## 5. P4 代码热更新（建议 HybridCLR）
+- [ ] 技术选型定稿：建议 `HybridCLR`（Unity 2022 + C# 生态兼容更自然）。
+- [ ] Assembly 拆分：
+  - `Main`：启动、资源更新、基础桥接（不可热更）。
+  - `Hotfix`：玩法规则、数值公式、技能与敌人行为树（可热更）。
+- [ ] 运行时加载流程：
+  - 启动时通过现有资源更新流程拉取热更 DLL（与版本号绑定）。
+  - 加载 AOT metadata + Hotfix DLL，反射启动 `HotfixEntry`。
+- [ ] 建立热更边界规范：
+  - Hotfix 不直接依赖编辑器代码。
+  - 跨域调用统一走接口/Facade（避免大量反射散落）。
+- [ ] 回滚机制：
+  - DLL 校验失败时回退上一个稳定版本。
+
+**验收标准**
+- 不发整包即可替换一条技能逻辑并在设备上生效。
+- 热更失败可自动回退，启动不中断。
+
+## 6. P5 玩法目标对齐（与技术栈并行）
+- [ ] 武器系统补完：
+  - 自动攻击、多武器并存、同武器升级/进化。
+  - `Shop` 武器购买流程补完（当前已有 TODO）。
+- [ ] 敌人系统扩展：
+  - 近战/远程/精英/首领模板化，支持波次参数化。
+- [ ] 关卡节奏：
+  - `DRLevel` 扩展为“时间轴+事件波次+奖励节点”。
+- [ ] 数值可调试工具：
+  - 实时查看 Dps、受击、击杀效率、掉落速率。
+
+**验收标准**
+- 一局 10~20 分钟循环可闭环，且关卡难度曲线平滑。
+
+## 7. 推荐执行顺序（避免返工）
+- [ ] 里程碑 A：`P0 -> P1`（稳定结构 + 可观测）
+- [ ] 里程碑 B：`P2`（CPU 性能突破）
+- [ ] 里程碑 C：`P3`（渲染性能突破）
+- [ ] 里程碑 D：`P4`（线上快速迭代能力）
+- [ ] 里程碑 E：`P5`（内容量与可玩性扩展）
+
+## 8. 交付物清单（每阶段都要有）
+- [ ] 设计文档（接口、数据结构、生命周期）。
+- [ ] 回归用例（至少战斗、关卡切换、商店、升级）。
+- [ ] Profiling 对比（改造前后同场景同参数）。
+- [ ] 风险与回滚说明（特别是热更新与渲染链路）。
@@ -0,0 +1,134 @@
+# Weapon Development Skill（VampireLike）
+
+## 目标
+本文件是 `Entity.Weapon` 体系的开发规范与速查手册。
+后续新增武器或扩展机制时，优先按本文档执行，避免重复通读历史上下文。
+
+## 当前架构总览
+- 武器运行时入口：`WeaponBase`（`Assets/GameMain/Scripts/Entity/EntityLogic/Weapon/WeaponBase.cs`）
+- 武器具体实现：`WeaponKnife`、`WeaponHandgun`、`WeaponSlash`
+- 目标选择策略：`ITargetSelector` + `TargetSelectorType`
+- 攻击可视化：`IWeaponAttackEffect`
+- 数据入口：`DRWeapon` -> `WeaponData`（及其子类）
+- 实体生成：`EntityExtension.ShowWeapon`
+
+## WeaponBase 统一职责（已上收）
+`WeaponBase` 负责以下通用逻辑，子类不要重复实现：
+- 生命周期模板：`OnShow/OnHide/OnAttachTo/OnDetachFrom`
+- 状态机管理：`RegisterState`、`EnsureStatesBuilt`、`TransitionTo`
+- 通用运行字段：`_target`、`_currAttackTimer`、`_sqrRange`
+- 启用门控：`OnUpdate` 中统一 `if (!_isEnabled) return`
+- 目标选择入口：`SelectTarget`、`SetTargetSelector`、`CreateSelector`
+- 距离判定：`IsInRange`（基于 XZ 平面距离）
+- 玩家攻击属性订阅：`BindAttackStatFromOwner` / `ReleaseAttackStatSubscription`
+
+## 状态机约定
+统一状态枚举：
+- `Idle`
+- `Check_OutRange`
+- `Check_InRange`
+- `Attack`
+- `Disabled`（可选）
+
+推荐流程：
+1. `Idle`：查找目标，计时器持续累积。
+2. `Check_OutRange`：有目标但不在攻击范围，继续转向并累积计时。
+3. `Check_InRange`：在攻击范围内，若 `currAttackTimer >= Cooldown` 切 `Attack`。
+4. `Attack`：执行攻击，重置计时器，结束后回 `Check_InRange`。
+
+关键规则：
+- 即使没有目标，也允许蓄力（计时器持续走）。
+- 一旦进入 `Check_InRange` 且冷却已满，应立即触发攻击。
+
+## 3D 场景下的距离/朝向原则
+- 射程与目标筛选：优先使用 XZ 平面距离（忽略 Y），调用 `AIUtility.GetSqrMagnitudeXZ`。
+- 视觉朝向与弹道：可按武器设计决定是否使用完整 3D 向量。
+  - `WeaponHandgun`：允许俯仰瞄准，逻辑上用射线命中对象判定伤害。
+  - 近战地面范围类（Knife/Slash）：伤害检测建议投影到地面（XZ）再判定。
+
+## 目标选择策略规范
+接口：`ITargetSelector.SelectTarget(WeaponBase weapon, IEnumerable<EntityBase> candidates, float maxSqrRange)`
+
+现有策略：
+- `NearestTargetSelector`
+- `HighestHealthTargetSelector`
+- `LowestHealthTargetSelector`
+
+语义约定：
+- `HighestHealth` / `LowestHealth` 必须按“当前血量”筛选。
+- 当前实现读取 `HealthComponent.CurrentHealth`。
+
+扩展策略步骤：
+1. 新建 selector 类并实现 `ITargetSelector`。
+2. 更新 `TargetSelectorType` 枚举。
+3. 在 `WeaponBase.CreateSelector` 中注册。
+4. 武器在 `OnWeaponShow` 或构造阶段选择策略。
+
+## 攻击可视化效果规范
+接口：`IWeaponAttackEffect.Play(WeaponBase weapon, Vector3 position, EntityBase target, float radius)`
+
+约定：
+- 可视化逻辑与伤害逻辑解耦。
+- 武器类只负责触发 `Play`，不把可视化细节塞回武器核心逻辑。
+- 当前阶段允许临时对象创建；后续若有性能压力再统一对象池化。
+
+## 数据层规范（DRWeapon / WeaponData）
+`DRWeapon` 提供通用字段：
+- `Attack`、`Cooldown`、`AttackRange`、`AttackSoundId`
+- `Pramas`（字典，Key 建议统一转小写）
+- `Modifiers`
+
+约定：
+- 参数解析尽量在数据层/初始化阶段完成。
+- 武器逻辑层读取 `WeaponData` 的强类型结果，不要散落 `Parse`。
+- 解析时必须容错：优先 `TryParse` + 默认值，避免运行时异常。
+
+## 新增武器标准流程
+1. 定义枚举
+   - 更新 `WeaponType`（保持递增值，避免重排已有值）。
+
+2. 建立数据类
+   - 新建 `WeaponXxxData : WeaponData`。
+   - 如果有独有参数，提供强类型字段或统一初始化逻辑。
+
+3. 建立行为类
+   - 新建 `WeaponXxx : WeaponBase`。
+   - 只实现差异化逻辑：`BuildStates`、`Check`、`Attack`、特有检测/动画。
+
+4. 建立状态类
+   - 推荐放在 `Weapon/WeaponXxx/` 目录，采用 partial 组织：
+     - `WeaponXxx.cs`
+     - `WeaponXxx.IdleState.cs`
+     - `WeaponXxx.CheckOutRangeState.cs`
+     - `WeaponXxx.CheckInRangeState.cs`
+     - `WeaponXxx.AttackState.cs`
+
+5. 建立可视化（可选）
+   - 新建 `WeaponXxxAttackEffect : IWeaponAttackEffect`，在武器中组合调用。
+
+6. 若为远程武器，建立子弹实体
+   - `BulletXxx : Bullet`
+   - `BulletXxxData : BulletData`
+   - 通过武器赋予伤害/阵营参数。
+   - 自动销毁应走对象池回收。
+
+7. 接入实体展示与数据表
+   - 确保 `DRWeapon` / `DREntity` 配置齐全。
+   - `EntityExtension.ShowWeapon` 可正确映射到 `Entity.Weapon.WeaponXxx`。
+
+8. 联动系统
+   - 背包、商店购买/出售、UI 展示、事件流刷新。
+
+## 代码检查清单（提交前）
+  - 是否重复实现了 `WeaponBase` 已有通用逻辑。
+    - 状态流转是否会卡死或漏转场。
+    - 冷却计时是否在无目标时仍正常累积。
+    - 目标失效（null/Unavailable/死亡）是否安全处理。
+    - 命中检测是否符合武器设计（地面范围/射线/扇形）。
+    - 数据参数是否全部容错解析。
+    - 可视化是否与伤害逻辑解耦。
+    - 是否正确订阅/解绑攻击属性（或复用基类方法）。
+
+## 已知注意点
+  - 目录中存在 `Pramas` 命名拼写历史包袱，保持兼容即可。
+    - 文档中的“规范”优先级高于历史实现；历史实现若偏离，按本规范逐步收敛。