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"
};

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

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...

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.

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

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

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");
}

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...

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.

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

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.

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

local leftVector = agent:GetLeft();

local upVector = agent:GetUp();

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.

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

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.

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

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

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

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.

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.

local avoidAgentForce = 
    agent:ForceToAvoidAgents(minTimeToCollision);

local avoidObjectForce =     
    agent:ForceToAvoidObjects...