zeling_v2/Assets/_Game/Scripts/AI/BrainBuilder.cs

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(this, _state, target);
        }

        public sealed class TransitionBuilder
        {
            readonly StateBuilder _stateBuilder;
            readonly AiState _state;
            readonly string _target;
            internal TransitionBuilder(StateBuilder sb, AiState state, string target)
            { _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.AddTransition(Transition.OnCondition(_target, cond, label ?? "cond"));
                return _stateBuilder;
            }

            /// <summary>事件转换。</summary>
            public StateBuilder OnEvent(AiSignal evt)
            {
                _state.AddTransition(Transition.OnEvent(_target, evt));
                return _stateBuilder;
            }

            /// <summary>在本状态停留 seconds 秒后转换（读 runtime 的状态计时器）。</summary>
            public StateBuilder After(float seconds)
            {
                _state.AddTransition(Transition.OnCondition(
                    _target, c => AiRuntime.TimeInState(c) >= seconds, $"after {seconds}s"));
                return _stateBuilder;
            }
        }

        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)
            {
                if (_pendingTarget == null)
                    throw new System.InvalidOperationException("Global(): 请先调用 To(target) 再 OnEvent/When。");
                _owner.AddGlobal(Transition.OnEvent(_pendingTarget, evt));
                return this;
            }

            public GlobalBuilder When(Func<IAiContext, bool> cond, string label = null)
            {
                if (_pendingTarget == null)
                    throw new System.InvalidOperationException("Global(): 请先调用 To(target) 再 OnEvent/When。");
                _owner.AddGlobal(Transition.OnCondition(_pendingTarget, cond, label ?? "cond"));
                return this;
            }
        }
    }
}