Getting Started
Entities
Levels
Plans & Mappings
What are Plans?
Plans are for a single Drive Type and have a list of Root Mappings. A Root Mapping is the start of the Plan Tree
and contains the Mapping Type that has an OutputChange that reduces the Drive Type Level. Plans are generated by
the Planner Type.
Plans also contain information on the status (Not Complete, Complete, Running, Finished, or Interrupted) of each Plan.
What is a Mapping?
A Mapping represents one unit of a Plan. Think of it as a single action that has Input Conditions that need to be
satisfied for it to start and then once it is started, Output Changes can occur. The Ouput Changes can occur anytime during
Mapping and there are currently ten ways to control the timing of an Output Change: On Finish, On Animation Event,
Repeating, On Behavior Invoke, Before Start, On Trigger Enter, On Collision Enter, After Game Minutes, On Interrupt,
and On Quit Agent Event.
A Mapping is a C# class that has a parent and children, so it is a Node in the Plan Tree. If the parent is null
it means the Mapping is a Root Mapping and will have at least one Output Change that reduces the Plan's DriveType.
If the Mapping has no children then the Mapping is a leaf in the Plan Tree. If all of the leaves in a Plan Tree have
all of their Input Conditions satisified then the Agent can perform this Plan. TAI considers the Plan to be "Complete".
Also if the Mapping's MappingType has at least one Input Condition Type (ICT) that requires an Entity Target
then the Mapping will have an Entity target. An Entity
target is passed to the Behavior Type, the code that actually runs the Mapping, so it can perform logic related to the
target. The Entity target is also passed to the Output Changes that are set to TargetType of "ToTargetEntity".
How is a Mapping Created?
Mappings are usually created by the Planner Type when generating Plan Trees but special GoTo Mappings can also be generated while a Plan is being run by an Agent. These are generated if the Mapping has an Entity Target and needs to get within interaction distance of the Entity Target. By generating this GoTo Mappings only when running a Plan the overall number of Mappings in generated Plans is greatly reduced. The GoToActionType is set on the Mapping Type and determines what Behavior Type should be used.
Mapping Type
Inspector Reference
Script Reference
A Mapping Type defines the configuration and logic of a Mapping. A Mapping Type inherits from ScriptableObject and can
be created similar to other ScriptableObjects by right clicking in the Project File View and following the menu.
(Create -> Total AI)
Mapping Types contain the following main fields:
- Action Type: Acts as a grouping of Mapping Types and also specifies the Behavior Type that will occur.
- Behavior Type Selectors: Selectors for choosing attributes values to send to the Behavior Type.
- Utility Modifiers: Utility AI style modifiers to change the Utility of the Mapping.
- Target Factors: Utility AI style selectors for picking an Entity and/or inventory Target(s).
- Input Conditions: What needs to be true for an agent to perform this MappingType?
- Output Changes: What changes will occur at various times when running this MappingType?
Input Conditions
Inspector Reference
Script Reference
A MappingType can have zero to many Input Conditions (ICs). Each IC represents one check to see if the Agent
can perform this Mapping Type. If all checks pass then the Mapping will be marked as "Completed". If the
Agent is using the GOAPPlannerType or any Planner Type that can generate planning trees and an IC fails, the planner type
will try to find a Mapping Type with an Output Change that "fixes" the Input Condition. If it finds a fix, a
new child Mapping will created. For more information on how GOAPPlannerType generates Plan Trees see
GOAP Info.
The two main fields on an IC is its type, Input Condition Type (ICT), and what match type (Match multiple Entity Types)
of object it is checking. The final fields on an IC define the values the ICT needs to do the check.
The required values along with the specific match type are dependent on the ICT, so the ICT contains an
TypeInfo class that will dynamically change the shown inspector fields to only show fields the ICT
needs along with descriptions and tooltips. It can also make the Type fields more specific. For example if
the ICT is for an Agent Type, the editor will only allow you to select Agent Type ScriptableObject assets.
Output Changes
Inspector Reference
Script Reference
A Mapping Type can have zero to many Output Changes (OCs). An OC's Target Type can be for the Agent (To Self) or
for the Target (To Entity Target). An OC also has ten Timing options: On Finish, On Animation Event,
Repeating, On Behavior Invoke, Before Start, On Trigger Enter, On Collision Enter, After Game Minutes, On Interrupt,
and On Quit Agent Event. Behavior Invoked relies on the Behavior Type to specifically call an Output Change
check. AnimationEvent relies on Unity's
AnimationEvent
feature. The AnimationEvent's Function name should be exactly "AnimationOutputChange".
An OC is similar to IC in that it's main field is a type, Output Change Type (OCT). Similar to an ICT, an OCT
has an TypeInfo class in order to make the OC inspector dynamic based on the OCT.
An OC can contain Change Conditions if the OC needs to have specific logic causing it not to run.
Target Factors
Script Reference
If a MappingType has at least one ICT that requires an Entity Target, the Mapping will need to select an Entity Target
that passes ALL of the Entity Type ICs. The logic for this can be specified in the Decider Type or Planner Type.
If there are multiple Entities found that pass all of the EntityType ICs, TargetFactors (TFs) come into play. They
provide a Utility AI like mechanism for choosing the best Entity.
A Mapping can have zero to many TFs. If there are multiple TargetFactors you can supply a weight for each TargetFactor.
The weights will be normalized. For example if you have two TargetFactors, one with a weight of 0.5 and one with a weight
of 1.0, the first one will count for 0.5/1.5 = 1/3 and the second one for 1.0/1.5 = 2/3.
The TargetFactor abstract class inherits from ScriptableObject. All TargetFactors then inherit from TargetFactor.
There is only one method that needs to be implemented, Evaluate. Evaluate must return a value between 0-1 or -1.
-1 is a special value denoting a veto. If any TF returns -1, that Entity will be removed from consideration.
Selectors
Script Reference
Selectors are required to select the desired values for the Behavior Type.
They are also used by Ouput Changes to select values.
See Selector Guide.