vreHumanGunActuatorDescriptor.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreHumanGunActuatorDescriptor.h
//! \ingroup vreVrfobjparam
//! \brief Human gun actuator descriptor for VREngage
//!
//! This file defines the DtVreHumanGunActuatorDescriptor class, which configures
//! human gun actuator components in VREngage. It provides parameters for realistic
//! human weapon handling, including recoil effects and burst fire behavior.
 
#pragma once
 
#include "vreVrfobjparam/export.h"
#include <vrfobjparam/humanGunActuatorDescriptor.h>
 
 
namespace makVre
{
//! \brief Type identifier string for the human gun actuator descriptor
const char DtVreHumanGunActuatorDescriptorType[] = "vre-human-gun-actuator-descriptor";
 
//! \brief Human gun actuator descriptor for VREngage
//!
//! This class defines a descriptor for human gun actuator components in VREngage.
//! It extends the base human gun actuator descriptor to add configuration for
//! realistic human weapon handling, including maximum range, burst fire behavior,
//! and recoil effects. These parameters affect how human entities interact with
//! and operate weapons in VREngage simulations.
class VREVRFOBJPARAM_DLL DtVreHumanGunActuatorDescriptor : public DtHumanGunActuatorDescriptor
{
public:
   //! \brief Constructor with component name
   //! \param name The name of this component
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new human gun actuator descriptor with the specified name.
   DtVreHumanGunActuatorDescriptor(const DtString& name, DtReaderWriterRegistry* parentRegistry = NULL);
 
   //! \brief Constructor with component name as symbol string
   //! \param name The name of this component as a symbol string
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new human gun actuator descriptor with the specified name.
   DtVreHumanGunActuatorDescriptor(const DtSymbolString& name, DtReaderWriterRegistry* parentRegistry = NULL);
 
   //! \brief Copy constructor
   //! \param orig The source descriptor to copy from
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new human gun actuator descriptor as a copy of the provided original.
   DtVreHumanGunActuatorDescriptor(
      const DtVreHumanGunActuatorDescriptor& orig, DtReaderWriterRegistry* parentRegistry = NULL);
 
   //! \brief Assignment operator
   //! \param orig The source descriptor to copy from
   //! \return Reference to this descriptor after assignment
   //!
   //! Assigns the contents of the provided descriptor to this one.
   DtVreHumanGunActuatorDescriptor& operator=(const DtVreHumanGunActuatorDescriptor& orig);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the descriptor.
   virtual ~DtVreHumanGunActuatorDescriptor() override;
 
   //! \brief Gets the type identifier for this descriptor
   //! \return String identifying this descriptor type
   //!
   //! Returns a unique type identifier string for this descriptor type.
   //! Will return DtVreHumanGunActuatorDescriptorType.
   virtual DtString type() const override;
 
   //! \brief Creates a clone of this descriptor
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //! \return Pointer to a new descriptor that is a clone of this one
   //!
   //! Creates a new human gun actuator descriptor as a deep copy of this one.
   virtual DtComponentDescriptor* clone(DtReaderWriterRegistry* parentRegistry = NULL) const override;
 
   //! \brief Gets the maximum range of the weapon
   //! \return The maximum range in meters
   //!
   //! Returns the maximum possible range of the weapon, beyond which projectiles
   //! cannot travel. This limits the length of the chord used in intersection tests
   //! for determining targets.
   virtual DtReal maxRange() const;
 
   //! \brief Sets the maximum range of the weapon
   //! \param maxRange The maximum range in meters
   //!
   //! Sets the maximum possible range of the weapon, beyond which projectiles
   //! cannot travel. This limits the length of the chord used in intersection tests
   //! for determining targets.
   virtual void setMaxRange(DtReal maxRange);
 
   //! \brief Gets the number of rounds per trigger pull
   //! \return The number of bullets fired per trigger pull
   //!
   //! Returns the number of bullets fired per trigger pull for burst fire mode.
   virtual DtInt16 burstPerTrigger() const;
 
   //! \brief Sets the number of rounds per trigger pull
   //! \param rounds The number of bullets fired per trigger pull
   //!
   //! Sets the number of bullets fired per trigger pull for burst fire mode.
   virtual void setBurstPerTrigger(DtInt16 rounds);
 
   //! \brief Gets the recoil offset vector
   //! \return Reference to the recoil offset vector
   //!
   //! Returns the offset vector that controls weapon orientation changes
   //! during rapid fire (burst) mode, simulating recoil effects.
   virtual const DtVector& recoilOffset() const;
 
   //! \brief Sets the recoil offset vector
   //! \param muzzleOffset The recoil offset vector
   //!
   //! Sets the offset vector that controls weapon orientation changes
   //! during rapid fire (burst) mode, simulating recoil effects.
   virtual void setRecoilOffset(const DtVector& muzzleOffset);
 
   //! \brief Checks if recoil offset is specified
   //! \return True if recoil offset is specified, false otherwise
   //!
   //! Returns whether a custom recoil offset has been specified for this weapon.
   virtual bool isRecoilOffsetSpecified() const;
 
   //! \brief Factory function to create a new instance of this descriptor
   //! \return Pointer to a newly created descriptor
   //!
   //! Static factory function used by the descriptor creation system to instantiate
   //! new instances of this descriptor type.
   static DtComponentDescriptor* creator();
 
protected:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is protected and not implemented to prevent
   //! creation of instances without proper initialization.
   DtVreHumanGunActuatorDescriptor();
 
protected:
   //! \brief Maximum range of the weapon in meters
   //!
   //! The maximum possible range of the weapon, beyond which projectiles
   //! cannot travel. This limits the length of the chord used in intersection
   //! tests for determining targets.
   //! Parameter name: "max-range"
   //! Default value: 500.0 meters
   DtRwReal myMaxRange;
 
   //! \brief Number of bullets fired per trigger pull
   //!
   //! Defines the number of bullets fired in sequence when the trigger is pulled once.
   //! Used for burst fire mode configuration.
   //! Parameter name: "rounds-per-trigger"
   //! Default value: 1 (single shot)
   //! Units: Bullets
   DtRwInt myBurstPerTrigger;
 
   //! \brief Recoil offset vector for weapon orientation during rapid fire
   //!
   //! This vector defines how the weapon orientation changes during rapid fire (burst) mode,
   //! simulating recoil effects. In a body coordinate system, the axes are specified as follows:
   //! - x: limits of the randomized change in weapon 'heading' (yaw)
   //! - y: limits of the randomized change in weapon 'pitch'
   //! - z: unused
   //!
   //! Parameter name: "recoil-offset"
   //! Default value: 0.0
   //! Units: Degrees
   DtRwOffsetVector myRecoilOffset;
};
} // namespace makVre