From 2643f58b084664cde9ec0fec38f14d38bf262174 Mon Sep 17 00:00:00 2001 From: Joywayer Date: Wed, 29 Jul 2026 11:43:15 +0800 Subject: [PATCH] =?UTF-8?q?docs(enemy):=20=E8=AE=A1=E5=88=92=E5=90=8C?= =?UTF-8?q?=E6=AD=A5=E2=80=94=E2=80=94AiStateFragments=20=E7=A9=BA?= =?UTF-8?q?=E8=83=BD=E5=8A=9B=20id=20=E6=94=B9=E5=BB=BA=E5=9B=BE=E6=9C=9F?= =?UTF-8?q?=E6=8A=A5=E9=94=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 原稿沿用旧代码的静默跳过写法。AiStateFragments 成为公开原语后， 定制 AiScript 漏配 id 会产出"存在但什么都不做"的状态且无报错， 与 T1 引入 BrainBuilder.RequireState 的理由是同一类失败，不应双标。 校验放建图期而非每帧回调，兼顾快速失败与热路径开销。 Co-Authored-By: Claude Opus 5 (1M context) --- .../2026-07-29-enemy-ai-composable-modules.md | 29 ++++++++++++++++--- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/Docs_Dev/superpowers/plans/2026-07-29-enemy-ai-composable-modules.md b/Docs_Dev/superpowers/plans/2026-07-29-enemy-ai-composable-modules.md index f20643fd..2ab5763d 100644 --- a/Docs_Dev/superpowers/plans/2026-07-29-enemy-ai-composable-modules.md +++ b/Docs_Dev/superpowers/plans/2026-07-29-enemy-ai-composable-modules.md @@ -492,17 +492,23 @@ namespace BaseGames.Enemies /// 用于追击、冲锋这类"只要还在这个状态就该一直在做"的能力。 /// public static BrainBuilder.StateBuilder Ability(BrainBuilder b, string state, string abilityId) - => b.State(state) + { + RequireAbilityId(state, abilityId); + return b.State(state) .OnEnter(x => EnsureAbility(x, abilityId)) .Tick (x => EnsureAbility(x, abilityId)) .OnExit(x => x.Combat.InterruptAbilities()); + } /// /// 由能力驱动的一次性态：只在进入时触发，不每帧重触发。 /// 用于死亡等一次性演出——若用 Ability()，演出播完会被 Tick 无限重播。 /// public static BrainBuilder.StateBuilder AbilityOnce(BrainBuilder b, string state, string abilityId) - => b.State(state).OnEnter(x => EnsureAbility(x, abilityId)); + { + RequireAbilityId(state, abilityId); + return b.State(state).OnEnter(x => EnsureAbility(x, abilityId)); + } /// /// 无行为的终态。不需要在这里停移动——转入本态时，上一个态的 OnExit 已经收尾。 @@ -517,15 +523,30 @@ namespace BaseGames.Enemies else x.Locomotion.SetMode(mode); } + // 建图期校验：空 id 会让状态存在却什么都不做——敌人杵着不动、无任何报错， + // 正是 BrainBuilder.RequireState 要防的同一类静默失败。放建图期而非运行时回调里， + // 既能快速失败，也省掉热路径上每帧一次的判空。 + static void RequireAbilityId(string state, string abilityId) + { + if (string.IsNullOrEmpty(abilityId)) + throw new ArgumentException( + $"AiStateFragments: 状态 '{state}' 未配置能力 id。若该状态本就不需要能力" + + "（如死亡演出交给物理状态机），请改用 Terminal()。", nameof(abilityId)); + } + static void EnsureAbility(IAiContext x, string abilityId) { - if (!string.IsNullOrEmpty(abilityId) && !x.Combat.IsAbilityRunning(abilityId)) - x.Combat.UseAbility(abilityId); + if (!x.Combat.IsAbilityRunning(abilityId)) x.Combat.UseAbility(abilityId); } } } ``` +> 注：`RequireAbilityId` 是计划执行中根据质量审查加入的（原稿沿用了旧代码里 +> `if (!string.IsNullOrEmpty(abilityId) && ...)` 的静默跳过）。旧写法在 `AiStateFragments` +> 成为**公开**原语后不可接受——定制 AiScript 直接调用时，漏配 id 会产出一个什么都不做的 +> 状态且无任何报错。`Terminal()` 才是"本就不需要能力"的正确出口。 + - [ ] **Step 5: 运行测试确认通过** 运行 `AiStateFragmentsTests`。期望：5 项全部 PASS。