vreGunActuator.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreGunActuator.h
//! \ingroup vreVrfmodel
//! \brief Actuator that models firing a mounted gun
//!
//! This file defines the DtVreGunActuator class which provides a model of a
//! mounted gun actuator. It handles firing events, ammunition management, and
//! integrates with input controls for weapon operation.
#pragma once
 
#include "vreVrfmodel/export.h"
 
#include "vreVrfmodel/ballisticGunJoy.h"
 
#include "vreMessageManager/vreMessage.h"
 
#include <vrfobjcore/simObjectReference.h>
 
class DtBooleanInputPort;
class DtBooleanOutputPort;
class DtInputPortGroup;
 
//! \brief Type identifier for the VRE gun actuator component
const char DtVreGunActuatorType[] = "vre-gun-actuator";
 
//! \brief Timer type for gun detonation events
const unsigned int DtVreGunDetonationTimerType = 500;
 
namespace makVrfEvents
{
class DtFireEvent;
class DtDetonationEvent;
} // namespace makVrfEvents
 
//! \brief Actuator that models firing a mounted gun
//!
//! DtVreGunActuator provides a model of a mounted gun, handling firing events,
//! ammunition management, and weapon operation through input controls. This actuator
//! manages the firing logic, ammunition resources, and targeting for guns mounted on
//! entities such as vehicles or fixed emplacements.
//!
//! Uses Descriptor Type: DtVreGunActuatorDescriptor
 
namespace makVre
{
class DtVreGunActuatorDescriptor;
 
class VREVRFMODEL_DLL DtVreGunActuator : public DtActuatorComponent
{
protected:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is protected and not implemented to prevent
   //! creation of instances without proper initialization.
   DtVreGunActuator();
 
   //! \brief Copy constructor (not implemented)
   //!
   //! Copy constructor is protected and not implemented to prevent
   //! copy construction.
   DtVreGunActuator(const DtVreGunActuator& orig);
 
   //! \brief Assignment operator (not implemented)
   //! \return Reference to this object
   //!
   //! Assignment operator is protected and not implemented to prevent assignment.
   const DtVreGunActuator& operator=(const DtVreGunActuator& orig);
 
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 actuator component with the specified parameters.
   DtVreGunActuator(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the gun actuator component, including
   //! any pending detonation timers.
   virtual ~DtVreGunActuator() override;
 
   //! \brief Initializes the gun actuator
   //! \return True if initialization is successful, false otherwise
   //!
   //! Performs initial setup of the gun actuator, including port connections
   //! and state initialization. Called during component initialization.
   virtual bool init() override;
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtVreGunActuatorType)
   //!
   //! 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, 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.
   //! This initialization is performed once before the first tick of the simulation.
   virtual void preFirstTickInit() override;
 
 
   //! \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 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.
   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 and outputs,
   //! such as fire, next weapon, previous weapon, and firing state ports.
   virtual bool createPorts() override;
 
   //! \brief Creates the process state repository for the actuator
   //! \return True if the PSR is successfully created, false otherwise
   //!
   //! Creates the myProcessState data member and adds it to the process state
   //! repository manager. Uses the name and type specified in the component
   //! descriptor (if they exist) or appropriate defaults if not specified.
   //! This PSR is used to maintain state across simulation frames and saves.
   virtual bool createPSR();
 
   //! \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 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 Schedules a detonation event to occur at a specific time
   //! \param detInter Pointer to the detonation event to schedule
   //! \param detTime The simulation time at which the detonation should occur
   //!
   //! Schedules a detonation event to occur at the specified simulation time.
   //! This creates a timer that will trigger the detonation callback when the time is reached.
   virtual void scheduleDetonation(makVrfEvents::DtDetonationEvent* detInter, DtTime detTime);
 
   //! \brief Calculates the current muzzle position in world coordinates
   //! \return Vector containing the muzzle position coordinates
   //!
   //! Calculates the current world position of the weapon muzzle based on
   //! the entity position, orientation, and configured muzzle offset.
   DtVector calculateMuzzlePosition();
 
   //! \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 Callback function for detonation timers
   //! \param timer Pointer to the timer that triggered this callback
   //!
   //! Static callback function called when a detonation timer expires.
   //! This processes the detonation event associated with the timer.
   static void detonationCallback(DtTimer* timer);
 
   //! \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;
 
   //! \brief Flag indicating whether the weapon is currently firing
   bool myIsFiring;
 
   //! \brief Index of the currently selected munition type
   int myCurrentMunition;
 
   //! \brief Part ID of the articulated part the weapon is attached to
   int myAttachedPart;
 
   //! \brief Muzzle velocity of fired projectiles in meters per second
   double myMuzzleSpeed;
 
   //! \brief Number of rounds per magazine for ammunition management
   int myRoundsPerMagazine;
 
   //! \brief Rate of fire in rounds per minute
   int myRoundsPerMinute;
 
   //! \brief Offset vector from entity origin to muzzle position
   DtVector myMuzzleOffset;
 
   //! \brief Time required to load the weapon in seconds
   double myLoadTime;
 
   //! \brief Time required to unload the weapon in seconds
   double myUnloadTime;
 
   //! \brief Maximum effective range of the weapon in meters
   double myRange;
 
   //! \brief Name of the range parameter for configuration
   std::string myRangeName;
 
   //! \brief Number of rounds consumed per detonation event
   int myRoundsPerDetonation;
 
   //! \brief List of available munition types for this weapon
   std::vector<DtEntityType> myMunitionList;
 
   //! \brief List of active detonation timers
   DtList myTimerList;
 
   //! \brief Flag indicating whether a missing articulation warning has been reported
   bool myReportedNoArticulation;
 
   //! \brief Process state repository for preserving state data
   //!
   //! Container for state data associated with this component. This state
   //! is saved and restored as part of a scenario (or checkpoint).
   DtVrfBalGunPSR* myProcessState;
 
   //! \brief Pointer to the gun actuator descriptor with configuration parameters
   DtVreGunActuatorDescriptor* myGunDescriptor;
 
   //! \brief Reference to the current target entity
   //!
   //! Set by createFireInteraction and used by createDetonationInteraction.
   DtSimObjectReference myCurrentTarget;
 
   //! \brief Current event ID for tracking interaction events
   //!
   //! Set by createFireInteraction and used by createDetonationInteraction.
   DtString myCurrentEventId;
 
   //! \brief Current range to target in meters
   //!
   //! Set by createFireInteraction and used by createDetonationInteraction.
   DtReal myCurrentRange;
};
 
} // namespace makVre