How to use

The below material aims to provide a quick way to kickstart development with ‘fAutonomy for Unity’, and also aims to provide a practical overview of the architecture, functionality and design philosophy of the tool.

The material first provides a quick overview of the product, then 2 flowcharts (workflow diagrams) summarizing the (suggested way of) setup and usage of fAutonomy, respectively.

The two flowcharts are followed by a concise, practical step-by-step guide, detailing the process of using fAutonomy. The following figure gives an OVERVIEW OF THE SYSTEM.

QUICK USER GUIDE 1

  1. Users (Unity games developers) interact with the client-side (the fAutonomy Unity plugin) to construct AI behaviours for in-game agents with the fAutonomy Visual Editor.
  2. The constructed AI behaviours can then be trained using the fAutonomy AI servers. For this purpose, the client (the Unity plugin) connects to the fAutonomy AI servers, authenticates, and uploads the constructed (and compiled) AI behaviours to the servers.
  3. Uploaded AI behaviours are trained into DNNs (Deep Neural Networks) on the servers.
  4. After server-side training is complete, the trained AI behaviours (DNNs) are downloaded by the client and made available via the fAutonomy C# API, for controlling in-game agents (e.g. NPCs). For this, fAutonomy C# API calls have to be placed in the game-code.

Typically a Unity game consists of several Unity scenes (.unity files), and AI may be needed in all, or just some of them. NOTE: below it is assumed fAutonomy is already setup.

After the project has loaded, please double-click on a scene you want to load, and which should be extended to an AI Scene using fA (short for fAutonomy), i.e. in which scene there is at least 1 agent (NPC, or intelligent environment, quest generator, whatever agent).


REMINDER (Definition of Agent):An agent is anything that can perceive its environment through sensors and acts upon that environment through effectors.”


Accordingly, a human-like, or robotic, or animal NPC can be an agent, or even the environment, or any other function or controller in your game, that takes an input, and produces an output. For more information please check the following URL:

https://www.tutorialspoint.com/artificial_intelligence/artificial_intelligence_agents_and_environments.htm


With fA one can create goal/utility-driven learning agents (most advanced type of agents).


Sensors perceive the state of the environment, provide it to the agent for decision-making (in case of fA, this decision-making is going to be done by a trained Deep Neural Network (DNN)), and then the agent responds with the action selected during decision-making (in case of fA that is an AI Action), which is then executed in the Unity game-environment.

Effectors realize a mapping from AI Actions to Real-World Actions (or Game-World Actions, or for short: Game Actions). This is something, that should be also set up with fA (cf. the manual). The mapping from AI Actions to Game Actions can be identical, i.e. each AI Action can correspond directly to a same Unity C# Game Action, or an AI Action can also correspond to a non-empty, arbitrarily long sequence of Unity C# Game Actions.

Now, that some of the basics are clarified, and you have the Unity scene loaded and _active_, which you wish to extend with fA into an AI scene, comes the question

I am text block. Click edit button to change this text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut elit tellus, luctus nec ullamcorper mattis, pulvinar dapibus leo.

When we use fA (Tools / fAutonomy), it is going to be applied to the currently active Unity scene. When used for the 1st time in a Unity scene, fA creates some folders (under Assets/fAutonomy/Resources) to store internal data about the AI Scene and the AI Behaviours in the scene + some other data (user settings, etc.). Next time this data is used.

With an active scene loaded in the Unity Editor, the Unity games developer (user) has to decide, which GameObject-s they want to be part of the AI Scene (which corresponds to the currently loaded, active Unity scene).

There should be at least 1 GameObject, which functions as an agent (cf. description above), and 0 or more GameObject-s, that are not agents (or agents which are not controlled by fA, but which can be perceived & with which fA agents can interact with, such as e.g. the PC (Player Character), which is controlled by the player, and not by fA AI (i.e. the PC can be considered an uncontrollable agent from the perspective of fA)).


To all such GameObject-s, please first attach the Assets/fAutonomy/FA.cs C# script.


NOTE: please note, that such GameObject-s (or Prefab-s, actually) can be inactive (disabled) in the scene, but then in runtime the game-code should set them to active dynamically.

The FA.cs C# source should be attached to GameObject-s (active or inactive) in a Unity scene, which we may want fA to see, which we want to include in the AI Scene corresponding to the currently active Unity scene, and with which the AI Behaviours in the AI Scene may interact with.

The previous figure summarizes the concept of AI Scenes:

  • A Unity Game (or App) may consist of one or more Unity Scenes;
  • Some or all of these Unity Scenes may be extended with fAutonomy to corresponding AI Scenes;
  • Each AI Scene may have 0 or more AI Behaviours, but it makes sense to create an AI Scene only, if there is at least 1 AI Behaviour in it;
  • Each agents in the AI Scene (which is a GameObject in the corresponding Unity Scene) can have 0 or 1 AI Behaviour.
  • Each AI Behaviour may be associated however to 0 or more agents (nonetheless, again, if makes sense to create an AI Behaviour only, if it is associated to at least 1 agent).

In the following we go step-by-step to summarize how fAutonomy should be used to create an AI Scene corresponding / extending a Unity Scene, and run that AI Scene in the game. For the sake of simplicity, let’s imagine, that we have a Stealth scene (typical in so many games), with several guard NPCs (Non-Player Characters) and 1 player-controlled character (PC).

  • AI Scene setup / AIEntityType hierarchy: access the AI Scene Setup through the Tools/fAutonomy/Setup AI Scene menu, where you can create an AI ontology. Staying with our stealth example, let’s create 2 new ontology-classes (called AIEntityType-s in fAutonomy): one for guard NPCs, and one for the player(s), as shown on the below screenshot. The properties defined for the AIEntityType-s are those, which fA AI may want to perceive.

For guards e.g. an Assets\…\AIGuard.cs C# source can provide the value of the defined properties, via the GetPropertyValue C# function, inherited from fA C# API class, AIBrain.AIEntity, which is an essential base class of the fA C# API.

For the player(s), e.g. an Assets\…\AIPlayer.cs C# source can provide the value of the above defined AIEntityType-properties, similarly by overriding the AIEntity.GetPropertyValue C# fA API function. Cf. Flowchart #2 for more.

    • Guards have a guard-name and Player(s) have a player-name property, whose range is the AIEntityType itself. The main reason to have this is to be able to know, in case of perception, possibly, which AI Object was perceived/observed (e.g. which guard, which player…in case it matters, as it should now in our example). Having these AIEntityType properties may seem as a redundancy, since the entity-name property is already inherited from AIEntityTypeObject (the root object in the above taxonomy/ontology), however AIEntityTypeObject does not have many of the properties defined, which the derived types (guard and player) have. So, in case we wish to reference those additional properties (during percept-processing), e.g. to allow the AI to reason with their value, we have to re-define them for the derived AIEntityType-s.
    • While guards are derived from AIEntityTypeAgent (as is the AIGuard.cs…derived from fA C# API class, AIEntityTypeAgent.cs), the player should be considered a non-agent from the perspective of fA AI. It can be modelled e.g. as a NonControllableAgent – an object, which fA cannot control, but which is going to act like an agent (e.g. dynamically change the value of its position properties, based on hard-to-predict user-input, etc.).
    • For guards, we have a boolean intruder-lost property defined, which is set by the game code (from default false to true), in case the PC (Player Character) appears and then goes out of view of a guard, and then back (from true to false), if the player re-appears in the view of the guard again. Setting the value of this property from game code can happen e.g. by setting the value of a public variable in AIGuard.cs. This can be a practice to follow, in order to reflect the state of the Unity game-world/environment toward fA AI.
  • AI Scene setup / GameObject mapping: at least guard and the player GameObject-s from the active Unity Scene should be included (and classified) here. These GameObject-s are going to be the AI Agent-s and AI Object-s, which fAutonomy AI Behaviours in this AI Scene can use (e.g. drive & reason with).

AI Scene setup / Environment setup: the environment can have at least e.g. 1 boolean property (game-over), however that is not necessary in the most simple case. What is more important, is that the value of this property is provided e.g. by the Assets\…\AIEnvironmentStealth.cs C# source via the GetPropertyValue C# function (inherited from fA C# API class, AIBrain.AIEntityEnvironment). This C# source (AIEnvironmentStealth.cs) should be attached (manually), as a component, to a GameObject that represents the game-environment to fA in the Unity scene at hand. Let’s call this GameObject, for the sake of simplicity, e.g. AIEnvironment (but it could have any other name too).

NOTE: AIEnvironmentStealth.cs attached to the GameObject, AIEnvironment, should perform some essential steps _necessary_ to make fA work well:

(1) the AIEnvironmentStealth::Start() function should call an AIScene initialization function of the fA C# API:

AIBrainAPI.Instance.InitialiseSceneAI(SceneManager.GetActiveScene().name, this);

(2) and then the AIEnvironmentStealth::Update() function should call another fA C# API function, which is responsible for bridging from core fA AI (Assets\fAutonomy\Runtime\Plugins\Windows\x64\AIBrainLibrary.dll under Windows x64) and the game-code through the fA C# API:

AIBrainAPI.Instance.AIBrainUpdate()

What happens in this case is that AIEnvironmentStealth::Update() calls the above fA C# API function, which then results in calls to the ReceiveActionFromAI function in AIGuard.cs (which C# class derives from AIBrain.AIEntityAgent fA C# API class). From within AIGuard::ReceiveActionFromAI actual game-actions should be initiated

NOTE: another important note and reminder is the following: when an action ends, the games developer (user of fA) should provide the fA AI (e.g. a guard) with a so called ‘action-outcome percept’. Omitting this percept is possible, however it is highly recommended to signal the end of in-game action-execution to the fA AI this way. In our Stealth-example this can happen from the game-code, e.g. from a C# game-function, which calls the AIBrain.AIBrainAPI::SendPerceptActionOutcomeToAI fA C# API function. …so, whenever an action-outcome percept has to be provided from the game to the fA AI (e.g. to a guard), the AIBrainAPI::SendPerceptActionOutcomeToAI fA C# API function should be called from game-code, at the moment in-game action-execution ends.

Similarly, so called regular percepts (that can arise anytime, depending on game logic) can be provided from the game to fA AI by calling the AIBrain.AIBrainAPI::SendPerceptRegularToAI fA C# API function (e.g. whenever a guard sees the player, or some other object, e.g. door, or key, etc.). Accordingly, regular percept do not have to be tied to action-execution. They can arise during or after action-execution as well.

NOTE: important is to know, that even if the AI Scene is initialized from the AIEnvironment C# script at Start(), the Update() won’t receive any actions from fA AI (and forward them properly to the game-code) until the fA AI (e.g. a guard NPC) does not receive at least 1 percept.

Above we already discussed action-outcome percepts. These result from the execution of Unity game actions (e.g. successful ending of a Unity game action can trigger the generation of an action-outcome percept in the game-code toward fA AI, as described above)…but such actions are going to be initiated by fA AI only after fA AI received some percept (to be able to make a decision based on that percept, about what action the related agent (e.g. guard NPC) should take). 

Regular percepts (as described above) can be useful for that purpose, of course, but it is warmly suggested to provide fA AI with a special, so called initial percept, at some point, initially (to each agent in the AIScene), after the AIScene is initialized, before sending any regular or action-outcome percepts to the fA AI agents.

This can be done by calling the AIBrain.AIBrainAPI::SendPerceptInitialToAI fA C# API function from the game-code (e.g. called once _after_ the Start() of the Unity scene, i.e. _after_ the AI Scene is fully initialized).

Regular percepts, and action-outcome percepts may have partial information about the environment (i.e. partial-observability, e.g. what the agent can see/hear around itself within a given range), however an initial percept may contain complete or partial information about the initial state of the environment (depending on what the games developer sees as right). I.e. we suggest fA users (games developers) to consider full observability in terms of the initial percepts. It is of course not necessary, and eventually fA does not restrict the content of percepts. Even regular or action-outcome percepts may contain full / complete information about the environment. Nonetheless initial percepts are most suitable (~intended) for this purpose.

  • AI Behaviour setup / List of Behaviours: after the AI Scene is set up, AI Behaviours can be created, which are then listed in this step. For the sake of simplicity, staying with our Guard-Intruder Stealth example, let’s assume that we have only one behaviour here for the guards, called ‘guard-behaviour’. This means, that each guard has the same behaviour, but (!) each of the guards has its own AIBrain (fA AI reasoner), with their own personal agent memory, etc. So providing multiple agents in an AI Scene with the same AI Behaviour does not mean that they are going to perform exactly the same actions in tandem. Providing the same AI Behaviour to multiple agents in an AI Scene means, that these agents are going to act according to the same policy, but if they are in a different situation (e.g. at a different location, having different percepts, different percept-history), then they are going to act accordingly, possibly differently, as dictated by their AI Behaviour. Now since the guard-behaviour is trained, thus there is a binary Google TensorFlow ProtoBuf (.bytes) file in the Assets\fAutonomy\Resources\AIScenes\<scene-name>\AIBehaviours\guard-behaviour folder of the Unity project), a TensorFlow graph, which is a DNN (Deep Neural Network): dcnn-graph.bytes, which corresponds to the trained guard-behaviour. In case multiple agents have the same AI Behaviour in an AI Scene, then they share this same AIBrain (DNN).(NOTE: fA AI server connectivity is required for training fA AIBehaviour-s).

NOTE: an agent may have 0 or 1 AIBehaviours in an AIScene, and multiple agents may have the same behaviour, or each agent may have a different behaviour, or anything in-between.

For the sake efficiency (e.g. to reduce the memory footprint of fA), a trained AI Behaviour (i.e. a DNN) can be shared between multiple NPCs (e.g. guards), but again: still, each guard has its own AI reasoner (a so called NeuralPlanner) instance, which uses the shared DNN, and which has its own personal agent-memory (its own belief base), so each such agent may act differently. Further details are beyond the scope of this document, and are not necessary for the users (games developers) to use fA.

What is important to know now is that each AI Behaviour (regardless of whether it is shared by multiple agents or not), when trained, becomes a DNN. I.e. a DNN is a trained AI Behaviour in fAutonomy. The trained DNN is the core of the trained AI behaviour in runtime, i.e. during gameplay…and for that no AI Server connectivity is required anymore.

IMPORTANT (!):Unity games can be built and distributed, and gamers can use them without any server connection. Only: Made with fAutonomy this has to be included on one of the first flash screens when a game made with fAutonomy starts. For more information, please check the Terms of Usage and License.

  • AI Behaviour setup / Types & Objects: all types and objects (defined in the AI Scene) can be used, e.g. in our Stealth-example (guard-behaviour). This is the default setup.
  • AI Behaviour setup / AI properties: beyond the properties defined in AI Scene setup for AIEntityType-s and the Environment, the guard-behaviour can have e.g. the following, behaviour-specific properties:

A key element of an AI Behaviour, which is associated to multiple agents, can be the definition of a self (behaviour specific) property, which in case of the guard-behaviour can be initially set to Guard0, and then updated from percepts / observations in runtime (cf. belief-update aka percept-processing), if needed, to the actual value (to the name of the guard NPC, that actually uses the guard-behaviour).

Another behaviour-specific property, which is worth to note at this point, is the tdg-multiplier (numeric)property. This is sort of a legitimate ‘trick’ to uniformly (and redundantly) multiply the size of the generated training data (hence the name: tdg…).

More information about the above two BS-props. is provided below, in the respective steps of AI Behaviour setup.

  • AI Behaviour setup / AI actions: staying with our simple Stealth-example, we can have two action-definitions here: patrol and chase. These are the AI Actions, with which fA AI can reason (plan). These however have to be mapped to C# Game Actions in order to execute them (if needed). More details about this below.
  • AI Behaviour setup / Initial Beliefs: here the initial value of all the properties (selected from the AI Scene, and also the behaviour specific props.) is provided.
  • AI Behaviour setup / Belief Update (Percept Processing): this step is of crucial importance, but optional. The user can define so called ‘percept-preprocessing rules’ in this step, to bridge between the game-environment, and the beliefs of the fA AI Agents (e.g. the beliefs of a guard NPC). There can be multiple PPP (Percept Pre-Processing) rules for each type of percept defined. Just as a reminder: there are currently 3 types of percepts in fAutonomy:
  1. Initial
  2. Regular
  3. Action-outcome

In case of our simple Stealth-example we made 3 PPP-rules for initial percepts, 6 PPP-rules for regular percepts, and 4 PPP-rules for action-outcome percepts.

NOTE: to connect back to AI properties, as discussed before, and especially to the self property (as defined in guard-behaviour), just to give an idea: the value of the self BS-property can be updated to the proper value by an initial PPP-rule, e.g.
ip-0-self, that checks, whether the guard-name in the self-perception-part of the initial percept (hence the naming, ip…) is equivalent, or not, to the current (belief)value of the self BS-property. If not, then the value of the self BS-prop. should be updated to the perceived value (guard-name). For more information about PPP rules please check the user’s manual and the contextual help menu.

  • AI Behaviour setup / Action Mapping: this is another very important step in configuring an fA AIBehaviour, just while PPP rules (cf .above) translate information from the game-environment to the AI, the ‘Action Mapping’ is responsible from translating information exactly in the opposite direction: from fA AI back towards the Unity game-environment. Action mapping can map each AI Action to a sequence of 1 or more C# Game Actions. Not every AI Action has to be mapped. Some AI Actions can be cognitive actions, modifying the beliefs of the agent, without affecting the game-environment (if needed), and so they do not have to be mapped. Other AI Actions (e.g. physical or communicative actions) may however be mapped to corresponding C# Game Actions, in order to take place (happen) in the game.In our simple Stealth-example both the patrol and chase AI Actions have their respective C# Unity Game Actions specified, which correspond to them 1-to-1
  • NOTE: please see below, that in case of the chase AI Action, which has no parameters, the corresponding C# Game Action can have 2 parameters: the (X,Z) coordinates of the player character, as far as the guard agent knows/believes. I.e. the value of the parameters comes from the ever-actual beliefs of the agent (guard), however parameters can also be passed between AI Actions and C# Game Actions, or parameters of AI Actions can be used to access beliefs in a more advanced way… 

NOTE: in Unity the 2D plane is usually measured along the X and Z axis (height is Y).

    • AI Behaviour setup / Training Data Generation: this is a most important step for the quality of trained AI Behaviours (e.g. trained guard-behaviour). This setup-step determines, what kind of data is going to be generated on fA AI server side for training, testing and validating DNNs (Deep Neural Networks). It is important to see, that the beliefs selected here in this step are going to be used to generate data, more precisely: data-points, part of which data-points is then going to train the DNN corresponding to the AI Behaviour, while another part of the generated data-points is going to be used to test/validate the DNN during server-side ML (Machine Learning). The distribution of the generated data can be set in a later step (cf. Training Settings). Now, at this step, the user should only specify, what (total) data has to be generated. The minimum size of the total data is 3 (due to that it has to be divided in 3 non-empty sets: training, test and validation), while the maximum depends on the subscription-tier of the user.In case of our simple Stealth-example the tdg-multiplier behaviour-specific AI property can be used to multiply the number of generated data-points, by looping over some of its values as well (e.g. looping through the values from 0 to 99, would multiply the training data redundantly with 2 orders of magnitude, i.e. 100-times).NOTE: in ML, a data-point, in terms of DNN training, is actually an (X,Y) pair, where X is an input for the DNN, and Y is an expected output of the DNN (in case of supervised learning, which the fA AI server currently does). So, in this step the user can define, what combinations of AI-property-values they want to use to generate the set of X values, where each X is a belief-state the agent using the given AI Behaviour. All selected AI-property-value combinations are generated.
  • AI Behaviour setup / Encoding: in this step the user has to define, how to encode an X input (generated e.g. during TDG, i.e. Training Data Generation, cf. previous step) for the DNN. Currently, in case of the guard-behaviour, the only thing that matters, for the fA AI to decide, whether to patrol or chase, is whether the intruder was spotted, or not. This is very simply set, for now, but can be extended with further information, that can refine the DNN-based decision making of guard NPCs. For now, in our example, the Encoder configuration is kept so simple (as simple, as possible), but still useful for proper AI decision-making. NOTE: the DNN input size is 12×12=144

  • AI Behaviour setup / Training Settings: the solver settings can be high, to provide better Y values for the X values generated in the TDG (Training Data Generation) step above. The training settings (i.e. the DNN structure and training hyperparameters) are set to properly align with the number of generated data-points (generated in the TDG step above). In case of our simple Stealth-example 200 total data-points was enough, so the training is lightning fast this way. The guard-behaviour-DNN was trained for 200 steps as well. For more complex inputs, however, and more AI Actions, more data-points (in TDG) and more training steps may be required.

  • AI Behaviour setup / Compile & Train: in this step the user should only click on the ‘Compile’ button, to generate the internal representation of the AI Behaviour at hand (i.e. the proper .txt and .json files in the Assets\fAutonomy\Resources\AIScenes\<scene-name>\AIBehaviours\guard-behaviour\configuration folder), and then they can click on ‘Start Training’ (if the Preferences are set-up properly), to train the guard-behaviour via the fA AI servers.

IMPORTANT: to train AI behaviours with fA, the user (Unity games developer) has to connect to the fAutonomy AI servers. The fAutonomy AI servers perform the training of AI behaviours. To access and authenticate with these servers can be done without registering on the http://fautonomy.ai website. In fA-terminology this is called ‘unregistered subscription’, which is the default (the user-credentials have to be left empty in the Preferences menu, to access the fA AI servers via unregistered subscription). However the user can also create a free user account on the http://fautonomy.ai website, which is better in terms of AI Behaviour complexity, which the fA AI servers accept. This is called ‘free registered subscription’. Both the registered and unregistered subscription are unlimited in time, however registered subscriptions are identified by a unique Subscription ID (SID), which is automatically provided to the user after login on the http://fautonomy.ai website. To use a registered subscription, the user then has to input the obtained SID and their user-credentials (username and password used during website registration) in the Tools / fAutonomy / Preferences menu, and successfully verify them with the fAutonomy AI servers by clicking on the “Verify Details” button.

Nonetheless, again, let us re-iterate:

fAutonomy for Unity can be fully used without website-registration (the functions provided by the fAutonomy client do not require website-registration).

The progress of training (and possible errors during that process) can be monitored in the AI behaviour list, and also (in a bit more detail) in the Unity console, as fAutonomy outputs all the information there during the training.

State 12 (job status code 12) means training is completed. In that moment the DNN file is downloaded from AI server-side, and can be used in runtime to drive the agents, who have the given AI behaviour, which the trained DNN implements.

  • Now the user can just play and enjoy their game in the Unity Editor, or build and run it outside of the Unity Editor.NOTE: Build & Run works only on Windows 64-bit systems for now, but we are in the process of extending this to mobile and console platforms as well. fAutonomy for Unity is still in Open Beta, provided completely for free. As such, there may be still some bugs in the system to be ironed out, with the help of our user community. 😊
Login
Loading...
Sign Up

New membership are not allowed.

Loading...