Getting Started

Entities

Levels

Introduction

What is Total AI?

Watch Quick Overview Video

TAI is currently in Alpha and is available for FREE on GitHub

Total AI (TAI) is a complete open source agent AI Framework for Unity. Its goals are to provide an easy to prototype, flexible, fully customizable, and performant framework for a broad array of AI types and for a broad array of game types. Eventually TAI hopes to have a vast library of community created types that anyone can use to jumpstart their AI.

The core of TAI are Agents who can to sense the world, create memories, plans, and act in order to either reduce their Drives or based on the action with the most utility. This is accomplished with its Type System and Plan/Mapping System. It is also easy to extend and customize through ScriptableObject's pluggable data and logic ability. This makes writing and plugging in your own custom AI logic easy.

General AI Framework

Total AI is designed to be flexible to accomodate many different types and hyprids of AI Logic. In fact each Agent in your game could be using a different type of AI. This is due to how all of the key logic for an Agent is in Types that inherit from Scriptable Objects with the two key types being the Decider Type and the Planner Type. Every agent gets its base configuration from its Agent Type but it can then use Agent Type Overrides to change that setup configuration. Thus every Agent even if they are of the same Agent Type can be using different AI Logic.

The following AI Types are currently implemented or are planned:

Type System

The Type System is at the core of TAI. Most objects and an object's levels have a type associated with them. For example, An Agent has an Agent Type and an Agent's Attribute has an Attribute Type. These types not only define what the object is and its starting configuration but also inform TAI that this type can be used in certain Mapping Types (core unit of planning).

Entities

An Entity actual exists in the World. It will be a Game Object with a subclass of Entity Component. For Example, an Agent will always have an Agent Component. Agent inherits from Entity which inherits from MonoBehaviour. Also every Entity has an Entity Type. Entity Type inherits from Input Output Type which inherits from Scriptable Object. Similar to how Agent inherits from Entity, Agent Type inherits from Entity Type.

There are currently three types of Entities:

  • Agent: Only Entity that can plan and act in the world.
  • World Object: Any Entity that can't plan or act. Can be built or grow and can have states.
  • Agent Event: A multi-Agent coordinated event. Can add Roles to Agents to force them to only have certain Actions and Drives.

Levels

Levels are properties of Entities and have an associated level (usually a float value) and a Level Type. Default Level Types exist on Entity Types and Levels exist on Entities. For example, An Agent Type defines the default Level Types and the default Level values for an Agent. There are currently five Levels:

  • Drive: Drives are motivation for an Agent. An Agent wants to reduce all of their Drive Levels to 0.
  • Action: Defines the Behavior Type used to perform this Action.
  • Attribute: Defines a property of an Entity along with the level.
  • Tag: All Entities can be tagged which can then be used in planning.
  • Role: Can cause Drive Types and Action Types to be added or removed from an Agent.

Agent's Main Loop

The Agent's Main Loop handles the core requirement of being autonomous. The diagram below shows the main loop along with the Decider, Behavior, and interrupt logic. As can be seen in the diagram, all of the core logic is in Types (ScriptableObjects). This allows for customization of any logic and also the ability to easily give different Agents different logic.


Click on the diagram for full size.

Plans

A Plan is a tree structure with a Mapping representing a node with a parent and children. It's Root Mapping (no parent) has to reduce a Drive Type. The Planner Type is responsible for generating the plans and returns a List of Plans that reduce a certain Drive Type. The Decider Type is then responsible for selecting one of the plans.

The Planner Type is attached to the Decider Type so it is up to the Decider Type on how it uses the Planner Type(s). For example a Player Controlled Decider Type would not need a Planner Type as the Player would be directly choosing the Mapping to run.

A Player Controlled Decider Type is not currently implemented but is on TAI's Roadmap.

Mapping

A Mapping represents the core unit of a plan. Along with possibly having a parent and children Mappings, it contains a Mapping Type, an Entity target if it needs one, and multiple inventory Entity targets if needed. A Mapping Type consists of three main parts:

  • Input Conditions: What needs to be true for an agent to perform this Mapping Type?
  • Output Changes: What changes will occur at the start, during, at at the end of this Mapping Type?
  • Action Type: Specifies the Behavior Type that will occur. A Behavior Type holds the logic for running the Mapping along with hooking into movement and animation systems.
For more information on the Mappings and Mapping Types go here.

Drives

Drives represent an Agent's motivation. The Agent's goal is to reduce all Drive Levels to zero. An Agent will prioritize each Drive based on it's current utility level and then go one by one in order of Drives looking for a completed (all the Plan's leaf Mappings' Input Conditions are met) Plan to run. The Drive ranking/selection logic is easy to customize and lives in the subclasses of Decider Type. If there are multiple completed plans for a Drive the Agent's Decider Type chooses one based on a Utility Function the generates an overall utility for each Plan.

It is also easy to use TAI without the Drive logic. Just add one single Drive Type to every Agent and have your root mappings reduce that single Drive Type.

For more information on Drive Types go here.

How Drive-Based Total AI Works

TAI began with a series of simple questions. Why should NPCs (Agents) do anything at all? Why would they choose one action over another action? What motivates Agents? This last question led to the core of TAI. An Agent has Drives and an Agent's central goal is to reduce their Drive Levels to zero. A simple example is why should an Agent eat? Because their Hunger Drive is high. After eating it is reduced and the Agent can focus on reducing a different Drive or perhaps if there are no other drives with higher Drive Utility the Agent could continue to eat more.

Drive Utility is similar to how Utility AI Works, Drive levels are passed through a Utility Curve to generate a 0-1 value for how important it is to reduce that Drive. This allows Drives effects to be much more nuanced. For example, with an S shaped curve the drive will initially not be important, gradually rise up in importance, then be maxed out before the level actually reaches the Level's max. This might be a suitable curve to represent a Hunger Drive.

The Drive with the highest utility is choosen (or an alternate selection algorithm can be used) and the Agent's Planner Type then generates plans and the Agent's Decider Type chooses a plan to reduce this drive.

Choosing a plan can use a Utility Function that takes into account the rate of decreasing the drive along with any side-effects the plan might have. For example, if the Agent is cold and wants to make a fire they could burn their wood house down but the side-effect cost of losing a house would reduce the utility. They would find that the overall utility of gathering wood in the forest and burning that is much higher.