#MoonBit Behavior Tree

#特性

#安装

#方法一：moon add（推荐）

moon add mhh12345678/behavior_tree

#方法二：手动添加依赖

[deps]
"mhh12345678/behavior_tree" = "0.1.2"

import {
  "mhh12345678/behavior_tree" @bt
}

#快速开始

// 1. 创建共享黑板
let bb = @bt.Blackboard::new()
bb.set_int("health", 45)
bb.set_bool("enemy_in_sight", true)

// 2. 使用 Builder 声明式构建行为树
let tree = @bt.Builder::new()
  .selector()
    // 血量低时逃跑（优先级最高）
    .sequence()
      .condition(fn(bb) { bb.get_int("health").unwrap_or(100) < 50 })
      .action(fn(_) { println("Low health! Fleeing..."); @bt.BTSuccess })
      .end()
    // 发现敌人则追击
    .sequence()
      .condition(fn(bb) { bb.get_bool("enemy_in_sight").unwrap_or(false) })
      .action(fn(_) { println("Enemy spotted! Chasing..."); @bt.BTSuccess })
      .end()
    // 默认巡逻
    .action(fn(_) { println("Patrolling..."); @bt.BTSuccess })
    .end()
  .build()

// 3. 执行单次 Tick
let status = tree.tick(bb)
println("Result: \{status.to_string()}")
// 输出: Low health! Fleeing...
// 输出: Result: Success

#高级用法

#事件中断（InterruptNode）

let bus = @bt.EventBus::new()
let tree = @bt.interrupt_node(bus, "enemy_spotted", patrol_tree, attack_tree)

// 在任意时刻发出事件，下一次 tick 会切换到 attack_tree
bus.emit("enemy_spotted")
let _ = tree.tick(bb)

bus.on("damage", fn(bb) {
  bb.set_int("last_damage", 5)
  @bt.BTSuccess
})
bus.emit("damage")
let _ = bus.dispatch("damage", bb)

#多 NPC 并发调度（Scheduler）

let sched = @bt.Scheduler::new()
sched.add(@bt.SchedulerEntry::new("guard1", guard_tree, @bt.Blackboard::new()))
sched.add(@bt.SchedulerEntry::new("guard2", patrol_tree, @bt.Blackboard::new()))

// 单次帧调用，所有 NPC 同时 tick
let results = sched.tick()
for r in results {
  println("\{r.name}: \{r.status.to_string()}")
}

#黑板快照沙盒

bb.set_int("hp", 100)
bb.snapshot()         // 保存当前状态
bb.set_int("hp", 0)   // 模拟伤害
// 测试沙盒内的行为...
bb.restore()          // 回滚到快照
// bb.get_int("hp") == Some(100)

#原子状态事务与差异补丁

let before = bb.clone()
let accepted = bb.transactional(fn(working) {
  working.set_int("credits", working.get_int_or("credits", 0) - 20)
  working.set_string("last_action", "buy_potion")
  working.get_int_or("credits", 0) >= 0
})
let patch = before.diff(bb)
let _ = patch.to_text()

#有界事件路由

let queue = @bt.EventQueue::new()
let router = @bt.EventRouter::new(queue, 4)
let _ = router.on("damage", fn(bb, event) {
  bb.set_int("last_damage", event.payload().unwrap().as_int().unwrap())
  @bt.BTSuccess
})
let _ = queue.emit_value("damage", @bt.Value::Int(5))
let report = router.tick(bb)
println(report.to_line())

#优先级与帧预算调度

let scheduler = @bt.BudgetScheduler::new(8)
let _ = scheduler.add(
  @bt.BudgetTask::new("guard-1", 10, guard_tree, @bt.Blackboard::new()),
)
let report = scheduler.tick()
println("pending=\{report.pending()}, skipped=\{report.skipped()}")

#有界执行追踪

let trace = @bt.TraceBuffer::new(256)
let traced = @bt.trace_buffer_node("combat", combat_tree, trace)
let _ = traced.tick(bb)
println(trace.to_csv())

#项目结构

.
├── blackboard.mbt          # 黑板上下文（snapshot/restore）
├── blackboard_patch.mbt    # 事务、差异补丁和原子状态提交
├── node.mbt                # Status / Ref / Node / Sequence / Selector / Parallel / RandomSelector
├── decorator.mbt           # 8 种修饰器节点
├── leaf.mbt                # Action / Condition 叶子节点
├── builder.mbt             # 链式 Builder API
├── parser.mbt              # Trace 调试节点包装器
├── event.mbt               # EventBus / InterruptNode / ConditionGuardNode
├── event_router.mbt        # 有界 payload 事件路由器
├── scheduler.mbt           # 多树 Scheduler 调度器
├── budget_scheduler.mbt    # 优先级与帧预算调度器
├── helpers.mbt             # 便捷工厂函数
├── runtime.mbt / telemetry.mbt / health.mbt # 运行时生命周期与可观测性
├── trace_buffer.mbt        # 有界环形执行追踪
├── policy_nodes.mbt / safety.mbt / quorum.mbt # 生产策略与安全边界
├── benchmark.mbt / scenario.mbt # 可重复基准和场景矩阵
├── behavior_tree_wbtest.mbt # 核心单元测试
├── integration_test.mbt / boundary_test.mbt # 集成与边界测试
├── production_runtime_test.mbt # 事务、路由、追踪和预算调度场景
├── lib_doc.mbt             # 库文档快速入门示例
├── cmd/main/main.mbt       # 守卫 NPC AI 仿真演示
└── .github/workflows/ci.yml # CI：wasm-gc / js / native 全平台

#运行与测试

# 类型检查（全平台）
moon check --target all

# 执行 80 个测试用例（全部通过）
moon test --target all

# 运行守卫 NPC AI 仿真演示
moon run cmd/main

#可重复基准

let csv = @bt.standard_benchmark_csv()
println(csv)

#严格验收命令

moon fmt --check
moon check --deny-warn
moon test --deny-warn
moon info
moon run cmd/main

#示例输出

=== MoonBit Behavior Tree Guard AI Simulation ===

--- Tick 1: Patrol mode ---
-> Tick: Patrol Action
AI ACTION: Patrol waypoint 1
<- Patrol Action Result: Success

--- Tick 3: Enemy spotted at distance 8.0 ---
-> Tick: Combat Branch
AI ACTION: Chasing enemy... distance 5
<- Combat Branch Result: Running

--- Tick 7: Guard HP=20, flees ---
-> Tick: Flee Branch
AI ACTION: Low health! Fleeing...
<- Flee Branch Result: Success

#许可证

#参考资料

• Behavior Trees in AI：https://en.wikipedia.org/wiki/Behavior_tree_(artificial_intelligence,_robotics_and_control)
• MoonBit 文档：https://docs.moonbitlang.com
• mooncakes.io：https://mooncakes.io