vreGunActuatorDescriptor.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreGunActuatorDescriptor.h
//! \ingroup vreVrfobjparam
//! \brief Gun actuator descriptor for VREngage
//!
//! This file defines the DtVreGunActuatorDescriptor class, which configures gun
//! actuator components in VREngage. It provides parameters for ammunition, firing rates,
//! ranges, and other properties necessary for gun behavior in simulations.
 
#pragma once
 
#include "vreVrfobjparam/export.h"
#include <vrfobjparam/actuatorComponentDescriptor.h>
#include <vrfutil/rwStringList.h>
#include <readerWriter/rwInt.h>
#include <readerWriter/rwVector.h>
 
namespace makVre
{
//! \brief Type identifier string for the gun actuator descriptor
const char DtVreGunActuatorDescriptorType[] = "vre-gun-actuator-descriptor";
 
//! \brief Gun actuator descriptor for VREngage weapon systems
//!
//! This class defines a descriptor for gun actuator components in VREngage.
//! It provides configuration for ammunition, firing rates, ranges, muzzle parameters,
//! and other properties necessary for realistic gun behavior in simulations.
class VREVRFOBJPARAM_DLL DtVreGunActuatorDescriptor : public DtActuatorComponentDescriptor
{
private:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is private and not implemented to prevent
   //! creation of instances without proper initialization.
   DtVreGunActuatorDescriptor();
 
public:
   //! \brief Constructor with component name
   //! \param componentName The name of this component
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new gun actuator descriptor with the specified name.
   DtVreGunActuatorDescriptor(const DtString& componentName, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Constructor with component name as symbol string
   //! \param componentName The name of this component as a symbol string
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new gun actuator descriptor with the specified name.
   DtVreGunActuatorDescriptor(const DtSymbolString& componentName, 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 gun actuator descriptor as a copy of the provided original.
   DtVreGunActuatorDescriptor(const DtVreGunActuatorDescriptor& orig, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the descriptor.
   virtual ~DtVreGunActuatorDescriptor() override;
 
   //! \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.
   DtVreGunActuatorDescriptor& operator=(const DtVreGunActuatorDescriptor& orig);
 
   //! \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 DtVreGunActuatorDescriptorType.
   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 gun actuator descriptor as a deep copy of this one.
   virtual DtComponentDescriptor* clone(DtReaderWriterRegistry* parentRegistry = 0) const override;
 
   //! \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();
 
   //! \brief Gets the attached part index
   //! \return The index of the attached part
   //!
   //! Returns the index of the articulated part to which this gun is attached.
   virtual int attachedPart() const;
 
   //! \brief Sets the attached part index
   //! \param part The index of the attached part
   //!
   //! Sets the index of the articulated part to which this gun is attached.
   virtual void setAttachedPart(int part);
 
   //! \brief Gets the muzzle speed
   //! \return The muzzle speed in meters per second
   //!
   //! Returns the speed of projectiles as they exit the gun's muzzle.
   virtual DtReal muzzleSpeed() const;
 
   //! \brief Sets the muzzle speed
   //! \param muzzleSpeed The muzzle speed in meters per second
   //!
   //! Sets the speed of projectiles as they exit the gun's muzzle.
   virtual void setMuzzleSpeed(DtReal muzzleSpeed);
 
   //! \brief Gets the number of rounds per magazine
   //! \return The number of rounds per magazine
   //!
   //! Returns the number of rounds that can be loaded in a single magazine.
   virtual int roundsPerMagazine() const;
 
   //! \brief Sets the number of rounds per magazine
   //! \param roundsPerMagazine The number of rounds per magazine
   //!
   //! Sets the number of rounds that can be loaded in a single magazine.
   virtual void setRoundsPerMagazine(int roundsPerMagazine);
 
   //! \brief Gets the firing rate
   //! \return The firing rate in rounds per minute
   //!
   //! Returns the maximum firing rate of the gun in rounds per minute.
   virtual int roundsPerMinute() const;
 
   //! \brief Sets the firing rate
   //! \param roundsPerMinute The firing rate in rounds per minute
   //!
   //! Sets the maximum firing rate of the gun in rounds per minute.
   virtual void setRoundsPerMinute(const int roundsPerMinute);
 
   //! \brief Gets the muzzle offset
   //! \return Reference to the muzzle offset vector
   //!
   //! Returns the offset vector from the entity's origin to the gun's muzzle.
   virtual const DtVector& muzzleOffset() const;
 
   //! \brief Sets the muzzle offset
   //! \param muzzleOffset The muzzle offset vector
   //!
   //! Sets the offset vector from the entity's origin to the gun's muzzle.
   virtual void setMuzzleOffset(const DtVector& muzzleOffset);
 
   //! \brief Gets the loading time
   //! \return The loading time in seconds
   //!
   //! Returns the time required to load a new magazine into the gun.
   virtual DtReal loadTime() const;
 
   //! \brief Sets the loading time
   //! \param loadTime The loading time in seconds
   //!
   //! Sets the time required to load a new magazine into the gun.
   virtual void setLoadTime(DtReal loadTime);
 
   //! \brief Gets the unloading time
   //! \return The unloading time in seconds
   //!
   //! Returns the time required to unload a magazine from the gun.
   virtual DtReal unloadTime() const;
 
   //! \brief Sets the unloading time
   //! \param unloadTime The unloading time in seconds
   //!
   //! Sets the time required to unload a magazine from the gun.
   virtual void setUnloadTime(DtReal unloadTime);
 
   //! \brief Gets the effective range
   //! \return The effective range in meters
   //!
   //! Returns the effective range of the gun for accurate targeting.
   virtual DtReal range() const;
 
   //! \brief Sets the effective range
   //! \param range The effective range in meters
   //!
   //! Sets the effective range of the gun for accurate targeting.
   virtual void setRange(DtReal range);
 
 
   //! \brief Gets the range name
   //! \return String identifying the range configuration
   //!
   //! Returns a name that identifies the range configuration of this gun.
   virtual const DtString& rangeName() const;
 
   //! \brief Sets the range name
   //! \param rangeName String identifying the range configuration
   //!
   //! Sets a name that identifies the range configuration of this gun.
   virtual void setRangeName(const DtString& rangeName);
 
 
   //! \brief Gets the number of rounds per detonation
   //! \return The number of rounds required for detonation
   //!
   //! Returns the number of rounds that must be fired before detonation occurs.
   //! This is typically used for special ammunition types that require multiple hits.
   virtual int roundsPerDetonation() const;
 
   //! \brief Sets the number of rounds per detonation
   //! \param rpd The number of rounds required for detonation
   //!
   //! Sets the number of rounds that must be fired before detonation occurs.
   //! This is typically used for special ammunition types that require multiple hits.
   virtual void setRoundsPerDetonation(const int rpd);
 
   //! \brief Gets the list of available munitions
   //! \return Reference to the list of munition names
   //!
   //! Returns a list of names identifying the types of munitions this gun can use.
   virtual const DtRwStringList& munitionList() const;
 
   //! \brief Sets the list of available munitions
   //! \param munitionList The list of munition names
   //!
   //! Sets the list of names identifying the types of munitions this gun can use.
   virtual void setMunitionList(DtRwStringList& munitionList);
 
   //! \brief Gets the maximum range
   //! \return The maximum range in meters
   //!
   //! Returns the maximum possible range of the gun, 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
   //! \param range The maximum range in meters
   //!
   //! Sets the maximum possible range of the gun, beyond which projectiles
   //! cannot travel. This limits the length of the chord used in intersection tests
   //! for determining targets.
   virtual void setMaxRange(DtReal range);
 
protected:
   //! \brief Index of the articulated part to which this gun is attached
   DtRwInt myAttachedPart;
 
   //! \brief Speed of projectiles as they exit the gun's muzzle in meters per second
   DtRwReal myMuzzleSpeed;
 
   //! \brief Number of rounds that can be loaded in a single magazine
   DtRwInt myRoundsPerMagazine;
 
   //! \brief Maximum firing rate of the gun in rounds per minute
   DtRwReal myRoundsPerMinute;
 
   //! \brief Offset vector from the entity's origin to the gun's muzzle
   DtRwOffsetVector myMuzzleOffset;
 
   //! \brief Time required to load a new magazine in seconds
   DtRwReal myLoadTime;
 
   //! \brief Time required to unload a magazine in seconds
   DtRwReal myUnloadTime;
 
   //! \brief Effective range of the gun for accurate targeting in meters
   DtRwReal myRange;
 
   //! \brief Name identifying the range configuration of this gun
   DtRwString myRangeName;
 
   //! \brief Number of rounds that must be fired before detonation occurs
   //!
   //! Used for special ammunition types that require multiple hits for detonation.
   DtRwInt myRoundsPerDetonation;
 
   //! \brief List of names identifying the types of munitions this gun can use
   DtRwStringList myMunitionList;
 
   //! \brief Maximum possible range of the gun in meters
   //!
   //! The maximum range 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: 2000 meters
   DtRwReal myMaxRange;
};
} // namespace makVre