Chapter 2. Creating and Moving Agents

In this chapter, we will cover the following topics:

• Setting up your first sandbox executable

• Creating your first sandbox Lua scripts

• Understanding agent properties and their effects

• Basic Newtonian motion

• Agent-steering forces

• Creating seeking, pursuing, path following, and grouped agents

Now that we understand how AI sandbox is set up and some of the underlying system structure, we're going to dive head-first into creating a brand new sandbox demo. Throughout the rest of the book, the new Lua sandbox API will be introduced piece by piece, extending this demo with additional AI functionality, animation, graphics, and game play.

While the sandbox is doing a lot of heavy lifting in terms of graphics and physics, the core AI logic will be completely implemented in Lua, backed by data structures that are managed by the C++ code.

Creating a new sandbox project

First, to create a new sandbox executable, we need to declare a new Visual Studio demo project within the Premake build scripts. You can add a new sandbox project by opening the SandboxDemos.lua script and appending a new entry to the SandboxDemos table. In this case, you can name your my_sandbox demo or any other name you'd like. The project name will determine the name of the executable that is built:

SandboxDemos.lua:

SandboxDemos = {
    "chapter_1_introduction",
    ...
    "my_sandbox"
};

Note

All the heavy lifting of configuring a sandbox demo actually takes place in the premake.lua file by the CreateDemoProject function. The premake.lua script simply loops over all entries within the SandboxDemos table and creates the corresponding projects, setting up the source files, project dependencies, library includes, and so on.

Setting up the file structure

The next step is to set up the actual file structure for the C++ source files, C++ header files, and Lua script files for the demo. Create the corresponding directory structure based on the entry you added to the SandboxDemos table. Premake will automatically search for any .h, .cpp, and .lua files that reside within these folders and any subfolders, automatically adding them to the Visual Studio project during the solution regeneration:

src/my_sandbox/include
src/my_sandbox/src
src/my_sandbox/script

Extending the SandboxApplication class

Once your project has been set up, you need to create three blank files for Premake to discover.

Create the source and header files as follows:

src/my_sandbox/include/MySandbox.h
src/my_sandbox/src/MySandbox.cpp
src/my_sandbox/src/main.cpp

Now, it's time to regenerate the Visual Studio solution by executing vs2008.bat, vs2010.bat, vs2012.bat, or vs2013.bat. When you open the Visual Studio solution, you'll see your brand new My_Sandbox project!

Each of the sandbox demos is set up to extend the base SandboxApplication class and declare where to find the corresponding Lua script files for the executable.

Declaring your MySandbox class follows the same pattern and looks as follows:

MySandbox.h:

#include "demo_framework/include/SandboxApplication.h"

class MySandbox : public SandboxApplication {
public:
    MySandbox(void);

    virtual ~MySandbox(void);

    virtual void Initialize();
};

Inheriting from SandboxApplication gives you a base to start with. For now...

Running your sandbox for the first time

Now, compile your solution and run your sandbox. As no meshes, lights, and so on have been added to the sandbox yet, all you should see is a black screen. While this might seem small, a lot has happened already, and your SandboxApplication class is properly set up to let Lua take over.

Creating a new Decoda project

Once Visual Studio is out of the way, it's time to create a Decoda project. Open Decoda and create a blank new project. Save the project to the decoda folder, which will create the .deproj and .deuser files. Whenever we need to create a new Lua script file, we will create the file within Decoda and save the .lua file to the src/my_sandbox/script folder:

decoda/my_sandbox.deproj
decoda/my_sandbox.deuser

Configuring Decoda's run executable

In order for Decoda to execute your sandbox, we need to configure the Decoda project with the following settings. You can access the project settings by navigating to Project | Settings. Typically, we'll have Decoda run the Release version of the sandbox executable for performance. Unless you need to debug the C++ sandbox code and Lua scripts at the same time, it's advisable to run the Release version of your executable.

The configuration of new Decoda project debug settings

Note

Note the relative path for the release executable. The path that Decoda will execute is based on the location of the .deproj file.

Remember that you have to build the Visual Studio solution before trying to debug with Decoda.

Creating a sandbox Lua script

With a basic sandbox application out of the way, we're going to create the basic Lua script that sets up the sandbox. First, create a new Sandbox.lua script within the script folder:

Create the Lua file as follows:

src/my_sandbox/script/Sandbox.lua

A sandbox Lua script must implement four global functions that the C++ code will call, and they are Sandbox_Cleanup, Sandbox_HandleEvent, Sandbox_Initialize, and Sandbox_Update:

Sandbox.lua:

function Sandbox_Cleanup(sandbox)
end

function Sandbox_HandleEvent(sandbox, event)
end

function Sandbox_Initialize(sandbox)
end

function Sandbox_Update(sandbox, deltaTimeInMillis)
end

With the basic hooks in place, modify your SandboxApplication class to create a sandbox based on your Lua script:

MySandbox.cpp:

void MySandbox::Initialize() {
    SandboxApplication::Initialize();

    ...
    CreateSandbox("Sandbox.lua");
}

Tip

Don't forget to recompile your sandbox application whenever a change is made to any of the C++ files.

Creating...

Shooting blocks

Now that we have some basic lighting, a physics plane, and the ability to create and simulate physics objects, it's time to start shooting things. Before we jump head-first into creating agents, we'll take a quick detour into accessing some of the physics aspects of sandbox objects, as well as interacting with input controls.

The Sandbox_HandleEvent function allows the sandbox to respond to mouse and keyboard inputs. The event parameter is a Lua table that stores the source of the event, whether the event was generated by a down or up key press, and what key caused the event. Mouse-movement events are similar, but contain the width and height location of the mouse cursor.

As we already know how to create a sandbox object, all we need to do to shoot objects is position the object at the camera's position and orientation and apply a physics impulse on the object.

In this case, we're going to create and shoot a block on a space_key press event. The camera's position and forward...

Creating an agent Lua script

To start creating an agent, we need to create another Lua script that implements the Agent_Cleanup, Agent_HandleEvent, Agent_Initialize, and Agent_Update functions:

Create the Lua file as follows:

src/my_sandbox/script/Agent.lua

Agent.lua:

function Agent_Cleanup(agent)
end

function Agent_HandleEvent(agent, event)
end

function Agent_Initialize(agent)
end

function Agent_Update(agent, deltaTimeInMillis)
end

Now that we have a basic agent script, we can create an instance of the agent within the sandbox. Modify the initialization of the sandbox in order to create your AI agent with the Sandbox.CreateAgent function.

Tip

Remember that each AI agent runs within its own Lua virtual machine (VM). Even though a separate VM is running the agent logic, you can still access and modify properties of an agent from the sandbox Lua script, as the C++ code manages agent data.

Modify the initialization of the sandbox in order to create your AI agent with the Sandbox.CreateAgent function...

Agent properties

Now that we can create agents, we're going to take a step back and look at what properties are available to an agent and what they mean.

Orientation

Whenever you need to return the orientation of an agent, it's easiest to use the forward vector that usually represents the direction of movement of an agent. Both the left and up vectors of orientation are available as well. Whenever you need to change an agent's direction, simply set its forward vector.

The forward axis

To access and set the forward vector of our agents, we can use the built-in GetForward and SetForward helper functions.

local forwardVector = agent:GetForward();
Agent.SetForward(agent, forwardVector);

The left axis

We can also access the left orientation vector using the GetLeft helper function.

local leftVector = agent:GetLeft();

The up axis

Accessing the up orientation vector is similarly provided by a GetUp helper function.

local upVector = agent:GetUp();

Location

An agent's position is the center of the mass of its...

Physics

Even though agents are simulated with physics, not all of the agent's physics parameters are enforced at the physics simulation level. The mass of an agent, for example, is the identical mass used within the physics simulation itself, while the MaxForce and MaxSpeed functions of an agent are only enforced by the agent. These two properties represent the maximum amount of force an agent can exert on itself and the max speed the agent can reach without any outside influences.

An intuitive example of why this separation is desirable when dealing with agent physics is gravity. When an agent accelerates to its max speed, we still want gravity to accelerate the agents downward in the case of falls. This acceleration can force agents to have a speed larger than their max speed property.

Mass

To access and modify the mass of our agents we can use the agent's GetMass and SetMass helper functions.

local mass = agent:GetMass();
agent:SetMass(mass);

The max force

The maximum force of our agents can...

Knowledge

Agents themselves have a very basic set of knowledge so that external Lua scripts such as the sandbox script can direct agents with some amount of persistence. For example, when we create an agent that moves to a target position, we might want the sandbox to set this position instead of the agent having to determine its target.

Target

An agent's target is a vector position. Typically, agents will use the target as a position they want to reach or the known position of another agent.

local targetVector = agent:GetTarget();
agent:SetTarget(targetVector);

Target radius

A target radius is a number value that agents use to determine whether they are close enough to their target without having to be exactly at the target position. This fudge factor helps agents avoid circling a target position due to small numerical differences in their position and target position.

local targetRadius = agent:GetTargetRadius();
agent:SetTargetRadius(targetRadius );

Path

An agent's path is a series of vector...

Agents' movement

As all agents within the sandbox are automatically simulated through the physics system, it's time to get acquainted with some basic Newtonian physics.

Mass

The mass of an agent comes into play when colliding with other objects and is based on how much the agent should accelerate based on the forces applied to the agent. All mass calculations within the sandbox occur in kilograms.

Speed

Speed defines how fast an agent is moving without considering the direction the agent is moving in. All speed values within the sandbox will be measured in meters per second and signify the magnitude of the velocity vector.

Velocity

Velocity, on the other hand, is both the speed and direction the agent is moving in. It is measured in meters per second and is represented as a vector.

Acceleration

Acceleration within the sandbox is always measured in meters per second squared and represents the change in the velocity of an agent.

Force

Force plays a large part when moving agents around and is measured...

Agent-steering forces

With some basic agent properties and a full-fledged physics system supporting the sandbox, we can begin moving agents realistically through forces. This type of movement system is best known as a steering-based locomotion system. Craig Reynolds' Steering Behaviors For Autonomous Characters (http://www.red3d.com/cwr/papers/1999/gdc99steer.html) is best known for describing this style of steering system for moving characters. Steering forces allow for an easy classification of different movement types and allow for an easy way to apply multiple forces to a character.

As the sandbox uses the OpenSteer library to steer calculations, this makes it painless for Lua to request steering forces. While the steering calculations are left to OpenSteer, the application of forces will reside within our Lua Scripts.

Seeking

Seeking is one of the core steering forces and calculates a force that moves the agent toward their target. OpenSteer combines both seeking- and arrival-steering...

Avoidance

Avoidance steering behavior involves avoiding collisions between moving agents, objects, and other moving agents. The collision avoidance calculated from ForceToAvoidAgents creates a steering force in the tangent direction of a potential agent as two agents move closer to one another. Predictive movements are used to determine whether two agents will collide within a given amount of time.

Obstacle avoidance, on the other hand, approximates sandbox objects using spheres and uses the agent's predictive movement to create a steering force tangent for the potential collision.

Collision avoidance

To calculate the force to avoid other agents, based on the minimum time, to collide with other agents, we can use the ForceToAvoidAgents function.

local avoidAgentForce = 
    agent:ForceToAvoidAgents(minTimeToCollision);

Obstacle avoidance

A similar force to avoid other dynamic moving obstacles can be calculated using the ForceToAvoidObjects function.

local avoidObjectForce =     
    agent:ForceToAvoidObjects...

Avoiding blocks and agents

Modifying the SeekingAgent.lua script by adding the weighted sum of the ForceToAvoidAgents and ForceToAvoidObjects functions allows for the seeking agent to avoid potential collisions. When running the sandbox, try shooting boxes in the path of the agent and watch it navigate around the boxes:

SeekingAgent.lua

function Agent_Update(agent, deltaTimeInMillis)
    local destination = agent:GetTarget();
    local deltaTimeInSeconds = deltaTimeInMillis / 1000;
    local avoidAgentForce = agent:ForceToAvoidAgents(1.5);
    local avoidObjectForce = agent:ForceToAvoidObjects(1.5);
    local seekForce = agent:ForceToPosition(destination);
    local targetRadius = agent:GetTargetRadius();
    local radius = agent:GetRadius();
    local position = agent:GetPosition();
    local avoidanceMultiplier = 3;

    -- Sum all forces and apply higher priority to avoidance 
    -- forces.
    local steeringForces =
        seekForce +
        avoidAgentForce * avoidanceMultiplier ...

Group steering

Group steering can be broken down into three main steering behaviors: alignment, cohesion, and separation. An alignment steering force has the agent's face in the same forward direction as the rest of the agents in the group. Cohesion is a force that keeps the agents within the group together. Separation is the opposite of cohesion and forces the agents within the group to keep minimum distance from one another.

Using a combination of these three steering behaviors, which are also known as flocking, you can create groups of agents that are driven to move together yet not run into each other.

Alignment

To calculate a steering vector that will align our agent to a group of other agents, we can use the ForceToSeparate function.

local forceToAlign =
    agent:ForceToSeparate(maxDistance, maxAngle, agents);

Cohesion

To keep our agent together with a group of other agents, we can calculate a steering force for combining using the ForceToCombine function.

local forceToCombine =
    agent...

Creating a group of followers

In this example, we're going to build another AI type called a follower agent. This time, a group of followers will stay together and move toward their leader. The leader, on the other hand, is still the same seeking agent that will randomly move around the sandbox, completely oblivious to the group of followers behind it.

Group-based movement using separation, cohesion, and alignment

To create followers, we'll use multiple steering forces to combine, separate, and align our agents to the leader agent they are following.

Create the Lua file as follows:

src/my_sandbox/script/FollowerAgent.lua

FollowerAgent.lua:

require "AgentUtilities";

local leader;

function Agent_Initialize(agent)
    AgentUtilities_CreateAgentRepresentation(
        agent, agent:GetHeight(), agent:GetRadius());

    -- Randomly assign a position to the agent.
    agent:SetPosition(Vector.new(
        math.random(-50, 50), 0, math.random(-50, 50)));

    -- Assign the first valid agent as the...

Summing steering forces

So far, we've been adding weighted steering forces together and applying forces when certain thresholds have been met, but what does all this really do to an agent's locomotion? The two most common techniques that are used to add different steering forces together are through a weighted sums approach or a priority-based approach.

Weighted sums

A weighted sums approach takes all the steering forces into account all the time using fixed coefficients that weigh each force against every other. While this is very intuitive with a small number of forces, it can get very hard to balance competing forces together when a large number of different steering forces are being used.

Typically, this should be your first approach to get the agents to move, but when complex situations need to be handled, it's better to go with a priority-based approach.

Priority-based forces

When dealing with priorities, only certain forces are taken into account based on some sort of priority or condition...

Summary

So far we've created agents using steering forces such as seeking, pursuing, path following, and flocking. By now, you should be familiar with how Lua and the sandbox work together and where data and logic responsibilities lie.

In the next chapter, we'll start going over animation handling and how to create animation state machines in order to manage the stateful playback of animations and transitions. With a basic moving agent and an animating mesh, we'll move one step closer to a fully functioning AI agent.