engagedState.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file engagedState.h
//! \brief Defines the DtEngagedState class for gameplay control
//!
//! This file contains the DtEngagedState class which represents the application
//! state where the user is actively controlling an entity in the simulation.
//! This state handles gameplay-related messages, controls, and transitions
//! while the player is engaged with a role.
 
#pragma once
 
#include "vrePlayerStation/export.h"
#include "vrePlayerStation/playerStationState.h"
#include <vrvCore/DtUniqueID.h>
 
#include "vreMessageManager/vreMessage.h"
 
namespace makVre
{
//! \brief Forward declaration of the player station application class
class DtPlayerStationApp;
 
//! \brief Forward declaration of the persistent notification class
class DtPlayerStationPersistentNotification;
 
//! \brief Application state for active entity control and gameplay
//!
//! DtEngagedState represents the application state where the user is actively
//! controlling an entity in the simulation. It manages gameplay controls,
//! processes relevant messages, and handles transitions between gameplay-related
//! states such as pausing and resuming. This state is typically nested within
//! the network connected state.
class PLAYERSTATION_DLL DtEngagedState : virtual public DtPlayerStationState
{
public:
   //! \brief Constructor
   //! \param app Reference to the player station application
   //!
   //! Creates a new engaged state associated with the given application.
   DtEngagedState(DtPlayerStationApp& app);
 
   //! \brief Virtual destructor
   //!
   //! Ensures proper cleanup of the engaged state resources.
   virtual ~DtEngagedState() override;
 
   //! \brief Called when the state is entered
   //! \param args Pointer to arguments from the previous state
   //!
   //! Sets up the gameplay environment, registers message handlers,
   //! and initializes the player controls. This is called when the player
   //! first enters the engaged state, typically after selecting a role.
   virtual void onEnter(const DtPlayerStationStateArgs* args) override;
 
   //! \brief Called when the state is exited
   //!
   //! Cleans up resources, disconnects from the controlled entity,
   //! and unregisters message handlers. This is called when the player
   //! leaves the engaged state, typically when disengaging from a role.
   virtual void onExit() override;
 
   //! \brief Updates the state each frame
   //! \param dt Time in seconds since the last update
   //!
   //! Handles per-frame processing for gameplay, including checking
   //! for entity status changes and updating UI elements as needed.
   virtual void tick(double dt) override;
 
   //! \brief Called when the state becomes the topmost state again
   //!
   //! Restores gameplay functionality when this state is exposed
   //! after another state (like a menu) has been popped from the stack.
   virtual void onExposed() override;
 
   //! \brief Called when another state is pushed on top of this one
   //!
   //! Temporarily disables certain gameplay functionality while this state
   //! is covered by another state on the stack, such as a pause menu.
   virtual void onStacked() override;
 
   //! \brief Checks if the simulation is currently playing
   //! \return True if the simulation is playing, false if paused
   //!
   //! Reports whether the simulation is currently in a playing state
   //! or if it's paused. This affects how inputs are processed.
   virtual bool isPlaying() const;
 
   //! \brief Handles escape key press messages
   //! \param message Pointer to the key press message
   //! \return Message handling result
   //!
   //! Processes escape key presses, typically bringing up the pause menu
   //! or other options during gameplay.
   virtual DtVreMessageResult handleEscKey(DtVreMessage* message);
 
   //! \brief Handles back button click messages
   //! \param message Pointer to the button click message
   //! \return Message handling result
   //!
   //! Processes back button clicks, typically navigating back to a previous
   //! screen or opening the pause menu during gameplay.
   virtual DtVreMessageResult handleBackButtonClicked(DtVreMessage* message);
 
protected:
   //! \brief Message handlers for role assignment
   //! @{
 
   //! \brief Handles role assignment messages
   //! \param message Pointer to the role assignment message
   //! \return Message handling result
   //!
   //! Processes messages relating to assigning roles to players.
   virtual DtVreMessageResult handleAssignRolePlayer(DtVreMessage* message);
 
   //! \brief Handles role unassignment messages
   //! \param message Pointer to the role unassignment message
   //! \return Message handling result
   //!
   //! Processes messages relating to removing players from roles.
   virtual DtVreMessageResult handleUnassignRolePlayer(DtVreMessage* message);
 
   //! \brief Handles entity removal messages
   //! \param message Pointer to the entity removal message
   //! \return Message handling result
   //!
   //! Processes messages relating to entities being removed from the simulation,
   //! which may require disengaging if the player's entity is removed.
   virtual DtVreMessageResult handleEntityRemoved(DtVreMessage* message);
 
   //! \brief Handles choose role button click messages
   //! \param message Pointer to the button click message
   //! \return Message handling result
   //!
   //! Processes clicking the choose role button, typically returning
   //! to the role selection screen from gameplay.
   virtual DtVreMessageResult handleChooseRoleButtonClicked(DtVreMessage* message);
   //! @}
 
   //! \brief Handles simulation state update messages
   //! \param msg Pointer to the simulation state message
   //! \return Message handling result
   //!
   //! Processes simulation state updates, particularly tracking changes
   //! to embarkation status that might affect the player's entity.
   virtual DtVreMessageResult handleSimulationStateMessage(makVre::DtVreMessage* msg);
 
   //! \brief Handles entity element removal signals
   //! \param elementId ID of the removed element
   //!
   //! Callback for EntityResolver signals when elements are removed.
   //! Used to detect when the player's controlled entity is removed
   //! from the simulation, which requires disengagement.
   void elementRemoved(makVrv::DtElementID elementId);
 
   //! \brief Handles session play state messages
   //! \param message Pointer to the play state message
   //! \return Message handling result
   //!
   //! Processes messages about changes to the session's play state
   //! (playing/paused), updating UI and control systems accordingly.
   virtual DtVreMessageResult handleSessionPlayState(DtVreMessage* message);
 
   //! \brief Handles modal dialog state messages
   //! \param message Pointer to the modal state message
   //! \return Message handling result
   //!
   //! Processes messages about modal dialogs opening or closing,
   //! adjusting gameplay controls and input handling accordingly.
   virtual DtVreMessageResult handleModalState(DtVreMessage* message);
 
   //! \brief Handles VR-Forces simulation rewind messages
   //! \param message Pointer to the VrfRewindMessage
   //! \return Message handling result (HANDLED)
   //!
   //! Processes rewind requests from VR-Forces, transitioning the player
   //! back to the role selection state. The rewind message is copied and
   //! passed as state arguments to allow the choose role state to clean up
   //! and reset appropriately.
   virtual DtVreMessageResult handleVrfRewind(DtVreMessage* message);
 
   //! \brief Updates the state of player controls
   //!
   //! Enables or disables player controls based on current application state,
   //! such as whether the simulation is playing, paused, or a modal dialog is open.
   //! This ensures that controls are only active when appropriate.
   virtual void updatePlayerControlsState();
 
   //! \brief Updates player state after embarkation changes
   //!
   //! Called when embarkation status changes, such as when getting in
   //! or out of a vehicle, to update UI and control systems accordingly.
   virtual void updatePlayersForEmbarkationChange();
 
   //! \brief Starts the player station with default settings
   //! \return True if startup was successful, false otherwise
   //!
   //! Initializes the player station for the current entity and role
   //! using the default station configuration.
   virtual bool startPlayerStation();
 
   //! \brief Starts the player station with specific entity and station
   //! \param entityId Identifier of the entity to control
   //! \param station Name of the station or role to use
   //! \return True if startup was successful, false otherwise
   //!
   //! Initializes the player station for a specific entity and role,
   //! typically used when switching entities or roles during gameplay.
   virtual bool startPlayerStation(const DtEntityIdentifier& entityId, const std::string& station);
 
   //! \brief Ensures the application window has focus before engaging
   //!
   //! Checks if the application currently has active focus, and if not,
   //! attempts to activate and raise the main window. This is called before
   //! creating a player station to ensure that entity control logic has the
   //! correct focus state for activating mouse control.
   //!
   //! \note Uses Qt window activation methods to bring the window to front
   //! \see startPlayerStation()
   virtual void activateWindowFocus();
 
protected:
   //! \brief Persistent notification displayed during gameplay
   std::shared_ptr<DtPlayerStationPersistentNotification> myPersistentNotification;
 
   //! \brief Flag indicating whether the simulation is currently playing
   bool myIsPlaying;
 
   //! \brief Flag indicating whether a modal dialog is currently open
   bool myIsModalOpen;
 
   //! \brief Connection to the entity removed signal
   boost::signals2::connection myEntityRemovedConnection;
 
   //! \brief Role name for embarked player
   std::string myBasePlayerEmbarkedRole;
 
   //! \brief Entity identifier of the host entity for embarked player
   DtEntityIdentifier myBasePlayerHost;
 
   //! \brief Flag indicating whether the player entity is invisible
   bool myBasePlayerIsInvisible;
 
   //! \brief Flag indicating that the entity state has changed
   bool myOhMySomethingHasChanged;
};
} // namespace makVre