• Stars
    star
    927
  • Rank 48,985 (Top 1.0 %)
  • Language
    C#
  • License
    MIT License
  • Created over 6 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Behavior trees for Unity3D projects. Written with a code driven approach on the builder pattern.

Fluid Behavior Tree

Build Status

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 the Discord Community if you have questions or need help.

See upcoming features and development progress on the Trello Board.

Getting Started

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

using UnityEngine;
using CleverCrow.Fluid.BTs.Tasks;
using CleverCrow.Fluid.BTs.Trees;

public class MyCustomAi : MonoBehaviour {
    [SerializeField]
    private BehaviorTree _tree;
    
    private void Awake () {
        _tree = new BehaviorTreeBuilder(gameObject)
            .Sequence()
                .Condition("Custom Condition", () => {
                    return true;
                })
                .Do("Custom Action", () => {
                    return TaskStatus.Success;
                })
            .End()
            .Build();
    }

    private void Update () {
        // Update our tree every frame
        _tree.Tick();
    }
}

What a Returned TaskStatus Does

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

  • Success: Node has finished, next tree.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 time tree.Tick() is called. A pointer reference is tracked by the tree and can only be cleared if tree.Reset() is called.

Tree Visualizer

As long as your tree storage variable is set to public or has a SerializeField 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.

Visualizer

Extending Trees

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

using UnityEngine;
using CleverCrow.Fluid.BTs.Tasks;
using CleverCrow.Fluid.BTs.Tasks.Actions;
using CleverCrow.Fluid.BTs.Trees;

public class CustomAction : ActionBase {
    protected override TaskStatus OnUpdate () {
        Debug.Log(Owner.name);
        return TaskStatus.Success;
    }
}

public static class BehaviorTreeBuilderExtensions {
    public static BehaviorTreeBuilder CustomAction (this BehaviorTreeBuilder builder, string name = "My Action") {
        return builder.AddNode(new CustomAction { Name = name });
    }
}

public class ExampleUsage : MonoBehaviour {
    public void Awake () {
        var bt = new BehaviorTreeBuilder(gameObject)
            .Sequence()
                .CustomAction()
            .End();
    }
}

Installing

Fluid Behavior Tree is used through Unity's Package Manager. In order to use it you'll need to add the following lines to your Packages/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 the releases page.

Example Scene

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

Table of Contents

Example Scene

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

Library

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

Actions

Action Generic

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

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

Wait

Skip a number of ticks on the behavior tree.

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

Wait Time

Waits until the passed number of seconds have expired in deltaTime.

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

Conditions

Condition Generic

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

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

RandomChance

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()

Composites

Sequence

Runs each child node in order and expects a Success status to tick the next node. If Failure is returned, the sequence will stop executing child nodes and return Failure to the parent.

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

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

    .Do(() => { return TaskStatus.Success; })
.End()

Selector

Runs each child node until Success is returned.

.Selector()
    // Runs but fails
    .Do(() => { return TaskStatus.Failure; })

    // Will stop here since the node returns success
    .Do(() => { return TaskStatus.Success; })
    
    // Does not run
    .Do(() => { return TaskStatus.Success; })
.End()

SelectorRandom

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

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

Parallel

Runs all child nodes at the same time until they all return Success. Exits and stops all running nodes if ANY of them return Failure.

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

Decorators

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

Decorator Generic

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

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

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

Inverter

Reverse the returned status of the child node if it's TaskStatus.Success or TaskStatus.Failure. Does not change TaskStatus.Continue.

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

ReturnSuccess

Return TaskStatus.Success if the child returns TaskStatus.Failure. Does not change TaskStatus.Continue.

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

ReturnFailure

Return TaskStatus.Failure if the child returns TaskStatus.Success. Does not change TaskStatus.Continue.

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

RepeatForever

Return TaskStatus.Continue regardless of what status the child returns. This decorator (and all descendent tasks) can be interrupted by calling BehaviorTree.Reset().

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

RepeatUntilFailure

Return TaskStatus.Failure if the child returns TaskStatus.Failure, otherwise it returns TaskStatus.Continue.

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

RepeatUntilSuccess

Return TaskStatus.Success if the child returns TaskStatus.Success, otherwise it returns TaskStatus.Continue.

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

Creating Reusable Behavior Trees

Trees can be combined with just a few line of code. This allows you to create injectable behavior trees that bundles different nodes 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().

using CleverCrow.Fluid.BTs.Trees;
using CleverCrow.Fluid.BTs.Tasks;
using UnityEngine;

public class MyCustomAi : MonoBehaviour {
    private BehaviorTree _tree;
    
    private void Awake () {
        var injectTree = new BehaviorTreeBuilder(gameObject)
            .Sequence()
                .Do("Custom Action", () => {
                    return TaskStatus.Success;
                })
            .End();

        _tree = new BehaviorTreeBuilder(gameObject)
            .Sequence()
                .Splice(injectTree.Build())
                .Do("Custom Action", () => {
                    return TaskStatus.Success;
                })
            .End()
            .Build();
    }

    private void Update () {
        // Update our tree every frame
        _tree.Tick();
    }
}

Creating Custom Reusable Nodes

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.

var tree = new BehaviorTreeBuilder(gameObject)
    .Sequence()
        .AgentDestination("Find Enemy", target)
        .Do(() => {
            // Activate chase enemy code
            return TaskStatus.Success; 
        })
    .End()
    .Build();

Your First Custom Node and Extension

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

using CleverCrow.Fluid.BTs.Tasks;
using CleverCrow.Fluid.BTs.Tasks.Actions;
using UnityEngine;
using UnityEngine.AI;

public class AgentDestination : ActionBase {
    private NavMeshAgent _agent;
    public Transform target;

    protected override void OnInit () {
        _agent = Owner.GetComponent<NavMeshAgent>();
    }

    protected override TaskStatus OnUpdate () {
        _agent.SetDestination(target.position);
        return TaskStatus.Success;
    }
}

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

using CleverCrow.Fluid.BTs.Trees;

public static class BehaviorTreeBuilderExtensions {
    public static BehaviorTreeBuilder AgentDestination (this BehaviorTreeBuilder builder, string name, Transform target) {
        return builder.AddNode(new AgentDestination {
            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.

Custom Actions

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

using UnityEngine;
using CleverCrow.Fluid.BTs.Tasks;
using CleverCrow.Fluid.BTs.Tasks.Actions;

public class CustomAction : ActionBase {
    // Triggers only the first time this node is run (great for caching data)
    protected override void OnInit () {
    }

    // Triggers every time this node starts running. Does not trigger if TaskStatus.Continue was last returned by this node
    protected override void OnStart () {
    }

    // Triggers every time `Tick()` is called on the tree and this node is run
    protected override TaskStatus OnUpdate () {
        // Points to the GameObject of whoever owns the behavior tree
        Debug.Log(Owner.name);
        return TaskStatus.Success;
    }

    // Triggers whenever this node exits after running
    protected override void OnExit () {
    }
}

Add your new node to an extension.

using CleverCrow.Fluid.BTs.Trees;

public static class BehaviorTreeBuilderExtensions {
    public static BehaviorTreeBuilder CustomAction (this BehaviorTreeBuilder builder, string name = "My Action") {
        return builder.AddNode(new CustomAction {
            Name = name,
        });
    }
}

Custom Conditions

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.

using UnityEngine;
using CleverCrow.Fluid.BTs.Tasks;

public class CustomCondition : ConditionBase {
    // Triggers only the first time this node is run (great for caching data)
    protected override void OnInit () {
    }

    // Triggers every time this node starts running. Does not trigger if TaskStatus.Continue was last returned by this node
    protected override void OnStart () {
    }

    // Triggers every time `Tick()` is called on the tree and this node is run
    protected override bool OnUpdate () {
        // Points to the GameObject of whoever owns the behavior tree
        Debug.Log(Owner.name);
        return true;
    }

    // Triggers whenever this node exits after running
    protected override void OnExit () {
    }
}

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

using CleverCrow.Fluid.BTs.Trees;

public static class BehaviorTreeBuilderExtensions {
    public static BehaviorTreeBuilder CustomCondition (this BehaviorTreeBuilder builder, string name = "My Condition") {
        return builder.AddNode(new CustomCondition {
            Name = name,
        });
    }
}

Custom Composites

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

using CleverCrow.Fluid.BTs.TaskParents.Composites;
using CleverCrow.Fluid.BTs.Tasks;

public class CustomSequence : CompositeBase {
    protected override TaskStatus OnUpdate () {            
        for (var i = ChildIndex; i < Children.Count; i++) {
            var child = Children[ChildIndex];

            var status = child.Update();
            if (status != TaskStatus.Success) {
                return status;
            }

            ChildIndex++;
        }

        return TaskStatus.Success;
    }
}

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

using CleverCrow.Fluid.BTs.Trees;

public static class BehaviorTreeBuilderExtensions {
    public static BehaviorTreeBuilder CustomSequence (this BehaviorTreeBuilder builder, string name = "My Sequence") {
        return builder.ParentTask<CustomSequence>(name);
    }
}

Custom Decorators

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

using CleverCrow.Fluid.BTs.Decorators;
using CleverCrow.Fluid.BTs.Tasks;

public class CustomInverter : DecoratorBase {
    protected override TaskStatus OnUpdate () {
        if (Child == null) {
            return TaskStatus.Success;
        }

        var childStatus = Child.Update();
        var status = childStatus;

        switch (childStatus) {
            case TaskStatus.Success:
                status = TaskStatus.Failure;
                break;
            case TaskStatus.Failure:
                status = TaskStatus.Success;
                break;
        }

        return status;
    }
}

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

using CleverCrow.Fluid.BTs.Trees;

public static class BehaviorTreeBuilderExtensions {
    public static BehaviorTreeBuilder CustomInverter (this BehaviorTreeBuilder builder, string name = "My Inverter") {
        // See BehaviorTreeBuilder.AddNodeWithPointer() if you need to set custom composite data from arguments
        return builder.ParentTask<CustomInverter>(name);
    }
}

Nightly Builds

To access nightly builds of develop that are package manager friendly you'll need to manually edit your Packages/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.

Development Environment

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

npm install

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

Making Commits

All commits should be made using Commitizen (which is automatically installed when running npm 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

Pull Requests / Contributing

Please see the Contributing Guidelines document for more info.

Contributor Credits

Thanks goes to these wonderful people (emoji key):

Ash Blue
Ash Blue

πŸ’»
Jesse Talavera-Greenberg
Jesse Talavera-Greenberg

πŸ’»
PureSaltProductions
PureSaltProductions

πŸ““
Martin Duvergey
Martin Duvergey

πŸ›
call-stack
call-stack

πŸ›
Piotr Jastrzebski
Piotr Jastrzebski

πŸ’»
Sounghoo
Sounghoo

πŸ’»
TNThomas
TNThomas

πŸ› πŸ’»

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

Contributors ✨

Thanks goes to these wonderful people (emoji key):

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

More Repositories

1

fluid-dialogue

A Unity dialogue system that features an easy to use drag and drop graph. ScriptableObject driven with the ability to write custom actions and conditions to create complex dialogue workflows.
C#
191
star
2

unity-animator-helpers

A micro-framework for changing Unity 3D's Animator parameters with ScriptableObject(s). Designed to make going from custom scripts to Animator parameters easy. Works with 2D or 3D projects.
C#
128
star
3

unity-skill-tree-editor

Example Unity custom graph editor for editing skill trees.
C#
120
star
4

fluid-stats

A Unity3D character stats system for handling health, energy, defense, attack, ect. Supports dynamic stat values with modifiers such as addition, subtraction, multiplication, and division.
C#
79
star
5

fluid-state-machine

A finite state machine micro-framework for Unity3D focused on a pure code implementation.
C#
61
star
6

unity-quest-journal

A Unity 3D package for managing complex or simple quests in video games. Inspired by The Witcher 3 and Skyrim like quest management systems.
C#
59
star
7

pathfinding-platformer

JavaScript algorithm for A* Pathfinding in a platformer game. Includes a notion of gravity and able to take into account complex obstacles and jumping.
JavaScript
52
star
8

unity-elastic-inventory

An easy to use Unity inventory framework built with scaling and extendability in mind
C#
39
star
9

fluid-unique-id

A micro-framework to manage unique IDs in scenes with Unity
C#
35
star
10

unity-2d-parallax

Custom toolset for 2D Parallaxing in Unity
C#
35
star
11

simple-tween-js

A lightweight tweening micro-framewrok for your JavaScript projects. Only 2.8kb when minified.
JavaScript
27
star
12

unity-simple-spellcheck

A simple spell check tool for the Unity editor
C#
23
star
13

oyster-package-generator

Oyster is a package generator for Unity Package Manager (UPM). It generates a best standards Unity package with automated deployments via CLI. Focus on coding your package instead of deployments, changelogs, ect.
TypeScript
23
star
14

javascript-pathfinding

A* algorithm for pathfinding on a tile grid in JavaScript.
JavaScript
22
star
15

canvas-prime

A minimal OOP HTML5 game engine that uses extendable classes for its engine and objects without any libraries.
JavaScript
18
star
16

fluid-behavior-tree-ctf-example

CTF example that demonstrates how an AI might be written with Fluid Behavior Tree
C#
17
star
17

unity-package-manager-git-example

Example Unity3D projects that demonstrates how to use the new package manager with a Git repo.
C#
13
star
18

unity-timeline-dialogue-tool-sample

An example of how to use Unity's timeline tools with printed dialogue. Demonstrates how it could be used for dialogue boxes, subtitles, shoutboxes, ect.
C#
13
star
19

unity-simple-settings

Access static serialized files in Unity from your resources folder. Automatically initializes a runtime safe copy when the game starts.
C#
12
star
20

fluid-database

A simple key value pair database for Unity3d projects that supports string, bool, float, and int.
C#
11
star
21

canvas-sat

HTML5 JavaScript Canvas - Separating Axis Test (SAT) Demo
JavaScript
8
star
22

rect-wars

Rectangle wars is a retro style space shooter where you play as pixel, defender of the 2D universe. The game is built on the Canvas Prime engine and uses IndexedDB to record data.
JavaScript
7
star
23

upm-package-populator

A node.js build script to populate a nested package in a Unity Package Manager project to a dist folder. Also cross populates root package.json to the UPM package.
TypeScript
7
star
24

unity-ui-node-printer

Generic API for printing out complex UI graphs such as skill trees
C#
7
star
25

unity-event-plus

A simple wrapper utility to use interfaces with UnityEvent classes
C#
6
star
26

unity-simple-singleton

An easy to use singleton class for Unity3d projects. Easily installable as a package.
C#
6
star
27

fast-crop

HTML5 Canvas cropping utility that uses the File API to crop images in browser. All rendering is done client-side and finalized image is exported.
JavaScript
6
star
28

uvpm-server

A private Unity package manager server for Ultra Violet Package Manger (UVPM). The back-end server portion of the software.
TypeScript
6
star
29

unity-gauges

C#
5
star
30

unity-simple-notifications

A simple UPM package for displaying message notifications to a user
C#
5
star
31

cinemachine-rts-camera-test

C#
5
star
32

unity-find-and-replace

A simple modular find and replace utility for Unity3D projects
C#
5
star
33

unity-quest-log

C#
4
star
34

adnc-utilities

Unity utilities used for A Dragon Named Coal
C#
4
star
35

unity-inventory-example

C#
4
star
36

unity-platformer-pathfinding

C#
4
star
37

unity-additive-level-loading

http://blueashes.com/2015/game-development/unity-live-training-additive-level-loading/
C#
4
star
38

fluid-state-machine-examples

Door with lock and pressure plate state machine examples for Fluid State Machine
C#
3
star
39

unity-save-restore

Save and restore system for maintaining ScriptableObject(s) via serialization
C#
3
star
40

upm-package-nsubstitute

A simple Unity package wrapper around NSubstitute to prevent DLL dependency conflicts.
2
star
41

html5-games-presentation

Getting started with HTML5 games and Construct 2
JavaScript
2
star
42

unity-decision-editor

C#
2
star
43

terra

Lua
2
star
44

unity-move-along-bezier

C#
2
star
45

unity-skill-tree

Prototype skill tree for The Wanderer
C#
1
star
46

wp-simple-settings

An OOP script for handeling WordPress settings.
PHP
1
star
47

uvpm-cli

A Unity3D package manager CLI interface for Ultra Violet Packet Manager (UVPM)
TypeScript
1
star
48

ember-checklist

JavaScript
1
star
49

line-of-sight

Interactive JavaScript line of sight algorithm with debugging details.
JavaScript
1
star
50

unity-platform-astar

JavaScript
1
star
51

html5-form-validator

An HTML5 form validation fallback that targets browsers who don't support the functionality.
JavaScript
1
star
52

unity-narration-editor

C#
1
star
53

json-demo

A simple demo of sending JSON image file data to a JavaScript application via PHP.
PHP
1
star
54

slot

An input library for handling data IDs and arrays with complex data structures
JavaScript
1
star
55

pathfinding-presentation

Interactive pathfinding presentation
JavaScript
1
star
56

package-zipper

A lightweight PHP class that allows you to clone and create new zip file packages on the fly with the ZipArchive class. Originally built for packing up and returning compiled JavaScript code, but has many other uses.
PHP
1
star
57

sprite-animator

A flash like interface for creating pixel based animations on a timeline
JavaScript
1
star
58

unity-quest-editor

Quest editing interface for Unity with extendable objects.
C#
1
star
59

gamedev-blog

Statically generated blog for game development projects
Ruby
1
star
60

my-idb

Creates an asynchronous IndexedDB database from a JSON file and provides active caching for synchronous access. Includes polyfills for older implementations of IndexedDB. My IDB accessed through window.mydb
JavaScript
1
star
61

blender3d-robot-rigger

The Robot Rigger add-on for Blender provides a convenient way to automatically rig and unrig objects to bones based on a naming pattern. This tool is designed for quickly rigging robots, mechanical objects, and non-organic items. This is a micro-framework and designed to be non-intrusive to your existing Blender workflow.
Python
1
star