diff --git a/Docs/superpowers/specs/2026-07-03-enemy-ai-framework-design.md b/Docs/superpowers/specs/2026-07-03-enemy-ai-framework-design.md index b9f03869..30635bdd 100644 --- a/Docs/superpowers/specs/2026-07-03-enemy-ai-framework-design.md +++ b/Docs/superpowers/specs/2026-07-03-enemy-ai-framework-design.md @@ -120,6 +120,14 @@ Behavior Designer 的行为树是**手绘的二进制图资产**: - **LOD 调度**:idle/离屏慢 tick、战斗每帧;中央 `AiScheduler` 时间片分摊避免帧尖峰;**事件转换不受 LOD 影响、永远即时**。 - 共享不可变定义 + 极小实例态 → 低 GC、cache 友好。 +### 3.8 多实例复用与对象池(同一场景多个相同敌人) + +- **共享 `AiGraph`(每敌人类型 1 份,flyweight)**:状态图结构、转换、能力编排、条件 lambda、`[CallerArgumentExpression]` 抓到的条件文本标签,全部只构建一次、由该类型所有实例共享。场景放 N 个相同杂兵 → 结构零 per-instance 分配、无重复 GC、缓存友好。 +- **每实例 `AiRuntime`(N 份)**:仅当前状态指针、`Blackboard`、计时器、`AbilitySequence` 游标随实例独立演化。 +- **无实例捕获约束**:声明里的条件/动作 lambda 只能通过参数 `c`(上下文)访问实例,**不得闭包捕获具体敌人实例**——这是 lambda 能挂在共享图上的前提。由 `BrainBuilder` 约定保证(后续可加 Roslyn 分析器强校验)。 +- **对象池重置**:`EnemyBase : IPoolable`(池复用走 `ForceStateRespawn`)。敌人回池再生时,`EnemyAiBrain` 必须重置 `AiRuntime`:回到 Entry 状态、清空黑板/计时器/游标、清空 trace。**共享 `AiGraph` 不重置**(无状态)。挂进 `IPoolable` 的回收/取出回调。 +- **调度分摊**:`AiScheduler` 对同类多实例做 tick 时间片错峰(见 §3.7),避免 N 个相同敌人同帧集中评估造成尖峰。 + --- ## 4. 能力接口 ↔ 现有实现 1:1 映射 @@ -280,4 +288,5 @@ public sealed class BasicMeleeGruntAi : EnemyAiScript 4. `BaseGames/AI/Export Graph` 能为上述两个敌人导出与运行行为一致的 Mermaid 图。 5. 运行时经 MCP `unity_execute_code` 调 `AiDebugService.GetAgent(id)` 能取到当前状态/转换原因/黑板/能力/门状态。 6. 脚手架放置敌人时自动挂 `EnemyAiBrain` 并绑定定义 + 参数 SO(无手动步骤)。 -7. 通过项目自检:SO 校验、AddressKey 校验、Physics2D 层校验无新增错误。 +7. **多实例复用**:同一场景放多个相同敌人时,共享同一 `AiGraph`(每类型仅构建 1 次),各自 `AiRuntime` 独立互不干扰;敌人经对象池回收再生后 `AiRuntime` 完全重置、无上一条命的状态残留。 +8. 通过项目自检:SO 校验、AddressKey 校验、Physics2D 层校验无新增错误。