Add State Property (addStatePropertySim)

Table of Contents

• How to Run the Example
  • Usage
  • Plugin Code

The Add State Property example demonstrates the following:

• How to add custom state properties to entities that can be used locally and published to the network
• How to add a callback function for the receipt of a interaction message
• How to write a front-end example that works in conjunction with a back-end example

The Add State Property example shows how to add new state properties to entities and how to update them in your code and Lua scripts. To add a new state property, you must first define it in the OPE file used by your entity. This example uses an example SMS called addStateProperty which can be found in data. This SMS includes a new OPE file called HumanWithAccuracyStats.ope. At the bottom of the file is defined the following:

(state-data
   (DtRwInt TargetsMissed 0 publish)
   (DtRwInt TargetsHit 0 publish)
)

The state-data section defines the state properties which will be added to entities of this type. You can also add a parameter-data section to define parameter properties. The only difference between state and parameter properties is that parameter properties have static values whereas the values of state properties can change dynamically at run time.

There are four parts to the state property definitions.

• The first part is the data type, which must be one of the standard VR-Forces ReaderWriter types. In this example, both properties have a type of DtRwInt.
• The second part is the name of the property.
• The third part is the default value. This could also be a variable reference by using the $ as is done elsewhere in the OPE file.
• The fourth part is optional and indicates if this is a property that should be published. If absent, the property will not be published.

To publish a property in DIS, you must be using the IEEE 1278.1-2012 version of the standard (DIS 7). State properties will be published as special Attribute records attached to the entity.

To publish a property in HLA, there must also be an object class attribute with the same name defined in your FOM. If the attribute is added in a custom subclass, you must also specify this using the hla-fom-class setting in the OPE. This example adds a new subclass called HumanWithAccuracyStats. Please see one of the included VrfStateProperty FDD files for an example of how these attributes are added.

(hla-fom-class "BaseEntity.PhysicalEntity.Lifeform.Human.HumanWithAccuracyStats")

The data type can be anything from a simple integer to a list of complex structures. Below is a list of acceptable data types. For further examples of how to define complex data types, refer to the Aggregate.ope file in the AggregateLevel SMS.

Data Type	Description	HLA Representation/Encoding
DtRwInt	A 32 bit integer	RPRunsignedInteger32BE, HLAinteger32BE
DtRwReal	A 64 bit float	HLAfloat64BE
DtRwBoolean	A Boolean	RPRboolean
DtRwString	An ASCII string	RPRnullTerminatedArray of HLAASCIIchar
DtRwStructure	A fixed structure with multiple named fields	HLAfixedRecord with matching fields
DtRwList	A variable sized list of items	HLAvariableArray
DtRwMap	A variable sized map of items	HLAvariableArray of HLAfixedRecords, where the first field is the key

The plugin code just consists of a single callback that listens for detonation interactions. When a detonation is received, if the shooter is local, the result of the detonation is checked and the TargetsHit or TargetsMissed property is updated accordingly.

The example scenario also includes a Lua scripted set called Clear Accuracy Stats that sets each of these properties back to 0.

How to Run the Example

1. Copy VrfStateProperty.fed, VrfStateProperty.xml, and VrfStateProperty_evolved.xml from examples to the bin64 directory.
2. Since this example is loaded as a plugin, it can be used in conjunction with the released VR-Forces application

Usage

In the Launcher:

1. Set the addStateProperty plugin to load
2. Set Federation Name to "VrfStateProperty"
3. Set the FED File Name to VrfStateProperty.fed if using HLA 1.3, VrfStateProperty.xml if using HLA 1516-2000, or VrfStateProperty_evolved.xml if using HLA Evolved. If using DIS, you must use DIS 7.
4. Set the RPR FOM version to 2.0
5. Start VR-Forces

To view the new behavior:

1. Load the addStateProperty developer toolkit example scenario
2. Right-click on entity R1 and select Information... to open its information window.
3. Find the Hits and Misses entries on the State Data page.
4. Play the scenario. As the entity shoots at the opposing entities, watch Hits and Misses increase depending on the result of the shot taken.
5. Right-click on entity R1, go to the Set menu, and choose Clear Accuracy Stats. The Hits and Misses counts should return to 0.

Plugin Code

/*******************************************************************************
** Copyright (c) 2017 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/

// VR-Forces includes
#include <vrfcgf/vrfPluginExtension.h>
#include <vrfcgf/cgf.h>
#include <vrfobjcore/vrfObject.h>
#include <vrfobjcore/vrfObjectManager.h>
#include <vrfobjcore/vrfObjectStateRepository.h>
#include <vrfutil/propertyUtils.h>

// VR-Link includes
#include <vl/exerciseConn.h>
#include <vl/detonationInteraction.h>

// Updates the state properties based on the results of the detonation
void updateAccuracyStats(DtDetonationInteraction *inter, void *usr)
{
   if (usr)
   {
      DtCgf* cgf = static_cast<DtCgf*>(usr);
      DtVrfObjectManager* objMgr = cgf->vrfObjectManager();
      
      // Find the shooter and target objects
      DtSharedVrfObjectReference shooter = objMgr->lookupVrfObjectByGlobalId(inter->attackerId());
      DtSharedVrfObjectReference target = objMgr->lookupVrfObjectByGlobalId(inter->targetId());

      // If shooter is local, update its stats
      if (shooter.isValid() && shooter->isLocal())
      {
         DtRwInt* missProperty = findProperty<DtRwInt>(shooter->vrfState()->stateProperties(), "TargetsMissed");
         DtRwInt* hitProperty = findProperty<DtRwInt>(shooter->vrfState()->stateProperties(), "TargetsHit");

         // Check that this entity has these state properties
         if (missProperty && hitProperty)
         {
            // Check if this is a hit - it has a valid target and is an entity impact
            if (target.isValid() && inter->result() == DtDetResEntityImpact)
            {
               hitProperty->setValue(hitProperty->value() + 1);
            }
            else
            {
               missProperty->setValue(missProperty->value() + 1);
            }
         }
      }
   }
}

extern "C" {

   DT_VRF_DLL_PLUGIN void DtPluginInformation(DtVrfPluginInformation& info)
   {
      info.pluginName = "Add State Property Sim";
      info.pluginDescription = "This is an example of how to add an attribute to an entity as a state property and publish that attribute to the network.";
      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)
   {
      DtDetonationInteraction::addCallback(cgf->exerciseConn(), updateAccuracyStats, cgf);

      return true;
   }
}