decorator 
Base decorator node. Wraps a single child with a condition check.
Supports observer aborts: register to watch specific signals, which triggers a re-check of the condition, potentially aborting the plan depending on the observer_abort settings.
Vars | |
| child | Resolved child instance. Populated at tree construction. Do not set directly. |
|---|---|
| child_active | Whether the child is currently BT_RUNNING. This makes tick() skip check_condition() and delegate directly to child.tick(). |
| child_typepath | Typepath of the single child node. Resolved to an instance at tree construction. |
| has_observer_signals | Set to TRUE when register_observe_signals() registered at least one signal. If this is not true but we are observing; then we need to check the condition every tick; not efficient, but allows for reactivity. |
| invert | If TRUE, the result of check_condition() is inverted before gating the child. |
| is_polled | TRUE when this decorator is registered in the controller's polling_observers list. |
| last_poll_result | Last result seen by poll_condition(). null = not yet polled. Used to detect condition changes when no signal is available. |
| last_poll_time | world.time of the last poll_condition() evaluation. Only meaningful when polling_rate > 0. |
| observer_abort | Observer abort mode. Controls reactive re-planning when watched keys change. BT_ABORT_NONE (default) means no reactivity. BT_ABORT_SELF triggers re-plan if we're inside one of our children and the condition changes, while BT_ABORT_LOWER_PRIORITY triggers re-plan if we are in a lower priority (e.g. further to the right) node and the condition changes. BT_ABORT_BOTH does both. |
| observers_registered | Set to TRUE once register_observe_signals() has been called for this instance. |
| polling_rate | When polling (no observer signals), minimum deciseconds between condition re-evaluations. 0 = every controller tick. Please don't run viewers() every tick bro. |
Procs | |
| bb_key_equals | Returns TRUE if the blackboard value at key equals the given value. |
| bb_key_exists | Returns TRUE if the blackboard key holds a non-null, non-deleted value. |
| bb_key_greater | Returns TRUE if the blackboard value at key is strictly greater than threshold. |
| check_condition | Override to implement custom condition logic. Return TRUE to allow child.tick() to proceed, FALSE to return BT_FAILURE immediately. |
| evaluate_for_observer | Proc called by the observer system when a watched key changes. Return TRUE if the decorator's condition would pass, FALSE otherwise. |
| on_child_complete | Called when the child finishes (returns a non-RUNNING result after being ticked). NOT called when the condition gate blocks the child, or when the tree is cancelled mid-tick. |
| on_signal_changed | Shared signal handler. Calls on_observed_change() with owning_controller. |
| poll_condition | Called by the controller's observer handler when a watched blackboard key changes. Re-evaluates evaluate_for_observer() and aborts based on observer_abort policy. |
| register_observe_signals | Override to register all signal observers for this decorator. Return TRUE if any were registered. If a decorator does not handle this and we have an observer_abort mode that isn't BT_ABORT_NONE, the system will fall back to ticking the condition every tick, which is less efficient but allows for reactivity without signals. |
| unregister_observe_signals | Override to unregister all observers registered by register_observe_signals(). |
Var Details
child
Resolved child instance. Populated at tree construction. Do not set directly.
child_active
Whether the child is currently BT_RUNNING. This makes tick() skip check_condition() and delegate directly to child.tick().
child_typepath
Typepath of the single child node. Resolved to an instance at tree construction.
has_observer_signals
Set to TRUE when register_observe_signals() registered at least one signal. If this is not true but we are observing; then we need to check the condition every tick; not efficient, but allows for reactivity.
invert
If TRUE, the result of check_condition() is inverted before gating the child.
is_polled
TRUE when this decorator is registered in the controller's polling_observers list.
last_poll_result
Last result seen by poll_condition(). null = not yet polled. Used to detect condition changes when no signal is available.
last_poll_time
world.time of the last poll_condition() evaluation. Only meaningful when polling_rate > 0.
observer_abort
Observer abort mode. Controls reactive re-planning when watched keys change. BT_ABORT_NONE (default) means no reactivity. BT_ABORT_SELF triggers re-plan if we're inside one of our children and the condition changes, while BT_ABORT_LOWER_PRIORITY triggers re-plan if we are in a lower priority (e.g. further to the right) node and the condition changes. BT_ABORT_BOTH does both.
observers_registered
Set to TRUE once register_observe_signals() has been called for this instance.
polling_rate
When polling (no observer signals), minimum deciseconds between condition re-evaluations. 0 = every controller tick. Please don't run viewers() every tick bro.
Proc Details
bb_key_equals
Returns TRUE if the blackboard value at key equals the given value.
bb_key_exists
Returns TRUE if the blackboard key holds a non-null, non-deleted value.
bb_key_greater
Returns TRUE if the blackboard value at key is strictly greater than threshold.
check_condition
Override to implement custom condition logic. Return TRUE to allow child.tick() to proceed, FALSE to return BT_FAILURE immediately.
evaluate_for_observer
Proc called by the observer system when a watched key changes. Return TRUE if the decorator's condition would pass, FALSE otherwise.
on_child_complete
Called when the child finishes (returns a non-RUNNING result after being ticked). NOT called when the condition gate blocks the child, or when the tree is cancelled mid-tick.
on_signal_changed
Shared signal handler. Calls on_observed_change() with owning_controller.
poll_condition
Called by the controller's observer handler when a watched blackboard key changes. Re-evaluates evaluate_for_observer() and aborts based on observer_abort policy.
BT_ABORT_SELF: condition became FALSE and we're running our children > cancel actions BT_ABORT_LOWER_PRIORITY: condition became TRUE and we're running lower priority nodes > cancel actions Called by the controller's polling loop for decorators that have no signal observers. Sets a baseline on first call, then fires on_observed_change() only when the result changes.
register_observe_signals
Override to register all signal observers for this decorator. Return TRUE if any were registered. If a decorator does not handle this and we have an observer_abort mode that isn't BT_ABORT_NONE, the system will fall back to ticking the condition every tick, which is less efficient but allows for reactivity without signals.
unregister_observe_signals
Override to unregister all observers registered by register_observe_signals().