feat(ai): BrainGraph AiGraph + BrainBuilder(fluent, 显式标签, 目标校验)

2026-07-03 14:04:51 +08:00
parent 3d6cef1f41
commit 6f9fa8c4b8
8 changed files with 301 additions and 0 deletions
@@ -0,0 +1,73 @@
+using NUnit.Framework;
+using BaseGames.AI;
+
+namespace BaseGames.Tests.EditMode.AI
+{
+    public class BrainBuilderTests
+    {
+        static AiGraph BuildSample()
+        {
+            var b = new BrainBuilder();
+            b.Entry("Patrol");
+            b.Global().To("Dead").OnEvent(AiSignal.Died);
+            b.State("Patrol")
+                .To("Chase").When(c => c.Sensor.SeesPlayer(), "SeesPlayer");
+            b.State("Chase")
+                .To("Patrol").When(c => c.Sensor.LostFor(2f), "LostFor(2s)");
+            b.State("Dead");
+            return b.Build();
+        }
+
+        [Test]
+        public void Build_SetsEntryState()
+        {
+            Assert.AreEqual("Patrol", BuildSample().EntryState);
+        }
+
+        [Test]
+        public void Build_RegistersAllStates()
+        {
+            var g = BuildSample();
+            CollectionAssert.AreEquivalent(
+                new[] { "Patrol", "Chase", "Dead" },
+                System.Linq.Enumerable.ToList(g.StateNames));
+        }
+
+        [Test]
+        public void Build_UsesExplicitConditionLabel()
+        {
+            var g = BuildSample();
+            var t = g.GetState("Patrol").Transitions[0];
+            Assert.AreEqual("SeesPlayer", t.Label);
+        }
+
+        [Test]
+        public void Build_UnlabeledCondition_FallsBackToCond()
+        {
+            var b = new BrainBuilder();
+            b.Entry("A");
+            b.State("A").To("B").When(c => true);
+            b.State("B");
+            var g = b.Build();
+            Assert.AreEqual("cond", g.GetState("A").Transitions[0].Label);
+        }
+
+        [Test]
+        public void Build_GlobalTransitionsAreSeparate()
+        {
+            var g = BuildSample();
+            Assert.AreEqual(1, g.GlobalTransitions.Count);
+            Assert.AreEqual("Dead", g.GlobalTransitions[0].Target);
+            Assert.AreEqual(AiSignal.Died, g.GlobalTransitions[0].Event);
+        }
+
+        [Test]
+        public void Build_UnknownTransitionTarget_Throws()
+        {
+            var b = new BrainBuilder();
+            b.Entry("A");
+            b.State("A").To("Nonexistent").When(c => true);
+            Assert.Throws<System.InvalidOperationException>(() => b.Build());
+        }
+    }
+}
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 0dd4a9e62b5f3614cbf783a420b80ee8
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
@@ -0,0 +1,27 @@
+using System.Collections.Generic;
+
+namespace BaseGames.AI
+{
+    /// <summary>
+    /// 不可变状态图，每敌人类型构建一次、所有实例共享（flyweight）。
+    /// 既被 AiRuntime 执行，又被导出器/调试器只读投影。
+    /// </summary>
+    public sealed class AiGraph
+    {
+        readonly Dictionary<string, AiState> _states;
+        public string EntryState { get; }
+        public IReadOnlyList<Transition> GlobalTransitions { get; }
+
+        public AiGraph(string entry, Dictionary<string, AiState> states, IReadOnlyList<Transition> globals)
+        {
+            EntryState = entry;
+            _states = states;
+            GlobalTransitions = globals;
+        }
+
+        public AiState GetState(string name) => _states[name];
+        public bool HasState(string name) => _states.ContainsKey(name);
+        public IEnumerable<string> StateNames => _states.Keys;
+        public IEnumerable<AiState> States => _states.Values;
+    }
+}
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 5334a83a79910ba41a8e8892c4df95f9
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
@@ -0,0 +1,35 @@
+using System;
+
+namespace BaseGames.AI
+{
+    /// <summary>标注一个 AiScript 对应的敌人类型 id，供 AiDefinitionRegistry 反射收集（第 3 阶段）。</summary>
+    [AttributeUsage(AttributeTargets.Class, Inherited = false)]
+    public sealed class AiDefinitionAttribute : Attribute
+    {
+        public string Id { get; }
+        public AiDefinitionAttribute(string id) => Id = id;
+    }
+
+    /// <summary>
+    /// 一种敌人 AI 的声明基类（唯一事实来源）。子类实现 Build 用 fluent 描述状态机。
+    /// 构建结果 AiGraph 每类型只建一次、实例共享（flyweight）。
+    /// </summary>
+    public abstract class AiScript
+    {
+        AiGraph _cached;
+
+        /// <summary>惰性构建并缓存共享 AiGraph。</summary>
+        public AiGraph GetOrBuildGraph()
+        {
+            if (_cached == null)
+            {
+                var b = new BrainBuilder();
+                Build(b);
+                _cached = b.Build();
+            }
+            return _cached;
+        }
+
+        protected abstract void Build(BrainBuilder b);
+    }
+}
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 5c42a6f10cf2ed540a00bea550640b6c
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
@@ -0,0 +1,122 @@
+using System;
+using System.Collections.Generic;
+
+namespace BaseGames.AI
+{
+    /// <summary>fluent builder：声明层的唯一入口。构建出不可变 AiGraph。</summary>
+    public sealed class BrainBuilder
+    {
+        readonly Dictionary<string, AiState> _states = new Dictionary<string, AiState>();
+        readonly List<Transition> _globals = new List<Transition>();
+        string _entry;
+
+        public BrainBuilder Entry(string stateName)
+        {
+            _entry = stateName;
+            return this;
+        }
+
+        public StateBuilder State(string name)
+        {
+            if (!_states.TryGetValue(name, out var s))
+            {
+                s = new AiState(name);
+                _states[name] = s;
+            }
+            return new StateBuilder(this, s);
+        }
+
+        public GlobalBuilder Global() => new GlobalBuilder(this);
+
+        internal void AddGlobal(Transition t) => _globals.Add(t);
+
+        public AiGraph Build()
+        {
+            if (string.IsNullOrEmpty(_entry))
+                throw new InvalidOperationException("BrainBuilder: 未设置 Entry 状态。");
+            if (!_states.ContainsKey(_entry))
+                throw new InvalidOperationException($"BrainBuilder: Entry 状态 '{_entry}' 未声明。");
+
+            foreach (var s in _states.Values)
+                foreach (var t in s.Transitions)
+                    if (!_states.ContainsKey(t.Target))
+                        throw new InvalidOperationException(
+                            $"BrainBuilder: 状态 '{s.Name}' 的转换指向未声明状态 '{t.Target}'。");
+            foreach (var t in _globals)
+                if (!_states.ContainsKey(t.Target))
+                    throw new InvalidOperationException(
+                        $"BrainBuilder: 全局转换指向未声明状态 '{t.Target}'。");
+
+            return new AiGraph(_entry, _states, _globals);
+        }
+
+        public sealed class StateBuilder
+        {
+            readonly BrainBuilder _owner;
+            readonly AiState _state;
+            internal StateBuilder(BrainBuilder owner, AiState state) { _owner = owner; _state = state; }
+
+            public StateBuilder OnEnter(Action<IAiContext> fn) { _state.OnEnter = fn; return this; }
+            public StateBuilder Tick(Action<IAiContext> fn) { _state.OnTick = (c, _) => fn(c); return this; }
+            public StateBuilder Tick(Action<IAiContext, float> fn) { _state.OnTick = fn; return this; }
+            public StateBuilder OnExit(Action<IAiContext> fn) { _state.OnExit = fn; return this; }
+
+            public TransitionBuilder To(string target) => new TransitionBuilder(_owner, this, _state, target);
+        }
+
+        public sealed class TransitionBuilder
+        {
+            readonly BrainBuilder _owner;
+            readonly StateBuilder _stateBuilder;
+            readonly AiState _state;
+            readonly string _target;
+            internal TransitionBuilder(BrainBuilder owner, StateBuilder sb, AiState state, string target)
+            { _owner = owner; _stateBuilder = sb; _state = state; _target = target; }
+
+            /// <summary>
+            /// 条件转换。label 为可读标签（用于 Mermaid 边 / trace 触发原因），
+            /// C# 9 环境下需显式传入；不传则回退为 "cond"。
+            /// </summary>
+            public StateBuilder When(Func<IAiContext, bool> cond, string label = null)
+            {
+                _state.Transitions.Add(Transition.OnCondition(_target, cond, label ?? "cond"));
+                return _stateBuilder;
+            }
+
+            /// <summary>事件转换。</summary>
+            public StateBuilder OnEvent(AiSignal evt)
+            {
+                _state.Transitions.Add(Transition.OnEvent(_target, evt));
+                return _stateBuilder;
+            }
+
+            /// <summary>在本状态停留 seconds 秒后转换（读 runtime 的状态计时器）。Task 5 回填实现。</summary>
+            public StateBuilder After(float seconds)
+            {
+                // 依赖 AiRuntime.TimeInState（Task 5 定义）。本任务先临时抛异常以通过编译，Task 5 回填正式实现。
+                throw new NotImplementedException("After 将在 Task 5 回填（依赖 AiRuntime 状态计时器）。");
+            }
+        }
+
+        public sealed class GlobalBuilder
+        {
+            readonly BrainBuilder _owner;
+            string _pendingTarget;
+            internal GlobalBuilder(BrainBuilder owner) { _owner = owner; }
+
+            public GlobalBuilder To(string target) { _pendingTarget = target; return this; }
+
+            public GlobalBuilder OnEvent(AiSignal evt)
+            {
+                _owner.AddGlobal(Transition.OnEvent(_pendingTarget, evt));
+                return this;
+            }
+
+            public GlobalBuilder When(Func<IAiContext, bool> cond, string label = null)
+            {
+                _owner.AddGlobal(Transition.OnCondition(_pendingTarget, cond, label ?? "cond"));
+                return this;
+            }
+        }
+    }
+}
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 52f0da4a028419747ab6d48abe5aa786
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: