playerStation.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file playerStation.h
//! \brief Defines the DtPlayerStation class for managing engaged roles
//!
//! This file contains the DtPlayerStation class, which manages the user interface
//! for engaged roles in VR-Engage. It handles input, views, components, and connectors
//! to control entities in the simulation. DtPlayerStation instances are created when
//! a user engages with an entity to play a specific role.
 
#pragma once
 
#include "vrePlayerStation/export.h"
#include "vrePlayerStation/playerComponent.h"
#include "vreUtil/attribute.h"
#include "vrePlayerStation/playerStationApp.h"
#include "vreMessageManager/vreMessage.h"
 
#include "vreUtil/initializer.h"
 
#include <vrvCore/DtUniqueID.h>
 
#include <string>
#include <map>
#include <vector>
 
namespace makVre
{
//! \brief Class for managing the user interface for engaged roles
//!
//! DtPlayerStation manages all aspects of a user's engagement with a simulation entity.
//! It is responsible for handling user input, presenting the appropriate views, and
//! controlling the entity according to the selected role.
//!
//! Each instance is configured with a role definition that specifies:
//! - Components that provide specific functionality
//! - Connectors that handle communication with simulation protocols
//! - Input mappings that translate user actions to simulation commands
//! - Menu configurations for role-specific UI elements
//!
//! The class maintains an attribute store for data sharing between components and
//! manages the lifecycle of all component instances.
//!
//! This class may be referred to as a Role, Station, or Player in different contexts.
//!
//! \warning Not thread safe. Used only in the display engine's main render thread.
class PLAYERSTATION_DLL DtPlayerStation
{
public:
   //! \brief Type definition for a list of player components
   using ComponentList = std::vector<DtPlayerComponent*>;
 
   //! \brief Type definition for a list of connector names
   using ConnectorNameList = std::vector<std::string>;
 
   //! \brief Constructor for a player station
   //! \param app Pointer to the player station application
   //! \param playerDefinition Table containing the role definition
   //! \param attachTo ID of the entity this station will control
   //! \param stationName Name of the chosen role
   //! \param displayLayout Name of the display layout to use
   //!
   //! Creates a new player station instance when a role is engaged. This happens when:
   //! - A user clicks Engage from the Choose Role menu
   //! - The station is configured to auto-engage at startup
   //! - A secondary role is created when an entity embarks in a host slot
   //!
   //! The playerDefinition parameter contains the complete role configuration,
   //! which is assembled by merging the role definition from the .lua file,
   //! overrides from the .entity file, and display layout-specific settings.
   //! The stationName parameter identifies the chosen role from those available
   //! for the entity type. Available roles are defined in the .entity file, with
   //! each role specifying a .lua file containing its definition.
   //!
   //! Role configuration files are located in the vre-roles-dir folder as defined
   //! in the .sms file (default: "data/simulationModelSets/VR-Engage/roles").
   //!
   //! The displayLayout parameter specifies which layout to use with the chosen role.
   //! Roles can support multiple layouts that arrange views differently. Some roles
   //! only support a single layout, often called "default".
   //!
   //! \warning DtPlayerStation instances should only be created using
   //! DtPlayerStationApp::createPlayerStation and destroyed using
   //! DtPlayerStationApp::destroyPlayerStation.
   //!
   //! \see DtPlayerStationApp::createPlayerStation
   DtPlayerStation(DtPlayerStationApp* app, DtInitTable playerDefinition, DtEntityIdentifier attachTo,
      std::string stationName, std::string displayLayout);
 
   //! \brief Destructor for a player station
   //!
   //! If this instance was created as a secondary role as a result of the primary ownship embarking
   //! in a role slot, then this secondary instance is destroyed when the primary ownship leaves
   //! that slot. If this instance is a primary role, then this instance is destroyed either when the
   //! VR-Engage app is closed, or when the user returns to the Choose Role panel.
   virtual ~DtPlayerStation();
 
   //! \brief Initializes the player station
   //! \return True if all components initialized successfully, false otherwise
   //!
   //! Performs all required setup to create a functional role:
   //! - Instantiates all components defined in the role definition
   //! - Requests connectors to be started
   //! - Registers message handlers
   //! - Calls init() and postInit() on all components
   //!
   //! This method is called when initially engaging this role or when
   //! returning to this role from an embarked role.
   virtual bool init();
 
   //! \brief Updates the player station
   //! \param dt Seconds elapsed since the previous tick
   //!
   //! Called once per display engine frame to update the player station.
   //! Updates all components and processes any pending operations.
   virtual void tick(double dt);
 
   //! \brief Shuts down the player station
   //!
   //! Performs teardown of all setup done during initialization:
   //! - Destroys all components
   //! - Requests connectors to be stopped
   //! - Unregisters message handlers
   //!
   //! Called when disengaging from this role, or when suspending this
   //! role temporarily when embarking into a different role slot.
   virtual void shutdown();
 
   //! \brief Provides debugging information
   //!
   //! Invoked from the ImGui debug menu system to populate the Player tab
   //! of the Shift-F4 debug menu. Displays component status, attribute values,
   //! and other diagnostic information about the player station.
   virtual void debugPlayer();
 
   //! \brief Gets the player attribute store
   //! \return Reference to the attribute store
   //!
   //! The attribute store contains player/role data shared between components.
   virtual DtAttributeHandle& playerAttributeStore();
 
   //! \brief Gets the player attribute store (const version)
   //! \return Const reference to the attribute store
   virtual const DtAttributeHandle& playerAttributeStore() const;
 
   //! \brief Finds a component by type and optional name
   //! \tparam COMP_TYPE The component type to find
   //! \param name Optional name to match (empty to match by type only)
   //! \return Pointer to the found component, or NULL if not found
   //!
   //! Returns the first component that matches the template type. If a name is provided,
   //! both the type and name must match to find the component.
   template <typename COMP_TYPE>
   COMP_TYPE* findComponent(const std::string& name = "");
 
   //! \brief Finds all components of a specific type
   //! \tparam COMP_TYPE The component type to find
   //! \return Vector of pointers to matching components
   //!
   //! Returns a list of all components that match the specified template type.
   template <typename COMP_TYPE>
   std::vector<COMP_TYPE*> findComponents();
 
   //! \brief Gets the list of connectors by type
   //! \param connectionType The type of connectors to retrieve
   //! \return List of connector names for the specified type
   //!
   //! Returns a list of connectors belonging to this role with the
   //! ConnectorType protocol suffix appended to each name.
   virtual ConnectorNameList connectors(DtConnector::DtConnectorType connectionType);
 
   //! \brief Gets the player station application
   //! \return Pointer to the application
   //!
   //! Returns a pointer to the VR-Engage DtPlayerStationApp singleton.
   //! This pointer is provided in the constructor and saved for convenience.
   //! It should never be null and should remain valid for the life of this class.
   virtual DtPlayerStationApp* app() const;
 
   //! \brief Gets the display engine
   //! \return Pointer to the display engine
   //!
   //! Returns a pointer to the VR-Vantage DtDe singleton. This pointer is
   //! obtained from app() during construction and saved for convenience.
   //! It should never be null and should remain valid for the life of this class.
   virtual makVrv::DtDe* de() const;
 
   //! \brief Gets the element ID for the controlled entity
   //! \return Element ID of the controlled entity
   //!
   //! Returns the DtElementID associated with the entity that
   //! this player station controls in the display engine.
   virtual makVrv::DtElementID elementId() const;
 
   //! \brief Gets the entity ID for the controlled entity
   //! \return Reference to the entity identifier
   //!
   //! Returns the DtEntityIdentifier of the entity that this player station controls.
   virtual const DtEntityIdentifier& entityId() const;
 
   //! \brief Gets the entity type for the controlled entity
   //! \return Reference to the entity type
   //!
   //! Returns the DtEntityType of the entity that this player station controls.
   virtual const DtEntityType& entityType() const;
 
   //! \brief Gets the name of the role
   //! \return String containing the station name
   //!
   //! Returns the name of the role that this player station represents.
   //! This name is provided in the constructor and saved for reference.
   //! It should not change during the life of the player station.
   virtual std::string stationName() const;
 
   //! \brief Gets the display layout name
   //! \return String containing the display layout name
   //!
   //! Returns the name of the display layout chosen when the role was engaged.
   //! This is provided in the constructor and saved for reference.
   //! It should not change during the life of the player station.
   virtual std::string displayLayout() const;
 
   //! \brief Gets the list of joystick function groups
   //! \return List of joystick function groups
   //!
   //! Returns a list of joystick function groups that this station will control.
   //! Used internally with the VR-Forces Remote Control joystick API.
   //! This list is defined by the "roles" table in the Role definition.
   //! Note that these strings do not correspond to "Roles" as the term is generally used
   //! elsewhere, meaning a PlayerStation definition or instance.
   // TODO: rename this function and associated member var and config table; this is confusing.
   virtual std::vector<std::string> roles() const;
 
   //! @returns true unless the Role has been suspended in the case of an emplicit engagement
   //! of an embarked Role. If the player embarks in a role slot, the active primary PlayerStation
   //! is supsneded and a new secondary PlayerStation instance is created for the embarked Role.
   virtual bool isActive() const;
 
   //! @returns True after shutdown has been called and remains True until the PlayerStation
   //! instance is either destroyed or re-initialized by calling init again.
   virtual bool isShuttingDown() const;
 
   //! @returns the lua config table defining the Connector, Component, and Menu configuration
   //! for this Role. This is the final configuration for this Role, after filtering and merging
   //! the associated Display Layout configuration. This table is built when the user engages
   //! a role and before the DtPlayerStation instance is created. It should not change thereafter.
   virtual DtInitTable definition() const;
 
protected:
   //! Handler for the SimulationStateMessage for this station's ownship entity. This function
   //! is used only to cache initial state values of the ownship entity from the first message
   //! receied after engagement. This handler is then unregistered. The initial state values
   //! are saved in the AttributeStore as:
   //!  <DtEntityType> "entityType"
   //!  <DtVector> "InitialPosition"
   //!  <DtTaitBryan> "InitialOrientation"
   //!  <DtEntityIdentifier> "InitialParent"
   virtual DtVreMessageResult handleSimulationStateMessage(makVre::DtVreMessage* msg);
 
   //! Called from init. Calls initializeMenus on the DtActionMenuUpdater Component, if present,
   //! passing in the menuConfig table from the role definition.
   virtual bool initializeMenus();
 
   //! Called from init. Instantiates all components in the role definition and invokes their
   //! init function. Returns true if all components return true from component init.
   virtual bool initializeComponents();
 
   //! Called from init. Invokes postInit function on all components. Called only after and if
   //! initializeComponents has returned true. Returns true if all components return true from
   //! postInit.
   virtual bool postInitializeComponents();
 
   //! Writes name, type, and value of each attribute in Attribute Store to a human-readable
   //! string. Returns vector of these strings, one per attribute. Used by debugPlayer to write
   //! the data in the Attribute Store to the F4 menu or log file.
   // static std::list<std::string> serializeState(DtAttributeHandle& state, int depth = 0);
 
   //! Pointer to DtPlayerStationApp singleton that created and owns this DtPlayerStation
   //! instance. This should never be null.
   DtPlayerStationApp* myApp;
 
   // Contains definition for this PlayerStation/Role, includes all Connectors and Components
   // and their config data. Table has been filtered and merged using config for the chosen
   // display layout. Not a copy of original role config in lua file; does not contain data
   // for other display layouts.
   DtInitTable myPlayerDefinition;
 
   // Identifiers and properties of ownship entity controlled by this station
   makVrv::DtElementID myElementId;
   DtEntityIdentifier myEntityId;
   DtEntityType myEntityType;
   DtForceType myForceType;
 
   // List of string identfiers for joystick function groups, see roles() function above.
   std::vector<std::string> myRoles;
 
   // Role and Display Layout name chosen when engaging this role. These were used to
   // compose the final playerDefinition, and are saved here for later reference. These
   // are not expected to change for the life of the DtPlayerStation instance.
   std::string myStationName;
   std::string myDisplayLayout;
 
   // Stores data shared between components
   DtAttributeHandle myAttributeStore;
 
   // Component instances for this station/role.
   ComponentList myComponents;
 
   // Names of Connectors for this station/role. Note the actual instances are owned and
   // managed by the ConnectorAccessory in the net thread.
   ConnectorNameList myConnectorNames;
 
   // Status of this PlayerStation instance. myActive == !myShuttingDown. Set in init()
   // and shutdown().
   // TODO: These are redundant, we don't need both of these.
   bool myActive;
   bool myShuttingDown;
 
   // Convenience pointer found from app()->de(); should never be null, should never change.
   makVrv::DtDe* myDe;
 
   std::map<unsigned long long, bool[4]> myDebugAttributeTraceChecks;
};
 
template <typename COMP_TYPE>
COMP_TYPE* DtPlayerStation::findComponent(const std::string& name)
{
   for (int compIndex = 0; compIndex < myComponents.size(); compIndex++)
   {
      if (COMP_TYPE* comp = dynamic_cast<COMP_TYPE*>(myComponents[compIndex]))
      {
         if (name.empty())
         {
            return comp;
         }
         else
         {
            if (name == comp->name())
            {
               return comp;
            }
         }
      }
   }
 
   return nullptr;
}
 
template <typename COMP_TYPE>
std::vector<COMP_TYPE*> DtPlayerStation::findComponents()
{
   std::vector<COMP_TYPE*> ret;
 
   for (int compIndex = 0; compIndex < myComponents.size(); compIndex++)
   {
      if (COMP_TYPE* comp = dynamic_cast<COMP_TYPE*>(myComponents[compIndex]))
      {
         ret.push_back(comp);
      }
   }
 
   return ret;
}
 
} // namespace makVre