gunnerControlLogic.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
//! \file gunnerControlLogic.h
//! \brief Control logic for gunner roles in ground vehicles and weapon systems
//! \ingroup vreCommonComponents
 
 
#pragma once
 
#include "vreCommonComponents/export.h"
#include "vrePlayerStation/entityControlLogic.h"
 
#include "vreMessageManager/vreMessage.h"
#include "vreUtil/initializer.h"
 
#include <vrvCore/DtUniqueID.h>
 
#include <string>
 
namespace makVre
{
class DtVreMessage;
 
class DtWeaponResourceLogic;
 
namespace GunnerControlLogicConfig
{
//! \ingroup RoleConfigParams
//! \defgroup GunnerControlLogicRoleParams Gunner Control Logic Role Parameters
//! \roleInherits{EntityControlLogicRoleParams}
//! Configuration Options for gunner control logic role.
//! @{
 
//! \vreRoleParam{altRole,string,"",gunnerControlLogic,Alternate role name that can be switched to from the gunner role.}
constexpr const char* altRole = "altRole";
 
//! \vreRoleParam{armedProperty,string,"",gunnerControlLogic,Name of the property that controls the armed state for weapons requiring arming.}
constexpr const char* armedProperty = "armedProperty";
 
//! \vreRoleParam{azimuthStateAttribute,string,"mainGunAzimuth",gunnerControlLogic,State attribute name for storing the main gun azimuth angle.}
constexpr const char* azimuthStateAttribute = "azimuthStateAttribute";
 
//! \vreRoleParam{extendedWeaponSystems,table,"",gunnerControlLogic,Table of extended weapon system configurations for complex targeting scenarios.}
constexpr const char* extendedWeaponSystems = "extendedWeaponSystems";
 
//! \vreRoleParam{fireRequiresIntersection,bool,false,gunnerControlLogic,Determines whether firing requires a valid target intersection.}
constexpr const char* fireRequiresIntersection = "fireRequiresIntersection";
 
//! \vreRoleParam{forceResourceType,string,"",gunnerControlLogic,Forces the use of a specific resource type for weapon systems.}
constexpr const char* forceResourceType = "forceResourceType";
 
//! \vreRoleParam{isOverrideRole,bool,false,gunnerControlLogic,Indicates whether this gunner role operates in commander override mode.}
constexpr const char* isOverrideRole = "isOverrideRole";
 
//! \vreRoleParam{maxFireDegreesAzimuth,double,180.0,gunnerControlLogic,Maximum azimuth angle in degrees for weapon firing constraints.}
constexpr const char* maxFireDegreesAzimuth = "maxFireDegreesAzimuth";
 
//! \vreRoleParam{maxFireRange,double,10000.0,gunnerControlLogic,Maximum range in meters for weapon engagement.}
constexpr const char* maxFireRange = "maxFireRange";
 
//! \vreRoleParam{minFireDegreesAzimuth,double,-180.0,gunnerControlLogic,Minimum azimuth angle in degrees for weapon firing constraints.}
constexpr const char* minFireDegreesAzimuth = "minFireDegreesAzimuth";
 
//! \vreRoleParam{minFireRange,double,0.0,gunnerControlLogic,Minimum range in meters for weapon engagement.}
constexpr const char* minFireRange = "minFireRange";
 
//! \vreRoleParam{overrideSystem,string,"weapon",gunnerControlLogic,System name to use when operating in override mode.}
constexpr const char* overrideSystem = "overrideSystem";
 
//! \vreRoleParam{slewToCueTargetSystem,string,"",gunnerControlLogic,Target system name for slew-to-cue functionality.}
constexpr const char* slewToCueTargetSystem = "slewToCueTargetSystem";
 
//! \vreRoleParam{slewToCueUpdateDeltaThreshold,double,0.01,gunnerControlLogic,Threshold for slew-to-cue update sensitivity.}
constexpr const char* slewToCueUpdateDeltaThreshold = "slewToCueUpdateDeltaThreshold";
 
//! \vreRoleParam{slewToCueUpdateRate,double,10.0,gunnerControlLogic,Update rate in Hz for slew-to-cue operations.}
constexpr const char* slewToCueUpdateRate = "slewToCueUpdateRate";
 
//! \vreRoleParam{systemName,string,"weapon",gunnerControlLogic,Primary weapon system name for this gunner role.}
constexpr const char* systemName = "systemName";
 
//! \vreRoleParam{zoomLevels,table,"{1,2,4,8,16,32}",gunnerControlLogic,Array of available zoom magnification levels for the gunner sight system.}
constexpr const char* zoomLevels = "zoomLevels";
 
//! @}
} // namespace GunnerControlLogicConfig
 
//! \brief Type identifier for DtGunnerControlLogic component
constexpr const char* DtGunnerControlLogicType = "DtGunnerControlLogic";
 
//! \brief Control logic component that handles gunner role functionality for ground vehicles
//!
//! DtGunnerControlLogic provides input handling and simulation logic for gunner roles,
//! including weapon control, turret movement, firing, aiming modes, and commander override
//! capabilities. It manages weapon selection, zoom levels, sensor types, and slew-to-cue
//! functionality for targeting systems.
class VRECOMMONCOMPONENTS_DLL DtGunnerControlLogic : public DtEntityControlLogic
{
public:
   //! \brief Constructor for DtGunnerControlLogic
   //!
   //! Initializes component state and checks out required VRE_GROUND license
   DtGunnerControlLogic();
 
   //! \brief Destructor for DtGunnerControlLogic
   virtual ~DtGunnerControlLogic() override;
 
   //! \brief Initializes the gunner control logic component
   //! \param player Pointer to the player station this component belongs to
   //! \param config Configuration table containing gunner settings
   //! \return True if initialization succeeded, false otherwise
   //!
   //! Sets up joystick controls, input handlers, state attributes, zoom levels,
   //! and configures extended weapon systems and slew-to-cue functionality
   virtual bool initialize(DtPlayerStation* player, DtInitTable& config) override;
   //! \brief Performs post-initialization after all components are initialized
   //! \return True if post-initialization succeeded, false otherwise
   //!
   //! Locates and establishes connection with the DtWeaponResourceLogic component
   virtual bool postInitialize() override;
   //! \brief Called every frame to update gunner control logic
   //! \param dt Delta time since the last frame in seconds
   //!
   //! Updates weapon system state, handles extended weapon system targeting,
   //! manages slew-to-cue functionality, and sends firing position updates
   virtual void tick(double dt) override;
   //! \brief Shuts down the gunner control logic component
   //!
   //! Cleans up input handlers, message handlers, and disables commander override if active
   virtual void shutdown() override;
 
   //! \brief Returns the component type identifier
   //! \return The component type string
   virtual const char* type() const override;
 
   //! \brief Input functions mapped to particular action strings in configuration
   //!
   //! \brief Handles weapon firing input
   //! \param val Input value (1.0 = fire, 0.0 = stop firing)
   virtual void fire(double val);
   //! \brief Controls turret azimuth (horizontal rotation)
   //! \param val Input value for azimuth rate (-1.0 to 1.0)
   virtual void azimuth(double val);
   //! \brief Controls turret elevation (vertical angle)
   //! \param val Input value for elevation rate (-1.0 to 1.0)
   virtual void elevation(double val);
   //! \brief Controls weapon stabilization system
   //! \param val Input value (1.0 = enable, 0.0 = disable)
   virtual void stabilize(double val);
   //! \brief Selects the next available weapon
   //! \param val Input value (1.0 = select next weapon)
   virtual void nextWeapon(double val);
   //! \brief Selects the previous available weapon
   //! \param val Input value (1.0 = select previous weapon)
   virtual void previousWeapon(double val);
   //! \brief Increases the sight magnification level
   //! \param val Input value (1.0 = zoom in one level)
   virtual void zoomIn(double val);
   //! \brief Decreases the sight magnification level
   //! \param val Input value (1.0 = zoom out one level)
   virtual void zoomOut(double val);
   //! \brief Cycles to the next available sensor type (visual, NVG, thermal)
   //! \param val Input value (1.0 = select next sensor)
   virtual void nextSensor(double val);
   //! \brief Cycles between available aiming modes
   virtual void cycleAimingMode();
   //! \brief Activates or deactivates slew-to-cue functionality
   //! \param onoff True to activate slew-to-cue, false to deactivate
   virtual void slewToCue(bool onoff);
   //! \brief Switches between gunner and alternate role (e.g., commander RWS)
   virtual void switchToAltRole();
 
   //! \brief Handles input for slew-to-cue activation
   //! \param val Input value (1.0 = activate, 0.0 = deactivate)
   virtual void handleSlewToCue(float val);
   //! \brief Handles input for switching to alternate role
   //! \param val Input value (1.0 = switch role)
   virtual void handleSwitchToAltRole(float val);
 
   //! \brief Moves turret upward (direct control)
   //! \param val Input value (0.0 to 1.0 for speed)
   virtual void turretUp(float val);
 
   //! \brief Moves turret downward (direct control)
   //! \param val Input value (0.0 to 1.0 for speed)
   virtual void turretDown(float val);
 
   //! \brief Moves turret to the right (direct control)
   //! \param val Input value (0.0 to 1.0 for speed)
   virtual void turretRight(float val);
 
   //! \brief Moves turret to the left (direct control)
   //! \param val Input value (0.0 to 1.0 for speed)
   virtual void turretLeft(float val);
   //! \brief Controls continuous zoom level directly
   //! \param val Input value (-1.0 to 1.0) for zoom direction and speed
   virtual void zoom(float val);
 
   //! Set x and y inputs for manual missile aiming.
   virtual void missileX(double val);
   virtual void missileY(double val);
 
   //! Toggles armed state for a weapon that requires arming (weapons don't by default).
   virtual void toggleArmed();
 
   //! \brief Handles action menu messages for the gunner role
   //! \param msg The message to handle
   //! \return Message handling result indicating if the message was handled
   //!
   //! Processes menu actions like cycling weapons, sensors, aiming modes, and role switching
   virtual makVre::DtVreMessageResult handleMenuMessage(makVre::DtVreMessage* msg);
 
protected:
   //! \brief Determines if aiming should use the observer's view
   //! \return True if aiming should use the observer's view, false otherwise
   virtual bool aimWithObserver() const;
 
   //! \brief Sets the commander override active state
   //! \param active True to activate commander override, false to deactivate
   virtual void setCommanderOverrideActive(bool active) const;
 
   //! \brief Sends a joystick message to the entity
   //! \param func Function name to trigger on the entity
   //! \param val Value to send with the function (typically -1.0 to 1.0)
   void sendJoystickMessage(const std::string& func, const double val);
 
   //! Update missile's target point based on the x and y input. Called any time x and y are
   //! not 0.
   virtual void aimMissile(double x, double y);
 
   //! @brief  Returns true if the weapon can fire. Checks for range, azimuth and isArmed.
   virtual bool canFire();
 
protected:
   //! \brief Previously used munition name, used to detect changes
   std::string myPreviousMunitionType;
 
   //! \brief Primary control group name for this gunner station
   std::string myMainControlGroup;
 
   //! \brief Input logic that handles mapping of input actions to functions
   DtInputLogic myInputLogic;
 
   //! \brief Name of the weapon system controlled by this gunner
   std::string mySystemName;
 
   //! \brief Pointer to the weapon resource logic component
   DtWeaponResourceLogic* myResourceLogic;
 
   //! \brief Available zoom magnification levels
   std::vector<double> myZoomLevels;
 
   //! \brief Current index into the zoom levels array
   int myZoomIndex;
 
   //! \brief Configuration table for extended weapon systems
   makVre::DtInitTable myExtendedWeaponSystems;
 
   //! \brief Configuration for the currently active extended weapon system
   makVre::DtInitTable myCurrentExtendedSystem;
 
   //! \brief Current target location for extended weapon systems
   DtVector myTargetLocation;
 
   //! \brief Element ID of the current target
   makVrv::DtElementID myTargetElement;
 
   //! \brief Name of the target system for slew-to-cue functionality
   std::string mySlewToCueTargetSystem;
 
   //! \brief Flag indicating if slew-to-cue is currently active
   bool mySlewToCueActive;
 
   //! \brief Rate at which to send slew-to-cue updates (seconds)
   double mySlewToCueUpdateRate;
 
   //! \brief Timer for tracking when to send the next slew-to-cue update
   double mySlewToCueTimer;
 
   //! \brief Threshold for determining when to send updates based on angle change
   double mySlewToCueUpdateDeltaThreshold;
 
   //! \brief Last direction vector sent in a slew-to-cue message
   DtVector mySlewToCueLastSentVector;
 
   //! \brief Name of the alternate role to switch to
   std::string myAltRole;
 
   //! \brief Flag indicating if this gunner is in override mode
   bool myIsOverrideRole;
 
   //! \brief Name of the system to override
   std::string myOverrideSystem;
 
   //! \brief Flag indicating if a weapon cycle operation is in progress
   bool myCycleWeaponFlag;
 
   //! \brief Timer for delaying weapon cycling operations
   double myDelayedCycleWeaponTimer;
 
   //! Allow the configuration to specify a resource name directly.
   std::string myForceResourceType;
 
   DtAttributeHandle myResourceHandle;
   DtAttributeHandle myMunitionHandle;
 
   double myMissileX;
   double myMissileY;
 
   double myMinRange;
   double myMaxRange;
 
   bool myPreviousMissileInFlight;
 
   double myMinGunAzimuth;
   double myMaxGunAzimuth;
   std::string myAzimuthStateAttribute;
 
   std::string myArmedStateProperty;
};
} // namespace makVre