echelonLogic.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file echelonLogic.h
//! \brief Defines the DtEchelonLogic component for tracking hierarchical relationships between entities.
//!
//! This component handles military-style echelon relationships, determining superiors and subordinates
//! in the command structure and making this information available via state attributes.
//!
//! \ingroup vreCommonComponents
 
#pragma once
 
#include "vreCommonComponents/export.h"
 
#include "vrePlayerStation/playerComponent.h"
#include <vrvCore/DtUniqueID.h>
#include <vrvCore/DtElementIDHierarchyState.h>
 
namespace makVre
{
//! \brief Type identifier for DtEchelonLogic component
constexpr const char* DtEchelonLogicType = "DtEchelonLogic";
 
//! \brief Component for handling command hierarchy relationships between entities
//!
//! The DtEchelonLogic tracks hierarchical relationships between entities in a command structure.
//! It queries the DtElementIDHierarchyState to determine an entity's superior (commanding entity)
//! and its peer subordinates (other entities sharing the same superior), then publishes this
//! information as state attributes for use by other components.
//!
//! The component maintains the following state attributes:
//! - "Superior": The display name of the entity's commanding officer/unit
//! - "subordinateList": A list of display names of peer entities (others reporting to the same superior)
//! - "taskableEntities": Boolean flag indicating if there are any peer entities to potentially task
class VRECOMMONCOMPONENTS_DLL DtEchelonLogic : public makVre::DtPlayerComponent
{
public:
   //! \brief Constructor for DtEchelonLogic
   //!
   //! Initializes the component with the name "DtEchelonLogic".
   DtEchelonLogic();
 
   //! \brief Virtual destructor for DtEchelonLogic
   virtual ~DtEchelonLogic() override;
 
   //! \brief Initializes the component with configuration from Lua
   //!
   //! Performs basic initialization using the parent class implementation.
   //!
   //! \param player Pointer to the player station this component belongs to
   //! \param config Configuration table containing initialization parameters
   //! \return True if initialization succeeds, false otherwise
   virtual bool initialize(DtPlayerStation* player, DtInitTable& config) override;
 
   //! \brief Updates the component state
   //!
   //! Called each frame to update the command hierarchy information. This method:
   //! - Looks up the entity's superior/commanding entity
   //! - Finds all entities subordinate to that superior (peers of this entity)
   //! - Updates the "Superior", "subordinateList", and "taskableEntities" state attributes
   //!
   //! \param dt Delta time in seconds since the last tick
   virtual void tick(double dt) override;
 
   //! \brief Shuts down the component
   //!
   //! Performs cleanup by calling the parent class shutdown method.
   virtual void shutdown() override;
 
   //! \brief Returns the component type identifier
   //! \return The component type string
   virtual const char* type() const override;
 
protected:
   //! \brief Initializes state attributes
   //!
   //! This method is reserved for initializing state attributes in the future.
   //! Currently, it has an empty implementation with commented-out code.
   virtual void initializeStateAttributes() override;
 
   //! \brief Looks up the superior (commanding entity) for a given entity
   //!
   //! Queries the DtElementIDHierarchyState to find the parent entity ID
   //! for the specified entity.
   //!
   //! \param de Reference to the dynamic environment
   //! \param id Element ID of the entity to find the superior for
   //! \return Element ID of the superior entity, or 0 if not found
   virtual makVrv::DtElementID lookupSuperior(makVrv::DtDe& de, makVrv::DtElementID id) const;
 
   //! \brief Looks up subordinate entities for a given entity
   //!
   //! Queries the DtElementIDHierarchyState to find all child entities
   //! for the specified entity.
   //!
   //! \param de Reference to the dynamic environment
   //! \param id Element ID of the entity to find subordinates for
   //! \return Vector of element IDs of subordinate entities
   virtual const makVrv::DtElementIDHierarchyState::ElementIDVector lookupSubordinates(
      makVrv::DtDe& de, makVrv::DtElementID id) const;
 
   //! \brief Finds the hierarchy state attribute for a given entity
   //!
   //! Locates the DtElementIDHierarchyStateAttribute for the specified entity
   //! by looking it up in the data bank.
   //!
   //! \param de Reference to the dynamic environment
   //! \param id Element ID of the entity to find the hierarchy item for
   //! \return Pointer to the hierarchy state attribute, or nullptr if not found
   virtual const makVrv::DtElementIDHierarchyStateAttribute* findHierarchyItem(
      makVrv::DtDe& de, makVrv::DtElementID id) const;
 
   // Commented out attributes for future use
   //! \brief Pointer to the superior entity attribute (commented out)
   // DtAttribute<std::string>* mySuperiorAttr;
 
   //! \brief Pointer to the subordinate list attribute (commented out)
   // DtAttribute<std::vector<std::string>>* mySubordinateListAttr;
 
   //! \brief Pointer to the taskable entities flag attribute (commented out)
   // DtAttribute<bool>* myTaskableEntitiesAttr;
};
 
} // namespace makVre