vreGunJoyActuator.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreGunJoyActuator.h
//! \ingroup vreVrfmodel
//! \brief Actuator that models firing a turret mounted gun with joystick controls
//!
//! This file defines the DtVreGunJoyActuator class which provides a model of a
//! turret mounted gun controlled via joystick. It handles firing events, ammunition
//! management, aiming, and weapon switching through joystick inputs.
#pragma once
 
#include "vreVrfmodel/export.h"
#include "vreVrfmodel/vreSimComponent.h"
#include "vreVrfmodel/ballisticGunJoy.h"
 
#include "vreVrfobjparam/ammoLoadTime.h"
 
#include <vreMessageManager/vreMessage.h>
 
#include <matrix/vlTaitBryan.h>
#include <matrix/vlVector.h>
 
class DtBooleanInputPort;
class DtBooleanOutputPort;
class DtInputPortGroup;
class DtSimResource;
 
namespace makVrfEvents
{
class DtFireEvent;
class DtDetonationEvent;
} // namespace makVrfEvents
 
namespace makVre
{
class DtVreBallisticGunDescriptor;
class DtVreAmmunitionManager;
class DtProjectile;
 
//! \brief Type identifier for the VRE gun joystick actuator component
const char DtVreGunJoyActuatorType[] = "vre-gun-joystick-actuator";
 
//! \brief Actuator that models firing a turret mounted gun with joystick controls
//!
//! DtVreGunJoyActuator provides a model of a turret mounted gun controllable via joystick.
//! It extends the ballistic gun actuator and adds the ability to aim the gun using joystick
//! inputs without needing a separate aiming actuator. The component manages firing mechanics,
//! ammunition tracking, weapon switching, and projectile creation for various turret-mounted
//! weapons.
//!
//! Uses Descriptor Type: DtVreBallisticGunDescriptor
 
class VREVRFMODEL_DLL DtVreGunJoyActuator : public DtVreSimComponent<DtBallisticGunJoy>
{
public:
   //! \brief Constructor
   //! \param name The name of this component
   //! \param owner The local object that owns this component
   //! \param simManager The simulation services manager
   //! \param desc Component descriptor with configuration parameters
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //!
   //! Creates a new gun joystick actuator component with the specified parameters.
   DtVreGunJoyActuator(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the gun joystick actuator component,
   //! including ammunition manager and port connections.
   virtual ~DtVreGunJoyActuator() override;
 
   //! \brief Initializes the gun joystick actuator
   //! \return True if initialization is successful, false otherwise
   //!
   //! Performs initial setup of the gun joystick actuator, including port connections,
   //! ammunition management, and message handling. Called during component initialization.
   virtual bool init() override;
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtVreGunJoyActuatorType)
   //!
   //! Implements the DtSimComponent::type() method to return the
   //! type identifier for this component.
   virtual const char* type() const override;
 
   //! \brief Updates the actuator state each simulation frame
   //!
   //! Processes input controls, manages firing state, aims the gun using joystick inputs,
   //! and handles ammunition consumption during each simulation frame. This is the main
   //! update method called every simulation tick.
   virtual void tick() override;
 
   //! \brief Performs initialization before the first simulation tick
   //!
   //! Sets up initial states and configurations before the simulation begins,
   //! including loading ammunition types and initializing resources. This initialization
   //! is performed once before the first tick of the simulation.
   virtual void preFirstTickInit() override;
 
   //! \brief Updates the state properties for the gun actuator.
   //!
   //! Synchronizes and updates simulation state properties related to the gun actuator,
   //! such as ammunition counts, and weapon status. This method ensures
   //! that the current state of the gun is accurately reflected in the simulation's state
   //! properties for use by the VRE Frontend, networking, and other systems that
   //! monitor or display weapon status.
   //!
   //! Typically called after firing, reloading, or changing ammunition to keep
   //! state properties consistent with the gun's actual state.
   virtual void updateStateProperties();
 
public:
   //! \brief Factory method to create a new instance of this component
   //! \param name The name for the new component
   //! \param owner The local object that will own this component
   //! \param simManager The simulation services manager
   //! \param desc Optional component descriptor
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //! \return Pointer to the newly created component
   //!
   //! Static factory method used by the component creation system to instantiate
   //! new instances of this component type.
   static DtSimComponent* creator(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
protected:
   //! \brief Handles commander override message
   //! \param msg Pointer to the message containing override parameters
   //! \return Message processing result indicating success or failure
   //!
   //! Processes CommanderOverride messages, which activate or deactivate commander
   //! override mode. When in commander override mode, direct control inputs take
   //! precedence over AI control or other input methods.
   virtual DtVreMessageResult handleCommanderOverride(DtVreMessage* msg);
 
   //! \brief Gets the load time for a specific ammunition type
   //! \param ammoType The entity type ID of the ammunition
   //! \return The load time in seconds for the specified ammunition type
   //!
   //! Looks up the load time for the given ammunition type from the configured
   //! ammunition load time list. This determines how long it takes to switch
   //! to this ammunition type.
   virtual double getAmmoLoadTime(const DtEntityType& ammoType);
 
   //! \brief Controls the elevation aspect of gun aiming
   //! \return True if elevation aiming is complete, false otherwise
   //!
   //! Adjusts the elevation component of the gun's aim based on input controls.
   //! This method specifically handles the vertical movement of the gun turret.
   bool aimGunElevation();
 
   //! \brief Creates the port groups for weapon control
   //! \return True if port groups are successfully created, false otherwise
   //!
   //! Overridden to create the weapon control input port group. This method creates
   //! the port group structure needed for handling weapon control inputs via joystick.
   virtual bool createPortGroups() override;
 
   //! \brief Creates the input and output ports for the actuator
   //! \return True if ports are successfully created, false otherwise
   //!
   //! Overridden to create local ports for weapon control inputs (fire, next/previous
   //! weapon) and outputs (firing state) needed for joystick control.
   virtual bool createPorts() override;
 
   //! \brief Aims the gun based on joystick input ports
   //! \return True if aiming is complete, false otherwise
   //!
   //! Aims the gun based on joystick input ports. Uses the elevation input port
   //! to determine the correct elevation angle and the azimuth input port
   //! to determine the correct azimuth angle. Returns true when the gun has
   //! reached the desired aim position.
   virtual bool aimGun() override;
 
   //! \brief Structure containing the results of a firing action
   struct DtFireResult
   {
      DtDetonationResult result;         //!< Result of the detonation calculation
      double rangeToTarget;              //!< Range to the target in meters
      DtSimObjectReference targetEntity; //!< Reference to the targeted entity, if any
   };
 
   //! \brief Calculates the result of firing the weapon
   //! \param shooterPosition The geocentric position of the shooter
   //! \param shooterOrienation The orientation of the shooter
   //! \param fireResult Output parameter that will contain the fire result
   //!
   //! Calculates the result of firing the weapon from the given position and orientation.
   //! This includes determining if a target was hit, the range to the target, and
   //! the detonation result. The results are stored in the provided fireResult structure.
   virtual void getFireResult(
      const DtVector& shooterPosition, const DtTaitBryan shooterOrienation, DtFireResult& fireResult);
 
   //! \brief Creates a flyout projectile from the weapon
   //! \param shooterPosition The geocentric position of the shooter
   //! \param shooterOrienation The orientation of the shooter
   //! \return True if projectile was successfully created, false otherwise
   //!
   //! Creates a physical flyout projectile from the weapon at the specified position
   //! and with the specified orientation. This creates a visual representation of the
   //! projectile as it moves through the simulation.
   virtual bool createFlyOutProjectile(const DtVector& shooterPosition, const DtTaitBryan shooterOrienation);
 
   //! \brief Creates a detonation at the specified position
   //! \param detonationPosition The geocentric position where detonation occurs
   //! \param fireResult The fire result containing detonation parameters
   //!
   //! Creates a detonation at the given position using the fire result to determine
   //! detonation characteristics. This handles the effects and damage processing
   //! when a projectile reaches its target or maximum range.
   virtual void createDetonation(const DtVector& detonationPosition, const DtFireResult& fireResult);
 
 
   //! \brief Creates a fire event for interaction processing
   //! \param firingPosition The geocentric position of the firing point
   //! \param firingOrientation The orientation of the firing point
   //! \return Pointer to the created fire event, or nullptr if creation failed
   //!
   //! Creates and initializes a fire event based on the specified position and orientation.
   //! This event represents the firing of the weapon and is used in the interaction system.
   virtual makVrfEvents::DtFireEvent* createFireInteraction(
      const DtVector& firingPosition, const DtTaitBryan firingOrientation);
 
   //! \brief Creates a detonation event for interaction processing
   //! \param firingPosition The geocentric position of the firing point
   //! \param firingOrientation The orientation of the firing point
   //! \param fireResult The results of the firing calculation
   //! \param detTime Output parameter that will contain the detonation time
   //! \return Pointer to the created detonation event, or nullptr if creation failed
   //!
   //! Creates and initializes a detonation event based on the specified position,
   //! orientation, and fire result. This event represents the detonation of a projectile
   //! and is used in the interaction system. The detonation time is calculated and
   //! returned in the detTime parameter.
   virtual makVrfEvents::DtDetonationEvent* createDetonationInteraction(const DtVector& firingPosition,
      const DtTaitBryan firingOrientation, const DtFireResult& fireResult, DtReal& detTime);
 
   //! \brief Decrements the ammunition resource count
   //!
   //! Decrements the available ammunition count for the current munition type.
   //! This is called after firing the weapon to reflect ammunition consumption.
   virtual void decrementResource();
 
   //! \brief Gets the current ammunition resource count
   //! \return The number of available rounds for the current munition type
   //!
   //! Returns the number of available rounds remaining for the currently
   //! selected munition type. Used to track ammunition availability.
   virtual int currentResourceCount() const;
 
protected:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is protected and not implemented to prevent
   //! creation of instances without proper initialization.
   DtVreGunJoyActuator();
 
   //! \brief Copy constructor (not implemented)
   //!
   //! Copy constructor is protected and not implemented to prevent
   //! copy construction.
   DtVreGunJoyActuator(const DtVreGunJoyActuator& orig);
 
   //! \brief Assignment operator (not implemented)
   //! \return Reference to this object
   //!
   //! Assignment operator is protected and not implemented to prevent assignment.
   const DtVreGunJoyActuator& operator=(const DtVreGunJoyActuator& orig);
 
   //! \brief Sets the current munition type for the weapon
   //! \param munition Index of the munition type to set as current
   //!
   //! Updates the current munition type used by the weapon, which affects
   //! the ammunition type consumed and the firing characteristics.
   void setCurrentMunition(int munition);
   //! \brief Finds a specific resource by type
   //! \param resourceType The entity type of the resource to find
   //! \return Pointer to the resource if found, nullptr otherwise
   //!
   //! Searches for and returns a pointer to a resource of the specified type.
   //! This is used to access ammunition resources for the weapon.
   DtSimResource* findResource(DtEntityType resourceType);
   //! \brief Finds a specific resource by type (const version)
   //! \param resourceType The entity type of the resource to find
   //! \return Const pointer to the resource if found, nullptr otherwise
   //!
   //! Const version of findResource that searches for and returns a
   //! constant pointer to a resource of the specified type.
   const DtSimResource* findResource(DtEntityType resourceType) const;
 
   //! \brief Handles fire input messages from external sources
   //! \param msg Pointer to the message containing fire input parameters
   //! \return Message processing result indicating success or failure
   //!
   //! Processes FireInput messages, which provide external control over
   //! the firing state of the weapon. This allows the weapon to be fired
   //! through message-based commands rather than joystick inputs.
   virtual makVre::DtVreMessageResult handleFireInput(makVre::DtVreMessage* msg);
   //! \brief Handles weapon geometry messages for positioning
   //! \param msg Pointer to the message containing weapon geometry parameters
   //! \return Message processing result indicating success or failure
   //!
   //! Processes WeaponGeometry messages, which provide information about
   //! the position and orientation of the weapon. This is used for external
   //! control of weapon positioning, overriding articulated part geometry.
   virtual makVre::DtVreMessageResult handleWeaponGeometry(makVre::DtVreMessage* msg);
 
   //! \brief Initializes a resource for use with this weapon
   //! \param resource Pointer to the resource to initialize
   //!
   //! Sets up a simulation resource for use with this weapon, including
   //! configuring any necessary properties based on the weapon characteristics.
   //! This is typically called during initialization for each available ammunition type.
   virtual void initializeResource(const DtSimResource* resource);
 
protected:
   //! \brief Gets a munition object from a resource type
   //! \param resourceType The entity type of the resource
   //! \return Pointer to the munition object, or nullptr if not found
   //!
   //! Retrieves a munition object corresponding to the specified resource type.
   //! This translates between resource types and the actual munition objects
   //! that define the projectile characteristics.
   virtual DtSimMunition* getMunitionFromResourceType(const DtEntityType& resourceType) const;
   //! \brief Looks up a munition resource by entity type
   //! \param resource The entity type of the resource to find
   //! \return Const pointer to the resource if found, nullptr otherwise
   //!
   //! Looks up a munition resource by its entity type. This method searches
   //! through available resources to find a matching munition resource.
   virtual const DtSimResource* lookupMunitionResource(const DtEntityType& resource) const;
 
   //! \brief Cached pointer to the ballistic gun descriptor
   //!
   //! Caching expected derived descriptor pointer for convenience.
   //! Contains the configuration parameters for this gun component.
   DtVreBallisticGunDescriptor* myVreBallisticGunDescriptor;
 
   //! \brief List of ammunition load times
   //!
   //! Contains the load time information for different ammunition types,
   //! used to determine how long it takes to switch between ammunitions.
   makVre::DtAmmoLoadTimeList myAmmoLoadTimeList;
 
   //! \brief Port group for weapon control inputs
   DtInputPortGroup* myWeaponPortGroup;
 
   //! \brief Input port for fire command
   DtBooleanInputPort* myFirePort;
 
   //! \brief Input port for next weapon selection
   DtBooleanInputPort* myNextWeaponPort;
 
   //! \brief Input port for previous weapon selection
   DtBooleanInputPort* myPreviousWeaponPort;
 
   //! \brief Output port for firing state
   DtBooleanOutputPort* myFiringPort;
 
   // Used for each projectile that is in flight for
   // projectiles that are being incrementally flown out from the weapon
   // struct ProjectileInFlight
   //{
   //   DtEntityType myMunitionType;
 
   //   bool myShouldComputeDrag;  // Should drag be computed?  Not computing drag can reduce computation costs.
 
   //   //
   //   // Projectile properties
   //   //
   //   double myCrossSection;
   //   double myDragCoefficient;
   //   double myProjectileMass;
   //   double myMaxRange;  // This value is the squared of the max range to save having to use the sqrt operator.
 
   //   //
   //   // Projectile state
   //   //
   //   DtVector myPosition;
   //   DtVector myVelocity;
   //   double myDistanceTraveled;  // This value is the squared of the distance traveled to save having to use the sqrt
   //   operator.
   //};
   // std::list<ProjectileInFlight> myFiredProjectiles;
 
   //! \brief Manager for ammunition resources
   //!
   //! Handles tracking and management of ammunition resources for this weapon,
   //! including finding, loading, and decrementing ammunition counts.
   DtVreAmmunitionManager* myAmmunitionManager;
 
   //! \brief Structure containing munition configuration and state
   struct Munition
   {
      DtSimMunition myMunition;    //!< The munition object with projectile characteristics
      DtEntityType myResourceType; //!< The entity type of the resource for this munition
      double myLoadtime;           //!< Time required to load this munition type in seconds
   };
 
   //! \brief List of available munitions for this weapon
   std::vector<Munition> myMunitions;
 
   //! \brief Flag indicating whether the weapon is currently firing
   bool myIsFiring;
 
   //! \brief Index of the currently selected munition type
   int myCurrentMunition;
 
   //! \brief Current world position for firing the weapon
   DtVector myWorldFiringPosition;
 
   //! \brief Current world orientation for firing the weapon
   DtTaitBryan myWorldFiringOrientation;
   //! \brief Flag for overriding articulated part geometry
   //!
   //! Set to true when FireInput and WeaponGeometry messages are used for firing
   //! the weapon, false when using joystick input. Determines how myWorldFiringPosition
   //! and myWorldFiringOrientation values are set (either from FireInput/WeaponGeometry
   //! messages, or from articulated parts).
   bool myOverrideArtPartGeometry;
 
   //! \brief Flag for commander override mode
   //!
   //! When true, indicates that commander override mode is active, which gives
   //! direct control inputs precedence over AI control or other input methods.
   bool myCommanderOverrideActive;
 
   //! \brief Flag tracking previous engagement state
   //!
   //! Keeps track of engagement state so weapon can unload on disengagement.
   //! This prevents VR-Forces from using non-optimal ammunition under CGF control,
   //! which could occur when this component loads a munition and then CGF control
   //! fires on a valid target that might not be the best match by level of DIS
   //! enumeration specificity.
   bool myPreviouslyEngaged;
 
   //! \brief Elapsed time since player disengaged from gunner role
   //!
   //! Accumulates time in seconds since the player disengaged from the gunner role.
   //! Used to buffer the aimGun function to prevent CGF from immediately resetting
   //! gun elevation to 0 when swapping roles. Reset to 0.0 when player regains control.
   //!
   //! \see myReturnGunToCgfControlDuration
   double myDisengageElapsedTime;
 
   //! \brief Duration before returning gun control to CGF
   //!
   //! Time in seconds to wait after player disengages before allowing CGF to
   //! control gun aiming. This prevents unwanted elevation resets during role swaps.
   //! The value is read from the descriptor during initialization.
   //!
   //! \note Default value is 2.0 seconds
   //! \see myDisengageElapsedTime
   //! \see DtVreBallisticGunDescriptor::returnGunToCGFControlDuration()
   double myReturnGunToCgfControlDuration = 2.0;
};
 
} // namespace makVre