Modify Sim Component (modifySimComponent)

Table of Contents

• Adding a New Entity Behavior (Creating an Actuator)
• Initializing an Actuator
• Identifying the Component Type
• Ticking the Actuator
• Adding the Actuator Component to the Component Factory
• How to Run the Example
  • Usage
• Classes
• Plugin Entry Points

The Modify Sim Component example demonstrates the following:

• How to modify the behavior of an entity
  • Override an existing actuator
  • Access entity state repositories
  • Access a component's port data

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. Note that this affects all non-road movement. Road movement uses a different actuator, so is not changed by this example.
• 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 modifySimComponent 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/modifySimComponent/myActuator.cxx for the complete code.)

Adding the Actuator Component to the Component Factory

To use the modifySiComponent 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 conjunction with the released VR-Forces application

Usage

In the Launcher, click the Plug-ins button to bring up the Plug-ins Selection dialog. Enable the modifySimComponent plugin.

To view the new behavior:

1. Start VR-Forces GUI and SIM.
2. Create a new scenario - e.g. EntityLevel SMS on Ground_DB II terrain.
3. Create a new M1A2 entity.
4. Task the M1A2 to Move to Location... Select some arbitrary location.
5. Click on the play scenario button.
6. 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) 2019 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/

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

#include <vrfcgf/cgf.h>
#include <vrfcgf/factoryManager.h>
#include <vrfobjcore/simComponentTypes.h>

extern "C" {

   DT_VRF_DLL_PLUGIN void DtPluginInformation(DtVrfPluginInformation& info)
   {
      info.pluginName = "Modify Sim Component";
      info.pluginVersion = "1.00";
      info.pluginCreator = "MAK Technologies";
      info.pluginCreatorEmail = "sales@mak.com";
      info.pluginContactWebPage = "www.mak.com";
      info.pluginContactMailingAddress = "10 Fawcett Street, Suite 204, Cambridge, MA 02138 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;
   }
}