EG/plugins/user/USAGE_GUIDE.md

行为树和状态机插件使用指南

简介

本插件包提供了完整的行为树和状态机系统，用于实现复杂的AI决策逻辑和状态管理。

行为树插件

核心组件

1. 节点系统

• 基础节点：BTNode（所有节点的基类）
• 控制节点：
  • SelectorNode：选择节点（OR逻辑）
  • SequenceNode：序列节点（AND逻辑）
  • ParallelNode：并行节点
  • RandomSelectorNode：随机选择节点
  • PrioritySelectorNode：优先级选择节点
• 装饰节点：
  • RepeaterNode：重复节点
  • InverterNode：逆变节点
  • SucceederNode：成功节点
  • FailureNode：失败节点
  • TimerNode：计时器节点
  • CooldownNode：冷却节点
  • RandomizerNode：随机化节点
• 叶子节点：
  • ConditionNode：条件节点
  • ActionNode：动作节点
  • WaitNode：等待节点
  • SubtreeNode：子树节点
  • ProbabilityNode：概率节点
  • CounterNode：计数器节点
  • TimeoutNode：超时节点

2. 黑板系统

• 数据共享和状态管理
• 类型约束和数据验证
• 历史记录和回调机制
• 序列化支持（JSON/Pickle）

3. 管理器

• BehaviorTreeManager：行为树管理器
• BlackboardManager：黑板管理器

主要特性

• 完整的节点内存管理系统
• 支持中断和恢复机制
• 丰富的统计和调试信息
• 线程安全设计
• 可扩展的自定义功能

状态机插件

核心组件

1. 状态系统

• 基础状态：State（状态基类）
• 分层状态：HierarchicalState（支持子状态）
• 状态上下文：StateContext（状态数据管理）
• 状态转换：StateTransition（状态间转换）

2. 状态机管理

• StateMachine：状态机核心
• StateMachineManager：状态机管理器

主要特性

• 支持分层状态和子状态
• 灵活的状态转换机制
• 状态变更回调系统
• 完整的统计信息
• 线程安全设计

使用示例

行为树示例

# 创建行为树插件
bt_plugin = plugin_manager.load_plugin("behavior_tree")
plugin_manager.enable_plugin("behavior_tree")

# 创建黑板
blackboard = bt_plugin.create_blackboard("ai_blackboard")

# 创建节点
root = SelectorNode("Root")
sequence = SequenceNode("Patrol")
condition = ConditionNode("NeedPatrol", lambda bb: bb.get("need_patrol", True))
action = ActionNode("PatrolAction", lambda bb: print("巡逻中...") or True)

# 组装行为树
sequence.add_child(condition)
sequence.add_child(action)
root.add_child(sequence)

# 创建行为树
tree = bt_plugin.create_behavior_tree("patrol_ai", root)
tree.set_blackboard(blackboard)

# 执行
result = tree.run()

状态机示例

# 创建状态机插件
sm_plugin = plugin_manager.load_plugin("state_machine")
plugin_manager.enable_plugin("state_machine")

# 定义状态
class IdleState(State):
    def enter(self, context):
        print("进入空闲状态")
        
    def execute(self, context):
        if context.get("want_move", False):
            return "Moving"
        return None
        
    def exit(self, context):
        print("退出空闲状态")

# 创建状态机
state_machine = sm_plugin.create_state_machine("character_ai")
context = StateContext()
state_machine.set_context(context)

# 添加状态
state_machine.add_state(IdleState("Idle"))
state_machine.add_state(MovingState("Moving"))

# 设置初始状态并启动
state_machine.change_state("Idle")
state_machine.start()

# 更新
state_machine.update()

高级功能

行为树高级功能

1. 节点配置：支持优先级、超时时间、中断控制等
2. 内存管理：节点状态记忆和恢复
3. 统计系统：详细的执行统计和性能分析
4. 自定义扩展：支持添加自定义函数和回调

状态机高级功能

1. 分层状态：支持复杂的状态嵌套
2. 转换条件：灵活的状态转换逻辑
3. 回调系统：状态变更通知机制
4. 上下文管理：丰富的状态数据管理

性能优化

1. 缓存机制：条件节点支持结果缓存
2. 线程安全：所有组件都支持多线程环境
3. 内存管理：高效的内存使用和垃圾回收
4. 批量操作：支持批量更新和管理

扩展性

1. 插件架构：基于插件管理器的模块化设计
2. 接口标准：遵循统一的插件接口规范
3. 自定义节点：支持创建自定义节点类型
4. 事件系统：完善的事件和回调机制