Creating an Actor Tutorial, Part 3 - Loading Your Library

Now that we have our actor proxy, and actor set up, it’s time to create a library that we can import into the editor. This is the simplest process of them all, and only requires a couple of steps to accomplish. First, we have to code and compile the library. The next step is to run the editor. The final step is to use the Library Editor to import the library. That’s it!

To begin, please start by creating a new Visual Studio project that will export our actor library. To set up a Visual Studio project that will compile Delta3D, please see this tutorial . After completing that, we must now set the option in Visual Studio to tell it to compile the code into a dynamic library. Right click on the project you created and select the “Properties” tab. Under the “General” tab, select the “Configuration Type” item from the menu. Change it from “Application (.exe)” to “Dynamic Library (.dll)”.

Now that we are configured correctly, it’s time to look at some code! Let’s start by making a file called TessellationActorLib.h, and placing the following code inside:

#include <dtDAL/plugin_export.h>
#include <dtDAL/actorpluginregistry.h>

class DT_PLUGIN_EXPORT TessellationActorLib : 
   public dtDAL::ActorPluginRegistry

   void RegisterActorTypes();

First, we include the file “dtDAL/actorpluginregistry.h” so we can derive our class from it. It is worth noting that since we are going to be exporting this library, we declare DT_PLUGIN_EXPORT before the name of the class. After that, we declare the constructor, and the function RegisterActorTypes. The RegisterActorTypes function is where we will register the tessellation actor with the actor factory for instancing in the editor. Note that you can have as many actors in one library as you want. This actor library is named simply for our tutorial, but for your use, it is better to name a library something like 'MyProjectActorsLib'. Now it’s time to create a file called “TessellationActorLib.cpp” and place the following code inside:

#include "TessellationActorLib.h"
#include "TessellationActorProxy.h"

extern "C" DT_PLUGIN_EXPORT dtDAL::ActorPluginRegistry* CreatePluginRegistry()
   return new TessellationActorLib;

extern "C" DT_PLUGIN_EXPORT void DestroyPluginRegistry(dtDAL::ActorPluginRegistry *registry)
      delete registry;

TessellationActorLib::TessellationActorLib() : dtDAL::ActorPluginRegistry("Tessellation Actor Library")
   mDescription = "This library exports the tessellation actor";

void TessellationActorLib::RegisterActorTypes()
   dtDAL::ActorType *tessActor = new dtDAL::ActorType("Tesselation", "Awesome Actors", 
      "This actor represents a tesselating plane.");
   mActorFactory->RegisterType<TessellationActorProxy> (tessActor);

There is a very important issue to note here. When the editor is importing a library, it parses the library for two separate functions to ensure its validity. These functions are CreatePluginRegistry, and DestroyPluginRegistry. Due to C++ name mangling, these functions have to be declared with C linkage in order for the editor to be able to parse them correctly. Next, we set the description of the library in the constructor and pass the name of the library to the parent constructor. In the RegisterActorTypes function, we create a new actor type to represent our tessellation actor. We pass the constructor 3 parameters, which are the name, category, and description of the actor. Finally, we register the type with the actor factory by passing the class name of the proxy, and a pointer to the actor type. That’s it! Compile your code into a dynamic library and you will have successfully created an actor library. Now there is something to note about this. When you go to import a library into the editor, the library needs to be stored in a directory that is in your computer’s PATH environment variable. If you do not know what directories are in your PATH environment variable, you can find out by opening up a console window and echoing PATH. If you ever get the error “Failed to load the library:xxx”, this is probably the reason. That stated, it’s time to import our new library into the editor.

To begin, run the editor, select your project context and create a map. For more information of creating maps and selecting project contexts, please see the ‘Getting to Know the Editor’ tutorial. Navigate to the Edit menu and select Map Libraries. This will execute the Library Editor.

The Library Editor is where you can import or remove dynamic libraries from your map. Click the Import Library button. This will execute a file browser. Navigate to the directory where you saved the TesselationActorLibrary and double click it. Presto! Now the tessellation actor can be instanced in the editor.

Note - if you have trouble loading your library or it crashes during runtime, make sure that you have compiled your library in the same state as the editor (runtime for runtime and debug for debug). There are known issues when you try to load a dynamic library in conflicting states.

Now, create a tessellation actor just to test it out. You should see something like this:

This concludes the Creating an Actor series of tutorials. After you load this map into a Delta3D application, you should see the tessellation actor moving. Here are some screen shots:

If you have problems loading a map into a scene, please take a look at this tutorial .


Trackback URL for this entry:

No trackback comments for this entry.

About delta3d

delta3d is a game and simulation engine appropriate for a wide variety of simulation and entertainment applications. delta3d uses best-of-breed open source technologies to create a fully integrated game engine and with content creation tools.MORE


User Functions

Don't have an account yet? Sign up as a New User!

Lost your password?