Module nodes 

Built-in behavior-tree node library.

Every function in this module returns a BehaviorNode::Leaf (or a small composite that acts like a logical leaf) that encapsulates one well-defined game-AI action or condition. They are designed to be composed with crate::behavior::tree::TreeBuilder.

Node catalogue

Actions (mutate world state / run over time)

• wait — pause for a fixed duration
• move_to — move agent toward a target position
• look_at — rotate agent to face a target
• play_animation — trigger and wait for an animation clip
• set_blackboard — write a value onto the blackboard

Conditions (instant pass/fail checks)

• check_distance — is agent within/outside a range?
• check_health — compare health against a threshold
• check_line_of_sight — can the agent see a target?
• check_blackboard_bool — read a bool flag
• check_blackboard_float — compare a float value

Decorator wrappers (higher-order node constructors)

• invert_node — flip Success↔Failure
• repeat_node — run child N times
• timeout_node — fail child if it takes too long

Composite helpers

• random_selector — shuffle children then select
• weighted_selector — pick child by probability weight

Enums

CompareOp

Condition: compare a health value on the blackboard against a threshold.

Functions

blackboard_guard

Only tick child when a blackboard bool key equals expected.

check_blackboard_bool

Condition: return Success if key holds a truthy bool.

check_blackboard_exists

Condition: succeed if key is present in the blackboard.

check_blackboard_float

Condition: compare a float blackboard value.

check_distance

Condition: is the distance between two Vec3 positions within [min, max]?

check_health

Condition: health_key OP threshold → Success / Failure.

check_health_low

Shorthand: succeed if health < threshold (agent is wounded).

check_health_ok

Shorthand: succeed if health >= threshold (agent is healthy).

check_in_range

Condition: is the distance within range (i.e. 0 <= dist <= range)?

check_line_of_sight

Condition: can agent see target?

check_out_of_range

Condition: is the distance strictly outside range?

clear_blackboard

Remove a key from the blackboard and succeed.

cooldown_node

Only tick child if at least cooldown_secs have elapsed since last tick.

copy_blackboard

Copy a blackboard value from one key to another and succeed.

debug_log

A leaf that logs a message and always succeeds. Useful for tracing tree execution during development.

debug_log_blackboard

A leaf that logs the current value of a blackboard key and succeeds.

face_direction

Instantly snap the agent’s yaw to face a target position.

fail_always

A leaf that always fails immediately.

fire_at_target

Action: attempt to fire a projectile at a target.

flee

Move the agent away from a threat position stored on the blackboard.

idle

Always-running idle node. Returns Running indefinitely.

invert_node

Wrap child in an Invert decorator: Success↔Failure, Running unchanged.

look_at

Smoothly rotate the agent’s yaw toward a target.

melee_attack

Action: perform a melee attack if the target is within melee_range.

move_to

Move an agent toward a 3-D target stored on the blackboard.

move_to_2d

Variant that reads the target from a Vec2 position and moves in 2-D.

patrol_set_target

Move through a fixed list of waypoints in a loop.

play_animation

Trigger a named animation clip and block until it finishes.

random_selector

A Selector that shuffles its children randomly on each activation, then tries them in the shuffled order. Because the shuffle is computed per-activation (inside the tick closure), the node re-shuffles every time the selector restarts.

repeat_forever

Repeat child forever (always returns Running).

repeat_node

Repeat child exactly count times; succeed only if all iterations succeed.

set_blackboard

Instantly write a value onto the blackboard and succeed.

succeed_always

A leaf that always succeeds immediately.

timeout_node

Return Failure if child is still Running after timeout_secs seconds.

wait

Pause execution for duration_secs seconds, then succeed.

weighted_selector

A Selector that picks exactly one child based on probability weights and ticks only that child. Each activation samples a fresh child.