humanGunJoyActuator.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file humanGunJoyActuator.h
//! \ingroup vreVrfmodel
//! \brief Actuator that models firing of handheld weapons with joystick control
//!
//! This file defines the DtHumanGunJoyActuator class which extends the ballistic gun
//! model with specialized behavior for human-held weapons. It adds the ability to
//! aim the gun from side to side without requiring a separate turret component.
#pragma once
 
#include "vreVrfmodel/export.h"
#include "vreVrfmodel/vreSimComponent.h"
 
#include "vreMessageManager/vreMessage.h"
 
#include <vreVrfmodel/ballisticGunJoy.h>
 
#include <vrfobjcore/humanLocalObjectFacade.h>
 
class DtAnalogInputPort;
 
namespace makVrfEvents
{
class DtFireEvent;
class DtDetonationEvent;
} // namespace makVrfEvents
 
namespace makVre
{
class DtVreHumanGunActuatorDescriptor;
class DtVreMunitionLoader;
 
//! \brief Type identifier for the human gun joystick actuator component
const char DtHumanGunJoyActuatorType[] = "human-gun-Joystick-actuator";
 
//! \brief Actuator for human-held weapons with joystick control
//!
//! DtHumanGunJoyActuator provides a model of a handheld gun/weapon that can
//! be controlled via joystick inputs.
//!
//! Component Type: human-gun-Joystick-actuator
//!
//! Descriptor Class: DtHumanGunActuatorDescriptor, Type: vre-human-gun-actuator-descriptor
 
class VREVRFMODEL_DLL DtHumanGunJoyActuator : 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 human gun joystick actuator component with the specified parameters.
   DtHumanGunJoyActuator(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the human gun joystick actuator component.
   virtual ~DtHumanGunJoyActuator() override;
 
   //! \brief Initializes the component
   //! \return True if initialization is successful, false otherwise
   //!
   //! Performs component initialization, setting up message handlers for fire input
   //! and initializing internal state for weapon operation.
   virtual bool init() override;
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtHumanGunJoyActuatorType)
   //!
   //! Implements the DtSimComponent::type() method to return the
   //! type identifier for this component.
   virtual const char* type() const override;
 
   //! \brief Updates the component state each simulation frame
   //!
   //! Checks for transitions to/from player control. Upon taking control as a player,
   //! disables thresholding of ammo counts (clip state properties) to ensure the most
   //! accurate information possible for display in the HUD. Upon leaving player control,
   //! restores thresholding of ammo counts to reduce network load for CGF entities that
   //! don't require the same degree of precision.
   virtual void tick() override;
 
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 Creates the process state repository for this component
   //! \return True if PSR was created successfully, false otherwise
   //!
   //! Creates the process state repository for this component and adds it to the
   //! process state repository manager. Uses the name and type specified in the
   //! component descriptor if they exist, otherwise uses appropriate default
   //! strings defined in procSRTypes.h.
   virtual bool createPSR() override;
 
   //! \brief Processes fire input messages
   //! \param msg Pointer to the fire input message
   //! \return Message processing result
   //!
   //! Handles FireInputMessage sent from role logic (human, tank, etc.) and updates
   //! myTriggerMunition, myTriggerWorldPosition, and myTriggerWorldOrientation parameters
   //! used for rapid fire in the tick function.
   virtual makVre::DtVreMessageResult handleFireInput(makVre::DtVreMessage* msg);
 
   //! \brief Aims the gun in elevation
   //! \return True if aiming in elevation is complete, false otherwise
   //!
   //! Adjusts the gun's elevation based on input port values or pre-calculated values.
   virtual bool aimGunElevation();
 
   //! \brief Creates input and output ports for this component
   //! \return True if ports were created successfully, false otherwise
   //!
   //! Creates the required input and output ports for this component,
   //! particularly the azimuth aiming port specific to the human gun actuator.
   virtual bool createPorts() override;
 
   //! \brief Aims the gun based on input port values
   //! \return True if aiming is complete, false otherwise
   //!
   //! Aims the gun based on input port values. Uses the myAimElevationInputPort
   //! to determine the correct elevation and the myAimAzimuthInputPort
   //! to determine the correct azimuth, combining them to aim the weapon appropriately.
   virtual bool aimGun() override;
 
   //! \brief Structure to store fire event results
   //!
   //! Contains information about a firing event, including detonation result,
   //! distance to target, and reference to any hit entity.
   struct DtFireResult
   {
      //! \brief Result of the detonation calculation
      DtDetonationResult result;
 
      //! \brief Distance to the target in meters
      double rangeToTarget;
 
      //! \brief Reference to the target entity, if one was hit
      DtSimObjectReference targetEntity;
   };
 
   //! \brief Calculates the result of firing the weapon
   //! \param shooterPosition The position of the shooter in world coordinates
   //! \param shooterOrienation The orientation of the shooter in world coordinates
   //! \param fireResult Output parameter to store the fire result data
   //!
   //! Performs the ballistic calculations to determine what happens when the
   //! weapon is fired from the given position and orientation.
   virtual void getFireResult(
      const DtVector& shooterPosition, const DtTaitBryan shooterOrienation, DtFireResult& fireResult);
 
   //! \brief Creates a fire event to send to the simulation
   //! \param firingPosition The position from which the weapon is fired
   //! \param firingOrientation The orientation of the weapon when fired
   //! \return Pointer to the newly created fire event
   //!
   //! Creates a fire event interaction based on the firing position and orientation,
   //! which will be sent to the simulation to notify other components about the firing.
   virtual makVrfEvents::DtFireEvent* createFireInteraction(
      const DtVector& firingPosition, const DtTaitBryan firingOrientation);
 
   //! \brief Creates a detonation event to send to the simulation
   //! \param firingPosition The position from which the weapon was fired
   //! \param firingOrientation The orientation of the weapon when fired
   //! \param fireResult Result data from the fire calculation
   //! \param detTime Output parameter to store the detonation time
   //! \return Pointer to the newly created detonation event
   //!
   //! Creates a detonation event interaction based on the firing position, orientation,
   //! and fire result data. This event notifies other components about the impact of the projectile.
   virtual makVrfEvents::DtDetonationEvent* createDetonationInteraction(const DtVector& firingPosition,
      const DtTaitBryan firingOrientation, const DtFireResult& fireResult, DtReal& detTime);
 
   //! \brief Reduces ammunition count after firing
   //! \param amount Number of ammunition units to deplete (default: 1)
   //!
   //! Reduces the ammunition count in the current magazine by the specified amount,
   //! reflecting the consumption of ammunition when firing the weapon.
   virtual void depleteResource(int amount = 1);
 
   //! \brief Re-initializes pointers after a restore operation
   //!
   //! Re-assigns pointers to extended state data since the pointers could have
   //! become invalid during a save/restore operation.
   virtual void setRestored();
 
   //! \brief Checks if the weapon is allowed to fire
   //! \return True if the weapon can fire, false otherwise
   //!
   //! Determines whether the weapon is currently allowed to fire based on
   //! ammunition availability, weapon state, and other conditions.
   virtual bool allowWeaponFiring();
 
   //! \brief Initiates the weapon firing sequence
   //! \return Message processing result
   //!
   //! Creates and sends a fire interaction event, representing the firing of the weapon.
   //! This method is used only by VR Engage controlled entities.
   virtual makVre::DtVreMessageResult fire();
 
   //! \brief Calculates weapon recoil effects
   //! \param worldShooterPosition The position of the shooter in world coordinates
   //! \param worldShooterOrientation The orientation of the shooter in world coordinates
   //! \return Modified orientation accounting for recoil
   //!
   //! Creates a hit offset to simulate weapon recoil. The offset increases
   //! with the number of rounds fired in rapid succession, simulating the
   //! cumulative effect of recoil on accuracy.
   virtual DtTaitBryan recoilEffect(DtVector worldShooterPosition, DtTaitBryan worldShooterOrientation);
 
protected:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is private and not implemented to prevent
   //! creation of instances without proper initialization.
   DtHumanGunJoyActuator();
 
   //! \brief Copy constructor (not implemented)
   //!
   //! Copy constructor is private and not implemented to prevent
   //! copy construction.
   DtHumanGunJoyActuator(const DtHumanGunJoyActuator& orig);
 
   //! \brief Assignment operator (not implemented)
   //! \return Reference to this object
   //!
   //! Assignment operator is private and not implemented to prevent assignment.
   const DtHumanGunJoyActuator& operator=(const DtHumanGunJoyActuator& orig);
 
protected:
   //! \brief Pointer to the human gun actuator descriptor
   //!
   //! Contains configuration parameters for this human gun actuator component.
   DtVreHumanGunActuatorDescriptor* myHumanGunDescriptor;
 
   //! \name Ports and Port Groups
   //! @{
 
   //! \brief Input port for controlling weapon azimuth aim
   //!
   //! Receives the azimuth at which to aim the weapon, in radians.
   //! Range: -pi to pi, with default value of 0.
   DtAnalogInputPort* myAimAzimuthInputPort;
 
   //! @}
 
   //! \brief Pointer to the firepower health state value
   //!
   //! Tracks the health/damage state of the weapon's firing capability.
   DtRwInt* myFirepowerHealth;
 
   //! \brief Number of rounds remaining in current burst
   //!
   //! Tracks how many more rounds can be fired in the current burst firing sequence.
   int myBurstRoundsRemaining;
 
   //! \brief Type of munition selected for firing
   //!
   //! Stores the munition type received from FireInputMessage to use
   //! for subsequent firing operations.
   DtEntityType myTriggerMunition;
 
   //! \brief World position for weapon firing
   //!
   //! Stores the location of the first burst fire received from FireInputMessage,
   //! used for subsequent rounds in a burst sequence.
   DtVector myTriggerWorldPosition;
 
   //! \brief World orientation for weapon firing
   //!
   //! Stores the orientation of the first burst fire received from FireInputMessage,
   //! used for subsequent rounds in a burst sequence.
   DtTaitBryan myTriggerWorldOrientation;
 
   //! \brief Facade for human local object access
   //!
   //! Provides simplified access to human-specific functionality of the local object.
   DtHumanLocalObjectFacade myHumanLocalObjectFacade;
 
   //! \brief Flag indicating if this entity is currently player-controlled
   //!
   //! Tracks whether the entity is currently under player control, which affects
   //! how ammunition state is reported and other behaviors.
   bool myPlayerControlled;
 
   //! \brief Pointer to the munition loader component
   //!
   //! Convenience pointer to the munition loader component, which must be of type
   //! DtVreMunitionLoader. Used to manage ammunition loading and state.
   DtVreMunitionLoader* myVreMunitionLoader;
};
 
} // namespace makVre