Behavior Tree basic building blocks.
wikla.core aims to follow terminology outlined in Towards a Unified Behavior Trees Framework for Robot Control by Marzinotto et al. (2014), especially sections I-IV.
Whenever a tick is done it yields with a Result. That Result is tied to Status flag carried by the node and contains the modified state. When root returns a Result -- the tick is done.
Leaf nodes get ticked:
(tick leaf-node stash)
=> Result w/ leaf-node' and stash'
(tick! leaf-node)
=> Result w/ leaf-node'
Composite nodes provide children for execution via part call:
(part composite-node)
=> child-node
And compute Result when their child comes back carried by Result:
(join composite-node Result w/ child-node' and optional stash')
=> Result w/ composite-node' and optional stash'
All this is pure by default, using only immutable data.
For completeness a fourth status is introduced: Ready. It's the default status for all freshly created nodes that were not yet ticked and can be used to ask the Ticker for immediate re-execution during the tick. Unlike Success, Failure or Running it will not be reported outside of the Ticker. The source paper calls it NotTicked and only uses it for initial state.
Behavior Tree basic building blocks.
wikla.core aims to follow terminology outlined in _Towards a Unified Behavior
Trees Framework for Robot Control_ by Marzinotto et al. (2014), especially
sections I-IV.
Whenever a tick is done it yields with a Result. That Result is tied to Status
flag carried by the node and contains the modified state. When root returns
a Result -- the tick is done.
Leaf nodes get ticked:
(tick leaf-node stash)
=> Result w/ leaf-node' and stash'
(tick! leaf-node)
=> Result w/ leaf-node'
Composite nodes provide children for execution via part call:
(part composite-node)
=> child-node
And compute Result when their child comes back carried by Result:
(join composite-node Result w/ child-node' and optional stash')
=> Result w/ composite-node' and optional stash'
All this is pure by default, using only immutable data.
For completeness a fourth status is introduced: Ready. It's the default status
for all freshly created nodes that were not yet ticked and can be used to ask
the Ticker for immediate re-execution during the tick. Unlike Success, Failure
or Running it will not be reported outside of the Ticker. The source paper
calls it NotTicked and only uses it for initial state.(action tick-fn)(action properties tick-fn)Action wraps a single function: tick-fn. This constructor accepts properties map and the tick-fn.
Properties can contain special keys that will go directly into Action: :flag and :parameters. All other fields go to :properties.
Tick call with stash:
(tick a-action stash) → Result | flag
Translates to:
(tick-fn a-action stash) → Success | Failure | Running | Ready
Stash-less call:
(tick! a-action) → Result | flag
Translates to:
(tick-fn a-action) → Success | Failure | Running | Ready
Note: Both node and stash updates are persisted.
Action wraps a single function: tick-fn. This constructor accepts
properties map and the tick-fn.
Properties can contain special keys that will go directly into Action: :flag
and :parameters. All other fields go to :properties.
Tick call with stash:
(tick a-action stash) → Result | flag
Translates to:
(tick-fn a-action stash) → Success | Failure | Running | Ready
Stash-less call:
(tick! a-action) → Result | flag
Translates to:
(tick-fn a-action) → Success | Failure | Running | Ready
Note: Both node and stash updates are persisted.
(action? node)Is given node a conforming Action node?
Is given node a conforming Action node?
(all-tick root)(all-tick root stash)Stash and stashless tick: creates a Stepper, exhausts it, returns stage.
Stash and stashless tick: creates a Stepper, exhausts it, returns stage.
(attach-hook node hook-fn)(attach-hook node on-status hook-fn)Attach hook-fn for given status or Result if status not given.
Hooks can be attached on flags (SUCCESS, FAILURE, RUNNING, READY) or any Result.
Attach hook-fn for given status or Result if status not given. Hooks can be attached on flags (SUCCESS, FAILURE, RUNNING, READY) or any Result.
(condition tick-fn)(condition properties tick-fn)Condition wraps a single function: tick-fn. This constructor accepts properties map and the tick-fn.
Properties can contain special keys that will go directly into Condition: :flag and :parameters. All other fields go to :properties.
Tick call with stash:
(tick a-condition stash) → Result | flag
Translates to:
(tick-fn a-condition stash) → Success | Failure | Ready
Stash-less call:
(tick! a-condition) → Result | flag
Translates to:
(tick-fn a-condition) → Success | Failure | Ready
Note: Updates to node are kept, while stash updates are discarded.
Condition wraps a single function: tick-fn. This constructor accepts
properties map and the tick-fn.
Properties can contain special keys that will go directly into Condition:
:flag and :parameters. All other fields go to :properties.
Tick call with stash:
(tick a-condition stash) → Result | flag
Translates to:
(tick-fn a-condition stash) → Success | Failure | Ready
Stash-less call:
(tick! a-condition) → Result | flag
Translates to:
(tick-fn a-condition) → Success | Failure | Ready
Note: Updates to node are kept, while stash updates are discarded.
(condition? node)Is given node a conforming Condition node?
Is given node a conforming Condition node?
(decorator branch-cond-fn post-join-fn own-tick-fn node)(decorator properties branch-cond-fn post-join-fn own-tick-fn node)Decorator is a hybrid node, defining both tick and part/join calls.
It holds a single child and decides if it should be executed: first tick is executed and calls:
(branch-cond-fn decorator stash) → true | false
And in stash-less version:
(branch-cond-fn decorator) → true | false
cond-fn returns true: child will be executed. Decorator changes its type to composite and signals Ready. During join call child node lands in branches and post-join-fn is called via Action tick:
(tick (action properties post-join-fn) Result) → Result | flag
This function decides the final shape of the Result the Decorator will return, so it needs to at least extract stash from Result and pass it on during stash call or return Status during stash-less one. No changes done to Result's node will be kept, it's given for information only.
cond-fn returns false: child is not used, own-tick-fn is executed via Action tick:
(tick (action own-tick-action own-tick-fn) stash) → Result | flag
Or in stash-less variant:
(tick! (action own-tick-action own-tick-fn)) → Result | flag
This constructor accepts
Expectations:
(branch-cond-fn properties stash) → true | false
(post-join-fn post-join-action Result)
→ Success | Failure | Running | Ready
(own-tick-fn own-tick-action stash)
→ Success | Failure | Running | Ready
Decorator is a hybrid node, defining both tick and part/join calls.
It holds a single child and decides if it should be executed: first tick
is executed and calls:
(branch-cond-fn decorator stash) → true | false
And in stash-less version:
(branch-cond-fn decorator) → true | false
**cond-fn returns true:** child will be executed.
Decorator changes its type to composite and signals Ready. During join call
child node lands in branches and post-join-fn is called via Action tick:
(tick (action properties post-join-fn) Result) → Result | flag
This function decides the final shape of the Result the Decorator will
return, so it needs to at least extract stash from Result and pass it on
during stash call or return Status during stash-less one. No changes done
to Result's node will be kept, it's given for information only.
**cond-fn returns false:** child is not used, own-tick-fn is executed
via Action tick:
(tick (action own-tick-action own-tick-fn) stash) → Result | flag
Or in stash-less variant:
(tick! (action own-tick-action own-tick-fn)) → Result | flag
This constructor accepts
* properties, to be shared between Decorator and its Actions,
* branch-cond-fn used for branching? decision if first tick,
* post-join-fn used to seed post-join-action, ticked in join
* own-tick-fn used to seed own-tick-action, ticked in tick
* single child node.
Expectations:
(branch-cond-fn properties stash) → true | false
(post-join-fn post-join-action Result)
→ Success | Failure | Running | Ready
(own-tick-fn own-tick-action stash)
→ Success | Failure | Running | Ready
(decorator? node)Is given node a conforming Decorator node?
Is given node a conforming Decorator node?
The blessed way to represent node properties.
The blessed way to represent node properties.
(detach-hook node)(detach-hook node on-status)Detach hook-fn for given status or Result if status not given.
Hooks can be found on flags (SUCCESS, FAILURE, RUNNING, READY) or any Result.
Detach hook-fn for given status or Result if status not given. Hooks can be found on flags (SUCCESS, FAILURE, RUNNING, READY) or any Result.
(failure)(failure node)(failure node stash)Creates Result with Success flag. No argument version gives just FAILURE.
Creates Result with Success flag. No argument version gives just FAILURE.
(mu & _)Always nil, just like (constantly nil), except interned.
Always nil, just like (constantly nil), except interned.
(no & _)Always false, just like (constantly false), except interned.
Always false, just like (constantly false), except interned.
A Node's life.
A Node's life.
(-node? this)Am I a Node?
Am I a Node?
(join this sub)Composite: accepts Result, returns Result.
Composite: accepts Result, returns Result.
(shift this)(shift this new-flag)Get or set the Status flag.
Get or set the Status flag.
(tick this stash)Leaf: accepts stash, returns Result.
Leaf: accepts stash, returns Result.
(branch? this)True if composite (part & join), false if leaf (tick).
True if composite (part & join), false if leaf (tick).
(hooks this)(hooks this new-hooks)Get or set hooks. See ::hooks.
Get or set hooks. See ::hooks.
(part this)Composite: returns next child to execute, nil if none left.
Composite: returns next child to execute, nil if none left.
(params this)(params this new-params)Get or set the parameters.
Get or set the parameters.
(branches this)(branches this new-children)Get or set children.
Get or set children.
(tick! this)Leaf: smash in place, return stashless Result or flag.
Leaf: smash in place, return stashless Result or flag.
(label this)(label this new-label)Get or set the name.
Get or set the name.
(parallel success-threshold failure-threshold nodes)(parallel properties success-threshold failure-threshold nodes)Parallel runs children from left to right, Result from last join:
This constructor accepts properties map, along with success-threshold, failure-threshold and a sequence of at least one node.
Parallel runs children from left to right, Result from last join: * Success if enough children reported Success * Failure if enough children reported Failure * Running and reset if consensus not reached. This constructor accepts properties map, along with success-threshold, failure-threshold and a sequence of at least one node.
(parallel? node)Is given node a conforming Parallel node?
Is given node a conforming Parallel node?
(post-join-pass-through that result)Consume Result, pass Result through.
Consume Result, pass Result through.
(ready)(ready node)(ready node stash)Creates Result with Success flag. No argument version gives just READY.
Creates Result with Success flag. No argument version gives just READY.
(reset node)Accepts a Node and cycles it to fresh state, utilizing ::initial field from that node's meta.
Accepts a Node and cycles it to fresh state, utilizing ::initial field from that node's meta.
(resetable node)Returns a node with ::initial meta field propagated for future reset calls.
Returns a node with ::initial meta field propagated for future reset calls.
(resetable? node)Accepts a Node and tells if it can be reset.
Accepts a Node and tells if it can be reset.
(return-result new-flag node stash)Accepts status, Node node and stash. Sets flag in node and gives Result.
Accepts status, Node node and stash. Sets flag in node and gives Result.
(run-hooks! result)Run attached hooks, possibly with side effects! Returns result.
Run attached hooks, possibly with side effects! Returns result.
(running)(running node)(running node stash)Creates Result with Success flag. No argument version gives just RUNNING.
Creates Result with Success flag. No argument version gives just RUNNING.
(selection nodes)(selection properties nodes)Selection runs children from left to right, Result decided in join:
This constructor accepts properties map and a sequence of at least one node.
Selection runs children from left to right, Result decided in join: * Success immediately when child reported Success * Failure only when all children reported Failure * Running immediately when child reported Running This constructor accepts properties map and a sequence of at least one node.
(selection? node)Is given node a conforming Selection node?
Is given node a conforming Selection node?
(sequence nodes)(sequence properties nodes)Sequence runs children from left to right, Result decided in join:
This constructor accepts properties map and a sequence of at least one node.
Sequence runs children from left to right, Result decided in join: * Success only when all children reported Success * Failure immediately when child reported Failure * Running immediately when child reported Running This constructor accepts properties map and a sequence of at least one node.
(sequence? node)Is given node a conforming Sequence node?
Is given node a conforming Sequence node?
Shortcut methods for Status related checks. To be implemented by Result and extended over keyword type.
All checks? are strictly boolean, that is: true | false.
Shortcut methods for Status related checks. To be implemented by Result and extended over keyword type. All checks? are strictly boolean, that is: true | false.
(has-node? this)Is stem there?
Is stem there?
(success? this)Is this Success?
Is this Success?
(-status? this)Am I a status?
Am I a status?
(ready? this)Is this Ready?
Is this Ready?
(decided? this)Is this Success, Failure or Running?
Is this Success, Failure or Running?
(yield this)(yield this new-stash)Get-set stash.
Get-set stash.
(running? this)Is this Running?
Is this Running?
(done? this)Is this Success or Failure.
Is this Success or Failure.
(has-stash? this)Is yield there?
Is yield there?
(failure? this)Is this Failure?
Is this Failure?
(status this)Gives the keyword Status.
Gives the keyword Status.
(stem this)(stem this new-node)Get-set node.
Get-set node.
(exhaust this)Run until finished. Returns Result.
Run until finished. Returns Result.
(finished? this)Are we done? Returns a boolean.
Are we done? Returns a boolean.
(handle-branch this)Do the branch thing! Returns a Stepper.
Do the branch thing! Returns a Stepper.
(handle-leaf this)Do the leaf thing! Returns a Stepper.
Do the leaf thing! Returns a Stepper.
(step this)Do one thing. Returns Stepper.
Do one thing. Returns Stepper.
(stepper root)(stepper root stash)Initiate a stepper for functional or procedural execution.
Initiate a stepper for functional or procedural execution.
(success)(success node)(success node stash)Creates Result with Success flag. No argument version gives just SUCCESS.
Creates Result with Success flag. No argument version gives just SUCCESS.
(ticker tree)(ticker properties tree)Ticker abstracts a loop that executes its tree, until top level node returns Success, Failure or Running. Results from that group are propagated up the tree. Result marked as Ready is re-executed immediately.
This constructor accepts properties map and a node.
Ticker abstracts a loop that executes its tree, until top level node returns Success, Failure or Running. Results from that group are propagated up the tree. Result marked as Ready is re-executed immediately. This constructor accepts properties map and a node.
(ticker? node)Is given node a conforming Ticker node?
Is given node a conforming Ticker node?
(wrap-properties)(wrap-properties a-map)Creates a map based on default-properties.
Creates a map based on default-properties.
(wrapped-properties? a-thing)Is given thing a conforming instance?
Is given thing a conforming instance?
(yes & _)Always true, just like (constantly true), except interned.
Always true, just like (constantly true), except interned.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |