Programming
C++
C++ Plugins
HLA Support via HLAClient Plugin
Implementing HLA Client Logic for a Custom Project

Implementing HLA Client Logic for a Custom Project

Programming the HLA basically comes down to invoking services and receiving callbacks as defined by the HLA Interface Specification. The invocable services are provide by a software package known as the Runtime Infrastructure (RTI). One of the services (Join Federation Execution) is provided with a reference to an object that implements the callbacks defined in the Interface Specification. It is the responsibility of the federate developer to provide these callback implementations.

A general description of a federate implementation is as follows:

Initialize the Federate and join a Federation. These actions are performed when calling the init() method.
Obtain handles to Object / Interaction Classes.
Publish and/or Subscribe to Objects / Interactions.
Register callbacks coming from the RTI to the Federate Ambassador via the addCallback() method.
Periodically send something to the RTI Ambassador via the sendInteraction(), updateAttributeValues(), and other methods.
Clean up and quit

C++ Implementation

To enable the HLAClient in your application, follow the instructions below.

Initializing HLA Client

First of all, you should initialize HLAClient. To do so you can simply add the following code to the AppWorldLogic class.

In the AppWorldLogic.h file include HLAClientInterface.h library and declare a HLAClient manager interface pointer in the private section of the AppWorldLogic

Source code (C++)

// AppWorldLogic.h
#ifndef __APP_WORLD_LOGIC_H__
#define __APP_WORLD_LOGIC_H__

#include <UnigineLogic.h>
#include <UnigineStreams.h>
#include <UnigineConsole.h>
#include <UnigineEngine.h>

// including the HLAClient interface library
#include "plugins/HLAClientInterface.h"

using namespace Unigine;
using namespace Math;

class AppWorldLogic : public Unigine::WorldLogic {
	
public:
	AppWorldLogic();
	virtual ~AppWorldLogic();
	
/* .. */

private:
	// declaring a HLAClient manager interface pointer
	HLA::HLAClientInterface *hla;
	
	// declaring a ID's to store handles to be used
	unsigned long message_id, participant_id, parameter_id_text, parameter_id_sender;
	
	//  declaring auxiliary variables
	unsigned long attribute_id_name;
	String username;
	
	// function to be used to send messages
	void send_callback(int argc, char **argv);
};

#endif // __APP_WORLD_LOGIC_H__

Insert the following HLAClient initialization code into the AppWorldLogic::init() method:

Source code (C++)

// AppWorldLogic.cpp

int AppWorldLogic::init()
{
	// adding a custom console command "send" to send messages to other HLA clients
	Console::get()->addCommand("send", "", MakeCallback(this, &AppWorldLogic::send_callback));

	hla = (HLA::HLAClientInterface*)Engine::get()->getPluginData(Engine::get()->findPlugin("HLAClient"));
	
	time_t t = time(NULL);
	struct tm *tm = localtime(&t);
	
	// initializing HLA client with RTI version 1.3, using the "Chat.fed" FOM file
	hla->init(HLA::HLAClientInterface::RTI13, "Chat.fed", String::format("Chat%d%d", tm->tm_min, tm->tm_sec).get(), "ChatRoom");
	
	//getting a handle for the InteractionRoot.Communication class
	message_id = hla->getInteractionClassHandle("InteractionRoot.Communication");
	
	// getting 2 parameter handles for the message_id class: sender name and message text
	parameter_id_text = hla->getParameterHandle("Message", message_id);
	parameter_id_sender = hla->getParameterHandle("Sender", message_id);
	
	// reporting that our federate publishes and subscribes to the message_id interaction class
	hla->publishAndSubscribeInteraction(message_id);

	// getting a handle for the chat member (ObjectRoot.Participant)
	participant_id = hla->getObjectClassHandle("ObjectRoot.Participant");
	//
	attribute_id_name = hla->getAttributeHandle("Name", participant_id);
	Vector <unsigned long> attr;
	attr.append(attribute_id_name);
	
	hla->publishAndSubscribeObject(participant_id, attr);
	
	// creating a unique username
	username = String::format("User%d%d", tm->tm_min, tm->tm_sec);
	
	// and registering a new chat member
	hla->registerObjectInstance(participant_id, username);
	
	/* .. */
	
	return 1;
}



int AppWorldLogic::shutdown()
{
	// removing the custom console command "send"
	Console::get()->removeCommand("send");
	return 1;
}

Adding Callbacks for HLA Events

The following types of HLA events are supported.

Discover Object Instance
Reflect Attribute Values
Receive Interaction
Remove Object Instance

Callback functions are used to enable an HLA client to respond to these events.

To add a callback for a specific type of HLA events you should add callback functions to the private section of the AppWorldLogic class in the AppWorldLogic.h file:

Source code (C++)

// AppWorldLogic.h

/* .. */

class AppWorldLogic : public Unigine::WorldLogic 
{
/* .. */

private:
	// callback functions to handle HLA events
	void on_discovered_objects(const HLA::DiscoverObjectInstance *message);
	void on_reflected_attributes(const HLA::ReflectAttributeValues *message);
	void on_received_interactions(const HLA::ReceiveInteraction *message);
	void on_removed_interactions(const HLA::RemoveObjectInstance *message);
};

/* .. */

So, implement your callback functions in the AppWorldLogic.cpp file and register them in the AppWorldLogic::init() method:

Source code (C++)

/* .. */


// AppWorldLogic.cpp

/* .. */

/// function to be called when a federate registers an object belonging to an object class for which our federate is subscribed 
void AppWorldLogic::on_discovered_objects(const HLA::DiscoverObjectInstance *message)
{
	Log::message("Object %s was created (id: %d, class: %d)\n", message->object_name.get(),
		message->object, message->object_class);
}

/// function to be called when an attribute is updated by the owner federate
void AppWorldLogic::on_reflected_attributes(const HLA::ReflectAttributeValues *message)
{
	Log::message("Received attributes for object: %d\n", message->object);
	for (auto i = message->attributes.begin(); i != message->attributes.end(); i++)
	{
		Log::message("-- TYPE: %d, VALUE: %s\n", i->key, i->data.get());
	}
}

/// function to be called when an an interaction arrives
void AppWorldLogic::on_received_interactions(const HLA::ReceiveInteraction *message)
{
	if (message->interaction == message_id)
	{
		Log::message("%s: %s\n", 
			message->parameters.find(parameter_id_sender)->data.get(),
			message->parameters.find(parameter_id_text)->data.get());
	}
}

/// function to be called when an object belonging to an object class for which our federate is subscribed is removed
void AppWorldLogic::on_removed_interactions(const HLA::RemoveObjectInstance *message)
{
	Log::message("Object %d was removed\n", message->object);
}

/// function to be used to send messages to other clients
void AppWorldLogic::send_callback(int argc, char **argv)
{
	if (argc == 1)
		return;

	Map<unsigned long, String> p;
	//setting message parameters
	p.append(parameter_id_sender, username);
	p.append(parameter_id_text, argv[1]);
	
	// sending an interaction
	hla->sendInteraction(message_id, p);
}

/* .. */

/* .. */

int AppWorldLogic::init() 
{
	/* ... */

	// adding HLA callback functions
	hla->addCallback(HLA::CALLBACK_DISCOVER_OBJECT_INSTANCE, MakeCallback(this, &AppWorldLogic::on_discovered_objects));
	hla->addCallback(HLA::CALLBACK_REFLECT_ATTRIBUTE_VALUES, MakeCallback(this, &AppWorldLogic::on_reflected_attributes));
	hla->addCallback(HLA::CALLBACK_RECEIVE_INTERACTION, MakeCallback(this, &AppWorldLogic::on_received_interactions));
	hla->addCallback(HLA::CALLBACK_REMOVE_OBJECT_INSTANCE, MakeCallback(this, &AppWorldLogic::on_removed_interactions));

	return 1;
}

Defining a Federation Object Model

Federations must have an HLA federation object model (FOM). It is represented in a *.fed file, with the following structure (example):

Notice

*.fed files should be stored in your project's data folder

FED file example

Source code (XML)

//chat.fed
(FED
  (Federation FederationName)
  (FEDversion v1.3)
  (spaces)
  (objects
    (class ObjectRoot
      (attribute privilegeToDeleteObject reliable receive)
      (class RTIprivate)
      (class Participant
         (attribute Name reliable receive))
      (class Manager
         (class Federation
           (attribute FederationName reliable receive)
           (attribute FederatesInFederation reliable receive)
           (attribute RTIversion reliable receive)
           (attribute FEDid reliable receive)
           (attribute LastSaveName reliable receive)
           (attribute LastSaveTime reliable receive)
           (attribute NextSaveName reliable receive)
           (attribute NextSaveTime reliable receive))
         (class Federate
           (attribute FederateHandle reliable receive)
           (attribute FederateType reliable receive)
           (attribute FederateHost reliable receive)
           (attribute RTIversion reliable receive)
           (attribute FEDid reliable receive)
           (attribute TimeConstrained reliable receive)
           (attribute TimeRegulating reliable receive)
           (attribute AsynchronousDelivery reliable receive)
           (attribute FederateState reliable receive)
           (attribute TimeManagerState reliable receive)
           (attribute FederateTime reliable receive)
           (attribute Lookahead reliable receive)
           (attribute LBTS reliable receive)
           (attribute MinNextEventTime reliable receive)
           (attribute ROlength reliable receive)
           (attribute TSOlength reliable receive)
           (attribute ReflectionsReceived reliable receive)
           (attribute UpdatesSent reliable receive)
           (attribute InteractionsReceived reliable receive)
           (attribute InteractionsSent reliable receive)
           (attribute ObjectsOwned reliable receive)
           (attribute ObjectsUpdated reliable receive)
           (attribute ObjectsReflected reliable receive)))))
  (interactions
    (class InteractionRoot reliable receive
      (class RTIprivate reliable receive)
      (class Communication reliable receive 
        (parameter Message)
        (parameter Sender))
      (class Manager reliable receive
         (class Federate reliable receive
             (parameter Federate)
             (class Request reliable receive
               (class RequestPublications reliable receive)
               (class RequestSubscriptions reliable receive)
               (class RequestObjectsOwned reliable receive)
               (class RequestObjectsUpdated reliable receive)
               (class RequestObjectsReflected reliable receive)
               (class RequestUpdatesSent reliable receive)
               (class RequestInteractionsSent reliable receive)
               (class RequestReflectionsReceived reliable receive)
               (class RequestInteractionsReceived reliable receive)
               (class RequestObjectInformation reliable receive
                 (parameter ObjectInstance)))
             (class Report reliable receive
               (class ReportObjectPublication reliable receive
                 (parameter NumberOfClasses)
                 (parameter ObjectClass)
                 (parameter AttributeList))
               (class ReportObjectSubscription reliable receive
                 (parameter NumberOfClasses)
                 (parameter ObjectClass)
                 (parameter Active)
                 (parameter AttributeList))
               (class ReportInteractionPublication reliable receive
                 (parameter InteractionClassList))
               (class ReportInteractionSubscription reliable receive
                 (parameter InteractionClassList))
               (class ReportObjectsOwned reliable receive
                 (parameter ObjectCounts))
               (class ReportObjectsUpdated reliable receive
                 (parameter ObjectCounts))
               (class ReportObjectsReflected reliable receive
                 (parameter ObjectCounts))
               (class ReportUpdatesSent reliable receive
                 (parameter TransportationType)
                 (parameter UpdateCounts))
               (class ReportReflectionsReceived reliable receive
                 (parameter TransportationType)
                 (parameter ReflectCounts))
               (class ReportInteractionsSent reliable receive
                 (parameter TransportationType)
                 (parameter InteractionCounts))
               (class ReportInteractionsReceived reliable receive
                 (parameter TransportationType)
                 (parameter InteractionCounts))
               (class ReportObjectInformation reliable receive
                 (parameter ObjectInstance)
                 (parameter OwnedAttributeList)
                 (parameter RegisteredClass)
                 (parameter KnownClass))
               (class Alert reliable receive
                 (parameter AlertSeverity)
                 (parameter AlertDescription)
                 (parameter AlertID))
               (class ReportServiceInvocation reliable receive
                 (parameter Service)
                 (parameter Initiator)
                 (parameter SuccessIndicator)
                 (parameter SuppliedArgument1)
                 (parameter SuppliedArgument2)
                 (parameter SuppliedArgument3)
                 (parameter SuppliedArgument4)
                 (parameter SuppliedArgument5)
                 (parameter ReturnedArgument)
                 (parameter ExceptionDescription)
                 (parameter ExceptionID)))
             (class Adjust reliable receive
               (class SetTiming reliable receive
                 (parameter ReportPeriod))
               (class ModifyAttributeState reliable receive
                 (parameter ObjectInstance)
                 (parameter Attribute)
                 (parameter AttributeState))
               (class SetServiceReporting reliable receive
                 (parameter ReportingState))
               (class SetExceptionLogging reliable receive
                 (parameter LoggingState)))
             (class Service reliable receive
               (class ResignFederationExecution reliable receive
                 (parameter ResignAction))
               (class SynchronizationPointAchieved reliable receive
                 (parameter Label))
               (class FederateSaveBegun reliable receive)
               (class FederateSaveComplete reliable receive
                 (parameter SuccessIndicator))
               (class FederateRestoreComplete reliable receive
                 (parameter SuccessIndicator))
               (class PublishObjectClass reliable receive
                 (parameter ObjectClass)
                 (parameter AttributeList))
               (class UnpublishObjectClass reliable receive
                 (parameter ObjectClass))
               (class PublishInteractionClass reliable receive
                 (parameter InteractionClass))
               (class UnpublishInteractionClass reliable receive
                 (parameter InteractionClass))
               (class SubscribeObjectClassAttributes reliable receive
                 (parameter ObjectClass)
                 (parameter AttributeList)
                 (parameter Active))
               (class UnsubscribeObjectClass reliable receive
                 (parameter ObjectClass))
               (class SubscribeInteractionClass reliable receive
                 (parameter InteractionClass)
                 (parameter Active))
               (class UnsubscribeInteractionClass reliable receive
                 (parameter InteractionClass))
               (class DeleteObjectInstance reliable receive
                 (parameter ObjectInstance)
                 (parameter Tag)
                 (parameter FederationTime))
               (class LocalDeleteObjectInstance reliable receive
                 (parameter ObjectInstance))
               (class ChangeAttributeTransportationType reliable receive
                 (parameter ObjectInstance)
                 (parameter AttributeList)
                 (parameter TransportationType))
               (class ChangeAttributeOrderType reliable receive
                 (parameter ObjectInstance)
                 (parameter AttributeList)
                 (parameter OrderingType))
               (class ChangeInteractionTransportationType reliable receive
                 (parameter InteractionClass)
                 (parameter TransportationType))
               (class ChangeInteractionOrderType reliable receive
                 (parameter InteractionClass)
                 (parameter OrderingType))
               (class UnconditionalAttributeOwnershipDivestiture reliable receive
                 (parameter ObjectInstance)
                 (parameter AttributeList))
               (class EnableTimeRegulation reliable receive
                 (parameter FederationTime)
                 (parameter Lookahead))
               (class DisableTimeRegulation reliable receive)
               (class EnableTimeConstrained reliable receive)
               (class DisableTimeConstrained reliable receive)
               (class EnableAsynchronousDelivery reliable receive)
               (class DisableAsynchronousDelivery reliable receive)
               (class ModifyLookahead reliable receive
                 (parameter Lookahead))
               (class TimeAdvanceRequest reliable receive
                 (parameter FederationTime))
               (class TimeAdvanceRequestAvailable reliable receive
                 (parameter FederationTime))
               (class NextEventRequest reliable receive
                 (parameter FederationTime))
               (class NextEventRequestAvailable reliable receive
                 (parameter FederationTime))
               (class FlushQueueRequest reliable receive
                 (parameter FederationTime))))))))

Last update: 2018-08-10

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)

Implementing HLA Client Logic for a Custom Project

In This Article:

C++ Implementation

Initializing HLA Client

Adding Callbacks for HLA Events

Defining a Federation Object Model