Creating an Actor Tutorial, Part 1 – Overview and Concepts

So you’ve gotten the hang of STAGE. You’ve made some interesting worlds by placing and arranging static meshes. But, to finish your application, you need something more. After all, a few Static Meshes and a Sky Box doesn't make a game. You need trucks that move, game inventory objects, motion sensitive guards, or maybe even a rocket launcher. In short, you need the ability to make your own custom Actors!

This tutorial teaches you all you need to know to make your own Actors. By following this 3 part tutorial, you will learn how to create a waving flag that you can use right in the editor. You will learn how to create a complex tessellated Actor, expose its size, speed, and height properties via an ActorProxy, and even make your flag accessible to the editor.

This tutorial assumes you have already worked with STAGE. If not, please see the ‘Getting to Know the Editor’ tutorial. Note - this tutorial uses the word ‘Game’, ‘Simulation’, and ‘Training Application’ interchangeably.

Part 1 – Actors and Proxies and Properties, Oh My!

Before you can get started building that cool waving flag, there are a few things you need to know about how STAGE was built. The Delta3D Editor sits on top of a very dynamic architecture. In fact, STAGE was designed from the ground up to encourage customization. Since we could never anticipate what types of objects you’d need, we built an architecture that is completely generic and let you build your own game objects! Below are 3 key concepts you need to know.

Actor – An Actor is any game object that has properties you want to work with in the Editor. An Actor can truly be anything you can imagine, from flying planes to pulsing lights to droppable guns to scaly green monsters. Actors are the specialized objects that help define your game or simulation. In part 2 of this tutorial, you will create your first Actor called ‘TesselationActor’.

ActorProxy – An ActorProxy is a wrapper for an Actor. Proxies are simple, data oriented classes that have two main jobs. First, they provide a common, uniform class that the editor understands. Second, they know everything about the Actor they wrap, especially the properties. In part 2, you will create an ActorProxy for our flag called ‘TesselationActorProxy’.

ActorProperties – ActorProperties are the properties of an Actor that show up in the PropertyEditor. Actor properties allow level designers to tweak and change how an object works. The more properties you expose, the more useful your object becomes. When you expose numerous important properties for your object, you allow level designers to take full advantage of your Actors without changing your code. In part 2, you will expose Actor properties for ‘Width’, ‘Height’, ‘Number of Steps’, ‘Period’, ‘Amplitude’, ‘Phase’, and ‘Texture’. By changing the values of these properties, you can change the size of your flag, make it move faster, give it more ripples, or even change the texture. The following picture shows some of the properties in the editor.

Figure 1 – Tesselation Actor Properties

Now that you know the basics about Actors and ActorProxies, there is one final step to address. Since the editor can’t magically find your ActorProxy classes, we need to tell it about our new object. What you need to do is put your ActorProxy into a library that the editor can find. Once you create this library you will be able to import it directly into the editor. Fortunately, this sounds harder than it is. In fact, as you’ll see in part 3 of this tutorial, it takes about 5 lines of actual code to do this. Plus, you will only need 1 library for ALL of your actors.

OK. So, let’s sum up! To create any new Actor for STAGE, you will need to do the following steps:

1) Create your Actor – this is your specialty!
2) Create your Actor Proxy – simple data wrapper
3) Create an Actor Library - ONE time only
4) Add your Proxy to the Library – about 5 lines of code

Now, you know enough about the basic architecture of STAGE to get started.

Seriously, stop here! If you just want to know how to do something by example, it’s time to move on to Part 2 of the tutorial.

However, if you’re the technical type and really want to know what’s going on, then you’ll be happy to know that we’ve got some great information ahead. As it happens, the Dynamic Actor Layer (DAL) was thoroughly designed before we ever wrote a line of code. Below is some of the detailed design material used in the construction of the DAL.

2. Dynamic Actor Layer (DAL)

The Dynamic Actor Layer (DAL) provides a flexible, non-intrusive mechanism for generically exposing the properties of game actors in C++. The two primary components of this design are ActorProxies and ActorProperties. The proxy component is a wrapper for the underlying game actor and holds a collection of the individual properties. The property component exposes the data for a single game actor property via a getter and setter function object; similar to the Java bean specification. The proxy knows about its properties and the properties know how to access their data. These two components are used to generically expose all underlying data without ever modifying the original game actor code. Use of these data driven components, instead of the underlying game actor, promotes data encapsulation and code re-usability.

Figure 2 - Overview

The Dynamic Actor Layer and editor architecture overview is noted in Figure 2. The main purpose of the Editor is to allow for the manipulation of actors in a given scene. To support this, the DAL exposes a generic template allowing STAGE to work with actors as generic objects. The core of this concept is that each actor should be treated generically using only its name, id, and a collection of properties. A detailed description of the components of the DAL follows.

3. ActorProxy

As mentioned above, Actors are any objects in your training application that have behavior and need to be manipulated in STAGE. Since the Actor classes can be anything, the editor must be protected from the internal workings of any one object. To make this happen each Actor must have a corresponding Proxy class that allows access to the internal properties. In essence, the ActorProxy is a conduit for actors to communicate their behavior to external applications or to ensure a consistent communications protocol among actors. Figure 3 shows a class diagram of the ActorProxy, Actor (DeltaDrawable), and ActorProperty.

Figure 3 - ActorProxy Class Diagram

The following is a description of the classes portrayed by the class diagram in Figure 3.

DeltaDrawable
This is the base class for all Actors in the system. The DeltaDrawable (dtCore::DeltaDrawable) is the base class of all Delta3D objects that are in the scene. In addition, it has tracking information like a tag name and a unique ID.

MyTruck
This is an example of a user built Actor class. Some of these will be built internally as part of the Editor, but many of these will be built by end developers and may be known only to their own particular application. Actor classes can be pretty much anything. They can have lighting, articulated parts, movement, AI, meshes, sounds, triggers, and anything else that you can do with Delta3D. They can draw themselves in anyway they sit fit within the Delta3D architecture. They can have many or zero properties, can have references to shared resources, and can be anything from a square billboard to a full blown landscape.

ActorProxy
This is the base class for all Actor Proxies. The Proxy’s main purpose is to expose the attributes of an Actor class as a series of properties. It has interface methods for getting and setting properties, getting its actor, and getting the actor’s type. Each actor must have a Proxy. The editor will periodically ask for properties by name or even change the value of the property using the setValue() method.

MyTruckProxy
This is an example of an actual user built Actor Proxy. In this case, the truck has a property called speed, so the Truck Proxy might expose a property called ‘speed’ to the editor. Then, Truck proxy could handle a request such as setProperty(“speed”, value) by calling myTruck.setSpeed (value). In this case, the TruckProxy knows the inner workings of the Truck class. It knows that speed is actually a floating point value. Many times the proxy will be a simple pass through for data. However, sometimes, the proxy will need to do manipulation of data. For instance, speed might have been represented by a vector of floats (xspeed, yspeed, and zspeed). In that case the proxy might have exposed 3 properties to the editor where there is only one underlying actual value. It might alternately have used a vec3. In either case, the proxy is responsible for knowing how to handle a setProperty(“xSpeed”, value) request and setting the internal speed value of the truck.

4. ActorProperty

As stated above, the ActorProperty class provides a getter/setter mechanism for accessing properties of a class similar to the Java beans programming paradigm. Figure 4 depicts a more detailed view of the ActorProperty class including a subset of the property classes for a particular data type.

Figure 4 - ActorProperty Class Diagram

The getter and setter portions of the ActorProperty class are Functors (Function Objects) which reference a getter and a setter method on a given property class. Therefore, when an ActorProperty is created, it knows how to store and retrieve the data it represents. The ActorProperty class is also used to pass information about the properties of an Actor up to the Editor. It has a name, a display name, a description, and a type enumeration. The property class may also have a list of enumerations if the property is itself an enumeration. For example, a property of truck may be speed and it may support Slow, Medium, and Fast or a light may have a type property with settings of Directional, Strobe, Pulse, Omni, etc…

5. ActorLibraries

Actor libraries are distributable components that serve to package groups of related actors and actor proxies. Actor libraries are dynamic libraries of C++ code that are loaded into the editor or other application. Figure 5 shows an overview class diagram of the Actor Library subsystem. A detailed description of each component is given below.

Figure 5 - Dynamic Actor Layer Components

LibraryManager
This class is the main class in the Library Manager. It has a list of the libraries that are registered with the Manager as well as a list of which Actor Types each of the libraries can create. It is also the main vehicle for creating a new Actor Proxy. The Manager uses the singleton pattern.

ActorPluginRegistry
This is the base class that developers extend to build their own registry. The most important behavior in the registry is the ability to take an Actor Type and create a new Actor via the Actor Proxy. A registry is responsible for knowing which Actor types it can build. Since the Editor doesn’t know anything about object classes, the registry is responsible for figuring it out. The registry base class also exposes an object factory which provides most, if not all, of the ActorPluginRegistry’s Actor Type to Actor mapping capabilities.

MyPluginRegistry
This is a 3rd party implementation of the Registry. The developer will need to create and track which Actor Types it understands as well as be able to take an Actor Type and create a new Actor Proxy. This is likely a very simple class which creates and registers its actor types with the factory so that they are available at run-time.

ActorType
This is a simple data class that has information describing a particular Actor type. There will be one Actor Type for each unique Actor class like ‘BouncyTruck’ or ‘AgressiveSoldier’. For each actor class, there must be an Actor Type with a name, a category, and a description. The category is of particular note because it is used to visually sort classes in the editor. It follows a hierarchical dot notation (ex. “Vehicles.Trucks.NeatTrucks”) used to group related classes in some of the UI panels. It can also be used to search for objects.

6. Project / Map

The project context is basically the “home” directory of your map. It is responsible for storing resources imported into the Editor; such as static meshes, particle systems, textures, and sounds. All of the imported actors in a map are stored and referenced relative to the project context of the map. The details of the Project and Map class interactions are beyond the scope of this tutorial; however Figure 6 shows a class diagram which depicts the basic interactions available to the Project and Map classes.