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.

referencescustom-nodes.md

≈1.5k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Beehave — Custom Nodes & Advanced Patterns

Reference for writing custom decorators and conditions, advanced Blackboard patterns, and runtime manual-tick control. Companion to skills/beehave/SKILL.md.


Custom decorator

Subclass Decorator and override tick(actor, blackboard). A decorator must have exactly one BeehaveNode child. Access it via get_children()[0] (or call _safe_tick on the child directly as Beehave's internal nodes do).

# DebugDecorator.gd — prints the child result each tick (useful during development)
class_name DebugDecorator
extends Decorator

@export var label: String = "debug"

func tick(actor: Node, blackboard: Blackboard) -> int:
    var child := get_children()[0] as BeehaveNode
    var result := child._safe_tick(actor, blackboard)
    var result_name := ["SUCCESS", "FAILURE", "RUNNING"][result]
    print("[%s] %s → %s" % [label, child.name, result_name])
    return result

Custom condition

# HasAmmoCondition.gd — checks a property on the actor, no Blackboard needed
class_name HasAmmoCondition
extends ConditionLeaf

func tick(actor: Node, blackboard: Blackboard) -> int:
    return SUCCESS if actor.ammo > 0 else FAILURE

Custom action with interrupt cleanup

When a SequenceReactiveComposite or SelectorReactiveComposite re-evaluates from the first child while an action is RUNNING, it calls interrupt() on the running node. Always pair per-run Blackboard writes with cleanup:

# MoveToTargetAction.gd
class_name MoveToTargetAction
extends ActionLeaf

const ARRIVE_DIST := 8.0

func tick(actor: Node, blackboard: Blackboard) -> int:
    # Beehave types `actor` as Node; cast to CharacterBody2D for the movement API.
    var body := actor as CharacterBody2D
    if body == null:
        return FAILURE
    var target_pos: Vector2 = blackboard.get_value("target_pos", Vector2.ZERO)
    if body.global_position.distance_to(target_pos) <= ARRIVE_DIST:
        _clear(blackboard)
        return SUCCESS

    var dir := body.global_position.direction_to(target_pos)
    body.velocity = dir * blackboard.get_value("move_speed", 150.0)
    body.move_and_slide()
    blackboard.set_value("is_moving", true)
    return RUNNING

func interrupt(actor: Node, blackboard: Blackboard) -> void:
    _clear(blackboard)
    var body := actor as CharacterBody2D
    if body != null:
        body.velocity = Vector2.ZERO

func after_run(actor: Node, blackboard: Blackboard) -> void:
    _clear(blackboard)

func _clear(blackboard: Blackboard) -> void:
    blackboard.erase_value("is_moving")

Manual tick (MANUAL process thread)

Set process_thread = MANUAL to drive the tree yourself — useful for turn-based or time-sliced AI:

# TurnManager.gd — tick all enemy trees once per turn
extends Node

@export var enemies: Array[Node] = []

func execute_enemy_turn() -> void:
    for enemy in enemies:
        var bt: BeehaveTree = enemy.get_node("BeehaveTree")
        var result := bt.tick()
        # result is SUCCESS, FAILURE, or RUNNING (int enum on BeehaveNode)
        if result == BeehaveNode.RUNNING:
            # Enemy needs more turns — re-queue for next call
            pass

bt.tick() returns the integer status code. In MANUAL mode BeehaveTree never calls tick() on its own — it only runs when you call it.


Sharing a Blackboard across multiple trees

One common pattern: give the actor a single Blackboard node and export it into several BeehaveTree nodes (e.g., movement tree + combat tree). All trees read/write the same key space.

# In the actor's _ready(), or wire via Inspector exports:
@onready var shared_bb: Blackboard = $Blackboard
@onready var combat_tree: BeehaveTree = $CombatTree
@onready var movement_tree: BeehaveTree = $MovementTree

func _ready() -> void:
    combat_tree.blackboard = shared_bb
    movement_tree.blackboard = shared_bb

Use named namespaces to avoid key collisions between subsystems:

# Combat leaf — writes into "combat" namespace
blackboard.set_value("target", enemy, "combat")

# Movement leaf — reads from default namespace; isolated from combat keys
var speed: float = blackboard.get_value("move_speed", 200.0)

Weight-based random composites

SequenceRandomComposite and SelectorRandomComposite support per-child weights via RandomizedComposite. Enable via the Inspector:

  1. Select the random composite node.
  2. Set use_weights = true in the Inspector.
  3. Per-child Weights/<child_name> integer properties (1–100) appear dynamically in the Inspector.

There is no dedicated method for weights, but each Weights/<child_name> property goes through _set(), so composite.set("Weights/Attack", 5) changes it at runtime (with use_weights on).


Known issues (v2.9.3)

  • RepeaterDecorator.get_class_name() bug: The method returns an Array[StringName] whose last entry is &"LimiterDecorator" instead of &"RepeaterDecorator", a copy-paste error in the source. The actual GDScript class_name is RepeaterDecorator (autocomplete and is checks work correctly); only get_class_name() returns the wrong value. Avoid get_class_name() for identity checks on this node.

Built-in expression leaves (no GDScript required)

Node Purpose
BlackboardSetAction Sets key → value (GDScript expressions evaluated against Blackboard)
BlackboardEraseAction Erases a key from the Blackboard
BlackboardHasCondition SUCCESS if key exists and is non-null
BlackboardCompareCondition Compares two expressions with ==, !=, >, <, >=, <=

Expressions run via Expression.execute([], blackboard) — the Blackboard is the base instance, so you can call get_value("health") directly in the expression string.

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