Adding a New Entity Behavior (Creating an Actuator)

This example changes the movement behavior of a ground vehicle by replacing the stock DtAutomotiveActuator with a derived version. In the derived actuator, we do the following:

Initialize the actuator
Identify the type of component
Create input ports to receive input from controllers
Do what the actuator is intended to do. The Add Actuator example creates an actuator that simulates a vehicle that travels due north regardless of steering inputs, but at a speed regulated by the throttle input. It replaces the DtAutomotiveActuatorComponent.
Add the actuator the the component factory

Initializing an Actuator

You can override init() to perform any initialization of your model. All components have an init() function that gets invoked whenever an entity that uses your actuator is instantiated. In the addActuator example, there is no change in initialization requirements in our example derived class as compared to its parent, so the derived init() function simply calls the parent class's init() method from DtAutomotiveActuatorComponent.

Identifying the Component Type

The type() function returns the string by which the actuator is identified in the object parameter database - in this case the global DtAutomotiveActuatorType, set to "automotive-actuator". Since we are replacing DtAutomotiveActuatorComponent with the new component, we return the type string normally returned by DtAutomotiveActuatorComponent. Every place in the object parameter database that the DtAutomotiveActuator is called for (with the string "automotive-actuator"), the new actuator will be used instead.

If you create a completely new actuator, you must give it a name, then modify the appropriate reference in the object parameter database to reference that name. For instance, if your actuator's type() returned "new actuator" then you would want the appropriate section in the entity's OPE file to read:

(actuators
  (MyNewActuator
    (component-descriptor-type "automotive-component-descriptor")
    (component-type "new-actuator")
  )
)
...

Ticking the Actuator

The most important function that you need to override in your derived actuator is tick(). This is where the real work of the actuator gets done. The job of tick() is tocompute the state of the vehicle for the current frame, based on:

The last frame's state
Controller inputs (throttle position, steering wheel position, and so on)
Frame length
Perhaps, information about terrain.

The VR-Forces simulation engine calls tick() each frame or, optionally, at some interval specified by the user.

In the following code, note how the actuator gets information from the state repository and the port input group and how it then calculates and sets new values. (Some of the comments have been deleted. Please see ./examples/addActuator/myActuator.cxx for the complete code.)

Adding the Actuator Component to the Component Factory

To use the addActuator class, you must add it to the Component Factory. To add a new component to the Component Factory, call the addCreatorFcn() method in the DtInitializeVrfPlugin function, defined in plugin.cxx.

This example is loaded as a VR-Forces back-end plugin. It can be used in conjunction with the released VR-Forces application.

How to Run the Example

Since this example is loaded as a plugin, it can be used in conjunctionwith the released VR-Forces application

Usage

Select Settings, Plugins... and on the Plugins Editor page, use the combobox at the top of the page to select the plug-in. Then enable the LoadPlugin checkbox and re-start VR-Forces.

To view the new behavior:

Create a new scenario on the terrain of your choice.
Create a new M1A2 entity.
Task the M1A2 to move to some arbitrary location.
Click on the play button.

The M1A2 will move north, regardless of where you have tasked the entity to move.

Classes

MyActuatorComponent

Add Actuator Component, which is derived from DtAutomotiveActuatorComponent, modifies movement behavior to travel due north.

Plugin Entry Points

/*******************************************************************************
** Copyright (c) 2003 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/
/*******************************************************************************
** $RCSfile: plugin.cxx,v $ $Revision: 1.4 $ $State: Exp $
*******************************************************************************/

#include "vrfcgf/vrfPluginExtension.h"
#include "myActuator.h"

#include <vrfcgf/cgf.h>
#include <vrfcgf/factoryMgr.h>
#include <vrfobjcore/compTypes.h>

extern "C" {

   DT_VRF_DLL_PLUGIN void DtPluginInformation(DtVrfPluginInformation& info)
   {
      info.pluginName = "Add Actuator";
      info.pluginVersion = "1.00";
      info.pluginCreator = "MAK Technologies";
      info.pluginCreatorEmail = "sales@mak.com";
      info.pluginContactWebPage = "www.mak.com";
      info.pluginContactMailingAddress = "150 Cambridge Park Drive 3rd Floor - Cambridge, MA 02140 USA";
      info.pluginContactPhone = "(617) 876 8085";
   }

   DT_VRF_DLL_PLUGIN bool DtInitializeVrfPlugin(DtCgf* cgf)
   {
      //Register the creation function for our derived actuator with the
      //DtSimComponentFactory. Because we're registering it with the existing 
      //type of DtAutomativeActuatorType, our derived actuator will replace all
      //instances of the DtAutomotiveActuator class.
      cgf->factoryManager()->componentFactory()->addCreatorFcn(
         DtAutomotiveActuatorType, MyActuatorComponent::creator);
      
      return true;
   }
}

Table of Contents