roleSelectionControl.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file roleSelectionControl.h
//! \brief Component that enables switching between different roles on the same entity
//! \ingroup vreCommonComponents
 
#pragma once
 
#include "vreCommonComponents/export.h"
 
#include "vrePlayerStation/playerComponent.h"
#include "vrePlayerStation/inputLogic.h"
 
#include <vector>
 
#include <vreMessageManager/vreMessage.h>
 
namespace makVre
{
class DtPlayerStation;
 
namespace RoleSelectionControlConfig
{
//! \ingroup RoleConfigParams
//! \defgroup RoleSelectionControlRoleParams Role Selection Control Role Parameters
//! \roleInherits{PlayerComponentRoleParams}
//! Configuration Options for role selection control role.
//! @{
 
//! \vreRoleParam{availableRolesAttributeName,string,"availableRoles",roleSelectionControl,Name of the state attribute that stores the list of available role names for selection.}
constexpr const char* availableRolesAttributeName = "availableRolesAttributeName";
 
//! \vreRoleParam{excludedRoles,table,{},roleSelectionControl,Table of role names to exclude from the available roles list.}
constexpr const char* excludedRoles = "excludedRoles";
 
//! \vreRoleParam{hasAvailableRolesAttributeName,string,"hasAvailableRoles",roleSelectionControl,Name of the boolean state attribute indicating whether any roles are available for selection.}
constexpr const char* hasAvailableRolesAttributeName = "hasAvailableRolesAttributeName";
 
//! \vreRoleParam{inputConfigFile,string,"",roleSelectionControl,Input configuration file path for role selection key bindings.}
constexpr const char* inputConfigFile = "inputConfigFile";
 
//! \vreRoleParam{inputConfigGroup,string,"general",roleSelectionControl,Input configuration group name for role selection controls.}
constexpr const char* inputConfigGroup = "inputConfigGroup";
 
//! \vreRoleParam{nextRoleBinding,string,"next-role",roleSelectionControl,Input binding name for selecting the next available role.}
constexpr const char* nextRoleBinding = "nextRoleBinding";
 
//! \vreRoleParam{previousRoleBinding,string,"previous-role",roleSelectionControl,Input binding name for selecting the previous available role.}
constexpr const char* previousRoleBinding = "previousRoleBinding";
 
//! \vreRoleParam{rolesList,table,{},roleSelectionControl,Table of specific role names to include in the role selection list (overrides automatic discovery).}
constexpr const char* rolesList = "rolesList";
 
//! \vreRoleParam{selectRoleMenuAction,string,"selectRole",roleSelectionControl,Menu action name for triggering role selection via the menu system.}
constexpr const char* selectRoleMenuAction = "selectRoleMenuAction";
 
//! @}
} // namespace RoleSelectionControlConfig
 
//! \brief Type identifier for DtRoleSelectionControl component
constexpr const char* DtRoleSelectionControlType = "DtRoleSelectionControl";
 
//! \brief Component that enables switching between different roles on the same entity
//!
//! DtRoleSelectionControl provides functionality for cycling through and selecting
//! different roles available on the current ownship entity. It tracks which roles
//! are available (not occupied or engaged by other players), maintains state attributes
//! for the UI to display, and handles the role switching process through input bindings
//! or menu actions. It supports both direct-engaged roles and embark-engaged roles where
//! a human avatar must be re-embarked in a specific slot.
class VRECOMMONCOMPONENTS_DLL DtRoleSelectionControl : public DtPlayerComponent
{
public:
   //! \brief Constructor for DtRoleSelectionControl
   //!
   //! Initializes the component with default settings
   DtRoleSelectionControl();
 
   //! \brief Virtual destructor for DtRoleSelectionControl
   virtual ~DtRoleSelectionControl() override;
 
   //! \brief Initializes the role selection control component
   //! \param player Pointer to the player station this component belongs to
   //! \param config Configuration table containing role selection settings
   //! \return True if initialization succeeded, false otherwise
   //!
   //! Sets up available roles list, determines the component mode (stacked or direct),
   //! configures input bindings, and registers message handlers
   virtual bool initialize(DtPlayerStation* player, DtInitTable& config) override;
   //! \brief Performs post-initialization after all components are initialized
   //! \return True if post-initialization succeeded, false otherwise
   //!
   //! Completes any setup that requires other components to be initialized first
   virtual bool postInitialize() override;
 
   //! \brief Called every frame to update the component state
   //! \param dt Delta time since the last frame in seconds
   //!
   //! For stacked roles, periodically requests embarkation information to
   //! update slot availability status
   virtual void tick(double dt) override;
   //! \brief Shuts down the role selection control component
   //!
   //! Removes message handlers and input bindings
   virtual void shutdown() override;
 
   //! \brief Returns the type identifier for this component
   //! \return The type string for DtRoleSelectionControl
   virtual const char* type() const override;
 
   //! \brief Switches to a specific role on the ownship entity
   //! \param roleName Name of the role to switch to
   //!
   //! For stacked roles, embarks the human player in the new role slot.
   //! For direct-engaged roles, assigns the player to the new role directly.
   virtual void selectRole(const std::string& roleName);
 
   //! \brief Handles simulation state messages
   //! \param msg Simulation state message
   //! \return Message handling result indicating if the message was handled
   //!
   //! Updates role engagement status based on information in simulation state messages
   virtual DtVreMessageResult handleSimState(DtVreMessage* msg);
 
   //! \brief Handles menu action messages
   //! \param msg Menu action message
   //! \return Message handling result indicating if the message was handled
   //!
   //! Processes role selection menu actions
   virtual DtVreMessageResult handleMenuAction(DtVreMessage* msg);
 
   //! \brief Handles entity embarkation information messages
   //! \param msg Entity embarkation information message
   //! \return Message handling result indicating if the message was handled
   //!
   //! Updates slot occupancy status based on embarkation information
   virtual DtVreMessageResult handleEntityEmbarkationInformation(DtVreMessage* msg);
 
   //! \brief Input handler for cycling to the next available role
   //! \param keyState Input value (1.0 for pressed, 0.0 for released)
   //!
   //! When triggered, finds the next non-occupied, non-engaged role and switches to it
   virtual void nextRole(double keyState);
 
   //! \brief Input handler for cycling to the previous available role
   //! \param keyState Input value (1.0 for pressed, 0.0 for released)
   //!
   //! When triggered, finds the previous non-occupied, non-engaged role and switches to it
   virtual void previousRole(double keyState);
 
protected:
   //! \brief Updates the available roles state attributes
   //!
   //! Builds a list of available roles based on occupancy and engagement status
   //! and updates the corresponding state attributes for UI display
   virtual void updateAvailableRolesAttribute();
 
   //! \brief Structure representing a role with its availability status
   struct RoleListItem
   {
      //! \brief Constructor for RoleListItem
      //! \param _name Role name
      //! \param _slotOccupied Flag indicating if the corresponding slot is occupied
      //! \param _roleEngaged Flag indicating if the role is currently engaged by another player
      RoleListItem(const std::string& _name, bool _slotOccupied, bool _roleEngaged)
         : name(_name)
         , slotOccupied(_slotOccupied)
         , roleEngaged(_roleEngaged)
      {
      }
 
      //! \brief Name of the role
      std::string name;
 
      //! \brief Flag indicating if the corresponding slot is occupied
      bool slotOccupied;
 
      //! \brief Flag indicating if the role is currently engaged by another player
      bool roleEngaged;
   };
 
   //! \brief List of roles available on the current entity
   std::vector<RoleListItem> myRolesList;
 
   //! \brief Index of the current role in the roles list
   unsigned int myRoleIndex;
 
   //! \brief Name of the attribute indicating if there are available roles
   std::string myHasAvailableRolesAttributeName;
 
   //! \brief Name of the attribute containing the list of available roles
   std::string myAvailableRolesAttributeName;
 
   //! \brief Name of the menu action for selecting a role
   std::string mySelectRoleMenuAction;
 
   //! \brief Flag indicating if this is a stacked role (embarked) versus direct-engaged
   bool myIsStackedRole;
 
   //! \brief Input logic for handling role selection bindings
   DtInputLogic myInputLogic;
};
 
} // namespace makVre