refactor(behavior-tree)!: 迁移到 Runtime 执行器架构 (#196)
* refactor(behavior-tree)!: 迁移到 Runtime 执行器架构 * fix(behavior-tree): 修复LogAction中的ReDoS安全漏洞 * feat(behavior-tree): 完善行为树核心功能并修复类型错误
This commit is contained in:
YHH
GitHub
@@ -1,22 +1,22 @@
|
||||
# 最佳实践
|
||||
|
||||
本文介绍行为树设计和使用的最佳实践，帮助你构建高效、可维护的AI系统。
|
||||
本文介绍行为树设计和使用的最佳实践,帮助你构建高效、可维护的AI系统。
|
||||
|
||||
## 行为树设计原则
|
||||
|
||||
### 1. 保持树的层次清晰
|
||||
|
||||
将复杂行为分解成清晰的层次结构：
|
||||
将复杂行为分解成清晰的层次结构:
|
||||
|
||||
```
|
||||
Root Selector
|
||||
├── Emergency (高优先级：紧急情况)
|
||||
├── Emergency (高优先级:紧急情况)
|
||||
│ ├── FleeFromDanger
|
||||
│ └── CallForHelp
|
||||
├── Combat (中优先级：战斗)
|
||||
├── Combat (中优先级:战斗)
|
||||
│ ├── Attack
|
||||
│ └── Defend
|
||||
└── Idle (低优先级：空闲)
|
||||
└── Idle (低优先级:空闲)
|
||||
├── Patrol
|
||||
└── Rest
|
||||
```
|
||||
@@ -24,309 +24,272 @@ Root Selector
|
||||
|
||||
### 2. 单一职责原则
|
||||
|
||||
每个节点应该只做一件事：
|
||||
每个节点应该只做一件事。要实现复杂动作,创建自定义执行器,参见[自定义节点执行器](./custom-actions.md)。
|
||||
|
||||
```typescript
|
||||
// 好的设计
|
||||
// 好的设计 - 使用内置节点
|
||||
.sequence('AttackSequence')
|
||||
.condition(hasTarget, 'CheckTarget')
|
||||
.action(aim, 'Aim')
|
||||
.action(fire, 'Fire')
|
||||
.blackboardExists('target', 'CheckTarget')
|
||||
.log('瞄准', 'Aim')
|
||||
.log('开火', 'Fire')
|
||||
.end()
|
||||
|
||||
// 不好的设计 - 一个动作做太多事
|
||||
.action('AttackPlayer', () => {
|
||||
checkTarget();
|
||||
aim();
|
||||
fire();
|
||||
playAnimation();
|
||||
playSound();
|
||||
// 太多职责了！
|
||||
})
|
||||
```
|
||||
|
||||
### 3. 使用描述性名称
|
||||
|
||||
节点名称应该清楚地表达其功能：
|
||||
节点名称应该清楚地表达其功能:
|
||||
|
||||
```typescript
|
||||
// 好的命名
|
||||
.condition(isHealthLow, 'CheckHealthLow')
|
||||
.action(findNearestHealthPack, 'FindHealthPack')
|
||||
.action(moveToHealthPack, 'MoveToHealthPack')
|
||||
.blackboardCompare('health', 20, 'less', 'CheckHealthLow')
|
||||
.log('寻找最近的医疗包', 'FindHealthPack')
|
||||
.log('移动到医疗包', 'MoveToHealthPack')
|
||||
|
||||
// 不好的命名
|
||||
.condition(check1, 'C1')
|
||||
.action(doSomething, 'Action1')
|
||||
.action(move, 'A2')
|
||||
.blackboardCompare('health', 20, 'less', 'C1')
|
||||
.log('Do something', 'Action1')
|
||||
.log('Move', 'A2')
|
||||
```
|
||||
|
||||
## 黑板变量管理
|
||||
|
||||
### 1. 变量命名规范
|
||||
|
||||
使用清晰的命名约定：
|
||||
使用清晰的命名约定:
|
||||
|
||||
```typescript
|
||||
.blackboard()
|
||||
const tree = BehaviorTreeBuilder.create('AI')
|
||||
// 状态变量
|
||||
.defineVariable('currentState', BlackboardValueType.String, 'idle')
|
||||
.defineVariable('isMoving', BlackboardValueType.Boolean, false)
|
||||
.defineBlackboardVariable('currentState', 'idle')
|
||||
.defineBlackboardVariable('isMoving', false)
|
||||
|
||||
// 目标和引用
|
||||
.defineVariable('targetEnemy', BlackboardValueType.Object, null)
|
||||
.defineVariable('patrolPoints', BlackboardValueType.Array, [])
|
||||
.defineBlackboardVariable('targetEnemy', null)
|
||||
.defineBlackboardVariable('patrolPoints', [])
|
||||
|
||||
// 配置参数
|
||||
.defineVariable('attackRange', BlackboardValueType.Number, 5.0)
|
||||
.defineVariable('moveSpeed', BlackboardValueType.Number, 10.0)
|
||||
.defineBlackboardVariable('attackRange', 5.0)
|
||||
.defineBlackboardVariable('moveSpeed', 10.0)
|
||||
|
||||
// 临时数据
|
||||
.defineVariable('lastAttackTime', BlackboardValueType.Number, 0)
|
||||
.defineVariable('searchAttempts', BlackboardValueType.Number, 0)
|
||||
.endBlackboard()
|
||||
.defineBlackboardVariable('lastAttackTime', 0)
|
||||
.defineBlackboardVariable('searchAttempts', 0)
|
||||
// ...
|
||||
.build();
|
||||
```
|
||||
|
||||
### 2. 避免过度使用黑板
|
||||
|
||||
只在需要跨节点共享的数据才放入黑板：
|
||||
只在需要跨节点共享的数据才放入黑板。在自定义执行器中使用局部变量:
|
||||
|
||||
```typescript
|
||||
// 不好的做法 - 局部变量放黑板
|
||||
.action('Calculate', (e, bb) => {
|
||||
bb?.setValue('temp1', 10); // 不需要
|
||||
bb?.setValue('temp2', 20); // 不需要
|
||||
bb?.setValue('result', 30); // 如果其他节点需要，这个可以
|
||||
return TaskStatus.Success;
|
||||
})
|
||||
|
||||
// 好的做法 - 使用局部变量
|
||||
.action('Calculate', (e, bb) => {
|
||||
const temp1 = 10;
|
||||
const temp2 = 20;
|
||||
const result = temp1 + temp2;
|
||||
bb?.setValue('calculationResult', result); // 只保存需要共享的结果
|
||||
return TaskStatus.Success;
|
||||
})
|
||||
export class CalculateAction implements INodeExecutor {
|
||||
execute(context: NodeExecutionContext): TaskStatus {
|
||||
// 局部计算
|
||||
const temp1 = 10;
|
||||
const temp2 = 20;
|
||||
const result = temp1 + temp2;
|
||||
|
||||
// 只保存需要共享的结果
|
||||
context.runtime.setBlackboardValue('calculationResult', result);
|
||||
|
||||
return TaskStatus.Success;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 使用类型安全的访问
|
||||
|
||||
```typescript
|
||||
// 定义类型接口
|
||||
interface EnemyBlackboard {
|
||||
health: number;
|
||||
target: Entity | null;
|
||||
state: 'idle' | 'patrol' | 'chase' | 'attack';
|
||||
}
|
||||
export class TypeSafeAction implements INodeExecutor {
|
||||
execute(context: NodeExecutionContext): TaskStatus {
|
||||
const { runtime } = context;
|
||||
|
||||
// 使用时进行类型检查
|
||||
.action('UseBlackboard', (e, bb) => {
|
||||
const health = bb?.getValue<number>('health');
|
||||
const target = bb?.getValue<Entity | null>('target');
|
||||
const state = bb?.getValue<string>('state');
|
||||
// 使用泛型进行类型安全访问
|
||||
const health = runtime.getBlackboardValue<number>('health');
|
||||
const target = runtime.getBlackboardValue<Entity | null>('target');
|
||||
const state = runtime.getBlackboardValue<string>('currentState');
|
||||
|
||||
if (health !== undefined && health < 30) {
|
||||
bb?.setValue('state', 'flee');
|
||||
if (health !== undefined && health < 30) {
|
||||
runtime.setBlackboardValue('currentState', 'flee');
|
||||
}
|
||||
|
||||
return TaskStatus.Success;
|
||||
}
|
||||
|
||||
return TaskStatus.Success;
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
## 条件节点设计
|
||||
## 执行器设计
|
||||
|
||||
### 1. 条件应该是无副作用的
|
||||
### 1. 保持执行器无状态
|
||||
|
||||
条件检查不应该修改状态：
|
||||
状态必须存储在`context.state`中,而不是执行器实例:
|
||||
|
||||
```typescript
|
||||
// 正确的做法
|
||||
export class TimedAction implements INodeExecutor {
|
||||
execute(context: NodeExecutionContext): TaskStatus {
|
||||
if (!context.state.startTime) {
|
||||
context.state.startTime = context.totalTime;
|
||||
}
|
||||
|
||||
const elapsed = context.totalTime - context.state.startTime;
|
||||
|
||||
if (elapsed >= 3.0) {
|
||||
return TaskStatus.Success;
|
||||
}
|
||||
|
||||
return TaskStatus.Running;
|
||||
}
|
||||
|
||||
reset(context: NodeExecutionContext): void {
|
||||
context.state.startTime = undefined;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 条件应该是无副作用的
|
||||
|
||||
条件检查不应该修改状态:
|
||||
|
||||
```typescript
|
||||
// 好的做法 - 只读检查
|
||||
.condition((e, bb) => {
|
||||
const health = bb?.getValue('health') || 0;
|
||||
return health < 30;
|
||||
}, 'IsHealthLow')
|
||||
|
||||
// 不好的做法 - 条件中修改状态
|
||||
.condition((e, bb) => {
|
||||
const health = bb?.getValue('health') || 0;
|
||||
if (health < 30) {
|
||||
bb?.setValue('needsHealing', true); // 不应该在条件中修改
|
||||
return true;
|
||||
@NodeExecutorMetadata({
|
||||
implementationType: 'IsHealthLow',
|
||||
nodeType: NodeType.Condition,
|
||||
displayName: '检查生命值低',
|
||||
category: '条件',
|
||||
configSchema: {
|
||||
threshold: {
|
||||
type: 'number',
|
||||
default: 30,
|
||||
supportBinding: true
|
||||
}
|
||||
}
|
||||
return false;
|
||||
})
|
||||
```
|
||||
export class IsHealthLow implements INodeExecutor {
|
||||
execute(context: NodeExecutionContext): TaskStatus {
|
||||
const threshold = BindingHelper.getValue<number>(context, 'threshold', 30);
|
||||
const health = context.runtime.getBlackboardValue<number>('health') || 0;
|
||||
|
||||
### 2. 复杂条件拆分
|
||||
|
||||
将复杂条件拆分为多个简单条件：
|
||||
|
||||
```typescript
|
||||
// 不好的做法
|
||||
.condition((e, bb) => {
|
||||
const health = bb?.getValue('health');
|
||||
const ammo = bb?.getValue('ammo');
|
||||
const enemy = bb?.getValue('enemy');
|
||||
const distance = calculateDistance(e, enemy);
|
||||
|
||||
return health > 50 && ammo > 0 && enemy && distance < 10;
|
||||
}, 'ComplexCheck')
|
||||
|
||||
// 好的做法
|
||||
.sequence('CanAttack')
|
||||
.condition((e, bb) => (bb?.getValue('health') || 0) > 50, 'HasEnoughHealth')
|
||||
.condition((e, bb) => (bb?.getValue('ammo') || 0) > 0, 'HasAmmo')
|
||||
.condition((e, bb) => bb?.getValue('enemy') != null, 'HasTarget')
|
||||
.condition((e, bb) => {
|
||||
const enemy = bb?.getValue('enemy');
|
||||
return calculateDistance(e, enemy) < 10;
|
||||
}, 'InRange')
|
||||
.end()
|
||||
```
|
||||
|
||||
## 动作节点设计
|
||||
|
||||
### 1. 使用状态机模式处理长时间动作
|
||||
|
||||
```typescript
|
||||
.action('ChargeLaser', (e, bb, dt) => {
|
||||
// 初始化状态
|
||||
if (!bb?.hasVariable('chargeState')) {
|
||||
bb?.setValue('chargeState', 'charging');
|
||||
bb?.setValue('chargeTime', 0);
|
||||
return health < threshold ? TaskStatus.Success : TaskStatus.Failure;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
const state = bb?.getValue('chargeState');
|
||||
const chargeTime = bb?.getValue('chargeTime') || 0;
|
||||
### 3. 错误处理
|
||||
|
||||
switch (state) {
|
||||
case 'charging':
|
||||
bb?.setValue('chargeTime', chargeTime + dt);
|
||||
```typescript
|
||||
export class SafeAction implements INodeExecutor {
|
||||
execute(context: NodeExecutionContext): TaskStatus {
|
||||
try {
|
||||
const resourceId = context.runtime.getBlackboardValue('resourceId');
|
||||
|
||||
if (chargeTime >= 3.0) {
|
||||
bb?.setValue('chargeState', 'ready');
|
||||
if (!resourceId) {
|
||||
console.error('[SafeAction] 资源ID未设置');
|
||||
return TaskStatus.Failure;
|
||||
}
|
||||
return TaskStatus.Running;
|
||||
|
||||
case 'ready':
|
||||
// 发射激光
|
||||
fireLaser();
|
||||
bb?.setValue('chargeState', null);
|
||||
bb?.setValue('chargeTime', 0);
|
||||
// 执行操作...
|
||||
|
||||
return TaskStatus.Success;
|
||||
|
||||
default:
|
||||
return TaskStatus.Failure;
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### 2. 错误处理
|
||||
|
||||
```typescript
|
||||
.action('LoadResource', async (e, bb) => {
|
||||
try {
|
||||
const resourceId = bb?.getValue('resourceId');
|
||||
if (!resourceId) {
|
||||
console.error('资源ID未设置');
|
||||
} catch (error) {
|
||||
console.error('[SafeAction] 执行失败:', error);
|
||||
context.runtime.setBlackboardValue('lastError', error.message);
|
||||
return TaskStatus.Failure;
|
||||
}
|
||||
|
||||
const resource = await loadResource(resourceId);
|
||||
bb?.setValue('loadedResource', resource);
|
||||
return TaskStatus.Success;
|
||||
|
||||
} catch (error) {
|
||||
console.error('资源加载失败:', error);
|
||||
bb?.setValue('loadError', error.message);
|
||||
return TaskStatus.Failure;
|
||||
}
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
## 性能优化技巧
|
||||
|
||||
### 1. 使用冷却装饰器
|
||||
|
||||
避免高频执行昂贵操作：
|
||||
避免高频执行昂贵操作:
|
||||
|
||||
```typescript
|
||||
.cooldown(1.0) // 最多每秒执行一次
|
||||
.action('ExpensiveSearch', () => {
|
||||
// 昂贵的搜索操作
|
||||
return TaskStatus.Success;
|
||||
})
|
||||
.end()
|
||||
const tree = BehaviorTreeBuilder.create('ThrottledAI')
|
||||
.cooldown(1.0, 'ThrottleSearch') // 最多每秒执行一次
|
||||
.log('昂贵的搜索操作', 'ExpensiveSearch')
|
||||
.end()
|
||||
.build();
|
||||
```
|
||||
|
||||
### 2. 缓存计算结果
|
||||
|
||||
```typescript
|
||||
.action('FindNearestEnemy', (e, bb) => {
|
||||
// 检查缓存是否有效
|
||||
const cacheTime = bb?.getValue('enemyCacheTime') || 0;
|
||||
const currentTime = Date.now();
|
||||
export class CachedFindNearest implements INodeExecutor {
|
||||
execute(context: NodeExecutionContext): TaskStatus {
|
||||
const { state, runtime, totalTime } = context;
|
||||
|
||||
if (currentTime - cacheTime < 500) { // 缓存500ms
|
||||
// 使用缓存结果
|
||||
return bb?.getValue('nearestEnemy') ? TaskStatus.Success : TaskStatus.Failure;
|
||||
// 检查缓存是否有效
|
||||
const cacheTime = state.enemyCacheTime || 0;
|
||||
|
||||
if (totalTime - cacheTime < 0.5) { // 缓存0.5秒
|
||||
const cached = runtime.getBlackboardValue('nearestEnemy');
|
||||
return cached ? TaskStatus.Success : TaskStatus.Failure;
|
||||
}
|
||||
|
||||
// 执行搜索
|
||||
const nearest = findNearestEnemy();
|
||||
runtime.setBlackboardValue('nearestEnemy', nearest);
|
||||
state.enemyCacheTime = totalTime;
|
||||
|
||||
return nearest ? TaskStatus.Success : TaskStatus.Failure;
|
||||
}
|
||||
|
||||
// 执行搜索
|
||||
const nearest = findNearestEnemy();
|
||||
bb?.setValue('nearestEnemy', nearest);
|
||||
bb?.setValue('enemyCacheTime', currentTime);
|
||||
|
||||
return nearest ? TaskStatus.Success : TaskStatus.Failure;
|
||||
})
|
||||
reset(context: NodeExecutionContext): void {
|
||||
context.state.enemyCacheTime = undefined;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 使用早期退出
|
||||
|
||||
```typescript
|
||||
.selector('FindTarget')
|
||||
// 先检查缓存的目标
|
||||
.condition((e, bb) => bb?.hasVariable('cachedTarget'), 'HasCachedTarget')
|
||||
const tree = BehaviorTreeBuilder.create('EarlyExit')
|
||||
.selector('FindTarget')
|
||||
// 先检查缓存的目标
|
||||
.blackboardExists('cachedTarget', 'HasCachedTarget')
|
||||
|
||||
// 没有缓存才进行搜索
|
||||
.action('SearchNewTarget', (e, bb) => {
|
||||
const target = performExpensiveSearch();
|
||||
bb?.setValue('cachedTarget', target);
|
||||
return target ? TaskStatus.Success : TaskStatus.Failure;
|
||||
})
|
||||
.end()
|
||||
// 没有缓存才进行搜索(需要自定义执行器)
|
||||
.log('执行昂贵的搜索', 'SearchNewTarget')
|
||||
.end()
|
||||
.build();
|
||||
```
|
||||
|
||||
## 可维护性
|
||||
|
||||
### 1. 使用子树模块化
|
||||
|
||||
将可复用的行为提取为子树：
|
||||
### 1. 使用有意义的节点名称
|
||||
|
||||
```typescript
|
||||
// 巡逻子树
|
||||
const patrolBehavior = BehaviorTreeBuilder.create(scene, 'Patrol')
|
||||
.sequence()
|
||||
.action('MoveToNextWaypoint', () => TaskStatus.Success)
|
||||
.wait(2.0)
|
||||
// 好的做法
|
||||
const tree = BehaviorTreeBuilder.create('CombatAI')
|
||||
.selector('CombatDecision')
|
||||
.sequence('AttackEnemy')
|
||||
.blackboardExists('target', 'HasTarget')
|
||||
.log('执行攻击', 'Attack')
|
||||
.end()
|
||||
.end()
|
||||
.build();
|
||||
|
||||
// 主树中引用
|
||||
const mainTree = BehaviorTreeBuilder.create(scene, 'EnemyAI')
|
||||
.selector()
|
||||
.sequence('Combat')
|
||||
// 战斗逻辑
|
||||
// 不好的做法
|
||||
const tree = BehaviorTreeBuilder.create('AI')
|
||||
.selector('Node1')
|
||||
.sequence('Node2')
|
||||
.blackboardExists('target', 'Node3')
|
||||
.log('Attack', 'Node4')
|
||||
.end()
|
||||
.subTree(patrolBehavior) // 复用巡逻行为
|
||||
.end()
|
||||
.build();
|
||||
```
|
||||
|
||||
### 2. 使用编辑器创建复杂树
|
||||
|
||||
对于复杂的AI，使用可视化编辑器：
|
||||
对于复杂的AI,使用可视化编辑器:
|
||||
|
||||
- 更直观的结构
|
||||
- 方便非程序员调整
|
||||
@@ -337,27 +300,26 @@ const mainTree = BehaviorTreeBuilder.create(scene, 'EnemyAI')
|
||||
### 3. 添加注释和文档
|
||||
|
||||
```typescript
|
||||
const ai = BehaviorTreeBuilder.create(scene, 'BossAI')
|
||||
.blackboard()
|
||||
.defineVariable('phase', BlackboardValueType.Number, 1) // 1=正常, 2=狂暴, 3=濒死
|
||||
.endBlackboard()
|
||||
// 为行为树添加清晰的注释
|
||||
const bossAI = BehaviorTreeBuilder.create('BossAI')
|
||||
.defineBlackboardVariable('phase', 1) // 1=正常, 2=狂暴, 3=濒死
|
||||
|
||||
.selector('MainBehavior')
|
||||
// 阶段3：生命值<20%，使用终极技能
|
||||
// 阶段3: 生命值<20%,使用终极技能
|
||||
.sequence('Phase3')
|
||||
.compareBlackboardValue('phase', CompareOperator.Equal, 3)
|
||||
.action('UltimateAbility', () => TaskStatus.Success)
|
||||
.blackboardCompare('phase', 3, 'equals')
|
||||
.log('使用终极技能', 'UltimateAbility')
|
||||
.end()
|
||||
|
||||
// 阶段2：生命值<50%，进入狂暴
|
||||
// 阶段2: 生命值<50%,进入狂暴
|
||||
.sequence('Phase2')
|
||||
.compareBlackboardValue('phase', CompareOperator.Equal, 2)
|
||||
.action('BerserkMode', () => TaskStatus.Success)
|
||||
.blackboardCompare('phase', 2, 'equals')
|
||||
.log('进入狂暴模式', 'BerserkMode')
|
||||
.end()
|
||||
|
||||
// 阶段1：正常战斗
|
||||
// 阶段1: 正常战斗
|
||||
.sequence('Phase1')
|
||||
.action('NormalAttack', () => TaskStatus.Success)
|
||||
.log('普通攻击', 'NormalAttack')
|
||||
.end()
|
||||
.end()
|
||||
.build();
|
||||
@@ -368,44 +330,52 @@ const ai = BehaviorTreeBuilder.create(scene, 'BossAI')
|
||||
### 1. 使用日志节点
|
||||
|
||||
```typescript
|
||||
.log('开始攻击序列', 'info')
|
||||
.sequence('Attack')
|
||||
.log('检查目标', 'debug')
|
||||
.condition(hasTarget)
|
||||
.log('执行攻击', 'info')
|
||||
.action(attack)
|
||||
.end()
|
||||
const tree = BehaviorTreeBuilder.create('Debug')
|
||||
.log('开始攻击序列', 'StartAttack')
|
||||
.sequence('Attack')
|
||||
.log('检查目标', 'CheckTarget')
|
||||
.blackboardExists('target')
|
||||
.log('执行攻击', 'DoAttack')
|
||||
.end()
|
||||
.build();
|
||||
```
|
||||
|
||||
### 2. 添加断言
|
||||
### 2. 在自定义执行器中调试
|
||||
|
||||
```typescript
|
||||
.action('ValidateState', (e, bb) => {
|
||||
const health = bb?.getValue('health');
|
||||
const maxHealth = bb?.getValue('maxHealth');
|
||||
export class DebugAction implements INodeExecutor {
|
||||
execute(context: NodeExecutionContext): TaskStatus {
|
||||
const { nodeData, runtime, state } = context;
|
||||
|
||||
console.assert(health !== undefined, 'health不应为undefined');
|
||||
console.assert(maxHealth !== undefined, 'maxHealth不应为undefined');
|
||||
console.assert(health <= maxHealth, `health(${health})不应大于maxHealth(${maxHealth})`);
|
||||
console.group(`[${nodeData.name}]`);
|
||||
console.log('配置:', nodeData.config);
|
||||
console.log('状态:', state);
|
||||
console.log('黑板:', runtime.getAllBlackboardVariables());
|
||||
console.log('活动节点:', Array.from(runtime.activeNodeIds));
|
||||
console.groupEnd();
|
||||
|
||||
return TaskStatus.Success;
|
||||
})
|
||||
return TaskStatus.Success;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 状态可视化
|
||||
|
||||
```typescript
|
||||
.action('DebugState', (e, bb) => {
|
||||
if (process.env.NODE_ENV === 'development') {
|
||||
console.group('AI State');
|
||||
console.log('Entity:', e.name);
|
||||
console.log('Health:', bb?.getValue('health'));
|
||||
console.log('State:', bb?.getValue('currentState'));
|
||||
console.log('Target:', bb?.getValue('target'));
|
||||
console.groupEnd();
|
||||
export class VisualizeState implements INodeExecutor {
|
||||
execute(context: NodeExecutionContext): TaskStatus {
|
||||
if (process.env.NODE_ENV === 'development') {
|
||||
console.group('AI State');
|
||||
console.log('Entity:', context.entity.name);
|
||||
console.log('Health:', context.runtime.getBlackboardValue('health'));
|
||||
console.log('State:', context.runtime.getBlackboardValue('currentState'));
|
||||
console.log('Target:', context.runtime.getBlackboardValue('target'));
|
||||
console.groupEnd();
|
||||
}
|
||||
|
||||
return TaskStatus.Success;
|
||||
}
|
||||
return TaskStatus.Success;
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
## 常见反模式
|
||||
@@ -418,133 +388,81 @@ const ai = BehaviorTreeBuilder.create(scene, 'BossAI')
|
||||
.sequence()
|
||||
.sequence()
|
||||
.sequence()
|
||||
.action('DeepAction', () => TaskStatus.Success)
|
||||
.log('太深了', 'DeepAction')
|
||||
.end()
|
||||
.end()
|
||||
.end()
|
||||
.end()
|
||||
|
||||
// 好 - 使用子树扁平化
|
||||
const innerBehavior = BehaviorTreeBuilder.create(scene, 'Inner')
|
||||
.action('DeepAction', () => TaskStatus.Success)
|
||||
.build();
|
||||
|
||||
// 好 - 使用合理的深度
|
||||
.selector()
|
||||
.subTree(innerBehavior)
|
||||
.sequence()
|
||||
.log('Action1')
|
||||
.log('Action2')
|
||||
.end()
|
||||
.sequence()
|
||||
.log('Action3')
|
||||
.log('Action4')
|
||||
.end()
|
||||
.end()
|
||||
```
|
||||
|
||||
### 2. 在行为树中实现游戏逻辑
|
||||
### 2. 在执行器中存储状态
|
||||
|
||||
```typescript
|
||||
// 不好 - 行为树不应包含具体游戏逻辑
|
||||
.action('Attack', (e, bb) => {
|
||||
const enemy = bb?.getValue('enemy');
|
||||
const damage = calculateDamage(e.getComponent(Weapon));
|
||||
enemy.health -= damage;
|
||||
// 错误 - 状态存储在执行器中
|
||||
export class BadAction implements INodeExecutor {
|
||||
private startTime = 0; // 错误!多个节点会共享这个值
|
||||
|
||||
if (enemy.health <= 0) {
|
||||
enemy.die();
|
||||
e.experience += enemy.expReward;
|
||||
execute(context: NodeExecutionContext): TaskStatus {
|
||||
this.startTime = context.totalTime; // 错误!
|
||||
return TaskStatus.Success;
|
||||
}
|
||||
}
|
||||
|
||||
playAttackAnimation();
|
||||
playAttackSound();
|
||||
// 太多细节了！
|
||||
})
|
||||
|
||||
// 好 - 行为树只负责决策，具体逻辑由系统处理
|
||||
.action('Attack', (e, bb) => {
|
||||
const enemy = bb?.getValue('enemy');
|
||||
// 发送攻击命令，具体逻辑由战斗系统处理
|
||||
Core.ecsAPI?.emit('combat:attack', { attacker: e, target: enemy });
|
||||
return TaskStatus.Success;
|
||||
})
|
||||
// 正确 - 状态存储在context.state中
|
||||
export class GoodAction implements INodeExecutor {
|
||||
execute(context: NodeExecutionContext): TaskStatus {
|
||||
if (!context.state.startTime) {
|
||||
context.state.startTime = context.totalTime; // 正确!
|
||||
}
|
||||
return TaskStatus.Success;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 频繁修改黑板
|
||||
|
||||
```typescript
|
||||
// 不好 - 每帧都修改黑板
|
||||
.action('UpdatePosition', (e, bb, dt) => {
|
||||
const pos = getCurrentPosition();
|
||||
bb?.setValue('position', pos); // 每帧都set
|
||||
bb?.setValue('velocity', getVelocity());
|
||||
bb?.setValue('rotation', getRotation());
|
||||
return TaskStatus.Running;
|
||||
})
|
||||
export class FrequentUpdate implements INodeExecutor {
|
||||
execute(context: NodeExecutionContext): TaskStatus {
|
||||
const pos = getCurrentPosition();
|
||||
context.runtime.setBlackboardValue('position', pos); // 每帧都set
|
||||
context.runtime.setBlackboardValue('velocity', getVelocity());
|
||||
context.runtime.setBlackboardValue('rotation', getRotation());
|
||||
return TaskStatus.Running;
|
||||
}
|
||||
}
|
||||
|
||||
// 好 - 只在需要时修改
|
||||
.action('UpdatePosition', (e, bb, dt) => {
|
||||
const oldPos = bb?.getValue('position');
|
||||
const newPos = getCurrentPosition();
|
||||
export class SmartUpdate implements INodeExecutor {
|
||||
execute(context: NodeExecutionContext): TaskStatus {
|
||||
const oldPos = context.runtime.getBlackboardValue('position');
|
||||
const newPos = getCurrentPosition();
|
||||
|
||||
// 只在位置变化时更新
|
||||
if (!positionsEqual(oldPos, newPos)) {
|
||||
bb?.setValue('position', newPos);
|
||||
// 只在位置变化时更新
|
||||
if (!positionsEqual(oldPos, newPos)) {
|
||||
context.runtime.setBlackboardValue('position', newPos);
|
||||
}
|
||||
|
||||
return TaskStatus.Running;
|
||||
}
|
||||
|
||||
return TaskStatus.Running;
|
||||
})
|
||||
```
|
||||
|
||||
## 测试建议
|
||||
|
||||
### 1. 单元测试节点
|
||||
|
||||
```typescript
|
||||
describe('AttackAction', () => {
|
||||
it('应该在有目标时返回Success', () => {
|
||||
const scene = new Scene();
|
||||
const entity = scene.createEntity('Test');
|
||||
const blackboard = entity.addComponent(new BlackboardComponent());
|
||||
|
||||
blackboard.setValue('target', mockEnemy);
|
||||
blackboard.setValue('ammo', 10);
|
||||
|
||||
const result = attackAction(entity, blackboard, 0);
|
||||
|
||||
expect(result).toBe(TaskStatus.Success);
|
||||
});
|
||||
|
||||
it('应该在没有弹药时返回Failure', () => {
|
||||
const scene = new Scene();
|
||||
const entity = scene.createEntity('Test');
|
||||
const blackboard = entity.addComponent(new BlackboardComponent());
|
||||
|
||||
blackboard.setValue('target', mockEnemy);
|
||||
blackboard.setValue('ammo', 0);
|
||||
|
||||
const result = attackAction(entity, blackboard, 0);
|
||||
|
||||
expect(result).toBe(TaskStatus.Failure);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### 2. 集成测试
|
||||
|
||||
```typescript
|
||||
describe('EnemyAI', () => {
|
||||
it('应该在玩家接近时攻击', () => {
|
||||
const scene = new Scene();
|
||||
const ai = createEnemyAI(scene);
|
||||
const blackboard = ai.getComponent(BlackboardComponent);
|
||||
|
||||
// 设置玩家在攻击范围内
|
||||
blackboard?.setValue('player', mockPlayer);
|
||||
blackboard?.setValue('distanceToPlayer', 5);
|
||||
|
||||
BehaviorTreeStarter.start(ai);
|
||||
scene.update();
|
||||
|
||||
// 验证进入了攻击状态
|
||||
expect(blackboard?.getValue('currentState')).toBe('attacking');
|
||||
});
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## 下一步
|
||||
|
||||
- 学习[自定义动作](./custom-actions.md)扩展行为树功能
|
||||
- 学习[自定义节点执行器](./custom-actions.md)扩展行为树功能
|
||||
- 探索[高级用法](./advanced-usage.md)了解更多技巧
|
||||
- 参考[核心概念](./core-concepts.md)深入理解原理
|
||||
|
||||
Reference in New Issue
Block a user