actionMenuLogic.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file actionMenuLogic.h
//! \brief Defines the action menu management and logic for VR-Engage
//!
//! This file contains the DtActionMenuLogic class which manages the interaction
//! menus for entities in the simulation. It controls the visibility and behavior
//! of action menus, processes entity interactions, and handles user selections.
//! The class manages both static action menus and context-sensitive quick menus
//! that appear when the player approaches interactive objects.
 
#pragma once
 
#include "vrePlayerStation/export.h"
#include "vrePlayerStation/playerComponent.h"
#include "vrePlayerStation/inputLogic.h"
 
#include <vreCommonComponents/deployableObjectsSimLogic.h>
 
#include "vreMessages/menuSetState.h"
#include "vreMessages/EntityEmbarkationInformation.h"
 
#include <matrix/vlVector.h>
 
namespace makVre
{
 
namespace ActionMenuLogicConfig
{
//! \ingroup RoleConfigParams
//! \defgroup ActionMenuLogicRoleParams Action Menu Logic Role Parameters
//! \roleInherits{PlayerComponentRoleParams}
//! Configuration Options for action menu logic component.
//! @{
 
//! \vreRoleParam{entityQuickMenus,table,{},actionMenuLogic,Configuration table defining quick menus for different entity types and interaction contexts.}
constexpr const char* entityQuickMenus = "entityQuickMenus";
 
//! \vreRoleParam{slotProximityAngleWeight,double,varies,actionMenuLogic,Weight factor for angle consideration in slot proximity calculations.}
constexpr const char* slotProximityAngleWeight = "slotProximityAngleWeight";
 
//! \vreRoleParam{slotProximityFov,double,varies,actionMenuLogic,Field of view angle in degrees for slot proximity detection.}
constexpr const char* slotProximityFov = "slotProximityFov";
 
//! \vreRoleParam{slotProximityMaxDistance,double,varies,actionMenuLogic,Maximum distance in meters for slot proximity detection.}
constexpr const char* slotProximityMaxDistance = "slotProximityMaxDistance";
 
//! \vreRoleParam{slotProximityOverlapDist,double,varies,actionMenuLogic,Distance threshold for handling overlapping slot proximity zones.}
constexpr const char* slotProximityOverlapDist = "slotProximityOverlapDist";
 
//! \vreRoleParam{slotProximityRearMaxDist,double,varies,actionMenuLogic,Maximum distance for rear-facing slot proximity detection.}
constexpr const char* slotProximityRearMaxDist = "slotProximityRearMaxDist";
 
//! \vreRoleParam{slotProximityZScale,double,varies,actionMenuLogic,Z-axis scaling factor for slot proximity calculations.}
constexpr const char* slotProximityZScale = "slotProximityZScale";
 
//! @}
} // namespace ActionMenuLogicConfig
 
} // namespace makVre
 
namespace makVrv
{
class DtSceneObject;
}
 
namespace makVre
{
class DtActionJoystickControl;
class DtActionMenuEventProcessor;
class DtMenuManager;
 
//! \brief Type identifier constant for DtActionMenuLogic components
//!
//! This constant defines the string identifier used to identify DtActionMenuLogic
//! component types within the VR-Engage framework. It is used for component
//! registration, type checking, and serialization operations.
constexpr const char* DtActionMenuLogicType = "DtActionMenuLogic";
 
//! \brief Component for managing entity interaction menus and their logic
//!
//! DtActionMenuLogic is responsible for handling all user interaction menus
//! in VR-Engage. It manages both static menus (like the main action menu) and
//! context-sensitive quick menus that appear when the player approaches interactive
//! objects like vehicles for embarkation, control stations, or other entities with
//! interaction points.
//!
//! The class processes entity proximity, evaluates interaction conditions, and
//! provides the appropriate menu options based on the current context. It also
//! handles menu selections and dispatches the appropriate actions in response.
class PLAYERSTATION_DLL DtActionMenuLogic : public DtPlayerComponent
{
public:
   //! \brief Constructor
   //!
   //! Creates a new action menu logic component with default state.
   DtActionMenuLogic();
 
   //! \brief Virtual destructor
   //!
   //! Ensures proper cleanup of derived action menu logic classes.
   virtual ~DtActionMenuLogic() override;
 
   //! \brief Gets the menu manager instance
   //! \return Pointer to the menu manager
   //!
   //! Provides access to the menu manager that controls all menus for this
   //! player station instance. The menu manager handles the creation, organization,
   //! and display of menus.
   virtual DtMenuManager* getMenuManager() const;
 
   //! \brief Initializes the action menu logic
   //! \param player Pointer to the owning player station
   //! \param config Configuration data for initialization
   //! \return True if initialization succeeded, false otherwise
   //!
   //! Sets up the action menu system based on the provided configuration.
   //! This includes loading menu definitions, setting up input handlers,
   //! and initializing the menu manager.
   virtual bool initialize(DtPlayerStation* player, DtInitTable& config) override;
 
   //! \brief Performs post-initialization setup
   //! \return True if post-initialization succeeded, false otherwise
   //!
   //! Completes setup tasks that need to occur after basic initialization,
   //! such as connecting to message handlers and setting up callbacks.
   virtual bool postInitialize() override;
 
   //! \brief Updates the menu system
   //! \param dt Time interval since the last tick in seconds
   //!
   //! Called once per frame to update the menu system. This includes checking
   //! for proximity to interaction points, updating menu visibility, and
   //! processing any pending menu actions.
   virtual void tick(double dt) override;
 
   //! \brief Shuts down the action menu system
   //!
   //! Performs cleanup when the action menu system is no longer needed.
   //! This includes disconnecting from message handlers, removing input
   //! handlers, and destroying menu resources.
   virtual void shutdown() override;
 
   //! \brief Returns the component type identifier
   //! \return String identifier for this component type
   //!
   //! Returns the type identifier string for this component, which is used
   //! by the VR-Engage framework for component identification and management.
   //! The returned value matches DtActionMenuLogicType.
   virtual const char* type() const override;
 
   //! \brief Handles changes in player embarkation state
   //! \param embarked True if the player is now embarked, false if disembarked
   //!
   //! Called when the player's embarkation state changes. This affects the
   //! available menu options, as different actions are available depending on
   //! whether the player is on foot or in a vehicle.
   virtual void handleEmbarkedChanged(bool embarked);
 
   //! \brief Handles changes in player aiming state
   //! \param aiming True if the player is now aiming, false otherwise
   //!
   //! Called when the player's aiming state changes. This may affect menu
   //! visibility and available options, as some menus may be disabled while aiming.
   virtual void handleAimingChanged(bool aiming);
 
   //! \brief Handles changes in player health
   //! \param health New health value
   //!
   //! Called when the player's health changes. This may affect available menu
   //! options, such as enabling medical actions when health is low.
   virtual void handleHealthChanged(double health);
 
   //! \brief Handles changes in deployed objects list
   //! \param deployableObjects Map of deployed object identifiers to entity data
   //!
   //! Called when the list of player-deployed objects (like sensors, markers, etc.)
   //! changes. This affects the available menu options for interacting with
   //! deployed objects.
   virtual void handleDeployableObjectsChanged(
      DtDeployableObjectsSimLogic::DeployableObjectStateMap deployableObjects);
 
   //! \brief Shows a specific menu
   //! \param name Name of the menu to show (defaults to "Action" for main menu)
   //! \param type Type of menu display (static or dynamic/contextual)
   //! \param selection Initial selection to make in the menu
   //!
   //! Displays the specified menu to the user. The menu type determines how it
   //! behaves - static menus remain open until explicitly closed, while dynamic
   //! menus may close automatically after selection or when context changes.
   virtual void showMenu(const std::string& name = "Action",
      MenuSetStateMessage::Type type = MenuSetStateMessage::Type_STATIC, const std::string& selection = "");
 
   //! \brief Hides a specific menu
   //! \param name Name of the menu to hide
   //!
   //! Hides the specified menu if it is currently visible.
   virtual void hideMenu(const std::string& name);
 
   //! \brief Hides the currently active quick menu
   //!
   //! Hides any context-sensitive quick menu that is currently visible.
   //! Quick menus appear when the player approaches interactive objects.
   virtual void hideQuickMenu();
 
   //! \brief Toggles the main action menu
   //! \param val Input value (typically 1.0 for full toggle)
   //!
   //! Toggles the visibility of the main action menu. If it's currently
   //! visible, it will be hidden; if hidden, it will be shown. The value
   //! parameter supports analog inputs like joysticks.
   virtual void toggleActionMenu(float val = 1);
 
   //! \brief Gets the entity ID associated with the current quick menu
   //! \return Entity identifier for the current quick menu target
   //!
   //! Returns the identifier of the entity that the current quick menu
   //! is associated with (e.g., a vehicle the player is interacting with).
   //! Returns an empty identifier if no quick menu is active.
   virtual DtEntityIdentifier currentQuickMenuEntityId();
 
protected:
   //! \brief Updates the current action object
   //! \param entityId Identifier of the entity to set as the current action object
   //! \param entityType Type of the entity
   //! \param marking Entity marking or name
   //!
   //! Sets the specified entity as the current action object, which affects
   //! the available menu options and context-sensitive actions.
   virtual void updateActionObject(
      const DtEntityIdentifier& entityId, const DtEntityType& entityType, const std::string& marking);
 
   //! \brief Checks if menu display conditions are met
   //! \return True if conditions for displaying menus are satisfied
   //!
   //! Evaluates the current state to determine if menus should be displayed.
   //! This considers factors like player posture, health, and context.
   virtual bool checkMenuDisplayConditionsMet();
 
   //! \brief Updates quick menu visibility based on current state
   //!
   //! Determines whether context-sensitive quick menus should be shown or hidden
   //! based on proximity to interactive objects and other conditions.
   virtual void updateQuickMenuVisibility();
 
   //! \brief Checks if action points in an entity's embarkation message are actionable
   //! \param msg The embarkation information message to evaluate
   //! \return True if any action points are actionable, false otherwise
   //!
   //! Examines embarkation information to determine if any action points
   //! (like entry points, control stations, etc.) are within interactive range.
   virtual bool checkActionPointListActionable(const EntityEmbarkationInformationMessage& msg);
 
   //! \brief Processes action points for a slotted entity
   //! \param msg Embarkation information message containing action point data
   //! \return True if action points were successfully processed
   //!
   //! Analyzes and processes action points for slotted entities (like vehicles
   //! with multiple seats/positions), determining which are actionable and
   //! should appear in menus.
   virtual bool processSlotActionPoints(const EntityEmbarkationInformationMessage& msg);
 
   //! \brief Finds the coordinate transformations needed for action point processing
   //! \param obj Scene object representing the entity with action points
   //! \param ownPos Output parameter for player's position
   //! \param objPos Output parameter for object's position
   //! \param worldToOwnRot Output parameter for world-to-player rotation matrix
   //! \param objToWorldRot Output parameter for object-to-world rotation matrix
   //! \return True if transforms were successfully computed
   //!
   //! Calculates the positions and rotation matrices needed to transform action points
   //! from object space to world space for distance and angle calculations.
   virtual bool findTransformsForSlotPointProcessing(const makVrv::DtSceneObject* obj, DtVector& ownPos,
      DtVector& objPos, DtDcm& worldToOwnRot, DtDcm& objToWorldRot) const;
 
   //! \brief Identifies actionable points based on proximity and orientation
   //! \param ownPos Player's position
   //! \param objPos Object's position
   //! \param worldToOwnRot World-to-player rotation matrix
   //! \param objToWorldRot Object-to-world rotation matrix
   //! \param actionPoints List of action points to evaluate
   //! \return True if any actionable points were found
   //!
   //! Analyzes each action point to determine if it's within actionable range
   //! and orientation relative to the player, scoring them for priority.
   virtual bool findActionablePoints(const DtVector& ownPos, const DtVector& objPos, const DtDcm& worldToOwnRot,
      const DtDcm& objToWorldRot, const std::vector<EntityEmbarkationInformationMessage::ActionPoint>& actionPoints);
 
   //! \brief Scores an action point for actionability
   //! \param vecToPoint Vector from player to action point
   //! \param maxDist Maximum distance for actionability
   //! \param retScore Output parameter for the computed score
   //! \return True if the action point is within actionable range
   //!
   //! Computes a score for an action point based on distance and orientation
   //! relative to the player. Higher scores indicate more easily accessible points.
   virtual bool scoreActionPoint(DtVector vecToPoint, double maxDist, double& retScore);
 
   //! \brief Modifies a vector to an action point before scoring
   //! \param vecToPoint Vector to modify
   //!
   //! Applies adjustments to the vector from player to action point before
   //! scoring, such as scaling components or normalizing.
   virtual void modifyActionPointVectorBeforeScore(DtVector& vecToPoint);
 
   //! \brief Combines dot product and distance scores
   //! \param dotScore Score based on dot product (angle)
   //! \param distScore Score based on distance
   //! \return Combined score
   //!
   //! Combines the orientation and distance scores into a single value
   //! representing the overall accessibility of an action point.
   virtual double combineDotAndDistScore(double dotScore, double distScore);
 
   //! \brief Handles sensor update messages
   //! \param message Pointer to the sensor update message
   //! \return Message handling result
   //!
   //! Processes sensor update messages that may affect menu options
   //! for sensor-related actions.
   virtual DtVreMessageResult handleSensorUpdate(DtVreMessage* message);
 
   //! \brief Handles entity state boolean messages
   //! \param msg Pointer to the entity state message
   //! \return Message handling result
   //!
   //! Processes boolean state changes for entities that may affect
   //! menu visibility and available options.
   virtual DtVreMessageResult handleEntityStateBool(DtVreMessage* msg);
 
   //! \brief Handles embarkation information messages
   //! \param msg Pointer to the embarkation information message
   //! \return Message handling result
   //!
   //! Processes embarkation information that describes interaction points
   //! for entities like vehicles, which affects quick menu availability.
   virtual DtVreMessageResult handleEntityEmbarkationInformationMessage(DtVreMessage* msg);
 
   //! \brief Handles menu state messages
   //! \param msg Pointer to the menu message
   //! \return Message handling result
   //!
   //! Processes messages related to menu state changes, such as requests
   //! to show or hide specific menus.
   virtual DtVreMessageResult handleMenuMessage(DtVreMessage* msg);
 
   //! \brief Handles menu action messages
   //! \param msg Pointer to the menu action message
   //! \return Message handling result
   //!
   //! Processes action messages generated when a user selects an option
   //! from a menu, executing the corresponding action.
   virtual DtVreMessageResult handleMenuAction(DtVreMessage* msg);
 
   //! \brief Handles entity discovery messages
   //! \param msg Pointer to the entity discovered message
   //! \return Message handling result
   //!
   //! Processes notifications about newly discovered entities that
   //! may be candidates for interaction menus.
   virtual DtVreMessageResult handleEntityDiscovered(DtVreMessage* msg);
 
   //! \brief Handles entity removal messages
   //! \param msg Pointer to the entity removed message
   //! \return Message handling result
   //!
   //! Processes notifications about entities being removed from the
   //! simulation, cleaning up any associated menu resources.
   virtual DtVreMessageResult handleEntityRemoved(DtVreMessage* msg);
 
   //! \brief Handles responses to entity type queries
   //! \param msg Pointer to the response message
   //! \return Message handling result
   //!
   //! Processes responses to queries about entities of specific types,
   //! which may affect available menu options for type-specific actions.
   virtual DtVreMessageResult handleRequestEntitiesByTypeResponse(DtVreMessage* msg);
 
   //! \brief Handles session play state changes
   //! \param msg Pointer to the session play state message
   //! \return Message handling result
   //!
   //! Processes notifications about simulation session state changes
   //! (e.g., paused, playing, stopped), which may affect menu availability.
   virtual DtVreMessageResult handleSessionPlayState(DtVreMessage* msg);
 
   //! \brief Checks if an entity ID corresponds to a deployed object
   //! \param entityId The entity identifier to check
   //! \return True if the entity is a deployable object, false otherwise
   //!
   //! Determines whether the specified entity is one of the player's
   //! deployable objects (like sensors, markers, etc.).
   virtual bool entityIdIsDeployableObject(const DtEntityIdentifier& entityId);
 
   //! \brief Checks if the player has a ground vehicle license
   //! \return True if the player has a ground vehicle license, false otherwise
   //!
   //! Checks state attribute "GroundVehicleEnabled" to determine if player has a ground vehicle license.
   virtual bool groundVehicleIsEnabled() const;
 
   //! \brief Checks if a vehicle has an implicit driver
   //! \param vehicleId Identifier of the vehicle to check
   //! \return True if the vehicle has an implicit driver, false otherwise
   //!
   //! Checks if given vehicle has an implicit driver (a visual-only model of a driver occupant).
   virtual bool vehicleHasImplicitDriver(const DtEntityIdentifier& vehicleId) const;
 
   //! \brief Input logic handler for menu interactions
   //!
   //! Manages input mapping and handling for menu navigation and selection.
   DtInputLogic myInputLogic;
 
   //! \brief Configuration table for quick menus
   DtInitTable myQuickMenuTable;
 
   //! \brief Name of the currently active quick menu
   std::string myCurrentQuickMenu;
 
   //! \brief Entity ID associated with the current quick menu
   DtEntityIdentifier myCurrentQuickMenuEntityId;
 
   //! \brief Entity type of the current quick menu target
   DtEntityType myCurrentQuickMenuEntityType;
 
   //! \brief Flag indicating if the current entity is a host entity
   bool myCurrentEntityIsHost;
 
   //! \brief Flag indicating if the current entity supports VRE slots
   bool myCurrentEntitySupportsVreSlots;
 
   //! \brief Last received embarkation information message
   //!
   //! Stores the most recent embarkation information for slot processing,
   //! containing action points and slot details for interactive entities.
   EntityEmbarkationInformationMessage myLastSlotDataMessage;
 
   //! \brief Timer for quick menu slot proximity checks
   //!
   //! Controls how frequently slot proximity is checked for quick menu updates.
   double myQuickMenuSlotTickTimer;
 
   //! \brief Maximum distance for slot proximity detection
   //!
   //! The maximum distance at which slots/action points are considered actionable.
   double mySlotProximityMaxDistance;
 
   //! \brief Scaling factor for vertical (Z) distance in proximity calculations
   //!
   //! Adjusts the importance of vertical distance in determining proximity to action points.
   double mySlotProximityZScale;
 
   //! \brief Weight given to angle in proximity calculations
   //!
   //! Determines how heavily the angle between player and action point affects actionability.
   double mySlotProximityAngleWeight;
 
   //! \brief Field of view angle for forward-facing action points
   //!
   //! The angle (in radians) defining the forward field of view within which
   //! action points are more easily actionable.
   double mySlotProximityFov;
 
   //! \brief Maximum distance for rear-facing action points
   //!
   //! The maximum distance at which action points behind the player are actionable.
   double mySlotProximityRearMaxDist;
 
   //! \brief Distance overlap tolerance for action points
   //!
   //! The distance by which action point ranges can overlap before prioritization occurs.
   double mySlotProximityOverlapDist;
 
   //! \brief Map of actionable points and their priority scores
   //!
   //! Maps action point identifiers to their calculated priority scores.
   std::map<std::string, int> myActionablePointsMap;
 
   //! \brief Last notification or hint displayed to the user
   //!
   //! Stores the text of the last note shown to avoid duplicate notifications.
   std::string myLastNote;
 
   //! \brief Location of the current task objective
   //!
   //! Stores the position of the current objective or task target.
   DtVector myTaskLocation;
 
   //! \brief Flag to toggle debug menu visibility
   //!
   //! Controls whether debug menus are shown for development and testing.
   bool myDebugMenuToggle;
 
   //! \brief Type definition for waypoint maps
   //!
   //! Maps waypoint identifiers to waypoint information.
   using WaypointMap = std::map<std::string, std::string>;
 
   //! \brief Type definition for route maps
   //!
   //! Maps route identifiers to route information.
   using RouteMap = std::map<std::string, std::string>;
 
   //! \brief Type definition for bullseye maps
   //!
   //! Maps bullseye identifiers to bullseye information.
   //! Used to show VRF Bullseye list in VRE pilot Set Bullseye menu.
   using BullseyeMap = std::map<std::string, std::string>;
};
 
} // namespace makVre