Add State Property (addStatePropertySim)

Table of Contents

• Adding New State Properties
• 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

Adding New State Properties

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 the included VrfStateProperty_evolved.xml FOM module for an example of how these attributes are added.

(hla-fom-class "BaseEntity.PhysicalEntity.Lifeform.Human.NETN_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_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. In the Launcher, click the Plug-ins button to bring up the Plug-ins Selection dialog. Enable the plugin.
2. Set Federation Name to "VrfStateProperty"
3. If using HLA, add the FOM module VrfStateProperty_evolved.xml.
4. Set the RPR FOM version to 2.0
5. Start VR-Forces

To view the new behavior:

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

  After the example run is completed - remove the previously copied FOM module (e.g. VrfStateProperty_evolved.xml) from the bin64 directory.
  Restore the previously set FED File Name within the Launcher dialog.

Plugin Code

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

// VR-Forces includes
#include <vrfcgf/vrfPluginExtension.h>
#include <vrfcgf/cgf.h>
#include <vrfMsgTransport/eventManager.h>
#include <vrfMsgTransport/detonationEvent.h>
#include <vrfMsgTransport/setEvent.h>
#include <vrfcore/simulationServices.h>
#include <vrfobjcore/localObject.h>
#include <vrfobjcore/localObjectManager.h>
#include <vrfobjcore/simObjectManager.h>
#include <vrfobjcore/vrfSimulatedSimObjectFacade.h>
#include <readerWriter/propertyUtils.h>
#include <vrftasks/setStateProperties.h>
#include <vrfmsgs/setDataRequestMessage.h>

#include <atomic>

// Since this is now done in a thread and there is no direct access in the thread to be able to write to the state properties
// from a non ownship object, keep a count of hits/misses this frame and update them on a post tick

void updateAccuracyStats(const makVrfEvents::DtEvent& evt, DtCgf* cgf)
{
   const makVrfEvents::DtDetonationEvent* inter = dynamic_cast<const makVrfEvents::DtDetonationEvent*>(&evt);
   DtLocalObjectManager* localObjMgr = cgf->localObjectManager();
   const DtSimObjectManager* simObjMgr = cgf->simulationServices()->simObjectManager();
      
   // Find the shooter and target objects
   DtLocalObject* shooter = localObjMgr->lookup(inter->attackerId());
   DtSimObjectReference target = simObjMgr->lookup(inter->targetId());

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

      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 = "10 Fawcett Street, Suite 204, Cambridge, MA 02138 USA";
      info.pluginContactPhone = "(617) 876 8085";
   }

   DT_VRF_DLL_PLUGIN bool DtPostInitializeVrfPlugin(DtCgf* cgf)
   {
      // Events are handled serially before object ticks, so, using the local object manager and local objects will not break thread safety
      cgf->eventManager()->signalForDetonationEvent().connect(boost::bind(&updateAccuracyStats, boost::placeholders::_1, cgf));

      return true;
   }
}