引入 claude code 和 初始化 codex

docs/TODO.md

@@ -0,0 +1,144 @@
+# CodeX TODO
+
+## GPU Instancing 改造路线
+
+### 目标定义
+
+- `SimulationWorld` 继续作为敌人 `position / rotation / state` 的唯一真相源。
+- 新增 `InstanceRendererComponent` 作为 Presentation 侧批量渲染组件，不把批次构建和 GPU Buffer 管理塞回 `SimulationWorld`。
+- 先做 `Graphics.DrawMeshInstanced` 低风险版，确认链路跑通后，再决定是否升级到 `DrawMeshInstancedIndirect`。
+- P3 首阶段只处理“敌人批量渲染”，不同时扩大到投射物、掉落物和所有特效。
+
+### 架构边界
+
+- `SimulationWorld`
+  - 只负责逻辑 Tick、生命周期同步、状态容器与碰撞结算。
+  - 不负责 `Mesh / Material / MaterialPropertyBlock / ComputeBuffer`。
+- `InstanceRendererComponent`
+  - 只负责收集可渲染实例、按 `Mesh + Material + Shadow + Layer + RenderState` 分组、构建 batch、发起 draw call。
+  - 只消费 `SimulationWorld` 输出，不反写 sim 状态。
+- `TransformSync`
+  - P3 第一阶段继续保留，用于 HPBar、受击特效、挂点和现有表现依赖。
+  - 不要求一开始就把所有敌人 `Transform` 写回移除，否则风险过高。
+- 敌人 GameObject
+  - 第一阶段继续保留，用于碰撞、生命周期、事件桥和表现挂点。
+  - 仅逐步移除“每敌人独立 MeshRenderer”这条渲染路径。
+
+### 组件规划
+
+1. 新增批量渲染组件骨架
+   - 建议文件：
+     - `Assets/GameMain/Scripts/CustomComponent/InstanceRendering/InstanceRendererComponent.cs`
+     - `Assets/GameMain/Scripts/CustomComponent/InstanceRendering/EnemyInstanceRegistry.cs`
+     - `Assets/GameMain/Scripts/CustomComponent/InstanceRendering/EnemyInstanceBatch.cs`
+   - 建议职责：
+     - `InstanceRendererComponent`：帧级调度、统一提交 draw call。
+     - `EnemyInstanceRegistry`：维护 `EntityId -> RenderBinding`，缓存 mesh/material/archetype。
+     - `EnemyInstanceBatch`：缓存每组矩阵、颜色、闪白参数和批次拆分结果。
+
+2. 接入 `GameEntry`
+   - 文件：`Assets/GameMain/Scripts/Base/GameEntry.Custom.cs`
+   - 处理：
+     - 增加 `GameEntry.InstanceRenderer`
+     - 与 `SimulationWorld` 一样在启动时自动获取或挂载组件
+
+### 第一阶段：低风险版 `DrawMeshInstanced`
+
+1. 建立渲染注册表
+   - 注册时机：敌人 show 时缓存渲染资源引用，hide 时释放注册。
+   - 注册内容：
+     - `EntityId`
+     - `Mesh`
+     - `Material`
+     - 阴影/Layer/子类型信息
+     - 受击闪白、稀有度色等实例化属性默认值
+   - 约束：
+     - 注册表只缓存渲染资源和 archetype，不缓存位置真相数据。
+
+2. 从 `SimulationWorld` 读取实例数据
+   - 读取来源：`_enemies` 或对外只读查询接口。
+   - 每帧收集：
+     - `Matrix4x4`
+     - 朝向/缩放
+     - `flashAmount`
+     - `baseColor`
+     - 其他实例化参数
+   - 约束：
+     - 由 sim 输出生成当前帧渲染数据，不从敌人 `Transform` 反推逻辑状态。
+
+3. 按批次分组并提交
+   - 分组键至少包含：
+     - `Mesh`
+     - `Material`
+     - `ShadowCastingMode`
+     - `ReceiveShadows`
+     - `Layer`
+     - 需要的渲染状态位
+   - 提交方式：
+     - 每批最多 `1023` 实例
+     - 使用 `Graphics.DrawMeshInstanced`
+     - 通过 `MaterialPropertyBlock` 下发实例颜色和闪白参数
+
+4. 接入现有 Instanced Shader
+   - 文件：`Assets/GameMain/Materials/Shaders/SimpleInstancedFlash.shader`
+   - 处理：
+     - 复用现有 `_BaseColor / _FlashColor / _FlashAmount` 实例化属性
+     - 确认敌人材质启用 instancing
+     - 不在第一阶段同时改复杂动画或多 Pass 材质
+
+5. 替换敌人独立 Renderer 路径
+   - 第一阶段做法：
+     - 保留敌人实体和挂点
+     - 禁用敌人身上的 `MeshRenderer/SkinnedMeshRenderer`
+     - 改由 `InstanceRendererComponent` 统一绘制
+   - 约束：
+     - 碰撞、伤害、掉落、状态切换仍完全走现有逻辑链路
+
+### 第二阶段：高上限版 `DrawMeshInstancedIndirect`
+
+1. 升级批次数据结构
+   - 将 `Matrix4x4[]` 和实例属性数组迁移到 `ComputeBuffer` / `GraphicsBuffer`
+   - 建立按 archetype 持久复用的 buffer，避免每帧重建
+
+2. 升级提交方式
+   - 使用 `Graphics.DrawMeshInstancedIndirect`
+   - 为实例数量、剔除结果和参数下发建立独立 buffer
+
+3. 逐步加入可选优化
+   - 视锥剔除
+   - 距离分层
+   - LOD
+   - 大规模敌人下的批次复用和 buffer 容量管理
+
+4. 进入该阶段的前提
+   - `DrawMeshInstanced` 版本已验证视觉正确
+   - `5k` 规模下 draw call 或主线程提交成本仍是瓶颈
+   - 否则不要过早把复杂度拉到 `Indirect`
+
+### 风险控制
+
+- 不要把 GPU batch 容器放进 `SimulationWorld` 主状态里。
+- 不要让碰撞、索引或目标选择依赖 `InstanceRendererComponent`。
+- 不要一上来就移除 `TransformSync`，先保住现有 HPBar/特效/挂点行为。
+- 不要在第一阶段同时处理敌人、投射物、掉落物三类 instancing。
+
+### 验证口径
+
+1. 功能回归
+   - 敌人朝向、受击闪白、死亡隐藏、精英/普通配色与当前一致
+   - `Battle -> LevelUp -> Shop -> Battle` 循环不丢渲染实例
+
+2. Profiling 指标
+   - `0.5k / 1k / 1.5k / 2k / 5k` 敌人
+   - `Draw Calls`
+   - `SetPass Calls`
+   - `Main Thread`
+   - Render Thread / GPU 时间
+
+3. 阶段验收
+   - 第一阶段验收：
+     - 先证明 `DrawMeshInstanced` 跑通且视觉一致
+     - Draw Calls 相比当前路径明显下降
+   - 第二阶段验收：
+     - `5k` 敌人规模下主线程提交和渲染耗时继续下降
+     - buffer 生命周期稳定，无泄漏、无错绘、无实例残留