From 0f676b0e88572c2368a4b98f0d1f287e961f9b32 Mon Sep 17 00:00:00 2001 From: Joywayer Date: Fri, 31 Jul 2026 11:50:40 +0800 Subject: [PATCH] =?UTF-8?q?feat(ai):=20Build()=20=E6=A0=A1=E9=AA=8C?= =?UTF-8?q?=E3=80=8C=E9=9D=9E=E7=BB=88=E6=80=81=E5=BF=85=E9=A1=BB=E6=9C=89?= =?UTF-8?q?=E5=87=BA=E5=8F=A3=E3=80=8D=EF=BC=8C=E5=A0=B5=E4=BD=8F=E9=9B=B6?= =?UTF-8?q?=E6=8A=A5=E9=94=99=E7=9A=84=E6=B0=B8=E4=B9=85=E5=8D=A1=E6=AD=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit BrainBuilder.Build() 此前只做正向校验——边指向的态是否已声明（RequireState 的同款关切）；反向从不检查。一个已声明却没有任何出边的非终态，会让敌人进去 就永久停在那里，且全程零报错。计划里点名的风险点是 BossFragments.PhaseTransition： 它按设计不自带出边，出口全靠调用方补挂，漏一条就把 Boss 锁死。 做法：AiState 加 IsTerminal，StateBuilder 加 .Terminal() 显式标记， AiStateFragments.Terminal() 自带该标记；Build() 对「非终态且无出口」抛异常。 「有出口」的判定比计划原话严一档，两点都是照 AiRuntime 的实际行为定的： - 自转换不算——Switch 对 Target == 当前态直接 return false，根本出不去； - 全局转换不算——全局事件边要外部推信号才触发，不是自主出口。把它算作出口， 等于让「只有死了才出得去」的死角通过校验，而那恰是本校验要暴露的东西。 校验放在 Build() 而非各生产入口：生产的完整图装配点是 AiScript.GetOrBuildGraph 与 AiRecipeSO 两处，放 Build() 能让将来新增的入口默认受保护。代价是模块单测 需要一条别的路——单个 IUnawareModule / IEngagementModule 按设计只声明自己的态， 升级边由 PerceptionSkeleton 事后挂，单独构建时的死角是正常中间态而非缺陷。 为此加 BuildPartial()：跳过本项校验，其余照旧。 测试侧按语义分两类处理，没有一刀切： - 概念上确实是终态的（Dead）标 .Terminal()，保留 Build() 的全量校验； - 隔离验证单个模块/片段的部分图改用 BuildPartial()； - AiScriptTests / AiDefinitionRegistryTests 的夹具经 GetOrBuildGraph 走生产 Build()，给桩汇态补了回边——这两条本就该验完整图。 - 断言 Build() 因别的原因抛异常的用例原样保留。 PerceptionSkeleton 与嘲风图建的都是完整图，无需改动即通过——这本身就是覆盖。 验证：编译 0 错；EditMode 269/269（264 + 新增 5）。 加校验后曾有 49 条既有测试变红，全部为上述两类夹具，逐条按语义修正后转绿。 变异验证：注释掉 ChaoFengAi 里 PhaseTx 的 txDone 出边后，ChaoFengAiTests 8 条全部变红，报错精确点名 'PhaseTransition'；还原后复验 269/269。 本改动之前，同样的删除是零报错的——Boss 会静默锁死在过渡态， 这正是本校验存在的理由。 Co-Authored-By: Claude Opus 5 --- .../EditMode/AI/AiDefinitionRegistryTests.cs | 4 +- Assets/Tests/EditMode/AI/AiFrameworkTests.cs | 26 +++--- Assets/Tests/EditMode/AI/AiRuntimeTests.cs | 8 +- Assets/Tests/EditMode/AI/AiScriptTests.cs | 3 +- .../EditMode/AI/AiStateFragmentsTests.cs | 3 +- .../AI/ApproachAttackEngagementTests.cs | 3 +- .../EditMode/AI/BrainBuilderDeadEndTests.cs | 81 +++++++++++++++++++ .../AI/BrainBuilderDeadEndTests.cs.meta | 11 +++ Assets/Tests/EditMode/AI/BrainBuilderTests.cs | 6 +- .../Tests/EditMode/AI/RushEngagementTests.cs | 3 +- .../Tests/EditMode/AI/UnawareModuleTests.cs | 3 +- Assets/_Game/Scripts/AI/AiState.cs | 6 ++ Assets/_Game/Scripts/AI/BrainBuilder.cs | 50 +++++++++++- .../AIBrain/Modules/AiStateFragments.cs | 3 +- 14 files changed, 184 insertions(+), 26 deletions(-) create mode 100644 Assets/Tests/EditMode/AI/BrainBuilderDeadEndTests.cs create mode 100644 Assets/Tests/EditMode/AI/BrainBuilderDeadEndTests.cs.meta diff --git a/Assets/Tests/EditMode/AI/AiDefinitionRegistryTests.cs b/Assets/Tests/EditMode/AI/AiDefinitionRegistryTests.cs index b9e40fb5..400edb24 100644 --- a/Assets/Tests/EditMode/AI/AiDefinitionRegistryTests.cs +++ b/Assets/Tests/EditMode/AI/AiDefinitionRegistryTests.cs @@ -11,7 +11,9 @@ namespace BaseGames.Tests.EditMode.AI { b.Entry("A"); b.State("A").To("B").When(c => c.Sensor.SeesPlayer(), "SeesPlayer"); - b.State("B"); + // 回边不可省：本夹具经 GetOrBuildGraph 走生产的 Build()， + // 它会校验「非终态必须有出口」——夹具也得是一张能自洽运转的图 + b.State("B").To("A").When(c => !c.Sensor.SeesPlayer(), "LostPlayer"); } } diff --git a/Assets/Tests/EditMode/AI/AiFrameworkTests.cs b/Assets/Tests/EditMode/AI/AiFrameworkTests.cs index 1c52d160..1494a843 100644 --- a/Assets/Tests/EditMode/AI/AiFrameworkTests.cs +++ b/Assets/Tests/EditMode/AI/AiFrameworkTests.cs @@ -7,6 +7,10 @@ namespace BaseGames.Tests.EditMode.AI /// BrainGraph 框架健壮性/边界测试：构图校验、转换优先级、全局转换、 /// 事件与条件优先、队列信号、自转换、trace 上限、Blackboard、dt 传递。 /// 与 AiRuntimeTests（主干行为）互补，覆盖易回归的边角。 + /// + /// 本文件的夹具多为「A → 桩汇态」的最小图，汇态刻意不挂出边， + /// 因此用 BuildPartial() 构建——它跳过「非终态必须有出口」校验， + /// 其余校验照旧。断言 Build() 抛异常的用例仍用 Build()。 /// public class AiFrameworkTests { @@ -66,7 +70,7 @@ namespace BaseGames.Tests.EditMode.AI .To("B").When(c => true, "first") .To("C").When(c => true, "second"); // 两者都真，先声明的 B 胜 b.State("B"); b.State("C"); - var rt = new AiRuntime(b.Build(), new FakeAiContext()); + var rt = new AiRuntime(b.BuildPartial(), new FakeAiContext()); rt.Tick(0.1f); Assert.AreEqual("B", rt.CurrentStateName); } @@ -80,7 +84,7 @@ namespace BaseGames.Tests.EditMode.AI b.Global().To("Panic").When(c => c.Vitals.HpBelow(0.3f), "lowHp"); var ctx = new FakeAiContext(); ctx.V.Hp = 0.1f; - var rt = new AiRuntime(b.Build(), ctx); + var rt = new AiRuntime(b.BuildPartial(), ctx); rt.Tick(0.1f); Assert.AreEqual("Panic", rt.CurrentStateName); } @@ -93,7 +97,7 @@ namespace BaseGames.Tests.EditMode.AI b.State("A").To("B").When(c => true, "local"); b.State("B"); b.State("G"); b.Global().To("G").When(c => true, "global"); // 全局先评估 - var rt = new AiRuntime(b.Build(), new FakeAiContext()); + var rt = new AiRuntime(b.BuildPartial(), new FakeAiContext()); rt.Tick(0.1f); Assert.AreEqual("G", rt.CurrentStateName); } @@ -109,7 +113,7 @@ namespace BaseGames.Tests.EditMode.AI .To("ByCond").When(c => true, "cond") // 条件恒真 .To("ByEvent").OnEvent(AiSignal.Died); // 事件优先(Tick 第1步) b.State("ByCond"); b.State("ByEvent"); - var rt = new AiRuntime(b.Build(), new FakeAiContext()); + var rt = new AiRuntime(b.BuildPartial(), new FakeAiContext()); rt.Send(AiSignal.Died); rt.Tick(0.1f); Assert.AreEqual("ByEvent", rt.CurrentStateName); @@ -124,7 +128,7 @@ namespace BaseGames.Tests.EditMode.AI b.State("B"); var ctx = new FakeAiContext(); ctx.S.Sees = true; - var rt = new AiRuntime(b.Build(), ctx); + var rt = new AiRuntime(b.BuildPartial(), ctx); rt.Send(AiSignal.Died); // A 无 Died 转换 → 被消费掉，不阻塞条件评估 rt.Tick(0.1f); Assert.AreEqual("B", rt.CurrentStateName); @@ -141,7 +145,7 @@ namespace BaseGames.Tests.EditMode.AI b.State("A").To("B").OnEvent(AiSignal.Died); b.State("B").OnEnter(c => c.Blackboard.Set("enters", c.Blackboard.Get("enters") + 1)); var ctx = new FakeAiContext(); - var rt = new AiRuntime(b.Build(), ctx); + var rt = new AiRuntime(b.BuildPartial(), ctx); rt.Send(AiSignal.Died); rt.Send(AiSignal.Died); rt.Tick(0.1f); @@ -162,7 +166,7 @@ namespace BaseGames.Tests.EditMode.AI .OnEnter(c => c.Blackboard.Set("enters", c.Blackboard.Get("enters") + 1)) .To("A").When(c => true, "self"); // 自转换 var ctx = new FakeAiContext(); - var rt = new AiRuntime(b.Build(), ctx); // 构造进入 → enters=1 + var rt = new AiRuntime(b.BuildPartial(), ctx); // 构造进入 → enters=1 rt.Tick(0.1f); // 自转换应 no-op，不重跑 OnEnter Assert.AreEqual(1, ctx.BB.Get("enters")); Assert.AreEqual("A", rt.CurrentStateName); @@ -178,7 +182,7 @@ namespace BaseGames.Tests.EditMode.AI .To("B").When(c => true, "go"); b.State("B"); var ctx = new FakeAiContext(); - var rt = new AiRuntime(b.Build(), ctx); + var rt = new AiRuntime(b.BuildPartial(), ctx); rt.Tick(0.1f); // 转换发生 → 当帧不应执行 A 的 OnTick Assert.AreEqual("B", rt.CurrentStateName); Assert.IsFalse(ctx.BB.Has("ticked")); @@ -191,7 +195,7 @@ namespace BaseGames.Tests.EditMode.AI b.Entry("A"); b.State("A").Tick((c, dt) => c.Blackboard.Set("dt", dt)); // 无转换 var ctx = new FakeAiContext(); - var rt = new AiRuntime(b.Build(), ctx); + var rt = new AiRuntime(b.BuildPartial(), ctx); rt.Tick(0.25f); Assert.AreEqual(0.25f, ctx.BB.Get("dt"), 1e-5f); } @@ -221,7 +225,7 @@ namespace BaseGames.Tests.EditMode.AI b.Global().To("Dead").OnEvent(AiSignal.Died); var ctx = new FakeAiContext(); ctx.V.Controllable = false; // 受击中（若无事件本会挂起） - var rt = new AiRuntime(b.Build(), ctx); + var rt = new AiRuntime(b.BuildPartial(), ctx); rt.Send(AiSignal.Died); rt.Tick(0.1f); Assert.AreEqual("Dead", rt.CurrentStateName); @@ -236,7 +240,7 @@ namespace BaseGames.Tests.EditMode.AI b.State("A").To("B").When(c => false, "t1"); // 第一次声明 b.State("A").To("C").When(c => true, "t2"); // 再次 State("A") 应取同一状态，累加转换 b.State("B"); b.State("C"); - var graph = b.Build(); + var graph = b.BuildPartial(); Assert.AreEqual(2, graph.GetState("A").Transitions.Count); var rt = new AiRuntime(graph, new FakeAiContext()); rt.Tick(0.1f); // t1 假、t2 真 → C diff --git a/Assets/Tests/EditMode/AI/AiRuntimeTests.cs b/Assets/Tests/EditMode/AI/AiRuntimeTests.cs index ab5559f5..5311acfd 100644 --- a/Assets/Tests/EditMode/AI/AiRuntimeTests.cs +++ b/Assets/Tests/EditMode/AI/AiRuntimeTests.cs @@ -20,7 +20,7 @@ namespace BaseGames.Tests.EditMode.AI .To("Search").When(c => c.Sensor.LostFor(2f), "LostFor(2s)"); b.State("Search") .To("Patrol").After(3f); - b.State("Dead"); + b.State("Dead").Terminal(); return b.Build(); } @@ -108,7 +108,7 @@ namespace BaseGames.Tests.EditMode.AI b.Entry("Start"); b.State("Start").OnEnter(c => c.Locomotion.SetMode(LocomotionMode.Idle)); var ctx = new FakeAiContext(); - var rt = new AiRuntime(b.Build(), ctx); + var rt = new AiRuntime(b.BuildPartial(), ctx); // 只验 OnEnter 的单态夹具，不是完整图 CollectionAssert.Contains(ctx.L.Calls, "SetMode:Idle"); } @@ -168,7 +168,7 @@ namespace BaseGames.Tests.EditMode.AI b.State("Idle").To("Flee").OnEvent(AiSignal.Died); b.State("Flee"); var ctx = new FakeAiContext(); - var rt = new AiRuntime(b.Build(), ctx); + var rt = new AiRuntime(b.BuildPartial(), ctx); // Flee 是夹具桩，不建完整图 rt.Send(AiSignal.Died); rt.Tick(0.1f); Assert.AreEqual("Flee", rt.CurrentStateName); @@ -180,7 +180,7 @@ namespace BaseGames.Tests.EditMode.AI var b = new BrainBuilder(); b.Entry("Dead"); int enterCount = 0; - b.State("Dead").OnEnter(c => enterCount++); + b.State("Dead").OnEnter(c => enterCount++).Terminal(); b.Global().To("Dead").OnEvent(AiSignal.Died); var ctx = new FakeAiContext(); var rt = new AiRuntime(b.Build(), ctx); diff --git a/Assets/Tests/EditMode/AI/AiScriptTests.cs b/Assets/Tests/EditMode/AI/AiScriptTests.cs index efb6a863..66835abf 100644 --- a/Assets/Tests/EditMode/AI/AiScriptTests.cs +++ b/Assets/Tests/EditMode/AI/AiScriptTests.cs @@ -13,7 +13,8 @@ namespace BaseGames.Tests.EditMode.AI BuildCount++; b.Entry("A"); b.State("A").To("B").When(c => c.Sensor.SeesPlayer(), "SeesPlayer"); - b.State("B"); + // 回边不可省：GetOrBuildGraph 走生产的 Build()，会校验「非终态必须有出口」 + b.State("B").To("A").When(c => !c.Sensor.SeesPlayer(), "LostPlayer"); } } diff --git a/Assets/Tests/EditMode/AI/AiStateFragmentsTests.cs b/Assets/Tests/EditMode/AI/AiStateFragmentsTests.cs index bfe448a8..603c6a28 100644 --- a/Assets/Tests/EditMode/AI/AiStateFragmentsTests.cs +++ b/Assets/Tests/EditMode/AI/AiStateFragmentsTests.cs @@ -11,7 +11,8 @@ namespace BaseGames.Tests.EditMode.AI var b = new BrainBuilder(); b.Entry("S"); build(b); - return new AiRuntime(b.Build(), ctx); + // 片段单独建图：被验的态就是唯一的态，没有出边是这类夹具的常态 + return new AiRuntime(b.BuildPartial(), ctx); } [Test] diff --git a/Assets/Tests/EditMode/AI/ApproachAttackEngagementTests.cs b/Assets/Tests/EditMode/AI/ApproachAttackEngagementTests.cs index f084d8ea..c62907c3 100644 --- a/Assets/Tests/EditMode/AI/ApproachAttackEngagementTests.cs +++ b/Assets/Tests/EditMode/AI/ApproachAttackEngagementTests.cs @@ -15,7 +15,8 @@ namespace BaseGames.Tests.EditMode.AI AiStateFragments.Locomotion(b, Rest, LocomotionMode.Patrol); m.Build(b, Rest); b.Entry(m.EntryState); - return new AiRuntime(b.Build(), ctx); + // 单独跑交战模块：Rest 的升级边由骨架挂，这里缺它是预期的部分图 + return new AiRuntime(b.BuildPartial(), ctx); } [Test] diff --git a/Assets/Tests/EditMode/AI/BrainBuilderDeadEndTests.cs b/Assets/Tests/EditMode/AI/BrainBuilderDeadEndTests.cs new file mode 100644 index 00000000..d468dee1 --- /dev/null +++ b/Assets/Tests/EditMode/AI/BrainBuilderDeadEndTests.cs @@ -0,0 +1,81 @@ +using NUnit.Framework; +using BaseGames.AI; +using BaseGames.Enemies; + +namespace BaseGames.Tests.EditMode.AI +{ + /// + /// Build() 必须挡住「非终态却没有出口」的状态。 + /// + /// 既有校验只做正向——边指向的态是否已声明（RequireState 的同款关切）； + /// 反向从不检查。一个已声明却没有任何出边的非终态会让敌人永久停在那里， + /// 且全程零报错，与 RequireState 要防的静默失败是同一类，只是方向相反。 + /// + public class BrainBuilderDeadEndTests + { + [Test] + public void Build_NonTerminalStateWithNoOutgoing_Throws() + { + var b = new BrainBuilder(); + b.Entry("A"); + b.DeclareState("A").To("B").When(c => true, "go"); + b.DeclareState("B"); // 忘了挂出边 + + var ex = Assert.Throws(() => b.Build()); + StringAssert.Contains("B", ex.Message, "报错必须点名是哪个态，否则大图里无从查起"); + } + + [Test] + public void Build_TerminalState_IsAllowedToHaveNoOutgoing() + { + var b = new BrainBuilder(); + b.Entry("A"); + b.DeclareState("A").To("Dead").When(c => true, "die"); + b.DeclareState("Dead").Terminal(); + + Assert.DoesNotThrow(() => b.Build()); + } + + [Test] + public void Build_StateWithOnlySelfTransition_Throws() + { + // 自转换在 AiRuntime.Switch 里是 no-op（Target == 当前态直接 return false）， + // 出不去——等同于没有出边，不能算作出口。 + var b = new BrainBuilder(); + b.Entry("A"); + b.DeclareState("A").To("B").When(c => true, "go"); + b.DeclareState("B").To("B").When(c => true, "self"); + + var ex = Assert.Throws(() => b.Build()); + StringAssert.Contains("B", ex.Message); + } + + [Test] + public void Build_GlobalTransition_DoesNotCountAsOutgoing() + { + // 全局事件边要外部推信号才触发，不是自主出口；把它算作出口， + // 等于让「只有死了才出得去」的死角通过校验——那正是要暴露的东西。 + var b = new BrainBuilder(); + b.Entry("A"); + b.DeclareState("A").To("B").When(c => true, "go"); + b.DeclareState("B"); + b.DeclareState("Dead").Terminal(); + b.Global().To("Dead").OnEvent(AiSignal.Died); + + Assert.Throws(() => b.Build()); + } + + [Test] + public void AiStateFragments_Terminal_MarksStateAsTerminal() + { + // 生产入口：骨架与 Boss 图都经这个片段声明死亡终态， + // 它必须自带标记，否则每个图都要额外记得手动标一次。 + var b = new BrainBuilder(); + b.Entry("A"); + b.DeclareState("A").To("Death").When(c => true, "die"); + AiStateFragments.Terminal(b, "Death"); + + Assert.DoesNotThrow(() => b.Build()); + } + } +} diff --git a/Assets/Tests/EditMode/AI/BrainBuilderDeadEndTests.cs.meta b/Assets/Tests/EditMode/AI/BrainBuilderDeadEndTests.cs.meta new file mode 100644 index 00000000..68581558 --- /dev/null +++ b/Assets/Tests/EditMode/AI/BrainBuilderDeadEndTests.cs.meta @@ -0,0 +1,11 @@ +fileFormatVersion: 2 +guid: 282b4a740e6e4f84ca26c5dbed5aee91 +MonoImporter: + externalObjects: {} + serializedVersion: 2 + defaultReferences: [] + executionOrder: 0 + icon: {instanceID: 0} + userData: + assetBundleName: + assetBundleVariant: diff --git a/Assets/Tests/EditMode/AI/BrainBuilderTests.cs b/Assets/Tests/EditMode/AI/BrainBuilderTests.cs index 899846aa..3fc11233 100644 --- a/Assets/Tests/EditMode/AI/BrainBuilderTests.cs +++ b/Assets/Tests/EditMode/AI/BrainBuilderTests.cs @@ -14,7 +14,7 @@ namespace BaseGames.Tests.EditMode.AI .To("Chase").When(c => c.Sensor.SeesPlayer(), "SeesPlayer"); b.State("Chase") .To("Patrol").When(c => c.Sensor.LostFor(2f), "LostFor(2s)"); - b.State("Dead"); + b.State("Dead").Terminal(); return b.Build(); } @@ -48,7 +48,7 @@ namespace BaseGames.Tests.EditMode.AI b.Entry("A"); b.State("A").To("B").When(c => true); b.State("B"); - var g = b.Build(); + var g = b.BuildPartial(); // B 是桩汇态，本例只验标签回退 Assert.AreEqual("cond", g.GetState("A").Transitions[0].Label); } @@ -102,7 +102,7 @@ namespace BaseGames.Tests.EditMode.AI b.Entry("A"); b.DeclareState("A").To("B").When(c => true, "go"); b.DeclareState("B"); - Assert.DoesNotThrow(() => b.Build()); + Assert.DoesNotThrow(() => b.BuildPartial()); // 只验 builder 可用，B 是桩汇态 } [Test] diff --git a/Assets/Tests/EditMode/AI/RushEngagementTests.cs b/Assets/Tests/EditMode/AI/RushEngagementTests.cs index ed5c41f2..c4a8b0a5 100644 --- a/Assets/Tests/EditMode/AI/RushEngagementTests.cs +++ b/Assets/Tests/EditMode/AI/RushEngagementTests.cs @@ -15,7 +15,8 @@ namespace BaseGames.Tests.EditMode.AI AiStateFragments.Locomotion(b, Rest, LocomotionMode.Patrol); m.Build(b, Rest); b.Entry(m.EntryState); - return new AiRuntime(b.Build(), ctx); + // 单独跑交战模块：Rest 的升级边由骨架挂，这里缺它是预期的部分图 + return new AiRuntime(b.BuildPartial(), ctx); } [Test] diff --git a/Assets/Tests/EditMode/AI/UnawareModuleTests.cs b/Assets/Tests/EditMode/AI/UnawareModuleTests.cs index bddeef41..4fe71bd7 100644 --- a/Assets/Tests/EditMode/AI/UnawareModuleTests.cs +++ b/Assets/Tests/EditMode/AI/UnawareModuleTests.cs @@ -13,7 +13,8 @@ namespace BaseGames.Tests.EditMode.AI m.Declare(b); m.Link(b); b.Entry(m.Entry); - return new AiRuntime(b.Build(), ctx); + // 不挂骨架升级边，未发现层的态本就没有出口——正是部分图 + return new AiRuntime(b.BuildPartial(), ctx); } [Test] diff --git a/Assets/_Game/Scripts/AI/AiState.cs b/Assets/_Game/Scripts/AI/AiState.cs index b95bf287..dc8e178d 100644 --- a/Assets/_Game/Scripts/AI/AiState.cs +++ b/Assets/_Game/Scripts/AI/AiState.cs @@ -14,6 +14,12 @@ namespace BaseGames.AI public Action OnExit { get; internal set; } public IReadOnlyList Transitions => _transitions; + /// + /// 是否为终态：进入后不再离开是设计意图，而非漏挂出边。 + /// 由 标记，供 Build() 的死角校验放行。 + /// + public bool IsTerminal { get; internal set; } + internal void AddTransition(Transition t) => _transitions.Add(t); public AiState(string name) => Name = name; diff --git a/Assets/_Game/Scripts/AI/BrainBuilder.cs b/Assets/_Game/Scripts/AI/BrainBuilder.cs index 948c5e3b..5f6dec4e 100644 --- a/Assets/_Game/Scripts/AI/BrainBuilder.cs +++ b/Assets/_Game/Scripts/AI/BrainBuilder.cs @@ -59,7 +59,22 @@ namespace BaseGames.AI internal void AddGlobal(Transition t) => _globals.Add(t); - public AiGraph Build() + /// + /// 构建**完整**图。除了引用完整性，还校验「非终态必须有出口」。 + /// 生产的两个装配点（AiScript.GetOrBuildGraph / AiRecipeSO）都走这里， + /// 将来新增的入口默认即受保护——这正是校验放在 Build() 而非各入口的理由。 + /// + public AiGraph Build() => BuildInternal(checkDeadEnds: true); + + /// + /// 构建**部分**图：跳过「非终态必须有出口」校验，其余校验照旧。 + /// 单个模块（IUnawareModule / IEngagementModule）按设计只声明自己的态， + /// 升级边由 PerceptionSkeleton 事后挂上——单独构建时的死角是正常中间态，不是缺陷。 + /// 仅用于隔离验证单个模块或片段；装配真实敌人图一律用 。 + /// + public AiGraph BuildPartial() => BuildInternal(checkDeadEnds: false); + + AiGraph BuildInternal(bool checkDeadEnds) { if (string.IsNullOrEmpty(_entry)) throw new InvalidOperationException("BrainBuilder: 未设置 Entry 状态。"); @@ -76,9 +91,35 @@ namespace BaseGames.AI throw new InvalidOperationException( $"BrainBuilder: 全局转换指向未声明状态 '{t.Target}'。"); + if (checkDeadEnds) + { + foreach (var s in _states.Values) + if (!s.IsTerminal && !HasEscape(s)) + throw new InvalidOperationException( + $"BrainBuilder: 状态 '{s.Name}' 不是终态，却没有任何指向其他状态的出边。" + + "进入后会永久停在这里，且全程零报错。请给它挂出边；" + + "若「进去就不出来」本就是设计意图（如死亡态），" + + "请用 AiStateFragments.Terminal() 声明，或对已有 builder 调 .Terminal() 标记；" + + "若这是隔离测试单个模块的部分图，请改用 BuildPartial()。"); + } + return new AiGraph(_entry, _states, _globals); } + /// + /// 该状态是否有真正的出口。两点刻意的判定： + /// 1. 自转换不算——AiRuntime.Switch 对 Target == 当前态直接 return false，出不去； + /// 2. 全局转换不算——全局事件边要外部推信号才触发，不是自主出口。把它算作出口， + /// 等于让「只有死了才出得去」的死角通过校验，而那正是本校验要暴露的东西。 + /// + static bool HasEscape(AiState s) + { + var ts = s.Transitions; + for (int i = 0; i < ts.Count; i++) + if (ts[i].Target != s.Name) return true; + return false; + } + public sealed class StateBuilder { readonly AiState _state; @@ -89,6 +130,13 @@ namespace BaseGames.AI public StateBuilder Tick(Action fn) { _state.OnTick = fn; return this; } public StateBuilder OnExit(Action fn) { _state.OnExit = fn; return this; } + /// + /// 标记为终态：声明"进入后不再离开"是设计意图。 + /// Build() 会对非终态且无出口的态抛异常，本标记是唯一的豁免方式—— + /// 用它而不是随手挂一条永假的边，意图才留在代码里。 + /// + public StateBuilder Terminal() { _state.IsTerminal = true; return this; } + public TransitionBuilder To(string target) => new TransitionBuilder(this, _state, target); } diff --git a/Assets/_Game/Scripts/Enemies/AIBrain/Modules/AiStateFragments.cs b/Assets/_Game/Scripts/Enemies/AIBrain/Modules/AiStateFragments.cs index 3660df69..629d2402 100644 --- a/Assets/_Game/Scripts/Enemies/AIBrain/Modules/AiStateFragments.cs +++ b/Assets/_Game/Scripts/Enemies/AIBrain/Modules/AiStateFragments.cs @@ -46,9 +46,10 @@ namespace BaseGames.Enemies /// /// 无行为的终态。不需要在这里停移动——转入本态时，上一个态的 OnExit 已经收尾。 /// 用于"死亡演出交给物理状态机（EnemyBase.PerformDeath）"的敌人。 + /// 自带终态标记，因此能通过 Build() 的"非终态必须有出口"校验。 /// public static BrainBuilder.StateBuilder Terminal(BrainBuilder b, string state) - => b.DeclareState(state); + => b.DeclareState(state).Terminal(); static void ApplyLocomotion(IAiContext x, LocomotionMode mode) {