Repository files navigation

Behavior trees for Unity3D projects. Written with a code driven approach to maximize maintainability on large projects with the builder pattern. Inspired by Fluent Behavior Tree.

Features

• Extendable, write your own custom re-usable nodes
• Pre-built library of tasks to kickstart your AI
• Tree visualizer to debug your trees at runtime
• Heavily tested with TDD and unit tests
• Tracks the last position of your behavior tree and restores it the next frame
• Built for Unity (no integration overhead)

Support

Join theDiscord Community if you have questions or need help.

See upcoming features and development progress on theTrello Board.

When creating trees you'll need to store them in a variable to properly cache all the necessary data.

usingUnityEngine;usingCleverCrow.Fluid.BTs.Tasks;usingCleverCrow.Fluid.BTs.Trees;publicclassMyCustomAi:MonoBehaviour{[SerializeField]privateBehaviorTree_tree;privatevoidAwake(){_tree=newBehaviorTreeBuilder(gameObject).Sequence().Condition("Custom Condition",()=>{returntrue;}).Do("Custom Action",()=>{returnTaskStatus.Success;}).End().Build();}privatevoidUpdate(){// Update our tree every frame_tree.Tick();}}

Depending on what you return for a task status different things will happen.

• Success: Node has finished, nexttree.Tick() will restart the tree if no other nodes to run
• Failure: Same as success, except informs that the node failed
• Continue: Rerun this node the next timetree.Tick() is called. A pointer reference is tracked by the tree and can only be cleared iftree.Reset() is called.

As long as your tree storage variable is set topublic or has aSerializeField attribute. You'll be able to print a visualization of your tree while the game is running in the editor. Note that you cannot view trees while the game is not running. As the tree has to be built in order to be visualized.

You can safely add new code to your behavior trees with several lines. Allowing you to customize BTs while supporting future version upgrades.

usingUnityEngine;usingCleverCrow.Fluid.BTs.Tasks;usingCleverCrow.Fluid.BTs.Tasks.Actions;usingCleverCrow.Fluid.BTs.Trees;publicclassCustomAction:ActionBase{protectedoverrideTaskStatusOnUpdate(){Debug.Log(Owner.name);returnTaskStatus.Success;}}publicstaticclassBehaviorTreeBuilderExtensions{publicstaticBehaviorTreeBuilderCustomAction(thisBehaviorTreeBuilderbuilder,stringname="My Action"){returnbuilder.AddNode(newCustomAction{Name=name});}}publicclassExampleUsage:MonoBehaviour{publicvoidAwake(){varbt=newBehaviorTreeBuilder(gameObject).Sequence().CustomAction().End();}}

Fluid Behavior Tree is used throughUnity's Package Manager. In order to use it you'll need to add the following lines to yourPackages/manifest.json file. After that you'll be able to visually control what specific version of Fluid Behavior Tree you're using from the package manager window in Unity. This has to be done so your Unity editor can connect to NPM's package registry.

{"scopedRegistries": [    {"name":"NPM","url":"https://registry.npmjs.org","scopes": ["com.fluid"      ]    }  ],"dependencies": {"com.fluid.behavior-tree":"2.2.0"  }}

Archives of specific versions and release notes are available on thereleases page.

You might want to look at thecapture the flag example projectfor a working example of how Fluid Behavior Tree can be used in your project. It demonstrates real time usagewith units who attempt to capture the flag while grabbing power ups to try and gain the upper hand.

• Library
  • Actions
    • Generic
    • Wait
    • Wait Time
  • Conditions
    • Generic
    • RandomChance
  • Composites
    • Sequence
    • Selector
    • SelectorRandom
    • Parallel
  • Decorators
    • Generic
    • Inverter
    • ReturnSuccess
    • ReturnFailure
    • RepeatForever
    • RepeatUntilFailure
    • RepeatUntilSuccess
• Creating Reusable Behavior Trees
• Creating Custom Reusable Nodes
  • Your First Custom Node and Tree
  • Custom Actions
  • Custom Conditions
  • Custom Composites
  • Custom Decorators
• Formatting Issues
• Nightly Builds
• Development Environment
  • Submitting your own actions, conditions, ect
  • Pull Requests / Contributing
• Contributor Credits

You might want to look at thecapture the flag example projectfor a working example of how Fluid Behavior Tree can be used in your project. It demonstrates real time usagewith units who attempt to capture the flag while grabbing power ups to try and gain the upper hand.

Fluid Behavior Tree comes with a robust library of pre-made actions, conditions, composites, and other nodesto help speed up your development process.

You can create a generic action on the fly. If you find yourself re-using the same actions you might want tolook into the section on writing your own custom actions.

.Sequence().Do("Custom Action",()=>{returnTaskStatus.Success;}).End()

Skip a number of ticks on the behavior tree.

.Sequence()// Wait for 1 tick on the tree before continuing.Wait(1).Do(MyAction).End()

Waits until the passed number of seconds have expired indeltaTime.

.Sequence().WaitTime(2.5f).Do(MyAction).End()

You can create a generic condition on the fly. If you find yourself re-using the same actions you might want tolook into the section on writing your own custom conditions.

.Sequence().Condition("Custom Condtion",()=>{returntrue;}).Do(MyAction).End()

Randomly evaluate a node as true or false based upon the passed chance.

.Sequence()// 50% chance this will return success.RandomChance(1,2).Do(MyAction).End()

Runs each child node in order and expects aSuccess status to tick the next node. IfFailure is returned, the sequence will stop executing child nodes and returnFailure to the parent.

NOTE It's important that every composite is followed by a.End() statement. This makes sure that your nodesare properly nested when the tree is built.

.Sequence().Do(()=>{returnTaskStatus.Success;}).Do(()=>{returnTaskStatus.Success;})// All tasks after this will not run and the sequence will exit.Do(()=>{returnTaskStatus.Failure;}).Do(()=>{returnTaskStatus.Success;}).End()

Runs each child node untilSuccess is returned.

.Selector()// Runs but fails.Do(()=>{returnTaskStatus.Failure;})// Will stop here since the node returns success.Do(()=>{returnTaskStatus.Success;})// Does not run.Do(()=>{returnTaskStatus.Success;}).End()

Randomly selects a child node with a shuffle algorithm. Looks untilSuccess is returned or every node fails. Shuffles every time the tree initially start running it.

.SelectorRandom().Do(()=>{returnTaskStatus.Failure;}).Do(()=>{returnTaskStatus.Success;}).Do(()=>{returnTaskStatus.Failure;}).End()

Runs all child nodes at the same time until they all returnSuccess. Exits and stops all running nodes if ANY of them returnFailure.

.Parallel()// Both of these tasks will run every frame.Do(()=>{returnTaskStatus.Continue;}).Do(()=>{returnTaskStatus.Continue;}).End()

Decorators are parent elements that wrap any node to change the return value (or execute special logic). They areextremely powerful and a great compliment to actions, conditions, and composites.

You can wrap any node with your own custom decorator code. This allows you to customize re-usable functionality.

NOTE: You must manually callUpdate() on the child node or it will not fire. Also every decorator must be followedby a.End() statement. Otherwise the tree will not build correctly.

.Sequence().Decorator("Return Success", child=>{child.Update();returnTaskStatus.Success;}).Do(()=>{returnTaskStatus.Failure;}).End().Do(()=>{returnTaskStatus.Success;}).End()

Reverse the returned status of the child node if it'sTaskStatus.Success orTaskStatus.Failure.Does not changeTaskStatus.Continue.

.Sequence().Inverter().Do(()=>{returnTaskStatus.Success;}).End().End()

ReturnTaskStatus.Success if the child returnsTaskStatus.Failure.Does not changeTaskStatus.Continue.

.Sequence().ReturnSuccess().Do(()=>{returnTaskStatus.Failure;}).End().End()

ReturnTaskStatus.Failure if the child returnsTaskStatus.Success.Does not changeTaskStatus.Continue.

.Sequence().ReturnFailure().Do(()=>{returnTaskStatus.Success;}).End().End()

ReturnTaskStatus.Continue regardless of what status the child returns. This decorator (and all descendenttasks) can be interrupted by callingBehaviorTree.Reset().

.Sequence().RepeatForever().Do(()=>{returnTaskStatus.Success;}).End().End()

ReturnTaskStatus.Failure if the child returnsTaskStatus.Failure, otherwise it returnsTaskStatus.Continue.

.Sequence().RepeatUntilFailure().Do(()=>{returnTaskStatus.Success;}).End().End()

ReturnTaskStatus.Success if the child returnsTaskStatus.Success, otherwise it returnsTaskStatus.Continue.

.Sequence().RepeatUntilSuccess().Do(()=>{returnTaskStatus.Success;}).End().End()

Trees can be combined with just a few line of code. This allows you to create injectable behavior trees that bundles differentnodes for complex functionality such as searching or attacking.

Be warned that spliced trees require a newly built tree for injection, as nodes are only deep copied on.Build().

usingCleverCrow.Fluid.BTs.Trees;usingCleverCrow.Fluid.BTs.Tasks;usingUnityEngine;publicclassMyCustomAi:MonoBehaviour{privateBehaviorTree_tree;privatevoidAwake(){varinjectTree=newBehaviorTreeBuilder(gameObject).Sequence().Do("Custom Action",()=>{returnTaskStatus.Success;}).End();_tree=newBehaviorTreeBuilder(gameObject).Sequence().Splice(injectTree.Build()).Do("Custom Action",()=>{returnTaskStatus.Success;}).End().Build();}privatevoidUpdate(){// Update our tree every frame_tree.Tick();}}

What makes Fluid Behavior Tree so powerful is the ability to write your own nodes and add them to the builder without editing any source. You can even create Unity packages that add new builder functionality. For example we can write a new tree builder method like this that sets the target of your AI system with just a few lines of code.

vartree=newBehaviorTreeBuilder(gameObject).Sequence().AgentDestination("Find Enemy",target).Do(()=>{// Activate chase enemy codereturnTaskStatus.Success;}).End().Build();

It should take about 3 minutes to create your first custom action and implement it. First create a new action.

usingCleverCrow.Fluid.BTs.Tasks;usingCleverCrow.Fluid.BTs.Tasks.Actions;usingUnityEngine;usingUnityEngine.AI;publicclassAgentDestination:ActionBase{privateNavMeshAgent_agent;publicTransformtarget;protectedoverridevoidOnInit(){_agent=Owner.GetComponent<NavMeshAgent>();}protectedoverrideTaskStatusOnUpdate(){_agent.SetDestination(target.position);returnTaskStatus.Success;}}

Next we need to extend theBehaviorTreeBuilder script with our new AgentDestination action. For more information on C# class extensions see theofficial docs.

usingCleverCrow.Fluid.BTs.Trees;publicstaticclassBehaviorTreeBuilderExtensions{publicstaticBehaviorTreeBuilderAgentDestination(thisBehaviorTreeBuilderbuilder,stringname,Transformtarget){returnbuilder.AddNode(newAgentDestination{Name=name,target=target,});}}

And you're done! You've now created a custom action and extendable behavior tree builder that's future proofed for new versions. The following examples will be more of the same. But each covers a different node type.

You can create your own custom actions with the following template. This is useful for bundling up codethat you're using constantly.

usingUnityEngine;usingCleverCrow.Fluid.BTs.Tasks;usingCleverCrow.Fluid.BTs.Tasks.Actions;publicclassCustomAction:ActionBase{// Triggers only the first time this node is run (great for caching data)protectedoverridevoidOnInit(){}// Triggers every time this node starts running. Does not trigger if TaskStatus.Continue was last returned by this nodeprotectedoverridevoidOnStart(){}// Triggers every time `Tick()` is called on the tree and this node is runprotectedoverrideTaskStatusOnUpdate(){// Points to the GameObject of whoever owns the behavior treeDebug.Log(Owner.name);returnTaskStatus.Success;}// Triggers whenever this node exits after runningprotectedoverridevoidOnExit(){}}

Add your new node to an extension.

usingCleverCrow.Fluid.BTs.Trees;publicstaticclassBehaviorTreeBuilderExtensions{publicstaticBehaviorTreeBuilderCustomAction(thisBehaviorTreeBuilderbuilder,stringname="My Action"){returnbuilder.AddNode(newCustomAction{Name=name,});}}

Custom conditions can be added with the following example template. You'll want to use these for checks such as sight,if the AI can move to a location, and other tasks that require a complex check.

usingUnityEngine;usingCleverCrow.Fluid.BTs.Tasks;publicclassCustomCondition:ConditionBase{// Triggers only the first time this node is run (great for caching data)protectedoverridevoidOnInit(){}// Triggers every time this node starts running. Does not trigger if TaskStatus.Continue was last returned by this nodeprotectedoverridevoidOnStart(){}// Triggers every time `Tick()` is called on the tree and this node is runprotectedoverrideboolOnUpdate(){// Points to the GameObject of whoever owns the behavior treeDebug.Log(Owner.name);returntrue;}// Triggers whenever this node exits after runningprotectedoverridevoidOnExit(){}}

Add the new condition to your behavior tree builder with the following snippet.

usingCleverCrow.Fluid.BTs.Trees;publicstaticclassBehaviorTreeBuilderExtensions{publicstaticBehaviorTreeBuilderCustomCondition(thisBehaviorTreeBuilderbuilder,stringname="My Condition"){returnbuilder.AddNode(newCustomCondition{Name=name,});}}

Fluid Behavior Tree isn't limited to just custom actions and conditions. You can create new composite types with a fairlysimple API. Here is an example of a basic sequence.

usingCleverCrow.Fluid.BTs.TaskParents.Composites;usingCleverCrow.Fluid.BTs.Tasks;publicclassCustomSequence:CompositeBase{protectedoverrideTaskStatusOnUpdate(){for(vari=ChildIndex;i<Children.Count;i++){varchild=Children[ChildIndex];varstatus=child.Update();if(status!=TaskStatus.Success){returnstatus;}ChildIndex++;}returnTaskStatus.Success;}}

Adding custom composites to your behavior tree is just as simple as adding actions. Just takes one line of code.

usingCleverCrow.Fluid.BTs.Trees;publicstaticclassBehaviorTreeBuilderExtensions{publicstaticBehaviorTreeBuilderCustomSequence(thisBehaviorTreeBuilderbuilder,stringname="My Sequence"){returnbuilder.ParentTask<CustomSequence>(name);}}

Decorators can also be custom written to cut down on repetitive code.

usingCleverCrow.Fluid.BTs.Decorators;usingCleverCrow.Fluid.BTs.Tasks;publicclassCustomInverter:DecoratorBase{protectedoverrideTaskStatusOnUpdate(){if(Child==null){returnTaskStatus.Success;}varchildStatus=Child.Update();varstatus=childStatus;switch(childStatus){caseTaskStatus.Success:status=TaskStatus.Failure;break;caseTaskStatus.Failure:status=TaskStatus.Success;break;}returnstatus;}}

Implementing decorators is similar to composites. If you need to set arguments on the composite you'll want to take a loot at the methodBehaviorTreeBuilder.AddNodeWithPointer().

usingCleverCrow.Fluid.BTs.Trees;publicstaticclassBehaviorTreeBuilderExtensions{publicstaticBehaviorTreeBuilderCustomInverter(thisBehaviorTreeBuilderbuilder,stringname="My Inverter"){// See BehaviorTreeBuilder.AddNodeWithPointer() if you need to set custom composite data from argumentsreturnbuilder.ParentTask<CustomInverter>(name);}}

If you are using an auto formatter it will probably mangle your code formatting with the builder syntax. To avoid this you can turn off formatting like so in JetBrains Rider. If you need a specific IDE, it shouldn't be too hard to google the specific formatting disable comment you need.

// @formatter:off_tree=newBehaviorTreeBuilder(gameObject).Sequence().Condition("Custom Condition",()=>{returntrue;}).Do("Custom Action",()=>{returnTaskStatus.Success;}).End().Build();// @formatter:on

To access nightly builds ofdevelop that are package manager friendly you'll need to manually edit yourPackages/manifest.json as so.

{"dependencies": {"com.fluid.behavior-tree":"https://github.com/ashblue/fluid-behavior-tree.git#nightly"    }}

Note that to get a newer nightly build you must delete this line and any related lock data in the manifest, let Unity rebuild, then add it back. As Unity locks the commit hash for Git urls as packages.

If you wish to run to run the development environment you'll need to installnode.js. Then run the following from the root once.

npm install

If you wish to create a build runnpm run build from the root and it will populate thedist folder.

All commits should be made usingCommitizen (which is automatically installed when runningnpm install). Commits are automatically compiled to version numbers on release so this is very important. PRs that don't have Commitizen based commits will be rejected.

To make a commit type the following into a terminal from the root

npm run commit

Please see theContributing Guidelines document for more info.

Thanks goes to these wonderful people (emoji key):

Ash Blue 💻	Jesse Talavera-Greenberg 💻	PureSaltProductions 📓	Martin Duvergey 🐛	call-stack 🐛	Piotr Jastrzebski 💻	Sounghoo 💻
TNThomas 🐛💻	Ownez 💻	angstr0m 🐛	Izzy 🐛	JeremyVansnick 💻

This project follows theall-contributors specification. Contributions of any kind welcome!

Thanks goes to these wonderful people (emoji key):

This project follows theall-contributors specification. Contributions of any kind welcome!