chooseRoleState.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file chooseRoleState.h
//! \brief Defines the DtChooseRoleState class for entity and role selection
//!
//! This file contains the DtChooseRoleState class which represents the application
//! state where users select entities to control or create new entities. It manages
//! the UI interactions for role selection and coordinates with other components
//! to transition into engaged gameplay.
 
#pragma once
 
#include "vrePlayerStation/export.h"
 
#include "vrePlayerStation/playerStationState.h"
 
#include "vreMessageManager/vreMessage.h"
 
#include <vrvCore/DtUniqueID.h>
 
namespace makVrv
{
class DtObserverViewsWidget;
class DtObserverViewsWidgetLogic;
} // namespace makVrv
 
namespace makVre
{
//! \brief Forward declaration of the player station application class
class DtPlayerStationApp;
 
//! \brief Forward declaration of the player selection dialog
class DtChoosePlayerDialog;
 
//! \brief Forward declaration of the initializer class
class DtInitializer;
 
//! \brief Forward declaration of the role selection panel
class DtChooseRolePanel;
 
//! \brief Forward declaration of the role selection page
class DtVreChooseRolePage;
 
//! \brief Forward declaration of the role assignment message
class VreAssignRolePlayerMessage;
 
//! \brief Application state for selecting entities and roles
//!
//! DtChooseRoleState represents the application state where users can
//! select existing entities to control or create new entities. It manages
//! the UI interactions, entity creation, and transitions to the engaged state.
class PLAYERSTATION_DLL DtChooseRoleState : virtual public DtPlayerStationState
{
public:
   //! \brief Constructor
   //! \param app Reference to the player station application
   //!
   //! Creates a new role selection state associated with the given application.
   DtChooseRoleState(DtPlayerStationApp& app);
 
   //! \brief Virtual destructor
   //!
   //! Ensures proper cleanup of the role selection state resources.
   virtual ~DtChooseRoleState() override;
 
   //! \brief Called when the state is entered
   //! \param args Pointer to arguments from the previous state
   //!
   //! Sets up the role selection UI and observer views, registers message handlers,
   //! and initializes the state's data structures. This is called when the player
   //! first enters the role selection state.
   virtual void onEnter(const DtPlayerStationStateArgs* args) override;
 
   //! \brief Called when the state is exited
   //!
   //! Cleans up resources, hides UI elements, and unregisters message handlers.
   //! This is called when the player leaves the role selection state.
   virtual void onExit() override;
 
   //! \brief Updates the state each frame
   //! \param dt Time in seconds since the last update
   //!
   //! Handles per-frame processing, such as updating entity status, managing
   //! user interactions, and handling deferred operations.
   virtual void tick(double dt) override;
 
   //! \brief Called when the state becomes the topmost state again
   //!
   //! Restores UI visibility and updates the panel when this state is exposed
   //! after another state has been popped from the stack.
   virtual void onExposed() override;
 
   //! \brief Called when another state is pushed on top of this one
   //!
   //! Hides UI elements and pauses processing while this state is covered
   //! by another state on the stack.
   virtual void onStacked() override;
 
   //! \brief Entity creation methods
   //! @{
 
   //! \brief Sets whether a new entity should be created
   //! \param newNotExisting True to create a new entity, false to use an existing one
   //!
   //! Determines whether the player will create a new entity or control an existing one.
   virtual void setCreatingOwnship(bool newNotExisting);
 
   //! \brief Sets the name for a new entity
   //! \param name Name to assign to the new entity
   //!
   //! Sets the display name for the entity being created.
   virtual void setNewEntityName(const std::string& name);
 
   //! \brief Sets the type for a new entity
   //! \param type Type identifier for the new entity
   //!
   //! Sets the type of entity to create (e.g., aircraft, vehicle, infantry).
   virtual void setNewEntityType(const DtEntityType& type);
 
   //! \brief Sets the force type for a new entity
   //! \param force Force type for the new entity (friendly, hostile, etc.)
   //!
   //! Sets the force affiliation for the entity being created.
   virtual void setNewEntityForce(const DtForceType& force);
 
   //! \brief Sets the location for a new entity
   //! \param location 3D position for the new entity (at ground level)
   //!
   //! Sets the ground location where the entity will be created.
   virtual void setNewEntityLocation(const DtVector& location);
 
   //! \brief Sets the location and altitude for a new entity
   //! \param location 3D position for the new entity (ground reference)
   //! \param altitude Height above ground in meters
   //!
   //! Sets both the ground position and altitude for the entity being created.
   virtual void setNewEntityLocationAtAltitude(const DtVector& location, double altitude);
 
   //! \brief Sets whether the entity should be clamped to terrain
   //! \param clamp True to clamp to terrain, false otherwise
   //!
   //! Determines whether the entity should be constrained to follow terrain contours.
   virtual void setNewEntityClamp(bool clamp);
 
   //! \brief Sets the heading for a new entity
   //! \param headingInDegrees Heading in degrees (0-360, clockwise from north)
   //!
   //! Sets the initial heading for the entity being created.
   //! This assumes the location has already been set.
   virtual void setNewEntityHeading(const double headingInDegrees);
 
   //! \brief Sets the pitch for a new entity
   //! \param pitch Pitch angle in degrees
   //!
   //! Sets the initial pitch angle for the entity being created.
   virtual void setNewEntityPitch(const double pitch);
 
   //! \brief Sets a parent entity for embarking
   //! \param host Entity identifier of the host/parent entity
   //! \param offset Relative offset from the host entity's position
   //!
   //! Specifies that the new entity should be created as embarked on another entity.
   virtual void setNewEntityEmbarkedOn(const DtEntityIdentifier& host, const DtVector& offset);
   //! @}
 
   //! \brief Gets the type of the entity being created
   //! \return Reference to the entity type
   //!
   //! Retrieves the entity type that has been set for creation.
   virtual const DtEntityType& getNewEntityType() { return myNewEntityDef.type; }
 
   //! \brief Gets the identifier of the created entity
   //! \return Reference to the entity identifier
   //!
   //! Retrieves the unique identifier of the entity that was created.
   //! Only valid after entity creation is complete.
   virtual const DtEntityIdentifier& getCreatedOwnshipEntity() const;
 
   //! \brief Gets the element ID of the created entity
   //! \return Element ID in the display engine
   //!
   //! Retrieves the display engine element ID for the created entity.
   //! Only valid after entity creation is complete.
   virtual makVrv::DtElementID getCreatedOwnshipElement() const;
 
   //! \brief Updates the player station with role information
   //! \param role Name of the role to play
   //! \param entityId Identifier of the entity to control (null for new entities)
   //! \param displayLayout Name of the display layout to use
   //!
   //! Sets up the player station with the selected role, entity, and display layout
   //! in preparation for transitioning to the engaged state.
   virtual void playStation(const std::string& role, const DtEntityIdentifier& entityId = DtEntityIdentifier::nullId(),
      const std::string& displayLayout = "");
 
   //! \brief Initiates engagement with the selected entity
   //! \param asSpectator True to engage as a spectator, false as a controller
   //!
   //! Transitions from the role selection state to the engaged state,
   //! starting gameplay with the selected entity and role.
   virtual void play(bool asSpectator = false);
 
   //! \brief Handles role assignment messages
   //! \param message Pointer to the role assignment message
   //! \return Message handling result
   //!
   //! Processes messages related to assigning roles to players,
   //! which may come from network or local sources.
   virtual DtVreMessageResult handleAssignRolePlayer(DtVreMessage* message);
 
   //! \brief Controls visibility of the observer views panel
   //! \param visible True to show the panel, false to hide it
   //!
   //! Shows or hides the observer views panel that provides
   //! alternative viewpoints of the simulated environment.
   virtual void setObserverViewsPanelVisible(bool visible);
 
protected:
   //! \brief Controls visibility of the UI components
   //! \param visible True to show UI elements, false to hide them
   //!
   //! Manages the visibility of the choose role page and entity panel components.
   //! Used when entering/exiting the state or when stacked/exposed.
   virtual void setUIVisibility(bool visible);
 
   //! \brief Resets the entity panel to its default state
   //!
   //! Clears all selections and inputs in the entity panel,
   //! preparing it for a fresh interaction.
   virtual void resetEntityPanel();
 
   //! \brief Structure containing definition data for a new entity
   //!
   //! Contains all the parameters needed to create a new entity in the simulation,
   //! including its type, position, orientation, and attributes.
   struct EntityDefinition
   {
      //! \brief Constructor that initializes with default values
      EntityDefinition()
         : force(DtForceOther)
         , clamp(true)
         , altitude(0.0)
         , heading(0.0)
         , pitch(0.0)
      {
      }
 
      std::string name;  //!< Display name for the entity
      DtEntityType type; //!< Type identifier for the entity
      DtForceType force; //!< Force affiliation (friendly, hostile, etc.)
      DtVector location; //!< Geocentric position at ground level
      bool clamp;        //!< Whether to clamp to terrain
      double altitude;   //!< Height above ground in meters
      DtVector position; //!< Geocentric position at specified altitude
      double heading;    //!< Heading in degrees (0-360, clockwise from north)
      double pitch;      //!< Pitch angle in degrees
   };
 
   //! \brief Structure defining a player station configuration
   //!
   //! Contains the information needed to set up a player station,
   //! including which entity to control and how to display it.
   struct StationDefinition
   {
      DtEntityIdentifier entityId; //!< Identifier of the entity to control
      std::string stationName;     //!< Name of the role or station
      std::string displayLayout;   //!< Name of the display layout to use
   };
 
   //! \brief Structure for entity attachment configuration
   //!
   //! Contains the configuration for attaching to an existing entity,
   //! including role and display layout information.
   struct AttachToEntity
   {
      std::string name;          //!< Name of the entity to attach to
      std::string displayLayout; //!< Display layout to use
      std::string role;          //!< Role to play in the entity
      bool spectator;            //!< Whether to attach as a spectator
   };
 
   //! \brief Message handlers
   //! @{
 
   //! \brief Handles messages about newly created ownship entities
   //! \param message Pointer to the message about the new entity
   //! \return Message handling result
   virtual DtVreMessageResult handleNewOwnshipCreated(DtVreMessage* message);
 
   //! \brief Handles messages about entities being realized in the simulation
   //! \param message Pointer to the entity realization message
   //! \return Message handling result
   virtual DtVreMessageResult handleEntityRealized(DtVreMessage* message);
 
   //! \brief Handles messages about application mode changes
   //! \param message Pointer to the application mode message
   //! \return Message handling result
   virtual DtVreMessageResult handleApplicationMode(makVre::DtVreMessage* message);
 
   //! \brief Handles escape key press messages
   //! \param msg Pointer to the key press message
   //! \return Message handling result
   virtual DtVreMessageResult handleEscKey(DtVreMessage* msg);
 
   //! \brief Handles back button click messages
   //! \param msg Pointer to the button click message
   //! \return Message handling result
   virtual DtVreMessageResult handleBackButtonClicked(DtVreMessage* msg);
   //! \brief Handles choose role button click messages
   //! \param msg Pointer to the button click message
   //! \return Message handling result
   virtual DtVreMessageResult handleChooseRoleButtonClicked(DtVreMessage* msg);
 
   //! \brief Handles VRF rewind messages
   //! \param msg Pointer to the rewind message
   //! \return Message handling result
   virtual DtVreMessageResult handleVrfRewind(DtVreMessage* msg);
   //! @}
 
   //! \brief Entity management methods
   //! @{
 
   //! \brief Creates a new entity in the simulation
   //!
   //! Uses the information in myNewEntityDef to create a new entity
   //! in the simulation and start tracking its realization.
   virtual void createNewEntity();
 
   //! \brief Updates an existing new entity
   //! \return True if the update was successful, false otherwise
   //!
   //! Applies changes from myNewEntityDef to the entity that is
   //! currently being created or modified.
   virtual bool updateNewEntity();
 
   //! \brief Destroys a new entity that was being created
   //!
   //! Removes the entity that was being created from the simulation.
   //! Typically called when canceling entity creation or during cleanup.
   virtual void destroyNewEntity();
 
   //! \brief Checks if a new ownship entity has been realized
   //! \return True if the entity exists and is ready, false otherwise
   //!
   //! Determines whether a newly created entity has been fully
   //! realized in the simulation and is ready for interaction.
   virtual bool haveNewRealizedOwnshipEntity() const;
 
   //! \brief Called when a new ownship entity is realized
   //!
   //! Handles the completion of entity creation, transitioning
   //! to the next step in the engagement process.
   virtual void onNewOwnshipRealized();
   //! @}
 
   //! \brief Gets the display layout for a station
   //! \param station Station definition to get layout for
   //! \return Name of the display layout to use
   //!
   //! Determines the appropriate display layout for the given station,
   //! using defaults if necessary.
   virtual std::string getDisplayLayout(const StationDefinition& station) const;
 
   //! \brief Validates an entity definition
   //! \param def Entity definition to validate
   //! \param error Optional pointer to receive error message
   //! \return True if the definition is valid, false otherwise
   //!
   //! Checks whether an entity definition contains all the required
   //! information to create a valid entity.
   virtual bool verifyEntityDefinition(EntityDefinition const& def, QString* error = NULL) const;
 
   //! \brief Validates a station definition
   //! \param def Station definition to validate
   //! \param error Optional pointer to receive error message
   //! \return True if the definition is valid, false otherwise
   //!
   //! Checks whether a station definition contains all the required
   //! information to set up a player station.
   virtual bool verifyStationDefinition(StationDefinition const& def, QString* error = NULL) const;
 
   //! \brief Flag indicating whether to create a new entity
   bool myWantNewEntity;
 
   //! \brief Flag indicating that entity creation is in progress
   bool myAwaitingNewRealizedEntity;
 
   //! \brief Flag indicating that a new entity has been created
   bool myHaveNewEntity;
 
   //! \brief Definition of the entity to create
   EntityDefinition myNewEntityDef;
 
   //! \brief Definition of the station to set up
   StationDefinition myStationDef;
 
   //! \brief Identifier of the host entity for embarking
   DtEntityIdentifier myHostId;
 
   //! \brief Offset from the host entity for embarking
   DtVector myHostOffset;
 
   //! \brief Flags indicating which entity properties have changed
   //!
   //! Used to track which properties of the entity definition have been
   //! modified and need to be updated in the simulation.
   enum DirtyBits
   {
      DirtyName = 1 << 0,     //!< Entity name has changed
      DirtyType = 1 << 1,     //!< Entity type has changed
      DirtyForce = 1 << 2,    //!< Entity force type has changed
      DirtyPosition = 1 << 3, //!< Entity position has changed
      DirtyHeading = 1 << 4,  //!< Entity heading has changed
      DirtyPitch = 1 << 5,    //!< Entity pitch has changed
      DirtyRoll = 1 << 6      //!< Entity roll has changed
   };
 
   //! \brief Bitmap of dirty flags for the entity definition
   int myDirtyBits;
 
   //! \brief Pointer to the entity selection panel UI
   DtChooseRolePanel* myEntityPanel;
 
   //! \brief Shared pointer to the role selection page
   std::shared_ptr<DtVreChooseRolePage> myChooseRolePage;
 
   //! \brief Shared pointer to the entity attachment configuration
   std::shared_ptr<AttachToEntity> myAttachToEntity;
};
 
} // namespace makVre