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

## 简介

本插件包提供了完整的行为树和状态机系统，用于实现复杂的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：状态机管理器

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

## 使用示例

### 行为树示例
```python
# 创建行为树插件
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()
```

### 状态机示例
```python
# 创建状态机插件
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. **事件系统**：完善的事件和回调机制