Index of every page on this site: llms.txt
All skills
jame581 avatar

/beehave

@426e8ab
by Jan Mesarčjame581/godotprompter979 stars
63
Run it yourself

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

Use this Skill: https://skilld.dev/gh/jame581/godotprompter/beehave

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈39 tokens for metadata: the name and description. ≈2.9k when used: this file. ≈1.5k more on demand in 1 file.

Description uses 1.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈154 characters, or 1.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.3 · Godot 4.1+ (README: 2.9.x is the 4.1.x line; CI runs 4.5.1, 4.6.3 and 4.7; 4.1–4.4 untested by CI) · MIT · source: https://github.com/bitbrain/beehave · written in GDScript (no official C# API — this skill is GDScript-only by design).

Godot 4.8: not yet confirmed by the addon. Its CI stops at 4.7, and no open issue mentions 4.8 (checked 2026-11-12).


1. When to use Beehave

Approach Best for
Core-engine FSM (state-machine skill) Simple agents, < 5 states, no addon
Beehave (GDScript addon) Lightweight BT, GDScript-only projects, fast iteration
LimboAI BT 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 (Project Settings → Addons → Plugins on 4.8) → tick Beehave.
    Two autoloads are registered on enable and removed again on disable: 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:

Role Node Behavior
Tree root BeehaveTree Ticks the child every frame (or physics/manual); extends Node (not BeehaveNode)
Composites SequenceComposite, SelectorComposite, SimpleParallelComposite, … Flow control — AND / OR / parallel logic
Decorators InverterDecorator, CooldownDecorator, RepeaterDecorator, … Wrap one child to modify its result
Leaves ActionLeaf, ConditionLeaf subclasses Your custom game logic

Composite quick reference

Class Logic
SequenceComposite AND — all children must succeed; fails on first failure
SequenceReactiveComposite AND — re-evaluates from first child every tick while running
SelectorComposite OR — succeeds on first success; fails if all fail
SelectorReactiveComposite OR — re-evaluates from first child every tick while running
SimpleParallelComposite Runs two children simultaneously; result follows primary (child 0)
SequenceRandomComposite Shuffled AND — executes children in random order
SelectorRandomComposite Shuffled OR — tries children in random order

Decorator quick reference

Class Effect
InverterDecorator Flips SUCCESS ↔ FAILURE; passes RUNNING through
AlwaysSucceedDecorator Forces SUCCESS; passes RUNNING through
AlwaysFailDecorator Forces FAILURE; passes RUNNING through
RepeaterDecorator Re-runs child until it succeeds repetitions times
LimiterDecorator Caps child to max_count running ticks, then FAILURE
CooldownDecorator Blocks re-execution for wait_time seconds after child finishes
TimeLimiterDecorator Gives child wait_time seconds; interrupts if still running
DelayDecorator Waits wait_time seconds before first executing child
UntilFailDecorator Loops 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   (empty = parent node; a wrong path leaves actor null)

# 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 2D members.
    var body := actor as Node2D
    var target: Node2D = blackboard.get_value("target")
    if body == null or not is_instance_valid(target):
        return FAILURE
    var in_range := body.global_position.distance_to(target.global_position) <= detection_range
    return SUCCESS if in_range else FAILURE
# AttackAction.gd
class_name AttackAction
extends ActionLeaf

@export var attack_duration: float = 0.5

func tick(actor: Node, blackboard: Blackboard) -> int:
    var elapsed: float = blackboard.get_value("attack_elapsed", 0.0)
    elapsed += get_physics_process_delta_time()

    if elapsed >= attack_duration:
        blackboard.erase_value("attack_elapsed")
        # `actor` is typed Node; guard game-specific methods (or cast to your actor type).
        if actor.has_method("play_attack_animation"):
            actor.call("play_attack_animation")
        return SUCCESS

    blackboard.set_value("attack_elapsed", elapsed)
    return RUNNING

func interrupt(actor: Node, blackboard: Blackboard) -> void:
    # Clean up per-run state when the tree interrupts this action (after_run is not called then)
    blackboard.erase_value("attack_elapsed")
    super(actor, blackboard)  # keeps the debugger's interrupt message

Return codes (defined on BeehaveNode):

  • SUCCESS — action complete / condition met.
  • FAILURE — action failed / condition not met; parent composite decides what to do next.
  • RUNNING — action needs more frames; tree will call tick() again next frame (ActionLeaf only — ConditionLeaf should never return RUNNING).

Optional overrides:

  • before_run(actor, blackboard) — called once before the first tick of a run.
  • after_run(actor, blackboard) — called after the tick that returns SUCCESS/FAILURE; not called on an interrupt.
  • interrupt(actor, blackboard) — called when the tree interrupts a running node.

5. Blackboard

The Blackboard node is a shared key/value store passed to every tick() call. BeehaveTree auto-creates an internal one if you don't assign an external Blackboard node.

# Share one Blackboard across multiple BeehaveTrees on the same actor.
# Assign the same exported Blackboard node to each tree in the Inspector.

# Read / write from any leaf's tick():
func tick(actor: Node, blackboard: Blackboard) -> int:
    # Write
    blackboard.set_value("target", actor.get_nearest_enemy())

    # Read with default
    var speed: float = blackboard.get_value("move_speed", 200.0)

    # Conditional check
    if blackboard.has_value("stunned"):
        return FAILURE

    # Erase (sets key to null; has_value returns false after erase)
    blackboard.erase_value("temp_flag")

    return SUCCESS

Named namespaces: set_value, get_value, has_value and erase_value accept an optional blackboard_name: String parameter (default "default"). Use this to keep separate namespaces on one Blackboard node without name collisions (e.g., per-enemy state vs. shared world state).

Built-in expression leaves: BlackboardSetAction, BlackboardEraseAction, BlackboardHasCondition, and BlackboardCompareCondition let you manipulate the Blackboard entirely via Inspector exports (no GDScript required). Expressions run via Godot's Expression.execute([], blackboard) — so you can call get_value("key") directly in the expression string.


6. Visual debugger

Beehave ships an EditorDebuggerPlugin that adds a 🐝 Beehave tab to the bottom editor panel while your game is running:

  1. Run the project from the Godot editor.
  2. Open the Debugger panel → click the 🐝 Beehave tab.
  3. Select a tree from the list to activate live visualization — active nodes are highlighted each tick.
  4. Optional: click the detach button to float the panel, or set Project Settings → beehave/debugger/start_detached = true to always start detached.

To track per-tree CPU cost in the Performance panel, set custom_monitor = true on the BeehaveTree node. This registers beehave [microseconds]/process_time_<actor_name>-<id> as a Performance monitor.

For a walkthrough of writing custom decorators and conditions, see references/custom-nodes.md.


Implementation checklist

  • addons/beehave/ copied into project; plugin enabled in Project Settings → Plugins (Project Settings → Addons → Plugins on 4.8)
  • BeehaveTree added as a child of the actor; actor_node_path set (or left blank to default to parent)
  • process_thread matches actor's loop: PHYSICS for _physics_process, IDLE for _process
  • tick_rate tuned — increase for background NPCs (e.g., 3) to reduce per-frame cost
  • Every tick() override returns SUCCESS, FAILURE, or RUNNING — never void/null
  • ConditionLeaf subclasses never return RUNNING
  • Per-run state written to the Blackboard, not stored on the leaf node itself
  • after_run or interrupt cleans up any Blackboard keys the action wrote
  • External Blackboard node exported and shared when multiple BeehaveTree nodes need the same data
  • Visual debugger checked at runtime to verify tick flow before shipping AI logic

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning7d3 checks · Risk SAFE
  • Gen Agent Trust Hub7d

    The skill provides comprehensive documentation and GDScript examples for the Beehave behavior tree addon for the Godot engine. It describes how to implement AI logic using behavior trees and blackboards without introducing any malicious code or security vulnerabilities.

  • Socket7d

    No alerts

  • Snyk7d

    Risk: MEDIUM · 1 issue

Signed by skilld at 426e8ab. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 6 days ago.

Activeupdated last week

README badge

README badge for jame581/godotprompter/beehave