Add Event (addEvent)

Table of Contents

• Adding a New Event
  • Usage

The Add Event example demonstrates the following:

• How to add new system event to communicate between the sim and the network threads in a thread-safe manner.
• How to send a new interaction type from the sim engine.
• How to receive a new interaction type in the sim engine.

Adding a New Event

The VR-Forces simulation threads do not have direct access to the network. In order for a sim component to signal to the network thread that a system event has occurred, it must use the DtEventManager class to pass a subclass of DtEvent. Similarly, the same mechanism is used by the network threads to signal to the sim that a system event was received on the network. Each type of event has an event translator class that knows how to translate the DtEvent between the threads.

This example creates a template class that can be templated on any subclass of the VR-Link DtInteraction class to allow the sim to send and receive any interaction type that is not already supported. The example uses the Event Report interaction to demonstrate. It contains the following template classes.

• DtInteractionEvent - A template class based on an interaction and a unique event id. It stores the interaction to be passed between the network and simulation.
• DtVrlinkInteractionTranslator - A template class to handle passing the event between the sim and network threads and vice versa.

It also registers the following functions.

• receivedEventReport - Processes new Event Report interaction events by printing a message to the console.
• objectAddedCallback - Called for the first lifeform entity created on this sim engine. Registers the checkForKia function.
• checkForKia - Called after every tick to check if the first lifeform entity has been destroyed. If so, sends a new Event Report.

Usage

In the Launcher:

1. Set the addEvent plugin to load.
2. Start VR-Forces.
3. Start a second instance of the VR-Forces sim engine with a different application ID.

To view the new behavior:

1. Create a new scenario
2. Create a new lifeform entity
3. Select the entity and Set Destroyed
4. Look at the consoles of both sim enginges. They should both print the message "Received KIA event report for <object name>"

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

#include "vrfcgf/vrfPluginExtension.h"
#include "interactionEvent.h"
#include "interactionEventTranslator.h"
#include <vrfStateData/stateData.h>
#include <vrfobjparam/vrfParameterTypes.h>
#include <vrfcgf/cgf.h>
#include <vrfobjcore/localObjectManager.h>
#include <vrlinkNetworkInterface/simObjectNetInterfaceFactory.h>
#include <vrlinkNetworkInterface/vrlinkNetworkInterface.h>
#include <vrfMsgTransport/communicationManager.h>
#include <vrfMsgTransport/eventManager.h>
#include <vl/exerciseConn.h>
#include <vl/eventReportInteraction.h>
#include <vrfobjcore/localObject.h>

const unsigned EventReportEventId = makVrfEvents::DtEvent::UserEvent;
typedef DtInteractionEvent<DtEventReportInteraction, EventReportEventId> DtEventReportInteractionEvent;
typedef DtVrlinkInteractionTranslator<DtEventReportInteraction, EventReportEventId> DtEventReportInteractionTranslator;

DtUUID UuidOfObjectToMonitor = DtUUID::nullUUID();

// Declare our callback functions
void receivedEventReport(const makVrfEvents::DtEvent& event, DtCgf* cgf);
void objectAddedCallback(const DtLocalObject* simObject, void* usr);
void checkForKia(void* usr);


extern "C" {

   DT_VRF_DLL_PLUGIN void DtPluginInformation(DtVrfPluginInformation& info)
   {
      info.pluginName = "Add Event";
      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)
   {
      // Find the exercise connection from the communications manager's VR-Link communication interface
      makVrf::DtVrlinkNetworkInterface* vrlinkInterface = dynamic_cast<makVrf::DtVrlinkNetworkInterface*>(
         cgf->communicationManager()->networkManagerInterface(makVrf::DtVrlinkNetworkInterface::Type()));

      if (vrlinkInterface)
      {
         // Register a translator class that knows how to pass our interaction between the simulation
         // and network threads.
         vrlinkInterface->addEventTranslator(EventReportEventId, new DtEventReportInteractionTranslator);
      }

      return true;
   }

   DT_VRF_DLL_PLUGIN bool DtPostInitializeVrfPlugin(DtCgf* cgf)
   {
      // Add a callback for our first local object. We will monitor this object to discover when it has
      // been destroyed.
      cgf->localObjectManager()->addSimObjectAddedCallback(objectAddedCallback, cgf,
         DtEntityType(3, -1, -1, -1, -1, -1, -1));

      // Connect to the signal for the Event Report interaction event in order to receive any events
      // sent about other entities being KIA.
      cgf->eventManager()->signalForEvent(static_cast<makVrfEvents::DtEvent::EventType>(EventReportEventId)).connect(
         boost::bind(&receivedEventReport, boost::placeholders::_1, cgf));

      return true;
   }

   DT_VRF_DLL_PLUGIN void DtUnloadVrfPlugin(DtCgf* cgf)
   {
      makVrf::DtVrlinkNetworkInterface* vrlinkInterface = dynamic_cast<makVrf::DtVrlinkNetworkInterface*>(
         cgf->communicationManager()->networkManagerInterface(makVrf::DtVrlinkNetworkInterface::Type()));

      if (vrlinkInterface)
      {
         // Register a translator class that knows how to pass our interaction between the simulation
         // and network threads.
         vrlinkInterface->removeEventTranslator(EventReportEventId);
      }
   }
}

// Callback to process receipt of an Event Report. This callback is received from the event manager
// when an Event Report interaction is received in the network thread.
void receivedEventReport(const makVrfEvents::DtEvent& event, DtCgf* cgf)
{
   const DtEventReportInteractionEvent* eventReport =
      static_cast<const DtEventReportInteractionEvent*>(&event);

   // Is this a KIA event report?
   if (eventReport->interaction().eventType() == DtEventKilledInAction)
   {
      DtSimObjectReference obj = cgf->simObjectManager()->lookup(eventReport->senderId());
      if (obj)
      {
         DtWarn << "Received KIA event report for " << obj->objectName() << std::endl;
      }
      else
      {
         DtWarn << "Received KIA event report from an unknown entity" << std::endl;
      }
   }
}

// Callback to process the first local object to be added. Just saves the UUID of the object and
// registers a post-tick callback to check for when the object is destroyed.
void objectAddedCallback(const DtLocalObject* simObject, void* usr)
{
   DtCgf* cgf = static_cast<DtCgf*>(usr);

   UuidOfObjectToMonitor = simObject->uuid();

   cgf->localObjectManager()->removeSimObjectAddedCallback(objectAddedCallback, cgf);

   cgf->addPostTickCallback(checkForKia, cgf);
}

// This callback is called after every sim tick to check if the monitored entity is destroyed. If it
// is, then we send an Event Report interaction indicating the entity is KIA. This is done by posting
// an event to the event manager to tell the network thread to send the interaction.
void checkForKia(void* usr)
{
   DtCgf* cgf = static_cast<DtCgf*>(usr);

   DtSimObjectReference obj = cgf->simObjectManager()->lookup(UuidOfObjectToMonitor);
   if (obj->isValid() && obj->isDestroyed())
   {
      DtEventReportInteractionEvent event;
      event.setSenderId(obj->uuid());

      DtEventReportInteraction inter;
      inter.setEventType(DtEventKilledInAction);
      event.setInteraction(inter);

      cgf->eventManager()->addEvent(event);

      // This entity has already been destroyed, no need to monitor anymore
      cgf->removePostTickCallback(checkForKia, cgf);
   }
}