humanControlLogic.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file humanControlLogic.h
//! \brief Defines DtHumanControlLogic for managing human entity controls and interactions
//! \ingroup vreHumanFrontend
 
#pragma once
 
#include "vreHumanFrontend/export.h"
 
#include "vreCommonComponents/stateDefines.h"
#include "vrePlayerStation/entityControlLogic.h"
#include "vreMessageManager/vreMessage.h"
 
#include <vrvCore/DtUniqueID.h>
 
#include <matrix/vlVector.h>
 
#include <vector>
#include <matrix/vlVector.inl>       // for DtVector64::DtVector64, DtVector64::operator=
#include <vlpi/entityIdentifier.inl> // for DtEntityIdentifier::DtEntityIdentifier, DtEntityIdentifier::operator=
#include <vlpi/entityType.h>         // for DtEntityType
#include <xstring>                   // for string, basic_string
 
namespace makVrv
{
//! \brief Forward declaration of the observer class
class DtObserver;
} // namespace makVrv
 
namespace makVre
{
//! \brief Forward declaration of the human input logic class
class DtHumanInputLogic;
 
//! \brief Forward declaration of the initialization table class
class DtInitTable;
 
//! \brief Forward declaration of the weapon resource logic class
class DtWeaponResourceLogic;
 
//! \brief Forward declaration of the Qt quick overlay class
class DtQtQuickOverlay;
 
//! \brief Forward declaration of the human virtual reality logic class
class DtHumanVirtualRealityLogic;
 
namespace HumanControlLogicConfig
{
//! \ingroup RoleConfigParams
//! \defgroup HumanControlLogicRoleParams Human Control Logic Role Parameters
//! \roleInherits{EntityControlLogicRoleParams}
//! Configuration Options for humanControlLogic role.
//! @{
 
//! \vreRoleParam{aimMultiplier,double,0.46666667,humanControlLogic,Movement speed multiplier when aiming weapons.}
constexpr const char* aimMultiplier = "aimMultiplier";
 
//! \vreRoleParam{aimingErrorCalcDistanceToTarget,double,1.0,humanControlLogic,Target distance in meters used for aiming error calculations.}
constexpr const char* aimingErrorCalcDistanceToTarget = "aimingErrorCalcDistanceToTarget";
 
//! \vreRoleParam{aimingErrorCalcMaxSpread,double,0.0,humanControlLogic,Maximum aiming spread in inches for error calculations.}
constexpr const char* aimingErrorCalcMaxSpread = "aimingErrorCalcMaxSpread";
 
//! \vreRoleParam{aimingImprovementPercent,double,1.0,humanControlLogic,Percentage value (0-1) for general aiming improvement.}
constexpr const char* aimingImprovementPercent = "aimingImprovementPercent";
 
//! \vreRoleParam{binocularsInputMultiplier,double,0.5,humanControlLogic,Input sensitivity multiplier when using binoculars.}
constexpr const char* binocularsInputMultiplier = "binocularsInputMultiplier";
 
//! \vreRoleParam{compassUnits,string,"Degrees",humanControlLogic,Units for compass display ("Degrees" or "NATO-MIL").}
constexpr const char* compassUnits = "compassUnits";
 
//! \vreRoleParam{invertPitchInput,bool,false,humanControlLogic,Whether to invert pitch input controls.}
constexpr const char* invertPitchInput = "invertPitchInput";
 
//! \vreRoleParam{isAllowedThirdPersonView,bool,false,humanControlLogic,Whether third-person view mode is allowed.}
constexpr const char* isAllowedThirdPersonView = "isAllowedThirdPersonView";
 
//! \vreRoleParam{joystickSensitivity,double,3.0,humanControlLogic,Sensitivity multiplier for joystick input.}
constexpr const char* joystickSensitivity = "joystickSensitivity";
 
//! \vreRoleParam{moveDelays,table,{},humanControlLogic,Table of posture change animation delays and timing.}
constexpr const char* moveDelays = "moveDelays";
 
//! \vreRoleParam{moveLockedPostures,table,{},humanControlLogic,Table of postures that prevent movement.}
constexpr const char* moveLockedPostures = "moveLockedPostures";
 
//! \vreRoleParam{postureSequence,table,{},humanControlLogic,Table defining the sequence of available postures.}
constexpr const char* postureSequence = "postureSequence";
 
//! \vreRoleParam{proneAimingImprovementPercent,double,1.0,humanControlLogic,Percentage value (0-1) for aiming improvement when prone.}
constexpr const char* proneAimingImprovementPercent = "proneAimingImprovementPercent";
 
//! \vreRoleParam{raiseGunOnAttach,bool,false,humanControlLogic,Whether to automatically raise weapon when attaching to entity.}
constexpr const char* raiseGunOnAttach = "raiseGunOnAttach";
 
//! \vreRoleParam{requiredAimingErrorPercent,double,0.0,humanControlLogic,Required percentage value (0-1) for aiming error calculations.}
constexpr const char* requiredAimingErrorPercent = "requiredAimingErrorPercent";
 
//! \vreRoleParam{runMultiplier,double,0.77777778,humanControlLogic,Movement speed multiplier when running.}
constexpr const char* runMultiplier = "runMultiplier";
 
//! \vreRoleParam{showCompass,bool,false,humanControlLogic,Whether to display the compass in the interface.}
constexpr const char* showCompass = "showCompass";
 
//! \vreRoleParam{sprintBackwardMultiplier,double,1.2,humanControlLogic,Movement speed multiplier when sprinting backward.}
constexpr const char* sprintBackwardMultiplier = "sprintBackwardMultiplier";
 
//! \vreRoleParam{sprintMultiplier,double,1.555556,humanControlLogic,Movement speed multiplier when sprinting forward.}
constexpr const char* sprintMultiplier = "sprintMultiplier";
 
//! \vreRoleParam{walkMultiplier,double,0.3,humanControlLogic,Movement speed multiplier when walking.}
constexpr const char* walkMultiplier = "walkMultiplier";
 
//! \vreRoleParam{weaponLockedPostures,table,{},humanControlLogic,Table of postures that prevent weapon usage.}
constexpr const char* weaponLockedPostures = "weaponLockedPostures";
 
//! \vreRoleParam{weaponLockedWhenMovingPostures,table,{},humanControlLogic,Table of postures that prevent weapon usage when moving.}
constexpr const char* weaponLockedWhenMovingPostures = "weaponLockedWhenMovingPostures";
 
//! @}
} // namespace HumanControlLogicConfig
 
//! \brief Type identifier for DtHumanControlLogic component
constexpr const char* DtHumanControlLogicType = "DtHumanControlLogic";
 
//! \brief Control logic component for the human entity
//!
//! DtHumanControlLogic manages user inputs and control actions for the human entity,
//! including movement, posture changes, weapon handling, and special actions like
//! using equipment or interacting with the environment. It translates input commands
//! into entity state changes and simulation actions.
class HUMAN_DLL DtHumanControlLogic : public DtEntityControlLogic
{
public:
   //! \brief Friend class declaration to allow VR logic access to protected members
   friend class DtHumanVirtualRealityLogic;
 
   //! \brief Enumeration of posture transition directions
   using DtPostureTransition = enum DtPostureTransition {
      POSTURE_UP,  //!< Transitioning to a more upright posture
      POSTURE_DOWN //!< Transitioning to a more prone posture
   };
 
   //! \brief Enumeration of compass unit types
   using DtCompassUnits = enum DtCompassUnits {
      DEGREES = 0, //!< Compass units in degrees (0-360)
      NATO_MIL     //!< Compass units in NATO mils (0-6400)
   };
 
   //! \brief Default constructor
   DtHumanControlLogic();
 
   //! \brief Virtual destructor
   virtual ~DtHumanControlLogic() override;
 
   //! \brief Initializes the human control logic
   //! \param player Pointer to the player station
   //! \param config Configuration settings for initialization
   //! \return True if initialization was successful, false otherwise
   virtual bool initialize(DtPlayerStation* player, DtInitTable& config) override;
 
   //! \brief Performs post-initialization setup
   //! \return True if post-initialization was successful, false otherwise
   virtual bool postInitialize() override;
 
   //! \brief Updates control logic for the current frame
   //! \param dt Delta time since the last frame in seconds
   virtual void tick(double dt) override;
 
   //! \brief Cleans up resources when the component is being shut down
   virtual void shutdown() override;
 
   //! \brief Returns the component type identifier
   //! \return The component type string
   virtual const char* type() const override;
 
   //! \brief Handles aim input
   //! \param val Input value in the range [-1.0, 1.0]
   virtual void aim(double val);
   
   //! \brief Set a temporary movement lockout
   //!
   //! Set time in seconds during which player cannot move; set 0 to clear.
   void setMoveLockTime(double seconds);
 
   //! \brief Add time to a temporary movement lockout
   //!
   //! Add time in seconds during which player cannot move
   void addMoveLockTime(double seconds);
   
   //! \brief Handles forward/backward movement input
   //! \param val Input value in the range [-1.0, 1.0], where positive is forward
   virtual void move(double val);
 
   //! \brief Handles left/right movement input
   //! \param val Input value in the range [-1.0, 1.0], where positive is right
   virtual void strafe(double val);
   //! \brief Handles pitch (up/down looking) input
   //! \param val Input value in the range [-1.0, 1.0], where positive is down
   //! \param mouseInput Flag indicating if input is from mouse
   //!
   //! Handles pitch input, applies value scaling, and sends pitch joystick command when not gazing.
   virtual void pitch(double val, bool mouseInput = false);
 
   //! \brief Handles yaw (left/right looking) input
   //! \param val Input value in the range [-1.0, 1.0], where positive is right
   //! \param mouseInput Flag indicating if input is from mouse
   //!
   //! Handles yaw input, applies value scaling, and sends yaw joystick command when not gazing.
   virtual void yaw(double val, bool mouseInput = false);
   //! \brief Sets the pitch angle directly
   //! \param pitch Pitch angle in degrees
   virtual void setPitch(double pitch);
 
   //! \brief Sets the yaw angle directly
   //! \param yaw Yaw angle in degrees
   virtual void setYaw(double yaw);
 
   //! \brief Simulates yaw movement over time
   //! \param dt Delta time since the last frame in seconds
   virtual void simulateYaw(double dt);
 
   //! \brief Simulates pitch movement over time
   //! \param dt Delta time since the last frame in seconds
   virtual void simulatePitch(double dt);
 
   //! \brief Sets the current pitch angle for VR input
   //! \param pitch Pitch angle in degrees
   //! \note VRE-3178 remove once we support proper VR input
   virtual void setCurrentPitch(double pitch);
 
   //! \brief Sets the current heading angle for VR input
   //! \param yaw Yaw angle in degrees
   //! \note VRE-3178 remove once we support proper VR input
   virtual void setCurrentHeading(double yaw);
   //! \brief Turns the entity's head to look up/down
   //!
   //! Updates the gazePitch attribute according to the processed pitch input (myPitch).
   virtual void gazePitch();
 
   //! \brief Turns the entity's head to look left/right
   //!
   //! Updates the gazeYaw attribute according to the processed yaw input (myYaw).
   virtual void gazeYaw();
 
   //! \brief Gets the desired posture for the human entity
   //! \return The current desired posture
   virtual HumanPosture desiredPosture() const;
 
   //! \brief Sets the entity posture
   //! \param val Input value, typically 1.0 for activation
   //! \param posture Target posture to transition to
   //! \param postureTransition Direction of posture transition
   virtual void setPosture(double val, HumanPosture posture, DtPostureTransition postureTransition);
 
   //! \brief Selects a posture based on the current state
   //! \param val Input value, typically 1.0 for activation
   virtual void postureSelect(double val);
 
   //! \brief Transitions to a more upright posture
   //! \param val Input value, typically 1.0 for activation
   virtual void postureUp(double val);
 
   //! \brief Transitions to a more prone posture
   //! \param val Input value, typically 1.0 for activation
   virtual void postureDown(double val);
 
   //! \brief Transitions to standing posture
   //! \param val Input value, typically 1.0 for activation
   virtual void standUp(double val);
 
   //! \brief Transitions to prone posture
   //! \param val Input value, typically 1.0 for activation
   virtual void goProne(double val);
 
   //! \brief Transitions to kneeling posture
   //! \param val Input value, typically 1.0 for activation
   virtual void kneel(double val);
 
   //! \brief Toggles binoculars equipment
   //! \param val Input value, typically 1.0 for activation
   virtual void toggleBinoculars(double val);
 
   //! \brief Initiates weapon reload
   //! \param val Input value, typically 1.0 for activation
   virtual void reload(double val);
 
   //! \brief Fires the current weapon
   //! \param val Input value, typically 1.0 for activation
   virtual void fire(double val);
 
   //! \brief Toggles free look mode
   //! \param val Input value, typically 1.0 for activation
   virtual void freeLook(double val);
 
   //! \brief Toggles the observer attachment mode
   //! \param val Input value, typically 1.0 for activation
   virtual void toggleObserverAttachMode(double val);
 
   //! \brief Sets the observer attachment mode directly
   //! \param mode The observer attachment mode to set
   virtual void setObserverAttachMode(ObserverAttachMode mode);
 
   //! \brief Activates sprint movement
   //! \param val Input value, typically 1.0 for activation
   virtual void sprint(double val);
 
   //! \brief Activates walk movement
   //! \param val Input value, typically 1.0 for activation
   virtual void walk(double val);
 
   //! \brief Toggles flashlight on/off
   //! \param val Input value, typically 1.0 for activation
   virtual void toggleFlashlight(double val);
 
   //! \brief Adjusts flashlight pitch upward
   //! \param val Input value, typically 1.0 for activation
   virtual void flashlightPitchUp(double val);
 
   //! \brief Adjusts flashlight pitch downward
   //! \param val Input value, typically 1.0 for activation
   virtual void flashlightPitchDown(double val);
 
   //! \brief Adjusts flashlight yaw leftward
   //! \param val Input value, typically 1.0 for activation
   virtual void flashlightYawLeft(double val);
 
   //! \brief Adjusts flashlight yaw rightward
   //! \param val Input value, typically 1.0 for activation
   virtual void flashlightYawRight(double val);
 
   //! \brief Handles first stage trigger input for weapons
   //! \param val Input value, typically 1.0 for activation
   virtual void firstStageTrigger(double val);
 
   //! \brief Toggles the compass display
   //! \param val Input value, typically 1.0 for activation
   //!
   //! Toggles the value of the makVre::DtState attribute "compass".
   virtual void toggleCompass(double val);
 
   //! \brief Toggles between compass unit types
   //! \param val Input value, typically 1.0 for activation
   virtual void toggleCompassUnits(double val);
 
   //! \brief Sets the compass units directly
   //! \param units The compass units to use
   virtual void setCompassUnits(enum DtCompassUnits units);
 
   //! \brief Toggles between true and magnetic north references
   //! \param val Input value, typically 1.0 for activation
   virtual void toggleNorthReference(double val);
 
   //! \brief Toggles night vision goggles
   //! \param val Input value, typically 1.0 for activation
   virtual void toggleNVG(double val);
 
   //! \brief Zooms in binoculars or toggles binoculars if not active
   //! \param val Input value, typically 1.0 for activation
   virtual void zoomInToggleBinoculars(double val);
 
   //! \brief Zooms out binoculars or toggles binoculars if not active
   //! \param val Input value, typically 1.0 for activation
   virtual void zoomOutToggleBinoculars(double val);
 
   //! \brief Toggles weapon stowed state
   //! \param val Input value, typically 1.0 for activation
   virtual void toggleWeaponStowed(double val);
 
   //! \brief Toggles weapon down state
   //! \param val Input value, typically 1.0 for activation
   virtual void toggleWeaponDown(double val);
 
   //! \brief Toggles HUD visibility
   //! \param val Input value, typically 1.0 for activation
   //!
   //! Toggles value of state attribute "showHUD".
   virtual void toggleHUD(double val);
 
   //! \brief Puts the weapon in down position
   virtual void weaponDown();
 
   //! \brief Stows the current weapon
   //! \param stow True to stow the weapon, false otherwise
   virtual void weaponStow(bool stow);
 
   //! \brief Brings the weapon to ready position
   virtual void weaponUp();
 
   //! \brief Cycles through weapon states (ready, down, stowed)
   //! \param val Input value, typically 1.0 for activation
   //!
   //! Toggles current "attackMode" extended state data, representing
   //! current attack mode of the launcher, top attack ("top-attack") or direct attack ("direct-attack").
   virtual void cycleWeaponState(double val);
 
   // Toggle current "attackMode" extended state data, representing
   // current attack mode of the launcher, top attack ("top-attack") or direct attack ("direct-attack").
   virtual void toggleMissileAttackMode(double val);
 
   //! \brief Cycles through weapons or puts current weapon down
   //! \param press True if button is pressed, false if released
   //!
   //! Cycles through available weapons if weapon is already in ready position,
   //! or puts the current weapon down if in ready position and not cycling.
   virtual void weaponCycleOrDown(bool press);
 
   //! \brief Selects the next weapon in the inventory
   //! \param val Input value, typically 1.0 for activation
   //!
   //! Cycles to the next available weapon in the entity's inventory.
   virtual void nextWeapon(double val);
 
   //! \brief Selects a specific weapon by index
   //! \param index The index of the weapon to select
   //!
   //! Selects a specific weapon from the entity's inventory based on its index.
   virtual void selectWeapon(int index);
 
   //! \brief Manipulates a terrain element
   //! \param element The terrain element to manipulate
   //! \param action The action to perform on the element
   //!
   //! Performs an action on a terrain element, such as opening a door,
   //! toggling a light switch, or operating other interactive objects.
   virtual void manipulateTerrainElement(TerrainElement element, TerrainAction action);
 
   //! \brief Toggles the left parachute control line
   //! \param val Input value, typically 1.0 for activation
   //!
   //! Controls the left steering of a parachute when deployed,
   //! causing the entity to turn left when in the air.
   virtual void parachuteLeftToggle(double val);
 
   //! \brief Toggles the right parachute control line
   //! \param val Input value, typically 1.0 for activation
   //!
   //! Controls the right steering of a parachute when deployed,
   //! causing the entity to turn right when in the air.
   virtual void parachuteRightToggle(double val);
 
   //! \brief Deploys the parachute
   //! \param val Input value, typically 1.0 for activation
   //!
   //! Deploys the entity's parachute when falling, allowing for
   //! controlled descent and safe landing.
   virtual void parachuteDeploy(double val);
 
   //! \brief Sets the laser designation code
   //! \param val The four-digit laser code to set
   //!
   //! Sets the laser designation code used for guiding laser-guided munitions.
   //! This code must match the code set on the munition for proper guidance.
   virtual void setLaserCode(int val);
 
   //! \brief Plays a DI-Guy animation action on the entity
   //! \param diguyAction The name of the DI-Guy action to play
   //! \param duration The duration of the animation in seconds (0 for default duration)
   //!
   //! Sends a VrfTaskAnimationMessage to the entity, instructing it to play the specified
   //! DI-Guy animation action, such as waving, saluting, or other gestures and movements.
   virtual void playDiguyAction(const std::string& diguyAction, double duration = 0);
 
   //! \brief Plays a DI-Guy gesture on the entity
   //! \param diguyGesture The name of the DI-Guy gesture to play
   //!
   //! Sends a VrfTaskGestureMessage to the entity, instructing it to play the specified
   //! DI-Guy gesture, typically used for facial expressions and minor movements.
   virtual void playDiguyGesture(const std::string diguyGesture);
 
   //! \brief Sends a joystick command to a specific entity
   //! \param id The entity identifier of the target entity
   //! \param functionGroup The function group of the command
   //! \param function The specific function to trigger
   //! \param val The input value for the function
   //! \param repeat Whether the command should be repeated (default: false)
   //!
   //! Sends a joystick command message to the specified entity, allowing
   //! control of its functions via simulated joystick input.
   virtual void sendJoystickCommand(const DtEntityIdentifier& id, const std::string& functionGroup,
      const std::string& function, double val, bool repeat = false);
 
   //! \brief Sends a joystick command to the controlled entity
   //! \param functionGroup The function group of the command
   //! \param function The specific function to trigger
   //! \param val The input value for the function
   //! \param repeat Whether the command should be repeated (default: false)
   //!
   //! Sends a joystick command message to the entity controlled by this logic component,
   //! allowing control of its functions via simulated joystick input.
   virtual void sendJoystickCommand(
      const std::string& functionGroup, const std::string& function, double val, bool repeat = false);
   //! \brief Forwards a joystick command to controlled drones
   //!
   //! Helper comment for the sendJoystickCommand methods, indicating that they
   //! can be used to forward commands to drones being controlled by the entity.
 
   //! \brief Resets the entity to its initial state
   //! \param value Input value, typically 1.0 for activation
   //!
   //! Resets the entity to its initial state, including position, orientation, and equipment.
   //! This overrides the base class implementation to handle human-specific reset behavior.
   virtual void reset(float value) override;
 
   //! \brief Resets the entity state without changing position
   //! \param value Input value, typically 1.0 for activation
   //!
   //! Resets the entity to its initial state but maintains its current position in the world.
   //! This is useful for resetting health, equipment, or other attributes without teleporting.
   virtual void resetInPlace(float value) override;
 
   //! \brief Updates the DI-Guy hand item based on current state
   //!
   //! Updates the item held in the entity's hands based on the current weapon
   //! or equipment selection. This affects the visual appearance of the entity.
   virtual void updateDiGuyHandItem();
 
   //! \brief Zooms in the weapon scope or optics
   //! \param val Input value, typically 1.0 for activation
   //!
   //! Increases the zoom level of the currently equipped weapon's scope or optics,
   //! providing a closer view of distant targets.
   void zoomInScope(double val);
 
   //! \brief Zooms out the weapon scope or optics
   //! \param val Input value, typically 1.0 for activation
   //!
   //! Decreases the zoom level of the currently equipped weapon's scope or optics,
   //! providing a wider field of view.
   void zoomOutScope(double val);
 
   //! \brief Converts a posture string to a HumanPosture enum value
   //! \param posture String representation of the posture
   //! \return The corresponding HumanPosture enum value
   //!
   //! Converts a string representation of a posture (e.g., "Standing", "Kneeling", "Prone")
   //! to the corresponding HumanPosture enumeration value.
   virtual HumanPosture postureFromString(const std::string& posture) const;
 
   //! \brief Converts a HumanPosture enum value to a string
   //! \param posture The HumanPosture enum value to convert
   //! \return String representation of the posture
   //!
   //! Converts a HumanPosture enumeration value to its string representation
   //! (e.g., "Standing", "Kneeling", "Prone").
   virtual std::string stringForPosture(const HumanPosture posture) const;
 
protected:
   //! \brief Checks if the entity is dead
   //! \return True if the entity is dead, false otherwise
   //!
   //! Determines whether the entity is currently dead based on its health value
   //! and appearance bits. Used to disable certain controls when the entity is dead.
   bool isDead();
 
   //! \brief Checks if the player can control the entity
   //! \return True if the player can control the entity, false otherwise
   //!
   //! Determines whether player input should be allowed to control the entity
   //! based on the current state, such as health, posture, and other conditions.
   bool playerCanControl();
 
   //! \brief Checks if the entity is in the air
   //! \return True if the entity is airborne, false otherwise
   //!
   //! Determines whether the entity is currently in the air, such as when
   //! jumping, falling, or parachuting. Affects available controls and animations.
   bool isAirborne();
 
   //! \brief Checks if the entity is aiming a launcher
   //! \return True if aiming a launcher, false otherwise
   //!
   //! Determines whether the entity is currently carrying a shoulder-mounted
   //! launcher or using a tripod-mounted launcher. Affects aiming behavior,
   //! movement restrictions, and available actions.
   bool isAimingLauncher() const;
 
   //! \brief Sets whether mouse control is enabled
   //! \param enabled True to enable mouse control, false to disable it
   //!
   //! Overrides the base class implementation to handle additional setup
   //! related to mouse pitch control for human entities.
   virtual void setMouseControlEnabled(bool enabled) override;
 
   //! \brief Handles simulation state messages
   //! \param msg Pointer to the simulation state message
   //! \return Message result indicating how the message was handled
   //!
   //! Processes messages containing updates to the simulation state,
   //! such as entity positions, orientations, and other dynamic attributes.
   virtual makVre::DtVreMessageResult handleSimState(makVre::DtVreMessage* msg) override;
 
   //! \brief Handles view mode change messages
   //! \param msg Pointer to the view mode message
   //! \return Message result indicating how the message was handled
   //!
   //! Processes messages that change the view mode, such as switching
   //! between first-person and third-person perspectives.
   virtual makVre::DtVreMessageResult handleViewModeMessage(makVre::DtVreMessage* msg);
 
   //! \brief Handles application focus update messages
   //! \param msg Pointer to the focus update message
   //! \return Message result indicating how the message was handled
   //!
   //! Processes messages about application focus changes. Used to disable
   //! walking when the application loses focus, preventing stuck movement
   //! when the ALT key release event is missed.
   virtual makVre::DtVreMessageResult handleAppFocusUpdate(makVre::DtVreMessage* msg);
 
   //! \brief Handles session play state messages
   //! \param msg Pointer to the session play state message
   //! \return Message result indicating how the message was handled
   //!
   //! Processes messages about changes to the simulation play state
   //! (running, paused, or stopped) and updates entity controls accordingly.
   virtual makVre::DtVreMessageResult handleSessionPlayState(makVre::DtVreMessage* msg);
 
   //! \brief Handles changes to the current state
   //! \param state The new state string
   //!
   //! Called when the current state changes. Provides faster response
   //! than waiting for a message-based notification (see VRE-2775).
   //! Updates controls based on the new state.
   virtual void onCurrentStateChanged(std::string state);
 
   //! \brief Handles changes to the launcher element ID
   //! \param launcherId The new launcher element ID
   //!
   //! Called when the "launcherElementId" attribute changes. Calls setupExternalLauncher
   //! when a valid launcher ID is set, or teardownExternalLauncher when the ID is cleared.
   //! This enables or disables launcher-specific functionality and UI elements.
   virtual void onLauncherIdChanged(makVrv::DtElementID launcherId);
 
   //! \brief Determines posture from appearance bits
   //! \param entityType The entity type
   //! \param appearanceBits The appearance bits from the entity
   //! \return The human posture derived from appearance bits
   //!
   //! Extracts the current posture (standing, kneeling, prone) from the
   //! entity's appearance bits, which encode visual state information.
   virtual HumanPosture getPostureFromAppearance(const DtEntityType& entityType, unsigned int appearanceBits);
 
   //! \brief Gets the currently equipped item
   //! \return The currently active equipment type
   //!
   //! Determines what equipment the entity is currently using, such as
   //! binoculars, NVGs, or weapons, based on attribute values.
   virtual Equipment getCurrentEquipment();
 
   //! \brief Gets the entity's health from appearance bits
   //! \return Health value between 0.0 (dead) and 1.0 (full health)
   //!
   //! Extracts the current health value from the entity's appearance bits,
   //! which include damage and injury state information.
   virtual double getHealthFromAppearance();
 
   //! \brief Initializes the posture-to-string mapping tables
   //!
   //! Sets up bidirectional mappings between HumanPosture enum values and
   //! their string representations. Called during initialization.
   virtual void initPostureStringMaps();
 
   //! \brief Maps a posture enum to a string representation
   //! \param posture The HumanPosture enum value to map
   //! \param postureString The string representation to associate with the posture
   //!
   //! Adds an entry to the bidirectional mapping tables between posture
   //! enum values and their string representations.
   virtual void mapPostureToString(const HumanPosture posture, const std::string& postureString);
 
   //! \brief Fires the currently equipped gun
   //!
   //! Handles the logic for firing a gun-type weapon, including ammunition
   //! tracking, recoil effects, and sending the appropriate messages to the
   //! simulation to create projectiles and effects.
   virtual void fireGun();
 
   //! \brief Fires the currently equipped launcher
   //!
   //! Handles the logic for firing a launcher-type weapon, such as rocket
   //! launchers or missile systems, including tracking ammunition and
   //! sending the appropriate messages to the simulation.
   virtual void fireLauncher();
 
   //! \brief Throws a grenade
   //!
   //! Handles the logic for throwing a grenade, including tracking inventory,
   //! animation timing, and sending the appropriate messages to the simulation
   //! to create the grenade entity.
   virtual void throwGrenade();
 
   //! \brief Sets up an external launcher
   //!
   //! Configures the control logic for using an external launcher, such as a
   //! tripod-mounted weapon system. Sets up appropriate UI elements, control
   //! mappings, and attribute listeners.
   virtual void setupExternalLauncher();
 
   //! \brief Tears down an external launcher
   //!
   //! Removes the configuration for an external launcher when the entity stops
   //! using it. Cleans up UI elements, control mappings, and attribute listeners.
   virtual void teardownExternalLauncher();
 
   //! \brief Starts laser designation
   //!
   //! Activates the laser designator for targeting laser-guided munitions.
   //! Sets up the necessary attributes and tracking for the laser spot.
   virtual void startLasing();
 
   //! \brief Updates the laser designation state
   //!
   //! Updates the position and state of the active laser designation spot.
   //! Called periodically when laser designation is active.
   virtual void updateLasingState();
 
   //! \brief Stops laser designation
   //!
   //! Deactivates the laser designator and cleans up associated resources.
   //! Removes the laser spot from the simulation.
   virtual void stopLasing();
 
   //! \brief Disables certain features while parachuting
   //!
   //! Disables features and controls that should not be available while
   //! the entity is using a parachute, such as weapon handling or posture changes.
   virtual void disableFeaturesWhileParachuting();
 
   //! \brief Updates the weapon ready state
   //!
   //! Updates the state of the currently equipped weapon based on entity
   //! attributes and conditions. Determines whether the weapon should be
   //! ready for use or put away.
   virtual void updateWeaponReady();
 
   //! \brief Computes the current aiming error
   //!
   //! Calculates the current aiming error based on factors like posture,
   //! movement, fatigue, and weapon type. This error affects weapon accuracy
   //! and is used to scale the reticle in the human overlay. Must be updated
   //! every frame for accurate visual feedback.
   virtual void computeAimingError();
 
   //! \brief Adds a random offset to the input aim orientation
   //! \param aimingOrientation The aiming orientation to which the error is added
   //!
   //! Takes an aim orientation from the player and adds a random degree of offset
   //! between myRequiredAimingErrorPercent and the max error determined by
   //! computeAimingError().
   virtual void addRandomAimingError(DtTaitBryan& aimingOrientation);
 
   //! \brief Determines if movement should be allowed
   //! \return True if movement should be allowed, false otherwise
   //!
   //! Checks various conditions to determine if the entity should be
   //! allowed to move, such as health, posture restrictions, and current actions.
   virtual bool shouldAllowMovement();
 
   //! \brief Returns the velocity of the player ownship entity
   //!
   //! Velocity is relative to the host if embarked, otherwise i
   DtVector32 walkingVelocity();
 
   //! \brief Updates the move lock state
   //!
   //! Updates the move lock state based on current posture and conditions.
   //! Move lock prevents the entity from moving in certain situations.
   void updateMoveLock();
 
   //! \brief Checks if the entity is currently moving
   //! \return True if the entity is moving, false otherwise
   //!
   //! Determines whether the entity is currently in motion based on
   //! movement inputs and velocity.
   bool isMoving();
 
   //! \brief Initializes the weapon index
   //!
   //! Sets up the initial weapon index based on the entity's configuration
   //! and available weapons. Called during initialization.
   void initWeaponIndex();
 
   //! \brief Sets the weapon stowed state
   //! \param stowed True to stow the weapon, false otherwise
   //!
   //! Updates the weapon stowed state and related attributes.
   //! A stowed weapon is put away completely (e.g., on the back).
   void setWeaponStowed(bool stowed);
 
   //! \brief Sets the weapon down state
   //! \param down True to put the weapon down, false to bring it up
   //!
   //! Updates the weapon down state and related attributes.
   //! A down weapon is lowered but still in hand (e.g., at low ready).
   void setWeaponDown(bool down);
 
   //! \brief Sets the weapon state directly
   //! \param state The weapon state value to set
   //!
   //! Sets the weapon state directly to a specific value, bypassing
   //! the individual stowed/down state setters.
   void setWeaponState(int state);
 
   //! \brief Gets the current ammunition count
   //! \return The current ammunition count for the active weapon
   //!
   //! Retrieves the current ammunition count for the active weapon
   //! from the appropriate attribute.
   double getCurrentAmmo();
 
   //! \brief Sets the gaze pitch attribute
   //! \param pitch The pitch angle in degrees
   //!
   //! Updates the gazePitch attribute, which controls the up/down
   //! orientation of the entity's head for looking.
   void setGazePitch(double pitch);
 
   //! \brief Sets the gaze yaw attribute
   //! \param yaw The yaw angle in degrees
   //!
   //! Updates the gazeYaw attribute, which controls the left/right
   //! orientation of the entity's head for looking.
   void setGazeYaw(double yaw);
 
   //! \brief Checks if third-person view is allowed
   //! \return True if third-person view is allowed, false otherwise
   //!
   //! Determines if the entity is allowed to switch to third-person view
   //! based on configuration settings in human.lua.
   virtual bool thirdPersonAllowed();
 
   // Commented out callback methods preserved for reference
   //   void onDiguyItemChanged(std::string);
   //   void onCanSwitchWeaponsChanged(bool);
 
   //! \brief Handles changes to the weapon list
   //! \param weaponList Vector of weapon names available to the entity
   //!
   //! Called when the list of available weapons changes. Updates the
   //! weapon selection UI and related controls.
   void onWeaponListChanged(const DtAttributeHandle& weaponList);
 
   //! \brief Handles changes to the ammunition count
   //! \param weaponResourceHandle The new ammunition count
   //!
   //! Called when the ammunition count for the current weapon changes.
   //! Updates UI elements and manages weapon state if out of ammunition.
   void onAmmoCountChanged(const DtAttributeHandle& weaponResourceHandle);
 
   //! \brief Current ammunition resource attribute name
   //!
   //! Stores the name of the attribute currently being monitored for ammunition count.
   DtAttributeHandle myCurrentResourceHandle;
   DtAttributeChangeCallback myCurrentAmmoResourceAttributeCallback;
 
   //! \brief Handles changes to the sprinting state
   //! \param sprinting True if the entity is sprinting, false otherwise
   //!
   //! Called when the sprinting state changes. Updates movement speed
   //! modifiers and related attributes.
   void onSprintingChanged(bool sprinting);
 
   //! \brief Handles changes to the backward movement state
   //! \param movingBackward True if the entity is moving backward, false otherwise
   //!
   //! Called when the backward movement state changes. Updates movement
   //! speed modifiers and other movement-related attributes.
   void onMovingBackwardChanged(bool movingBackward);
 
   //! \brief Handles changes to the walking state
   //! \param walking True if the entity is walking (vs running), false otherwise
   //!
   //! Called when the walking state changes. Updates movement speed
   //! modifiers and related attributes.
   void onWalkingChanged(bool walking);
 
   //! \brief Handles changes to the aiming state
   //! \param aiming True if the entity is aiming, false otherwise
   //!
   //! Called when the aiming state changes. Updates movement restrictions,
   //! accuracy modifiers, and weapon handling attributes.
   void onAimingChanged(bool aiming);
 
   //! \brief Handles changes to the weapon index
   //! \param weaponIndex The new weapon index
   //!
   //! Called when the selected weapon changes. Updates UI elements,
   //! ammunition tracking, and weapon-related attributes.
   void onWeaponIndexChanged(int weaponIndex);
 
   //! \brief Handles changes to the posture
   //! \param posture The new posture
   //!
   //! Called when the entity's posture changes. Updates movement restrictions,
   //! accuracy modifiers, and other posture-dependent attributes.
   void onPostureChanged(HumanPosture posture);
 
   //! \brief Handles changes to the movement capability
   //! \param canMove True if the entity can move, false otherwise
   //!
   //! Called when the entity's ability to move changes. Updates movement
   //! controls and related UI elements.
   void onCanMoveChanged(bool canMove);
 
   //! \brief Handles changes to the health
   //! \param health The new health value
   //!
   //! Called when the entity's health changes. Updates UI elements,
   //! movement capabilities, and other health-dependent attributes.
   void onHealthChanged(double health);
 
   //! \brief Handles changes to the active equipment
   //! \param equipment The new active equipment
   //!
   //! Called when the entity's active equipment changes. Updates UI elements,
   //! control modes, and equipment-dependent attributes.
   void onEquipmentChanged(Equipment equipment);
 
   //! \brief Handles changes to the binoculars state
   //! \param usingBinoculars True if binoculars are in use, false otherwise
   //!
   //! Called when the entity's binoculars usage state changes. Updates
   //! view settings, input sensitivity, and related UI elements.
   void onBinocularsChanged(bool usingBinoculars);
 
   //! \brief Handles changes to the forward controls state
   //! \param forwardControls True if forward controls are enabled, false otherwise
   //!
   //! Called when the entity's forward controls state changes. Updates
   //! control mappings and related UI elements.
   void onForwardControlsChanged(bool forwardControls);
 
   //! \brief Handles changes to the weapon state
   //! \param weaponState The new weapon state
   //!
   //! Called when the entity's weapon state changes (ready, down, stowed).
   //! Updates UI elements, control modes, and weapon-dependent attributes.
   void onWeaponStateChanged(int weaponState);
 
   //! \brief Handles changes to the DI-Guy action
   //! \param action The new DI-Guy action name
   //!
   //! Called when the entity's DI-Guy animation action changes. Updates
   //! control restrictions and other animation-dependent attributes.
   void onDiGuyActionChanged(std::string action);
 
   //! \brief Shows a QML overlay by name
   //! \param name Name of the QML overlay to show
   //!
   //! Activates and displays a named QML overlay, such as a weapon scope
   //! or other specialized UI element.
   void showQmlOverlay(const std::string& name);
 
   //! \brief Determines if gaze should be enabled
   //! \param pitch True to check pitch gaze, false to check yaw gaze
   //! \return True if gaze should be enabled, false otherwise
   //!
   //! Returns whether pitch/yaw gaze should be enabled according to the entity state
   //! (e.g. weapon/launcher state, freelook/climbing enabled state, spectator observer attach mode).
   bool shouldEnableGaze(bool pitch) const;
 
   //! \brief Handles gaze input and updates attributes
   //! \param pitch True to handle pitch gaze, false to handle yaw gaze
   //! \return True if gaze is enabled and input handled, false otherwise
   //!
   //! Checks if gaze should be enabled and sets the useGazePitch/Yaw attribute accordingly.
   //! Returns whether the gaze input was handled.
   bool handleGazeInput(bool pitch);
 
   //! \brief Handles changes to the firepower health
   //! \param newFirepowerHealthValue The new firepower health value
   //!
   //! Called when the entity's firepower health changes. This affects
   //! aiming accuracy and weapon handling capabilities.
   virtual void firepowerHealthChangeCallback(int newFirepowerHealthValue);
 
   //! \brief Handles changes to the fatigue level
   //! \param newFatigueValue The new fatigue value
   //!
   //! Called when the entity's fatigue level changes. This affects
   //! movement speed, aiming accuracy, and other performance attributes.
   virtual void fatigueChangeCallback(float newFatigueValue);
 
   //! \brief Handles changes to the percent of max speed
   //! \param newPercentOfMaxSpeedValue The new percent of max speed value
   //!
   //! Called when the entity's percent of maximum speed changes. This affects
   //! movement capabilities and is modified by fatigue and other factors.
   virtual void percentOfMaxSpeedChangeCallback(float newPercentOfMaxSpeedValue);
 
protected:
   //! \brief Weapon resource logic component
   //!
   //! Manages weapon resources such as ammunition and available weapons.
   DtWeaponResourceLogic* myWeaponResourceLogic;
 
   DtAttributeHandleType<std::vector<std::string>> myWeaponList;
 
   //! \brief Pointer to the associated observer
   //!
   //! Provides access to view-related functionality for the entity.
   makVrv::DtObserver* myObserver;
 
   //! \brief Human input logic component
   //!
   //! Handles input processing specific to human entities.
   DtHumanInputLogic* myHumanInputLogic;
 
   //! \brief Flag for inverting pitch input
   //!
   //! When true, pitch input is inverted (up becomes down and vice versa).
   bool myInvertPitch;
 
   //! \brief Multiplier for sprint movement speed
   //!
   //! Scales forward movement speed when sprinting forward.
   double mySprintMultiplier;
 
   //! \brief Multiplier for backward sprint movement speed
   //!
   //! Scales backward movement speed when sprinting backward.
   double mySprintBackwardMultiplier;
 
   //! \brief Multiplier for running movement speed
   //!
   //! Scales movement speed when running (the default movement mode).
   double myRunMultiplier;
 
   //! \brief Multiplier for walking movement speed
   //!
   //! Scales movement speed when in walking mode (slower than running).
   double myWalkMultiplier;
 
   //! \brief Multiplier for aiming movement speed
   //!
   //! Scales movement speed when aiming a weapon (typically slower).
   double myAimMultiplier;
 
   //! \brief Last forward/backward movement input value
   //!
   //! Stores the most recent forward/backward movement input value.
   double myLastMoveValue;
 
   //! \brief Last left/right strafe input value
   //!
   //! Stores the most recent left/right strafe input value.
   double myLastStrafeValue;
 
   //! \brief Map from posture enum to string representation
   //!
   //! Bidirectional mapping between posture enum values and their string representations.
   std::map<HumanPosture, std::string> myPostureToString;
 
   //! \brief Map from string representation to posture enum
   //!
   //! Bidirectional mapping between string representations and posture enum values.
   std::map<std::string, HumanPosture> myStringToPosture;
 
   //! \brief Sequence of postures for cycling
   //!
   //! Defines the order in which postures are cycled through when using posture cycling commands.
   std::vector<HumanPosture> myPostureSequence;
 
   //! \brief Map from posture to sequence index
   //!
   //! Maps each posture to its index in the posture sequence for quick lookup.
   std::map<HumanPosture, int> myPostureSequenceIndex;
 
   //! \brief Structure defining restrictions for each posture
   struct PostureRestrictions
   {
      //! \brief Default constructor initializing all restrictions to false
      PostureRestrictions()
         : moveLocked(false)
         , weaponLocked(false)
         , weaponLockedWhenMoving(false)
      {
      }
 
      //! \brief Whether movement is locked in this posture
      bool moveLocked;
 
      //! \brief Whether weapon use is locked in this posture
      bool weaponLocked;
 
      //! \brief Whether weapon use is locked while moving in this posture
      bool weaponLockedWhenMoving;
   };
 
   //! \brief Map of posture restrictions for each posture
   //!
   //! Defines movement and weapon usage restrictions for each posture type.
   std::map<HumanPosture, PostureRestrictions> myPostureRestrictions;
 
   //! \brief Map of animation transition timing for each posture
   //!
   //! Stores the delay times (in seconds) for transitioning into and out of each posture.
   //! The first value is the delay when transitioning into the posture,
   //! and the second value is the delay when transitioning out of the posture.
   std::map<HumanPosture, std::pair<double /* delay into */, double /* out of */>> myPostureAnimationWaitTimes;
 
   //! \brief Last posture transition direction
   //!
   //! Stores the direction of the last posture transition (up or down).
   DtPostureTransition myLastPostureTransition;
 
   //! \brief Expected posture after transition completes
   //!
   //! The posture that the entity is transitioning to or expected to reach.
   HumanPosture myExpectedPosture;
 
   //! \brief Desired posture requested by user input
   //!
   //! The posture that was requested through user input, which may differ
   //! from the expected posture during transitions.
   HumanPosture myDesiredPosture;
 
   //! \brief Last stable posture
   //!
   //! The last fully-established posture before any current transition.
   HumanPosture myLastPosture;
 
   //! \brief Timeout for posture command processing
   //!
   //! Time remaining (in seconds) before a posture command expires if not completed.
   double myPostureCommandTimeout;
 
   //! \brief Posture animation wait timer
   //!
   //! Time remaining (in seconds) to wait for the current posture animation to complete.
   double myPostureAnimationWait;
 
   //! \brief Timed move lock time remaining
   //! 
   //! Time in seconds remaining in temporary movement lockout.
   double myMoveLockTimer = 0.0;
 
   //! \brief Move lock active flag
   //!
   //! Indicates whether movement is currently locked due to posture constraints
   //! or other restrictions.
   bool myMoveLockActive;
 
   //! \brief Target weapon state to transition to
   //!
   //! The weapon state that the entity is transitioning to after any delays.
   int myEventualWeaponState;
 
   //! \brief Flag indicating grenade throw request
   //!
   //! When true, indicates that a grenade throw has been requested and is pending.
   bool myWantThrowGrenade;
 
   //! \brief Timer for delayed weapon state changes
   //!
   //! Time remaining (in seconds) before a delayed weapon state change occurs.
   double myDelayedToggleWeaponDownTimer;
 
   //! \brief Joystick input sensitivity multiplier
   //!
   //! Controls the sensitivity of joystick inputs for movement and aiming.
   double myJoystickSensitivity;
 
   //! \brief Current fatigue level
   //!
   //! Stores the current fatigue value, which affects aiming accuracy and movement speed.
   //! Higher values indicate greater fatigue and worse performance.
   float myFatigue;
 
   //! \brief Current firepower health value
   //!
   //! Stores the current firepower health value, which affects aiming accuracy.
   //! Lower values indicate degraded weapon handling capability.
   int myFirepowerHealth;
 
   //! \brief Current percentage of maximum movement speed
   //!
   //! Represents the current percentage of maximum speed available to the entity.
   //! Decreases as fatigue increases, limiting maximum movement speed.
   float myPercentOfMaxSpeed;
 
   //! \brief Maximum aiming error in radians
   //!
   //! The maximum half-angle of aiming error in radians. This is typically negative
   //! to produce the full spread of possible aiming error.
   double myMaxAimingError;
 
   //! \brief Current aiming error as a percentage of maximum
   //!
   //! The current aiming error expressed as a percentage of the maximum possible error.
   //! Affected by posture, movement, fatigue, and other factors.
   double myAimingErrorPercent;
 
   //! \brief Minimum required aiming error percentage
   //!
   //! The minimum error percentage that is always applied to ensure some spread
   //! in shots, preventing unrealistically perfect accuracy.
   double myRequiredAimingErrorPercent;
 
   //! \brief Aiming improvement percentage in prone position
   //!
   //! The percentage by which aiming accuracy improves when in the prone position.
   //! This reduces the effective aiming error.
   double myProneAimingImprovementPercent;
 
   //! \brief Aiming improvement percentage when aiming
   //!
   //! The percentage by which aiming accuracy improves when using the weapon's
   //! aiming capability (e.g., iron sights, optics).
   double myAimingImprovementPercent;
 
   //! \brief Current entity heading in degrees
   //!
   //! The current heading (yaw) angle of the entity in world space, in degrees.
   double myCurrentHeading;
 
   //! \brief Current entity pitch in degrees
   //!
   //! The current pitch angle of the entity in world space, in degrees.
   double myCurrentPitch;
 
   //! \brief Yaw rate in degrees per second
   //!
   //! The rate at which the entity's yaw angle changes when turning, in degrees per second.
   double myYawRate;
 
   //! \brief Pitch rate in degrees per second
   //!
   //! The rate at which the entity's pitch angle changes when looking up/down, in degrees per second.
   double myPitchingRate;
 
   //! \brief Turning rate modifier
   //!
   //! A modifier applied to the turning rate under various conditions.
   double myTurningRate;
 
   //! \brief Current input-driven yaw offset
   //!
   //! The current yaw offset resulting from user input, relative to the entity's base orientation.
   double myYaw;
 
   //! \brief Current input-driven pitch offset
   //!
   //! The current pitch offset resulting from user input, relative to the entity's base orientation.
   double myPitch;
 
   //! \brief Flag indicating heading initialization
   //!
   //! When true, indicates that the entity's heading has been initialized.
   bool myInitializedHeading;
 
   //! \brief Flag to force orientation update
   //!
   //! When true, forces an update to the entity's orientation even if other conditions
   //! would normally prevent it. Temporary solution for VR input (VRE-3178).
   bool myForceOrientationUpdate;
 
   //! \brief Flag for sending gaze angles
   //!
   //! When true, enables sending of gaze angle updates to the entity.
   bool mySendGazeAngles;
 
   //! \brief Flag for two-stage fire mode
   //!
   //! When true, indicates that the current weapon uses a two-stage firing process,
   //! such as missile launchers with target lock before firing.
   bool myTwoStageFire;
 
   //! \brief Current laser designation target location
   //!
   //! The world position of the current laser designation target point.
   DtVector myLasingLocation;
 
   //! \brief Input sensitivity multiplier when using binoculars
   //!
   //! Scales joystick and mouse pitch/yaw inputs while using binoculars.
   //! Corresponds to lua configuration variable "binocularsInputMultiplier".
   //! Defaults to 0.5 to provide finer control while using binoculars.
   double myUsingBinocularsInputMultiplier;
 
   //! \brief Cached observer attach mode before menu state
   //!
   //! Stores the observer attach mode at the time we enter the menu state.
   //! Used to restore the observer attach mode upon exiting menu state
   //! (while in the menu state, we force third person mode).
   ObserverAttachMode myCachedObserverAttachMode;
 
   //! \brief Cached compass visibility state before menu state
   //!
   //! Stores whether the compass was visible at the time we enter the menu state.
   //! Used to restore the compass visibility when exiting the menu state.
   bool myCachedShowCompass;
   
   //! \brief Currently active scope overlay
   //!
   //! The DtQtQuickOverlay scope currently in use. It may or may not be null
   //! over the lifetime of a player. For example, with shoulder mounted launchers,
   //! there may be a valid pointer when the launcher is raised, but once lowered,
   //! the pointer will be set to null again.
   DtQtQuickOverlay* myActiveScopeOverlay;
};
} // namespace makVre