Awesome
NPBehave - An event driven Behavior Tree Library for code based AIs in Unity
NPBehave aims to be:
- lightweight, fast & simple
- event driven
- easily extendable
- A framework to define AIs with code, there is no visual editing support
NPBehave builds on the powerful and flexible code based approach to define behavior trees from the BehaviorLibrary and mixes in some of the great concepts of Unreal's behavior trees. Unlike traditional behavior trees, event driven behavior trees do not need to be traversed from the root node again each frame. They stay in their current state and only continue to traverse when they actually need to. This makes them more performant and a lot simpler to use.
In NPBehave you will find most node types from traditional behavior trees, but also some similar to those found in the Unreal engine. Please refer to the Node Type Reference for the full list. It's fairly easy to add your own custom node types though.
If you don't know anything about behavior trees, it's highly recommended that you gain some theory first, this Gamasutra article is a good read.
Installation
Just drop the NPBehave
folder into your Unity project. There is also an Examples
subfolder, with some example scenes you may want to check out.
Example: "Hello World" Behavior Tree
Let's start with an example:
using NPBehave;
public class HelloWorld : MonoBehaviour
{
private Root behaviorTree;
void Start()
{
behaviorTree = new Root(
new Action(() => Debug.Log("Hello World!"))
);
behaviorTree.Start();
}
}
When you run this, you'll notice that "Hello World" will be printed over and over again. This is because the Root
node will restart the whole tree once traversal bypasses the last node in the tree. If you don't want this, you might add a WaitUntilStopped
node, like so:
// ...
behaviorTree = new Root(
new Sequence(
new Action(() => Debug.Log("Hello World!")),
new WaitUntilStopped()
)
);
///...
Up until now there really isn't anything event driven in this tree. Before we can dig into this, you need to understand what Blackboards are.
Blackboards
In NPBehave, like in Unreal, we got blackboards. You can think about them as beeing the "memory" of your AI. In NPBehave, blackboards are basically dictionaries that can be observed for changes. We mainly use Service
to store & update values in the blackboards. And we use BlackboardCondition
or BlackboardQuery
to observe the blackboard for changes and in turn continue traversing the bahaviour tree. Though you are free to access or modify values of the blackboard everywhere else (you'll also access them often from Action
nodes).
A blackboard is automatically created when you instantiate a Root
, but you may also provide another instance with it's constructor (this is particularly useful for Shared Blackboards)
Example: An event-driven behavior tree
Here's a simple example that uses the blackboard for event-driven behavior:
/// ...
behaviorTree = new Root(
new Service(0.5f, () => { behaviorTree.Blackboard["foo"] = !behaviorTree.Blackboard.Get<bool>("foo"); },
new Selector(
new BlackboardCondition("foo", Operator.IS_EQUAL, true, Stops.IMMEDIATE_RESTART,
new Sequence(
new Action(() => Debug.Log("foo")),
new WaitUntilStopped()
)
),
new Sequence(
new Action(() => Debug.Log("bar")),
new WaitUntilStopped()
)
)
)
);
behaviorTree.Start();
//...
Full sample | More sophisticated example
This sample will swap between printing "foo" and "bar" every 500 milliseconds. We use a Service
decorator node to toggle the foo
boolean value in the blackboard. We use a BlackboardCondition
decorator node to decide based on this flag whether the branch gets executed or not. The BlackboardCondition
also watches the blackboard for changes based on this value and as we provided Stops.IMMEDIATE_RESTART
the currently executed branch will be stopped if the condition no longer is true, also if it becomes true again, it will be restarted immediately.
Please note that you should put services in real methods instead of using lambdas, this will make your trees more readable. Same is true for larger actions.
Stops Rules
Some Decorators such as BlackboardCondition
, Condition
or BlackboardQuery
have a stopsOnChange
parameter that allows to define stop rules. The parameter allows the Decorator
to stop the execution of a running subtree within it's parent's Composite. It is your main tool to make power of the event-drivenness in NPBehave.
A lower priority node is a node that is defined after the current node within it's parent Composite.
The most useful and commonly used stops rules are SELF
, IMMEDIATE_RESTART
or LOWER_PRIORITY_IMMEDIATE_RESTART
.
Be careful if you're used to Unreal though. In NPBehave BOTH
and LOWER_PRIORITY
have a slightly different meaning. IMMEDIATE_RESTART
actually matches Unreal's Both
and LOWER_PRIORITY_IMMEDIATE_RESTART
matches Unreal's Lower Priority
.
The following stop rules exist:
Stops.NONE
: the decorator will only check it's condition once it is started and will never stop any running nodes.Stops.SELF
: the decorator will check it's condition once it is started and if it is met, it will observe the blackboard for changes. Once the condition is no longer met, it will stop itself allowing the parent composite to proceed with it's next node.Stops.LOWER_PRIORITY
: the decorator will check it's condition once it is started and if it's not met, it will observe the blackboard for changes. Once the condition is met, it will stop the lower priority node allowing the parent composite to proceed with it's next node.Stops.BOTH
: the decorator will stop both: self and lower priority nodes.Stops.LOWER_PRIORITY_IMMEDIATE_RESTART
: the decorator will check it's condition once it is started and if it's not met, it will observe the blackboard for changes. Once the condition is met, it will stop the lower priority node and order the parent composite to restart the Decorator immediately.Stops.IMMEDIATE_RESTART
: the decorator will check it's condition once it is started and if it's not met, it will observe the blackboard for changes. Once the condition is met, it will stop the lower priority node and order the parent composite to restart the Decorator immediately. As inBOTH
it will also stop itself as soon as the condition is no longer met.
One caveat with both IMMEDIATE_RESTART
variants is currently, that they may not actually always immediately restart your node. They won't immediately restart it in case the aborted branch leads the parent composite to evalutate to succeed
. Therefor it's generally advised to make use of stop rules within Selector nodes and return Failed
when your nodes are aborted.:
In NPBehave 2.0 this might change.
Blackboard Alternatives
In NPBehave you define your behavior tree within a MonoBehaviour
, as thus it isn't necessary to store everything in the blackboard. If you don't have BlackboardDecorator
or BlackboardQuery
with other stop rules than Stops.NONE
, you probably don't need them to be in the blackboard at all. You can also just make use of plain member variables - it is often the cleaner, faster to write and more performant. It means that you won't make use of the event-drivenness of NPBehave in that case, but it's often not necessary.
If you want to be able to make use of stopsOnChange
stops rules without using the Blackboard, two alternative ways exist in NPBehave:
- use a regular
Condition
decorator. This decorator has an optionalstopsOnChange
stops rules parameter. When providing any other value thanStops.NONE
, the condition will frequently check the condition and interrupt the node according to the stops rule when the result of the givenquery
function changes. Be aware that this method is not event-driven, it queries every frame (or at the provided interval) and as thus may lead to many queries if you make heavy use of them. However for simple cases it is often is sufficient and much simpler than a combination of a Blackboard-Key, aService
and aBlackboardCondition
. - Build your own event-driven
Decorator
s. It's actually pretty easy, just extend from ObservingDecorator and override theisConditionMet()
,StartObserving()
andStopObserving()
methods.
Node execution results
In NPBehave a node can either succeed
or fail
. Unlike traditional behavior trees, there is no result while a node is executing. Instead the node will itself tell the parent node once it is finished. This is important to keep in mind when you create your own node types.
Node Types
In NPBehave we have four different node types:
- the root node: The root has one single child and is used to start or stop the whole behavior tree.
- composite nodes: these have multiple children and are used to control which of their children are executed. Also the order and result is defined by this kind of node.
- decorator nodes: these nodes have always exactly one child and are used to either modify the result of the child or do something else while executing the child (e.g. a service updating the blackboard)
- task nodes: these are the leafs of the tree doing the actual work. These are the ones you most likely would create custom classes for. You can use the
Action
with lambdas or functions - For more complicated tasks, it is often a better option to create a new subclass ofTask
. Be sure to read the the golden rules if you do so.
Stopping the Tree
In case your Monster gets killed or you just destroy your GameObject, you should always stop the tree. You could put sometihng like the following on your Script:
// ...
public void OnDestroy()
{
StopBehaviorTree();
}
public void StopBehaviorTree()
{
if ( behaviorTree != null && behaviorTree.CurrentState == Node.State.ACTIVE )
{
behaviorTree.Stop();
}
}
// ...
The Debugger
You can use the Debugger
component to debug the behavior trees at runtime in the inspector.
Check out the sample
Shared Blackboards
You have the option to share blackboards across multiple instances of an AI. This can be useful if you want to implement some kind of swarm behavior. Additionally, you can create blackboard hierarchies, which allows you to combine a shared with a non-shared blackboard.
You can use UnityContext.GetSharedBlackboard(name)
to access shared blackboard instances anywhere.
Check out the sample
Extending the Library
Please refer to the existing node implementations to find out how to create custom node types, however be sure to at least read the following golden rules before doing so.
The golden rules
- Every call to
DoStop()
must result in a call toStopped(result)
. This is extremely important!: you really need to ensure that Stopped() is called within DoStop(), because NPBehave needs to be able to cancel a running branch at every time immediately. This also means that all your child nodes will also call Stopped(), which in turn makes it really easy to write reliable decorators or even composite nodes: Within DoStop() you just callStop()
on your active children, they in turn will call ofChildStopped()
on your node where you then finally put in your Stopped() call. Please have a look at the existing implementations for reference. - Stopped() is the last call you do, never do modify any state or call anything after calling Stopped. This is because Stopped will immediately continue traversal of the tree on other nodes, which will completley fuckup the state of the behavior tree if you don't take that into account.
- Every registered clock or blackboard observer needs to be removed eventually. Most of the time you unregister your callbacks immediately before you call Stopped(), however there may be exceptions, e.g. the BlackboardCondition keeps observers around up until the parent composite is stopped, it needs to be able to react on blackboard value changes even when the node itself is not active.
Implementing Tasks
For tasks you extend from the Task
class and override the DoStart()
and DoStop()
methods. In DoStart()
you start your logic and once you're done, you call Stopped(bool result)
with the appropriate result. Your node may get cancelled by another node, so be sure to implement DoStop()
, do proper cleanup and call Stopped(bool result)
immediately after it.
For a relatively simple example, check the source of the Wait Task
.
As already mentioned in the golden rules section, in NPBehave you have to always call Stopped(bool result) after your node is stopped. So it is currently not supported to have cancel-operations pending over multiple frames and will result in unpredictable behaviour.
Implementing Observing Decorators
Writing decorators is a lot more complex than Tasks. However a special base class exists for convenience. It's the ObservingDecorator
. This class can be used for easy implementation of "conditional" Decorators
that optionally make use stopsOnChange
stops rules.
All you have to do is to extend from it ObservingDecorator
and override the method bool IsConditionMet()
. If you want to support the Stops-Rules
you will have to implement StartObserving()
and StopObserving()
too. For a simple example, check the source of the Condition Decorator
.
Implementing Generic Decorators
For generic decorators you extend from the Decorator
class and override the DoStart()
, DoStop()
and the DoChildStopped(Node child, bool result)
methods.
You can start or stop your decorated node by accessing the Decoratee
property and call Start()
or Stop()
on it.
If your decorator receives a DoStop()
call, it's responsible to stop the Decoratee
accordingly and in this case will not call Stopped(bool result)
immediately. Instead it will do that in the DoChildStopped(Node child, bool result)
method. Be aware that the DoChildStopped(Node child, bool result)
doesn't necessarily mean that your decorator stopped the decoratee, the decoratee may also stop itself, in which case you don't need to immediately stop the Decoratee (that may be useful if you want to implement things like cooldowns etc). To find out whether your decorator got stopped, you can query it's IsStopRequested
property.
Check the source of the Failer Node
for a very basic implementation or the Repeater Node
for a little more complex one.
In addition you can also implement the method DoParentCompositeStopped()
, which may be called even when your Decorator is inactive. This is useful if you want to do additional cleanup work for listeners you kept active after your Decorator stopped. Check the ObservingDecorator
for an example.
Implementing Composites
Composite nodes require a deeper understanding of the library and you usually won't need to implement new ones. If you really need a new Composite, feel free to create a ticket on the GitHub project or contact me and I'll try my best to help you getting through it correctly.
Node States
Most likely you won't need to access those, but it's still good to know about them:
- ACTIVE: the node is started and not yet stopped.
- STOP_REQUESTED: the node is currently stopping, but has not yet called Stopped() to notify the parent.
- INACTIVE: the node is stopped.
The current state can be retrieved with the CurrentState
property
The Clock
You can use the clock in your nodes to register timers or get notified on each frame. Use RootNode.Clock
to access the clock. Check the Wait Task
for an example on how to register timers on the clock.
By default the behavior tree will be using the global clock privoded by the UnityContext
. This clock is updated every frame.
There may be scenarious where you want to have more control. For example you may want to throttle or pause updates to a group of AIs. For this reason you can provide your own controlled clock instances to the Root
node and Blackboard
, this allows you to precisely control when your behavior trees are updated. Check the Clock Throttling Example.
Node Type Reference
Root
Root(Node mainNode)
: run the givenmainNode
endlessly, regardless of it's failure stateRoot(Blackboard blackboard, Node mainNode)
: use the givenblackboard
instead of instantiating one; run the givenmainNode
endlessly, regardless of it's failure stateRoot(Blackboard blackboard, Clock clock, Node mainNode)
: use the givenblackboard
instead of instantiating one; use the givenclock
instead of using the global clock from theUnityContext
; run the givenmainNode
endlessly, regardless of it's success state
Composite Nodes
Selector
Selector(params Node[] children)
: Run children sequentially until one succeeds and succeed (succeeds if one of the children succeeds).
Sequence
Sequence(params Node[] children)
: Run children sequentially until one fails and fail (succeeds if none of the children fails).
Parallel
Parallel(Policy successPolicy, Policy failurePolicy, params Node[] children)
: Run children in parallel. WhenfailurePolocity
isPolociy.ONE
, the Parallel will stop (with failing resi;t) as soon as one of the children fails. WhensuccessPolicy
isPolicy.ONE
, the Parallel will stop (with succeeding result) when of the children fails. If the Parallel doesn't stop because of aPolicy.ONE
it will execute until all of the children are done, then it either succeeds if all children succeeded or fails.
RandomSelector
RandomSelector(params Node[] children)
: Run children in random order until one succeeds and succeed (succeeds if one of the children succeeds). Note that for abortion rules the original order defines priorities.
RandomSequence
RandomSequence(params Node[] children)
: Run children in random order until one fails and fail (succeeds if none of the children fails). Note that for abortion rules the original order defines priorities.
Task Nodes
Action
Action(System.Action action)
: fire and forget action (always finishes successfully immediately)Action(System.Func<bool> singleFrameFunc)
: action which can succeed or fail (return false to fail).Action(Func<bool, Result> multiframeFunc)
: action that can be ticked over multiple frames (returnResult.BLOCKED
when your action is not yet ready,Result.PROGRESS
when you're busy with the action,Result.SUCCESS
orResult.FAILED
when your action failed). The bool parameter that is passed to the delegate turns true when the task has to be aborted - in this case you are only allowed to returnResult.SUCCESS
orResult.FAILED
. When considering using this type of Action, you should also think about creating a custom subclass of theTask
instead.Action(Func<Request, Result> multiframeFunc2)
: similar to above, but the passedRequest
will give you a state information:Request.START
means it's the first tick to your action or you returnedResult.BLOCKED
last tick;Request.UPDATE
means the last time you returnedRequest.PROGRESS
;Request.CANCEL
means that you need to cancel your action and returnResult.SUCCESS
orResult.FAILED
. When considering using this type of Action, you should also think about creating a custom subclass of theTask
instead.
NavWalkTo (!!!! EXPERIMENTAL !!!!)
NavMoveTo(NavMeshAgent agent, string blackboardKey, float tolerance = 1.0f, bool stopOnTolerance = false, float updateFrequency = 0.1f, float updateVariance = 0.025f)
: move a NavMeshAgentagent
to either a transform or vector stored in the givenblackboardKey
. Allows atolerance
distance to succeed and optionally will stop once in the tolerance range (stopOnTolerance
).updateFrequency
controls how often the target position will be updated and how often the task checks wether it's done.
Wait
Wait(float seconds)
: Wait for given seconds with a random variance of 0.05 * secondsWait(float seconds, float randomVariance)
: Wait for given seconds with given random varainceWait(string blackboardKey, float randomVariance = 0f)
: wait for seconds set as float in given blackboardKeyWait(System.Func<float> function, float randomVariance = 0f)
: wait for result of the provided lambda function
WaitUntilStopped
WaitUntilStopped(bool sucessWhenStopped = false)
: just wait until stopped by some other node. It's often used to park at the end of aSelector
, waiting for any beforehead siblingBlackboardCondition
,BlackboardQuery
orCondition
to become active.
Decorator Nodes
BlackboardCondition
BlackboardCondition(string key, Operator operator, object value, Stops stopsOnChange, Node decoratee)
: execute thedecoratee
node only if the Blackboard'skey
matches theop
/value
condition. IfstopsOnChange
is not NONE, the node will observe the Blackboard for changes and stop execution of running nodes based on thestopsOnChange
stops rules.BlackboardCondition(string key, Operator operator, Stops stopsOnChange, Node decoratee)
: execute thedecoratee
node only if the Blackboard'skey
matches theop
condition (for one operand operators that just check for IS_SET for example). IfstopsOnChange
is not NONE, the node will observe the Blackboard for changes and stop execution of running nodes based on thestopsOnChange
stops rules.
BlackboardQuery
BlackboardQuery(string[] keys, Stops stopsOnChange, System.Func<bool> query, Node decoratee)
: whileBlackboardCondition
allows to check only one key, this one will observe multiple blackboard keys and evaluate the givenquery
function as soon as one of the value's changes, allowing you to do arbitrary queries on the blackboard. It will stop running nodes based on thestopsOnChange
stops rules.
Condition
Condition(Func<bool> condition, Node decoratee)
: executedecoratee
node if the givencondition
returns trueCondition(Func<bool> condition, Stops stopsOnChange, Node decoratee)
: executedecoratee
node if the givencondition
returns true. Re-Evaluate the condition every frame and stop running nodes based on thestopsOnChange
stops rules.Condition(Func<bool> condition, Stops stopsOnChange, float checkInterval, float randomVariance, Node decoratee)
: executedecoratee
node if the given condition returns true. Reevaluate the condition at the givencheckInterval
andrandomVariance
and stop running nodes based on thestopsOnChange
stops rules.
Cooldown
Cooldown(float cooldownTime, Node decoratee)
: Rundecoratee
immediately, but only if last execution wasn't at least pastcooldownTime
Cooldown(float cooldownTime, float randomVariation, Node decoratee)
: Rundecoratee
immediately, but only if last execution wasn't at least pastcooldownTime
withrandomVariation
Cooldown(float cooldownTime, bool startAfterDecoratee, bool resetOnFailiure, Node decoratee)
: Rundecoratee
immediately, but only if last execution wasn't at least pastcooldownTime
withrandomVariation
. WhenresetOnFailure
is true, the cooldown will be reset if the decorated node failsCooldown(float cooldownTime, float randomVariation, bool startAfterDecoratee, bool resetOnFailiure, Node decoratee)
Rundecoratee
immediately, but only if last execution wasn't at least pastcooldownTime
withrandomVariation
. WhenstartAfterDecoratee
is true, the cooldown timer will be started after the decoratee finishes instead of when it starts. WhenresetOnFailure
is true, the cooldown will be reset if the decorated node fails.Cooldown(float cooldownTime, bool startAfterDecoratee, bool resetOnFailiure, bool failOnCooldown, Node decoratee)
: Rundecoratee
immediately, but only if last execution wasn't at least pastcooldownTime
withrandomVariation
. WhenresetOnFailure
is true, the cooldown will be reset if the decorated node fails. IffailOnCooldown
is true, fail instead of wait in case the cooldown is still active.Cooldown(float cooldownTime, float randomVariation, bool startAfterDecoratee, bool failOnCooldown, bool resetOnFailiure, Node decoratee)
Rundecoratee
immediately, but only if last execution wasn't at least pastcooldownTime
withrandomVariation
. WhenstartAfterDecoratee
is true, the cooldown timer will be started after the decoratee finishes instead of when it starts. WhenresetOnFailure
is true, the cooldown will be reset if the decorated node fails. IffailOnCooldown
is true, fail instead of wait in case the cooldown is still active.
Failer
Failer(Node decoratee)
: always fail, regardless of thedecoratee
's result.
Inverter
Inverter(Node decoratee)
: ifdecoratee
succeeds, the inverter fails and if thedecoratee
fails, the inverter succeeds.
Observer
Observer(Action onStart, Action<bool> onStop, Node decoratee)
: runs the givenonStart
lambda once thedecoratee
starts and theonStop(bool result)
lambda once thedecoratee
finishes. It's a bit like a special kind ofService
, as it doesn't interfere in the execution of thedecoratee
directly.
Random
Random(float probability, Node decoratee)
: runs thedecoratee
with the givenprobability
chance between 0 and 1.
Repeater
Repeater(Node decoratee)
: repeat the givendecoratee
infinitly, unless it failsRepeater(int loopCount, Node decoratee)
: execute the givendecoratee
forloopCount
times (0 means decoratee would never run). Ifdecoratee
stops the looping is aborted and the Repeater fails. If all executions of thedecoratee
are successful, the Repeater will succeed.
Service
Service(Action service, Node decoratee)
: run the givenservice
function, start thedecoratee
and then run theservice
every tick.Service(float interval, Action service, Node decoratee)
: run the givenservice
function, start thedecoratee
and then run theservice
at the giveninterval
.Service(float interval, float randomVariation, Action service, Node decoratee)
: run the givenservice
function, start thedecoratee
and then run theservice
at the giveninterval
withrandomVariation
.
Succeeder
Succeeder(Node decoratee)
: always succeed, regardless of whether thedecoratee
succeeds or not
TimeMax
TimeMax(float limit, bool waitForChildButFailOnLimitReached, Node decoratee)
: run the givendecoratee
. If thedecoratee
doesn't finish within thelimit
, the execution fails. IfwaitForChildButFailOnLimitReached
is true, it will wait for the decoratee to finish but still fail.TimeMax(float limit, float randomVariation, bool waitForChildButFailOnLimitReached, Node decoratee)
: run the givendecoratee
. If thedecoratee
doesn't finish within thelimit
andrandomVariation
, the execution fails. IfwaitForChildButFailOnLimitReached
is true, it will wait for the decoratee to finish but still fail.
TimeMin
TimeMin(float limit, Node decoratee)
: run the givendecoratee
. If thedecoratee
finishes sucessfully before thelimit
time is reached the decorator will wait until the limit is reached and then stop the execution with the result of theDecoratee
. If thedecoratee
finishes failing before thelimit
time is reached, the decorator will immediately stop.TimeMin(float limit, bool waitOnFailure, Node decoratee)
: run the givendecoratee
. If thedecoratee
finishes sucessful before thelimit
time is reached, the decorator will wait until the limit is reached and then stop the execution with the result of theDecoratee
. IfwaitOnFailure
is true, thedecoratee
will also wait when the decoratee fails.TimeMin(float limit, float randomVariation, bool waitOnFailure, Node decoratee)
: run the givendecoratee
. If thedecoratee
finishes sucessful before thelimit
withrandomVariation
time is reached, the decorator will wait until the limit is reached and then stop the execution with the result of theDecoratee
. IfwaitOnFailure
is true, thedecoratee
will also wait when the decoratee fails.
WaitForCondition
WaitForCondition(Func<bool> condition, Node decoratee)
: Delay execution of thedecoratee
node until thecondition
gets true, checking every frameWaitForCondition(Func<bool> condition, float checkInterval, float randomVariance, Node decoratee)
: Delay execution of thedecoratee
node until thecondition
gets true, checking with the givencheckInterval
andrandomVariance
Video Tutorials
- Tutorial 01: Getting started
- Tutorial 02: Simple Patrolling AI
Contact
NPBehave was created and is maintained by Nils Kübler (E-Mail: das@nilspferd.net, Skype: disruption@web.de)
Games using NPBehave
If you have built a game or are building a game using NPBehave, I would be glad to have it on this list. You can submit your game eiter via contacting me or creating a pull request on the Github page