Welcome!

Welcome to the AIBrain Extensions for MoreMountains Unity3D engines (i.e.: Corgi and TopDown) documentation.

The project includes a set of tools that will (hopefully) ease your workflow with the AIBrain system.

What's Corgi Engine?

The Corgi Engine is a Unity 2D + 2.5D Platformer Kit, available on the Unity Asset Store. If you want to know more about it, please read the official documentation.

Alternatively, for a quick introduction, you can check the following feature video:

What's TopDown Engine?

The TopDown Engine is a complete solution for top-down games, available on the Unity Asset Store. Official documentation can be found on MoreMountains website.

For a quick feature walkthrough, please check the video below:

Note: To get you started using the AI Brain Graph, you should first follow the Install instructions and check that everything is working.

The Tutorial Scene

First of all, look for the AIBrain_Tutorial scene (and open it), that will serve as a starting point for this tutorial. Basically, it is the Corgi RetroAI scene with all enemies removed (with the exception of RetroSwordsman).

1. Open the Enemies group to check the content: you will find the RetroSwordsman prefab and two other gameObjects (stripped out of all AI components): RetroSwordsmanGenerated and RetroSwordsmanPluggable.

Creating the AI Brain Graph

To start working with the graph, you'll need to create an AI Brain Graph:

1. In the Project panel, right-click the mouse button and select Create > The Bit Cave > AI Brain Graph

2. Rename the newly created asset RetroSwordman AIBrain (or anything you deem appropriate)

3. Double-click on the asset to open the Editor

The RetroSwordsman AI Brain Structure

Select the RetroSwordsman prefab in scene and look at the AI Brain, AI Actions and AI Decisions components: we want to replicate the same structure with the AI Brain Graph:

• The AI Brain has two states: Patrol and Shooting

• While in Patrol the swordsman will perform an AIActionPatrol action

• While in Shooting the swordsman will perform an AIActionShoot action

• The swordsman will exit the Patrol state if the target is within range (AIDecisionDetectTargetRadius)

• The swordsman will exit the Shooting state after a while (AIDecisionTimeInState)

To create the AI Brain Graph we will need these nodes:

• Two states

• Two transistions

• Two actions

• Two decisions

Creating the States

First of all, let's create the two states:

1. Right click on the AI Brain graph canvas and choose AI > Brain State: this will create a state

2. Right click on the node header and choose Rename. Rename the state Patrol and select Apply

3. Repeat the first two steps, creating another node called Shooting

4. On the Patrol node, click the Set as starting state button: this will set the Patrol node as the entry state in the character brain

Adding Transitions

Each state has a single transition, so we are going to create two and connect them with Patrol and Shooting:

1. Right click on the Graph canvas and select AI > Transition: this will add a transition node

2. Click on the transitions output in Patrol state and drag it to the Input element of the transition node

3. Repeat the first two steps for the Shooting state

Adding AI Decisions

The original swordsman has two decisions, each one connected with a state, so let's add them to the graph.

For the Patrol state:

1. Right click on the graph canvas and select AI > Decision > Detect Target Radius

2. Set the Radius to 4

3. Set the Target Layer to Player

4. Connect the Output element to the Decision input of the patrol state AI Transition node

For the Shooting state:

1. Right click on the graph canvas and select AI > Decision > Time In State

2. Let the fields to their default values

3. Connect the Output element to the Decision input of the shooting state AI Transition node

Adding AI Actions

The swordsman has two actions, each one connected with a state: let's add them to the graph.

For the Patrol state:

1. Right click on the graph canvas and select AI > Action > Patrol

2. Check the Avoid Falling value

3. Set the Hole Detection Offset x value to 1

4. Connect the Output element to the Actions input of the Patrol state node

For the Shooting state:

1. Right click on the graph canvas and select AI > Action > Shoot

2. Check the Aim At Target value

3. Connect the Output element to the Actions input of the Shooting state node

Connecting Transitions

The last step to complete the brain graph is to connect the transitions True/False states. In this case we only need the True ones:

1. Connect the True State of the patrol AI Transition to the States in input of the Shooting state

2. Connect the True State of the shooting AI Transition to the States in input of the Patrol state

Generating the Character AIBrain System

We are now ready to add the brain graph to a gameObject and generate all the Corgi AI structure: we have two options for this.

AI Brain Generator

The AI Brain Generator component adds a static brain structure to your character, just like you are used to do in Corgi:

1. Enable the RetroSwordsmanGenerated gameObject

2. Click the Add Component button and select The Bit Cave > AI > AI Brain Generator

3. Drag the RetroSwordsman AIBrain we created above in the AI Brain Graph field

4. Click the Generate button and you will get the full working Corgi AI system for the RetroSwordsman (try comparing it with the original prefab)

AI Brain Pluggable

The AI Brain Pluggable generates all Corgi AI system at runtime from a list of brain graphs:

1. Enable the RetroSwordsmanPluggable gameObject

2. Click the Add Component button and select The Bit Cave > AI > AI Brain Pluggable

3. Drag the RetroSwordsman AIBrain in the AI Brain Graphs field: this is an array of elements, so you can add more than one (one will be chosen randomly at runtime)

4. Hit the Editor Play button and you should see the Corgi AI Brain structure generated

You can install the plugins (for both engines) in two ways:

1. From the Unity Asset Store: usually the quickest and best solution

2. From the development repository on GitHub

Corgi Engine

1. From Asset Store

On the Asset Store you will find the latest stable version:

1. Install the latest version of Corgi Engine on your project

2. Install the extension from the Unity Asset Store

2. From the Development Repository on GitHub

Downloading the plugin on GitHub will give you access to the latest (and, sometimes, less stable) features. You will have to follow these steps:

1. Install the latest version of Corgi Engine on your project

2. Download the latest release of xNode (freely available on GitHub) and add it to your Unity project

3. Download the latest develop branch release of AI Brain Extensions for MMTools (freely available on GitHub) and add it to your Unity project

4. Download the latest develop branch release of AI Brain Extensions for Corgi Engine (freely available on GitHub) and add it to your Unity project

TopDown Engine

1. From Asset Store

On the Asset Store you will find the latest stable version:

1. Install the latest version of TopDown Engine on your project

2. Install the extension from the Unity Asset Store

2. From the Development Repository on GitHub

Downloading the plugin on GitHub will give you access to the latest (and, sometimes, less stable) features. You will have to follow these steps

1. Install the latest version of TopDown Engine on your project

2. Download the latest release of xNode (freely available on GitHub) and add it to your Unity project

3. Download the latest develop branch release of AI Brain Extensions for MMTools (freely available on GitHub) and add it to your Unity project

4. Download the latest develop branch release of AI Brain Extensions for TopDown Engine (freely available on GitHub) and add it to your Unity project

The AI Brain Graph editor is a tool used to create Corgi/TopDown Engines AI logic through a visual node editor.

Working with the Graph

Creating a Graph

A graph is an asset stored in your project Assets folder. To create one:

1. Right click anywhere in the Assets folder

2. Select Create > The Bit Cave > AI Brain Graph

3. Rename the brain asset

4. Double click on it to show the editor window

Creating a SubGraph

Like the graph, a subgraph is an asset stored in your project Assets folder. To create one:

1. Right click anywhere in the Assets folder

2. Select Create > The Bit Cave > AI Brain Graph

3. Rename the brain asset

4. Double click on it to show the editor window

Adding Nodes

To add nodes to the graph (or subgraph) simply right click on any free space and select the desired node.

Using a Graph on a Character

When you add a graph to a Corgi/TopDown character, the system will parse your nodes and will translate them to AIBrain/AIAction/AIDecision components.

To achieve this, all you have to do is to add one of these components:

• AI Brain Generator: this component will generate all needed elements to the character

• AI Brain Pluggable: similar to the previous component, but the generation will be at runtime

If you are working on a game made with Corgi Engine, chances are you are going to create new AI Decisions and AI Actions: the AI Brain Graph is completely extensible, so you can create your own nodes.

Basically, each node acts as a component generator for the corresponding action or decision, so you'll just have to pass the correct attributes.

Creating AI Action Nodes

To create your own action nodes, you will have to extend the AIActionNode class and override a single method, called AddActionComponent: this component returns an instance of the Corgi AIAction you want to add with this node.

As an example, please take a look at the AIActionJumpNode that corresponds to the AIActionJump for the Corgi Engine:

using MoreMountains.CorgiEngine;
using MoreMountains.Tools;
using UnityEngine;

namespace TheBitCave.CorgiExensions.AI
{
    /// <summary>
    /// A node representing a Corgi <see cref="MoreMountains.CorgiEngine.AIActionJump"/> action.
    /// </summary>
    [CreateNodeMenu("AI/Action/Jump")]
    public class AIActionJumpNode : AIActionNode
    {
        public int numberOfJumps = 1;

        public override AIAction AddActionComponent(GameObject go)
        {
            var action = go.AddComponent<AIActionJump>();
            action.Label = label;
            action.NumberOfJumps = numberOfJumps;
            return action;
        }
    }
}

Please note the [CreateNodeMenu("AI/Action/Jump")] that adds this node to the graph contextual menu.

Creating AI Decision Nodes

To create your own decision nodes, you will have to extend the AIDecisionNode class and override a single method, called AddDecisionComponent: this component returns an instance of the Corgi (or TopDown Engine) AIDecision you want to add with this node.

As an example, please take a look at the AIDecisionHitNode that corresponds to the AIDecisionHit :

using UnityEngine;
using MoreMountains.CorgiEngine;
using MoreMountains.Tools;

namespace TheBitCave.CorgiExensions.AI
{
    /// <summary>
    /// A node representing a Corgi <see cref="MoreMountains.CorgiEngine.AIDecisionHit"/> decision.
    /// </summary>
    [CreateNodeMenu("AI/Decision/Hit")]
    public class AIDecisionHitNode : AIDecisionNode
    {
        public int numberOfHits = 1;

        public override AIDecision AddDecisionComponent(GameObject go)
        {
            var decision = go.AddComponent<AIDecisionHit>();
            decision.Label = label;
            decision.NumberOfHits = numberOfHits;
            return decision;
        }
    }
}

Please note the [CreateNodeMenu("AI/Decision/Hit")] that adds this node to the graph contextual menu.

The AI Brain Graph comes packed with four main type of nodes:

• AI Brain State Node

• AI Transition Node

• AI Action Node

• AI Decision Node

Additionally, you'll get some helper nodes:

• Comment Node

• AI Brain State Alias Node

• AI Brain Any State Node

Finally, when you work with a Subgraph, you have access to:

• AI Brain Subgraph Nodes

• AI State In Nodes

• AI Transition Out Nodes

Main Nodes

AI Brain State Node

A State node represents a single state in the MMTools AIBrain.

The Set as starting state button will set the state as the first one in the MMTools AIBrain states list.

Attributes

• Can Transition To Self: if set to false, self referencing transitions will be removed (for instance Idle > Idle)

Inputs

• States In (multiple State connections): a list of entry points from other states transitions

• Actions (multiple Action connections): a list of actions that should be performed when entering the state itself

Outputs

• Transitions (multiple Transition connections): a list of transitions that will let the system exit from this state

AI Transition Node

A Transition node represents a single transition from a state in the MMTools AI Brain: a state can have more than one transition.

If you wish, you can rename the node by right-clicking the header and choosing Rename but this won't affect the AI generation.

Attributes

This node has no attributes.

Inputs

• Decision (single Decision connection): a single AI Decision Node that will let the AI Brain exit from the actual state

• Input (single Transition connection): a single connection from the AI Brain State

Outputs

• True State (single State connection): a connection to the state that should be activated when the decision is true

• False State (single State connection): a connection to the state that should be activated when the decision is false

AI Action Node

Action nodes are graph representations of AIAction components. They come with a single output element that should be connected to the state. This will tell the state itself that this action should be executed.

A node may have some parameters, corresponding with the Corgi/TopDown engine AIAction components.

If you wish, you can rename the node by right-clicking the header and choosing Rename but this won't affect the AI generation.

Attributes

• Label: corresponds to the regular AIAction label

• Depending on the corresponding AIAction, you'll have access to a list of paramenters

Inputs

This node has no input connections.

Outputs

• Output (multiple Action connections): a single AI Decision Node that will let the AI Brain exit from the actual state

AI Decision Node

Decision nodes are a graph representation of AIDecision components. They come with a single output element that should be connected to a state transition. This will define the condition to exit the state.

If you wish, you can rename the node by right-clicking the header and choosing Rename but this won't affect the AI generation.

Attributes

• Label: corresponds to the regular AIDecision label

• Depending on the corresponding AIDecision, you'll have access to a list of paramenters

Inputs

This node has no input connections.

Outputs

• Output (multiple Decision connections): a single AIDecision Node that will let the AI Brain exit from the actual state

Helper Nodes

Comment Node

Comment nodes have the only purpose of letting you add notes in your graph. They won't generate anything in the character AI Brain System.

Attributes

This node has no input attributes.

Inputs

This node has no input connections.

Outputs

This node has no output connections.

AI Brain State Alias Node

The AI Brain State Alias Node will let you create alias elements for your states: this will avoid main spaghetti like brains when things get complicated.

Attributes

• Available States: the node will show a list of nodes:

  • In the main graph all nodes and subgraph-exposed nodes will be shown

  • In a subgraph, only inner nodes will be shown

Inputs

• States In (multiple State connections): a list of entry points from other states transitions

Outputs

This node has no output connections.

AI Brain Any State Node

The AI Brain Any State node will let you generate Decision/Transition logic for all nodes in your graph:

• If added in a main Graph, also subgraph States will be affected

• If added in a subgraph, only subgraph States will be affected

Attributes

This node has no input attributes.

Inputs

This node has no input connections.

Outputs

• Transitions (multiple Transition connections): a list of transitions that will let the system exit all included states

Subgraph Nodes

AI Brain Subgraph Node

A Subgraph node is a special state node, that lets you create a inner state/decision/action logic.

It can be set as a starting node (in this case its inner starting node will be used).

You can create a subgraph asset and assign it to the Subgraph field.

Attributes

• Subgraph: the subgraph data

Inputs

• State In (list of multiple State connections): a dynamically generated list of state connections (see AI State In Nodes)

Outputs

• Transition Out (list of single Transition connections): a dynamically generated list of transition connections (see AI Transition Out Nodes)

AI State In Node

The AI State In node exposes an AI Brain State node inside a subgraph to the parent brain graph.

Attributes

This node has no attributes

Inputs

This node has no input connections.

Outputs

• Input (single State connection): this node will generate a State In connection in the subgraph node of the parent graph

AI Transition Out Node

The AI Transition Out node exposes an AI Transition node connection inside a subgraph to the parent brain graph.

Attributes

This node has no attributes

Inputs

• Output (single Transition connection): this node will generate a Transition Out connection in the subgraph node of the parent graph

Outputs

This node has no output connections.

In this page you will find listed all the features of the package: all of them are tools for MoreMountains AIBrain system.

1. AIBrain Graph

The system lets you create AIBrains systems by using a node system.

The AIBrain Graph is based on , an opensource project by .

The graph includes the following features;

• A visual editing canvas with nodes for all the official AIDecisions and AIActions of Corgi and TopDown Engines

• A subgraph system for better reorganization and reusability

• An AI Brain Generator component, for quick creation of brain system starting from a brain graph

• An AI Pluggable Brain component for runtime generation of AI systems

2. AIBrain Debugger

The system will let you peek into some of the AIBrain inner workings and test states at runtime.

The debugger includes the following features:

• An AIBrainDebuggable component, that is an extension of the regular AIBrain component

• An AIBrain Debugger window to check what's going on at runtime including:

  • Force transitions during gameplay

  • Force the brain Target during gameplay

  • Track current/previous brain state tracking

3. Master/Slave Brains

The system will let you control an AIBrain (or a group of AIBrains) from another point in your game, usually from another AIBrain.

The Master/Brain system includes the following features:

• A channel system to send brain commands through the MMEventManager

• A Master component to send state change commands through a channel

• A Slave component to receive state change commands from one or more channels

The Master/Slave system implements a set of methods to control AIBrains (set as Slaves) from other AIBrains (set as Masters) or other parts of the application through the Corgi/TopDown Event System.

Using the System

The two main actors involved in this system are:

• Brain Master: not necessarily connected with a brain, it is used to send State change command events through dedicated channels

• Brain Slave: this element listens for State change command events and forces the AIBrain behavior

BrainMaster Ability

The BrainMaster ability component lets you send state change commands to slave brains through a dedicated channel: usually this is achieved through an AIActionChangeAIBrainStateCommand but you can access the SendCommand method:

SendCommand(StateCommandChannel channel, string newStateName, Transform target = null)

• channel is used to filter who will receive and execute the command

• newStateName is the state the AIBrain should transition in

• target is the AIBrain target (if any)

The Brain Slave Ability

The BrainSlave ability component is used to receive state change commands through a dedicated channel.

Whenever an event is received, the slave will try to change the AIBrain to the new state.

As an alternative, the state change can be also forced through the TransitionToState() method:

TransitionToState(string newStateName, Transform target = null)

• newStateName is the state the AIBrain should transition in

• target is the AIBrain target (if any)

Channels

To use the Master/Slave communication system, you will have to create a Channel, that will be added to the slave channel list:

1. Select Create > The Bit Cave > MasterSlave > State Command Channel

2. Rename the newly created asset

3. Add it to your slave Channels list

4. Add the same channel to the master AIActionChangeAIBrainStateCommand component

The AIBrain Debugger tool lets you peek into some inner workings of an AIBrain and modify runtime behaviours.

To check the debugger in function, please watch the video below:

Opening the AIBrain Debugger Window

To open the debugger window, simply select from the Main menu Tools > The Bit Cave > AI Brain Debugger.

Using the AIBrainDebuggable Component

To debug a brain, you will need an AIBrainDebuggable component, that is an extension of the regular MMTools AIBrain.To add such brain select Add Component > CorgiExtensions > AI > AI Brain Debuggable.

This brain works exactly like a regular brain, so you can add states and transitions, but it will give some more additional info to the debugger.

Debugging an AIBrain

To start debugging a debuggable AI Brain, all you have to do is to play the scene from the Unity Editor and select a gameobject with an AIBrainDebuggable. The brain is divided in three main sections:

• Brain state

• Transitions

• Target

Brain State

The Brain State section shows the brain status during gameplay. Info displayed are:

• The selected gameobject

• Brain status (active or not)

• Current brain target (if any)

• The previous state and how much time the brain has been in it

• The current state and how much time has passed since the brain entered it

• Which actions the brain is performing

Transitions

This section will display all available states in the brain. Each state is displayed as a button, so you can force the transition if it is needed. A state can be:

• [C] The current state: in this case the button will be disabled

• [>>] A state connected with the current state

• A state disconnected with the current state

Note that you can force the transition even to a disconnected state: this is pretty useful if you are working with the .

Target

This section will allow you to set the brain target or remove it if needed.

Note that you can force any kind of target, not just the one selected by the brain.

Editor Actions

Remove Brain System

This action will clean up a gameobject from all AIBrain, AIDecision and AIActions components.

How to Use

• Right click a GameObject in the Hierarchy window

• Select The Bit Cave > Remove Brain System

Graph Utilities

Node Collapsing

To make the graph (or subgraph) more readable, you can enable node collapsing for AI Action and AI Decision nodes. When enabled, this feature will show only the Label field and the output connection.

When a node is selected, it will automatically expand to show all available properties.

How to Use

• Right click on a free spot in the graph/subgraph canvas

• Select Enable Node Collapsing/Disable Node Collapsing

xNode Preferences

The AIBrain Graph system is based on , an open-source project by : some of the settings can be configured through the Preferences panel (In the Preferences panel, select Node Editor).

Note: To get you started using the AI Brain Graph, you should first follow the Install instructions and check that everything is working.

The Tutorial Scene

First of all, look for the MinimalAI3D_Tutorial scene (and open it), that will serve as a starting point for this tutorial. Basically, it is the TopDown MinimalAI3D scene with all enemies removed (with the exception of PatrolAndMoveAI).

1. Open the AIs group to check the content: you will find the PatrolAndMoveAI prefab along with two other gameObjects (stripped out of all AI components): PatrolAndMoveAI_Generated and PatrolAndMoveAI_Pluggable.

Creating the AI Brain Graph

To start working with the graph, you'll need to create an AI Brain Graph:

1. In the Project panel, right-click the mouse button and select Create > The Bit Cave > AI Brain Graph

2. Rename the newly created asset PatrolAndMoveBrain (or anything you deem appropriate)

3. Double-click on the asset to open the Editor

The PatrolAndMoveAI Brain Structure

Select the PatrolAndMoveAI prefab in scene and look at the AI Brain, AI Actions and AI Decisions components: we want to replicate the same structure with the AI Brain Graph:

• The AI Brain has two states: Patrolling and MoveTowardsTarget

• While in Patrolling the character will perform an AIActionMovePatrol3D and an AIActionAimWeaponAtMovement action

• While in MoveTowardsTarget the character will perform an AIActionMoveTowardsTarget3D and an AIActionAIMWeaponATMovement action

• The chracters will exit the Patrolling state if the target is within range (AIDecisionDetectTargetRadius3D)

• The character will not exit the MoveTowardsTarget state after a while

To create the AI Brain Graph we will need these nodes:

• Two states

• Two transistions

• Three actions

• One decision

Creating the States

First of all, let's create the two states:

1. Right click on the AI Brain graph canvas and choose AI > Brain State: this will create a state

2. Right click on the node header and choose Rename. Rename the state Patrolling and select Apply

3. Repeat the first two steps, creating another node called MoveTowardsTarget

4. On the Patrolling node, click the Set as starting state button: this will set the Patrolling node as the entry state in the character brain

Adding Transitions

The Patrolling state has a single transition, so we are going to create it:

1. Right click on the Graph canvas and select AI > Transition: this will add a transition node

2. Click on the transitions output in Patrolling state and drag it to the Input element of the transition node

Adding AI Decisions

The original character has a single decision, connected with the Patrolling state, so let's add it to the graph.

1. Right click on the graph canvas and select AI > Decision > 3D > Detect Target Radius

2. Set the Radius to 8

3. Set the Target Layer Mask to Player

4. Set the Obstacle Mask to Obstacles, ObstaclesDoors, NoPathfinding

5. Connect the Output element to the Decision input of the patrolling state AI Transition node

Adding AI Actions

The swordsman has three actions, with one of them in common with both states: let's add them to the graph.

For the Patrolling state:

1. Right click on the graph canvas and select AI > Action > 3D > Move Patrol

   1. Set the Obstacle Mask to Obstacles, ObstaclesDoors, NoPathfinding

   2. Connect the Output element to the Actions input of the Patroling state node

2. Right click on the graph canvas and select AI > Action > Aim Weapon At Movement

   1. Connect the Output element to the Actions input of the Patrolling state node

For the MoveTowardsTarget state:

1. Right click on the graph canvas and select AI > Action > 3D > Move Towards Target

   1. Connect the Output element to the Actions input of the MoveTowardsTarget state node

2. You don't need to create a second Aim Weapon At Movement

   1. Connect the Output element to the Actions input of the MoveTowardsTarget state node

Connecting Transitions

The last step to complete the brain graph is to connect the transitions True/False states. In this case we only need the True one:

1. Connect the True State of the patrolling AI Transition to the States in input of the MoveTowardsTarget state

Generating the Character AIBrain System

We are now ready to add the brain graph to a gameObject and generate all the TopDown Engine AI structure: we have two options for this.

AI Brain Generator

The AI Brain Generator component adds a static brain structure to your character, just like you are used to do in TopDown Engine:

1. Enable the PatrolAndMoveAI_Generated gameObject

2. Click the Add Component button and select The Bit Cave > AI > AI Brain Generator

3. Drag the PatrolAndMoveBrain we created above in the AI Brain Graph field

4. Click the Generate button and you will get the full working TopDown AI system for the PatrolAndMoveAI (try comparing it with the original prefab)

AI Brain Pluggable

The AI Brain Pluggable generates all Corgi AI system at runtime from a list of brain graphs:

1. Enable the PatrolAndMoveAI_Pluggable gameObject

2. Click the Add Component button and select The Bit Cave > AI > AI Brain Pluggable

3. Drag the PatrolAndMoveBrain in the AI Brain Graphs field: this is an array of elements, so you can add more than one (one will be chosen randomly at runtime)

4. Editor Play button and you should see the TopDown Engine AI Brain structure generated

Creating a Reroute Node

When connecting two nodes, you can create a reroute by right-clicking the mouse button. The reroute node can then be freely moved.

To delete the reroute, right-click on it and select the Remove option.