跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

beehave

Use when using the Beehave addon — pure-GDScript behavior trees with composites, decorators, leaves, a blackboard, and a visual runtime debugger

jame581 · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add jame581/GodotPrompter --skill beehave

技能说明


name: beehave description: Use when using the Beehave addon — pure-GDScript behavior trees with composites, decorators, leaves, a blackboard, and a visual runtime debugger

Beehave

Related skills: ai-navigation for the movement leaves drive, state-machine for core-engine FSM, limboai for a heavier C++ BT+HSM alternative, godot-brainstorming for choosing an AI approach.

Addon: Beehave · version v2.9.2 · Godot 4.1+ · MIT · source: https://github.com/bitbrain/beehave · written in GDScript (no official C# API — this skill is GDScript-only by design).


1. When to use Beehave

ApproachBest for
Core-engine FSM (state-machine skill)Simple agents, < 5 states, no addon
Beehave (GDScript addon)Lightweight BT, GDScript-only projects, fast iteration
LimboAIBT and HSM together, visual editor, C++ performance, C# support (module build)

Choose Beehave when your project is GDScript-only, you want a behavior tree without a custom engine build, and you value a simple node-in-scene-tree authoring workflow. Beehave trees live entirely in the scene tree — every composite, decorator, and leaf is a regular Node child. For a heavier C++/C# solution with HSM integration, use the limboai skill instead. For plain state machines without a BT, use the built-in state-machine skill.

C# note: Beehave has no official C# API (zero .cs files in addons/beehave/). From C# you can call the GDScript API via Godot cross-language interop (GetNode<Node>(...).Call("tick", actor, blackboard)), but Beehave provides no typed C# classes.


2. Install & enable

  1. Godot AssetLib → search "Beehave" → Download → Reload project.
    Or copy the addons/beehave/ folder from the GitHub release into res://addons/beehave/.
  2. Enable the plugin: Project → Project Settings → Plugins → tick Beehave.
    Two autoloads are registered: BeehaveGlobalMetrics and BeehaveGlobalDebugger.
  3. Optional — copy script_templates/ from the addon into the project root for leaf scaffolding templates.

3. Tree composition

A Beehave tree is built from three kinds of nodes, all placed as regular scene-tree children:

RoleNodeBehavior
Tree rootBeehaveTreeTicks the child every frame (or physics/manual); extends Node (not BeehaveNode)
CompositesSequenceComposite, SelectorComposite, SimpleParallelComposite, …Flow control — AND / OR / parallel logic
DecoratorsInverterDecorator, CooldownDecorator, RepeaterDecorator, …Wrap one child to modify its result
LeavesActionLeaf, ConditionLeaf subclassesYour custom game logic

Composite quick reference

ClassLogic
SequenceCompositeAND — all children must succeed; fails on first failure
SequenceReactiveCompositeAND — re-evaluates from first child every tick while running
SelectorCompositeOR — succeeds on first success; fails if all fail
SelectorReactiveCompositeOR — re-evaluates from first child every tick while running
SimpleParallelCompositeRuns two children simultaneously; result follows primary (child 0)
SequenceRandomCompositeShuffled AND — executes children in random order
SelectorRandomCompositeShuffled OR — tries children in random order

Decorator quick reference

ClassEffect
InverterDecoratorFlips SUCCESS ↔ FAILURE; passes RUNNING through
AlwaysSucceedDecoratorForces SUCCESS; passes RUNNING through
AlwaysFailDecoratorForces FAILURE; passes RUNNING through
RepeaterDecoratorRe-runs child until it succeeds repetitions times
LimiterDecoratorCaps child to max_count running ticks, then FAILURE
CooldownDecoratorBlocks re-execution for wait_time seconds after child finishes
TimeLimiterDecoratorGives child wait_time seconds; interrupts if still running
DelayDecoratorWaits wait_time seconds before first executing child
UntilFailDecoratorLoops child until it returns FAILURE, then returns SUCCESS

Minimal scene-tree example

# Scene tree:
#   Enemy (CharacterBody2D)
#     BeehaveTree               ← tick_rate = 1, process_thread = PHYSICS
#       SelectorComposite
#         SequenceComposite     ← "attack if in range"
#           IsInRangeCondition
#           AttackAction
#         PatrolAction          ← fallback

# BeehaveTree exports:
# @export var enabled: bool = true
# @export var tick_rate: int = 1          (1 = every frame; 3 = every 3 frames)
# @export var process_thread: ProcessThread = PHYSICS
# @export var blackboard: Blackboard      (auto-created if not set)
# @export_node_path var actor_node_path   (defaults to parent node)

# Access the tree from code if you need manual control:
@onready var bt: BeehaveTree = $BeehaveTree

func _ready() -> void:
    # Reduce tick cost: evaluate AI every 3 physics frames
    bt.tick_rate = 3
    # Default process_thread is PHYSICS — switch to IDLE if actor uses _process
    bt.process_thread = BeehaveTree.ProcessThread.IDLE

tick_rate note: tick_rate = 1 evaluates every frame; tick_rate = 3 every 3 frames. Increase for distant/background NPCs to save CPU. Default process thread is PHYSICS — if the actor script uses _process instead of _physics_process, set process_thread = IDLE to keep them in sync.


4. The leaf contract

Leaves hold your game logic. Subclass ActionLeaf for multi-tick work or ConditionLeaf for single-frame checks, then override tick(actor, blackboard).

# IsInRangeCondition.gd
class_name IsInRangeCondition
extends ConditionLeaf

@export var detection_range: float = 150.0

func tick(actor: Node, blackboard: Blackboard) -> int:
    # Beehave types `actor` as Node; cast to your concrete type for
阅读完整来源 ↗