VR-Forces Simulation Object Editor Plug-In API

Table of Contents

• Overview
• Common Uses Cases
• Writing Plug-In For Component Customization
• Writing Plug-In For Parameter Customization

Overview

The Simulation Object Editor API is a programming interface for customizing the Simulation Object Editor(SOE).

VR-Forces provides a simulation API that allows developers to add functionality to the simulation engine, such as adding a new kind of sensor, or extending the parameters of a simulation object. The SOE complements the simulation API, enabling developers to customize it so that end-users can configure their custom extensions to the simulation engine using the SOE. This enables new parameters and descriptors to be saved as part of simulation model set. The top class that encompasses the Simulation Object Editor is DtSimulationObjectEditorApplication. It has a DtSimulationObjectEditorWindow that shows the current lists of objects/systems/munitions depending on which tab is selected. This class has

• DtDisplayWidget to allow for editing 2D/3D aspects of selected object
• DtBehaviorCanvas for editing systems or object parameters. It uses its DtBehaviorUi to create the desired configurable elements derived from DtUiElement

DtUiElement

This is the base class for all the parameter/system parameter entry classes. A derived DtUiElement will have various controls allowing the user to input values for the parameters. Derived classes will register their creator function with the DtUiElement::UiElementFactoryMap.

Common Uses Cases

The most common situations in which VR-Forces customers decide they need to develop a Simulation Object Editor plug-in are:

• Configuring new kinds of components: The developer extends a simulation object with a new capability, for example, a new kind of sensor. This new component requires some parameters for configuration. The developer would like end-users to be able to configure the new sensor parameters using the SOE.
• Extending object parameters: The developer extends a simulation object with new object parameter data, for example, color. The developer would like end-users to be able to configure the simulation object with this new parameter using the SOE.

Writing Plug-In For Component Customization

To expose new component parameters to the end-users in the SOE, one needs to add in a hook to the new component's DtComponentDescriptor, adding it to the appropriate component list(sensor/controller/actuator). This is achieved using DtSimulationObjectEditorApplication parent class DtParameterAlteringApplication:

DtParameterAlteringApplication::app(*de)->addSensor("simple-radar-warning-receiver", DtRadarWarningReceiverDescriptorType, DtRadarWarningReceiverDescriptor::creator);

This regiesters the new type of component descriptor. For components that use an existing descriptor, those components still need to be registered with the SOE but use the existing component descriptor type. Once registered any parameter in the component descriptor that has been set up as a variable binding in the system definition file will show up in the SOE. See the Radar Warning (radarWarnRx) example which creates a new component descriptor and adds a variable binding to the new parameter that can be edited in the SOE.

Writing Plug-In For Parameter Customization

When an object is selected in the SOE, the DtBehaviorUi looks at the ui-filename in the selected object's .ope file to determine what uiElements to create. There are multiple ways to add new parameters to the SOE for user customization:

• Adding simple elements directly into the ui file that the base class UiElementForParams knows how to parse like adding an interger or double parameter. This can happen in 2 ways:
  • When there is already an existing parameter in the derived DtVrfObjectParameter class, the DtUiForParameter class will match up the name in the parameter ui file with name of parameter in the .ope file.
  • If this is a new parameter being added to the object parameter class then a derived parameter class will need to be made to accommodatethe new parameter. The exception to this being if the new parameter is added as state-data in the ope file. See the Custom Control Object example to see how to add new state data parameters to allow user to configure them in the SOE.
• For more complex parameter data structures, a new derive DtUiElement will need to be made that adds the new data structue to the ui element and hook into a derived object parameter class. Below are the steps for this:
  • Create a new derived object parameter class from DtVrfObjectParameter or one of it's derived verions. This will hole the new parameters.
  • Create a new widget for the data structure holding the new parameters. For example look at the DtMinefieldCompositionWidget. It holds a list of a mine types, their characteristics, and the density of that type in the minefield.
  • Open the ui-filename defined in the .ope file in QT's designer.exe to add in a place holder empty widget for your new widget. Name the empty widget object "gui_your_widget" Recommended to also add in a label widget to help with arrangment of the new widget. Look at the Minefield_Area.ope and it's ui-filename "minefield-object-param.ui" in the EntityLevel/gui/ui folder.
  • Create a new derived DtUiElement class to contain your new widget and correctly set the values in your derived object parameter class and also to be able to read in from your derived parameter class to know how to set the values in the Ui element's new widget. Look at DtUiMinefieldTableElement
  • Register the new Ui Element class in the plugin using the "gui_your_widget" name you gave to the place holder widget in the parameter ui.ui file. The derived ui element's creator function will be registered with the DtUiElement::UiElementFactoryMap like

    theFactory["gui_minefield_table"] = &DtUiMinefieldTableElement::CreatorFunction;