vrfTaskEntityScript.h

Go to the documentation of this file.

/*********************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*********************************************************************************/
 
//! \file vrfTaskEntityScript.h
//! \brief Defines message classes for entity script task operations
//!
//! This file contains classes for entity script task messages in the VREngage system.
//! These messages are used to execute scripts on entities and set entity attributes
//! through a flexible attribute system supporting multiple data types. The message
//! system enables communication between different components of the VREngage system
//! to control entity behavior through scripts.
 
#pragma once
 
#include "vreMessageManager/vreMessage.h"
#include "vreMessageManager/vreMessageId.h"
 
#include "vreMessages/export.h"
 
#include <vlpi/entityIdentifier.h>
 
namespace makVre
{
 
//! \brief Message for executing a script on an entity with arbitrary attributes
//!
//! This class represents a message for executing a script on a specific entity
//! with a set of named attributes. It supports multiple attribute types including
//! boolean, integer, double, string, vector, and entity identifier. Attributes
//! are added to the message using the templated addAttribute method, which
//! automatically determines the appropriate attribute type based on the template
//! parameter.
//!
//! The message contains the entity identifier, script name, and a list of attributes
//! that are passed to the script when it is executed.
class VREMESSAGES_DLL VrfScriptedEntityTaskMessage : public makVre::DtVreMessage
{
public:
   //! \brief Enumeration of supported attribute data types
   //!
   //! This enumeration defines the data types that can be used for attributes
   //! in scripted entity task messages.
   enum AttrType
   {
      BOOL,     //!< Boolean value
      INT,      //!< Integer value
      DOUBLE,   //!< Double-precision floating point value
      STRING,   //!< String value
      VECTOR,   //!< Vector value (vlVector)
      ENTITY_ID //!< Entity identifier (DtEntityIdentifier)
   };
 
   //! \brief Base structure for script attributes
   //!
   //! This structure serves as the base for all attribute types, containing
   //! the attribute name and type information. Specific attribute types
   //! derive from this base structure and add a typed value field.
   struct BaseAttribute
   {
      //! \brief Name of the attribute
      std::string name;
 
      //! \brief Type of the attribute
      AttrType type;
   };
 
   //! \brief Templated structure for typed script attributes
   //! \tparam T Data type of the attribute value
   //!
   //! This templated structure derives from BaseAttribute and adds a typed value
   //! field. It is used to store attributes of different data types in a type-safe
   //! manner.
   template <typename T>
   struct Attribute : public BaseAttribute
   {
      //! \brief Value of the attribute
      T value;
   };
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the message, including allocated attribute objects.
   virtual ~VrfScriptedEntityTaskMessage() override;
 
   //! \name Message Creation Methods
   //! @{
 
   //! \brief Creates a new instance of this message type as a DtVreMessage
   //! \return Pointer to a newly created message
   //!
   //! This static method is used by the message factory to create instances
   //! of this message type. It returns a base message pointer that must be
   //! cast to the appropriate type by the caller.
   static DtVreMessage* creator();
 
   //! \brief Creates a new instance of this message type
   //! \return Pointer to a newly created message of this specific type
   //!
   //! This static method creates a new instance of this message type and
   //! returns a pointer to the specific message type, avoiding the need for
   //! casting by the caller.
   static VrfScriptedEntityTaskMessage* create();
   //! @}
 
   static const std::string& theType();
   static const makVre::DtVreMessageId& theId();
 
   //! \brief Get the name of the message type
   virtual const std::string& type() const override;
   virtual const makVre::DtVreMessageId& messageId() const override;
 
   //! \brief Gets the entity identifier for this message
   //! \return Entity identifier of the target entity
   //!
   //! This method returns the entity identifier of the target entity for this message.
   //! The entity identifier specifies which entity the script should be executed on.
   virtual DtEntityIdentifier getEntityId() const;
 
   //! \brief Sets the entity identifier for this message
   //! \param val Entity identifier of the target entity
   //!
   //! This method sets the entity identifier of the target entity for this message.
   //! The entity identifier specifies which entity the script should be executed on.
   virtual void setEntityId(const DtEntityIdentifier& val);
 
   //! \brief Gets the script name for this message
   //! \return Name of the script to execute
   //!
   //! This method returns the name of the script that should be executed on the target entity.
   virtual std::string getScriptName() const;
 
   //! \brief Sets the script name for this message
   //! \param script Name of the script to execute
   //!
   //! This method sets the name of the script that should be executed on the target entity.
   virtual void setScriptName(const std::string& script);
 
   //! \brief Gets the number of attributes in this message
   //! \return Number of attributes
   //!
   //! This method returns the number of attributes that have been added to this message.
   virtual int getAttributeCount() const;
 
   //! \brief Gets an attribute at the specified index
   //! \param i Index of the attribute to retrieve (0-based)
   //! \return Pointer to the base attribute structure
   //!
   //! This method returns a pointer to the base attribute structure at the specified index.
   //! The returned pointer must be cast to the appropriate Attribute<T> type to access
   //! the value field.
   BaseAttribute* getAttribute(int i);
 
   //! \brief Adds an attribute to this message
   //! \tparam T Data type of the attribute value
   //! \param name Name of the attribute
   //! \param data Value of the attribute
   //!
   //! This templated method adds an attribute with the specified name and value to this message.
   //! The attribute type is automatically determined based on the template parameter type.
   //! Supported types include bool, int, double, std::string, vlVector, and DtEntityIdentifier.
   template <typename T>
   void addAttribute(const std::string& name, T data);
 
   //! \brief Gets the total size of the serialized message in bytes
   //! \return Size of the message in bytes
   //!
   //! This method calculates the total size of the message when serialized,
   //! including the base message header and all attributes.
   //! It overrides the base class implementation to include the size of the
   //! entity ID, script name, and attributes.
   virtual int messageSize() const override;
 
   //! \brief Decodes a serialized message
   //! \param buffer Pointer to the buffer containing the serialized message
   //! \param length Length of the buffer in bytes
   //! \return Pointer to a newly created message instance
   //!
   //! This static method deserializes a message from the provided buffer and
   //! creates a new message instance with the deserialized data. It is used by
   //! the message factory to create messages from received network data.
   static makVre::DtVreMessage* decode(char* buffer, int length);
 
protected:
   //! \brief Static message ID for this message type
   //!
   //! This static member holds the unique identifier for this message type.
   static makVre::DtVreMessageId theMessageId;
 
   //! \brief Serializes the message to a stream writer
   //! \param writer Reference to the stream writer
   //!
   //! This method writes the message data to the stream writer, including the
   //! entity ID, script name, and all attributes. It overrides the base class
   //! implementation to include the specific data for this message type.
   virtual void serialize(DtStreamWriter& writer) const override;
 
   //! \brief Deserializes the message from a stream reader
   //! \param reader Reference to the stream reader
   //!
   //! This method reads the message data from the stream reader, including the
   //! entity ID, script name, and all attributes. It overrides the base class
   //! implementation to include the specific data for this message type.
   virtual void deserialize(DtStreamReader& reader) override;
 
   //! \brief Protected constructor
   //!
   //! Initializes a new message with default values. This constructor is protected
   //! to enforce the use of the static create() method for creating new instances.
   VrfScriptedEntityTaskMessage();
 
   //! \brief Gets the attribute type for a template parameter type
   //! \tparam T Data type of the attribute value
   //! \return Attribute type enumeration value corresponding to the template parameter type
   //!
   //! This templated method determines the appropriate attribute type enumeration value
   //! for a given template parameter type. Specialized implementations exist for
   //! bool, int, double, std::string, vlVector, and DtEntityIdentifier.
   template <typename T>
   AttrType getType();
 
   //! \brief Entity identifier of the target entity
   DtEntityIdentifier myEntityId;
 
   //! \brief Name of the script to execute
   std::string myScriptName;
 
   //! \brief Type definition for the list of attributes
   using AttributeList = std::vector<BaseAttribute*>;
 
   //! \brief List of attributes for this message
   AttributeList myAttributes;
};
 
//! \brief Implementation of the addAttribute template method
//! \tparam T Data type of the attribute value
//! \param name Name of the attribute
//! \param data Value of the attribute
//!
//! This method creates a new Attribute object with the specified name and value,
//! determines the attribute type using the getType template method, and adds the
//! attribute to the message's attribute list.
template <typename T>
void VrfScriptedEntityTaskMessage::addAttribute(const std::string& name, T data)
{
   VrfScriptedEntityTaskMessage::Attribute<T>* attr = new VrfScriptedEntityTaskMessage::Attribute<T>();
   attr->type = getType<T>();
   attr->name = name;
   attr->value = data;
 
   myAttributes.push_back(attr);
};
 
//! \brief Message for setting entity attributes through a script
//!
//! This class extends VrfScriptedEntityTaskMessage to specifically represent
//! a message for setting entity attributes through a script. It uses the same
//! attribute system as the base class but with a specific message type and ID.
//! This specialization allows for targeted message routing and handling of
//! entity attribute setting operations.
class VREMESSAGES_DLL VrfScriptedEntitySetMessage : public VrfScriptedEntityTaskMessage
{
public:
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the message. The base class destructor
   //! handles cleanup of the attribute objects.
   virtual ~VrfScriptedEntitySetMessage() override;
 
   static const std::string& theType();
   static const makVre::DtVreMessageId& theId();
 
   //! \brief Get the name of the message type
   virtual const std::string& type() const override;
   virtual const makVre::DtVreMessageId& messageId() const override;
 
   //! \brief Creates a new instance of this message type as a DtVreMessage
   //! \return Pointer to a newly created message
   //!
   //! This static method is used by the message factory to create instances
   //! of this message type. It returns a base message pointer that must be
   //! cast to the appropriate type by the caller.
   static DtVreMessage* creator();
 
   //! \brief Creates a new instance of this message type
   //! \return Pointer to a newly created message of this specific type
   //!
   //! This static method creates a new instance of this message type and
   //! returns a pointer to the specific message type, avoiding the need for
   //! casting by the caller.
   static VrfScriptedEntitySetMessage* create();
 
protected:
   //! \brief Protected constructor
   //!
   //! Initializes a new message with default values. This constructor is protected
   //! to enforce the use of the static create() method for creating new instances.
   VrfScriptedEntitySetMessage();
 
   //! \brief Static message ID for this message type
   //!
   //! This static member holds the unique identifier for this message type.
   static makVre::DtVreMessageId theMessageId;
};
 
} // namespace makVre