vreBallisticGunDescriptor.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreBallisticGunDescriptor.h
//! \ingroup vreVrfobjparam
//! \brief Ballistic gun descriptor for VREngage
//!
//! This file defines the DtVreBallisticGunDescriptor class, which extends the base
//! ballistic gun descriptor with VREngage-specific parameters, including ammunition
//! load times, maximum range, and projectile configuration options.
 
#pragma once
 
#include "vreVrfobjparam/export.h"
#include "vreVrfObjparam/ammoLoadTime.h"
 
#include <vrfobjparam/ballisticGunDescriptor.h>
 
namespace makVre
{
//! \brief Type identifier string for the VREngage ballistic gun descriptor
const char DtVreBallisticGunDescriptorType[] = "vre-ballistic-gun-descriptor";
 
//! \brief Extended ballistic gun descriptor for VREngage weapon systems
//!
//! The DtVreBallisticGunDescriptor extends the base ballistic gun descriptor to add
//! ammunition-specific load times, maximum range, and additional configuration options
//! for VREngage weapon systems. This is particularly useful for complex weapon systems
//! like the LAV gun, where the gunner can utilize multiple different ammunition types
//! with different ballistic properties and loading times.
class VREVRFOBJPARAM_DLL DtVreBallisticGunDescriptor : public DtBallisticGunDescriptor
{
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 ballistic gun descriptor with the specified name.
   DtVreBallisticGunDescriptor(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 ballistic gun descriptor with the specified name.
   DtVreBallisticGunDescriptor(const DtSymbolString& componentName, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \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.
   DtVreBallisticGunDescriptor& operator=(const DtVreBallisticGunDescriptor& orig);
 
   //! \brief Copy constructor
   //! \param orig The source descriptor to copy from
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new ballistic gun descriptor as a copy of the provided original.
   DtVreBallisticGunDescriptor(const DtVreBallisticGunDescriptor& orig, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the descriptor.
   virtual ~DtVreBallisticGunDescriptor() 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 DtVreBallisticGunDescriptorType.
   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 ballistic gun descriptor as a deep copy of this one.
   virtual DtComponentDescriptor* clone(DtReaderWriterRegistry* parentRegistry = 0) const override;
 
   //! \brief Sets the ammunition load time list
   //! \param ammoLoadTimeList The list of ammunition load times
   //!
   //! Sets the list of ammunition types and their associated load times.
   //! This defines the loading time for each type of ammunition this gun can use.
   virtual void setAmmoLoadTimeList(const DtAmmoLoadTimeList& ammoLoadTimeList);
 
   //! \brief Gets the ammunition load time list
   //! \return The list of ammunition load times
   //!
   //! Returns the list of ammunition types and their associated load times.
   virtual DtAmmoLoadTimeList ammoLoadTimeList() const;
 
   //! \brief Gets the maximum range of the weapon
   //! \return The maximum range in meters
   //!
   //! Returns the maximum effective range of this weapon.
   virtual DtReal maxRange() const;
 
   //! \brief Sets the maximum range of the weapon
   //! \param maxRange The maximum range in meters
   //!
   //! Sets the maximum effective range of this weapon.
   virtual void setMaxRange(DtReal maxRange);
 
   //! \brief Checks if projectiles detonate at maximum range
   //! \return True if projectiles detonate at maximum range, false otherwise
   //!
   //! Returns whether projectiles should detonate when they reach maximum range
   //! if there is no line-of-sight collision before that point.
   virtual DtBoolean maxRangeDetonation() const;
 
   //! \brief Sets whether projectiles detonate at maximum range
   //! \param maxRangeDetonation True to enable detonation at maximum range, false otherwise
   //!
   //! Sets whether projectiles should detonate when they reach maximum range
   //! if there is no line-of-sight collision before that point.
   virtual void setMaxRangeDetonation(DtBoolean maxRangeDetonation);
 
   //! \brief Gets the initial munition type
   //! \return Reference to the initial munition entity type
   //!
   //! Returns the entity type of the munition that should be set as the
   //! initial current munition for this weapon.
   virtual const DtEntityType& initialMunition() const;
 
   //! \brief Sets the initial munition type
   //! \param munition The initial munition entity type
   //!
   //! Sets the entity type of the munition that should be used as the
   //! initial current munition for this weapon.
   virtual void setInitialMunition(const DtEntityType& munition);
 
   //! \brief Checks if flyout projectiles are created
   //! \return True if flyout projectiles are created, false otherwise
   //!
   //! Returns whether this weapon creates visible projectile entities
   //! when fired, rather than just simulating ballistic trajectories.
   virtual DtBoolean createFlyOutProjectile() const;
 
   //! \brief Sets whether flyout projectiles are created
   //! \param createFlyOutProjectile True to create flyout projectiles, false otherwise
   //!
   //! Sets whether this weapon creates visible projectile entities
   //! when fired, rather than just simulating ballistic trajectories.
   virtual void setCreateFlyOutProjectile(DtBoolean createFlyOutProjectile);
 
   //! \brief Gets the joystick function group
   //! \return String identifying the joystick function group
   //!
   //! Returns the joystick function group identifier, which is used to
   //! distinguish fire input meant for this weapon from other weapons.
   virtual const DtString& joystickFunctionGroup() const;
 
   //! \brief Sets the joystick function group
   //! \param group String identifying the joystick function group
   //!
   //! Sets the joystick function group identifier, which is used to
   //! distinguish fire input meant for this weapon from other weapons.
   virtual void setJoystickFunctionGroup(const DtString& group);
 
   //! \brief Gets the projectile type
   //! \return String identifying the projectile type
   //!
   //! Returns the type of projectile entity to create when the weapon is fired.
   //! This is used when createFlyOutProjectile is set to true.
   virtual const DtString& projectileType() const;
 
   //! \brief Sets the projectile type
   //! \param type String identifying the projectile type
   //!
   //! Sets the type of projectile entity to create when the weapon is fired.
   //! This is used when createFlyOutProjectile is set to true.
   virtual void setProjectileType(const DtString& type);
 
   //! \brief Gets the duration before returning gun control to CGF
   //! \return The duration in seconds
   //!
   //! Returns the time in seconds to wait after player disengages before
   //! allowing CGF to control gun aiming. This prevents unwanted elevation
   //! resets during role swaps.
   //!
   //! \see setReturnGunToCGFControlDuration()
   //! \see myReturnGunToCGFControlDuration
   virtual DtReal returnGunToCGFControlDuration() const;
 
   //! \brief Sets the duration before returning gun control to CGF
   //! \param duration The duration in seconds (must be >= 0)
   //!
   //! Sets the time in seconds to wait after player disengages before
   //! allowing CGF to control gun aiming. This prevents unwanted elevation
   //! resets during role swaps.
   //!
   //! \see returnGunToCGFControlDuration()
   //! \see myReturnGunToCGFControlDuration
   virtual void setReturnGunToCGFControlDuration(DtReal duration);
 
   //! \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();
 
private:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is private and not implemented to prevent
   //! creation of instances without proper initialization.
   DtVreBallisticGunDescriptor();
 
protected:
   //! \brief List of ammunition load times
   //!
   //! Stores the list of ammunition types and their associated load times.
   //! This defines the loading time for each type of ammunition this gun can use.
   DtAmmoLoadTimeList myAmmoLoadTimeList;
 
   //! \brief Maximum range of the weapon
   //!
   //! The maximum effective range of this weapon in meters.
   //! Parameter name: "max-range"
   //! Default value: 2000.0 meters
   DtRwReal myMaxRange;
 
   //! \brief Joystick function group identifier
   //!
   //! String used to distinguish fire input meant for this weapon from other weapons.
   //! This allows multiple weapons to be controlled by different joystick bindings.
   DtRwString myJoystickFunctionGroup;
 
   //! \brief Flag for maximum range detonation
   //!
   //! When true, projectiles will detonate when they reach maximum range
   //! if there is no line-of-sight collision before that point.
   //! Parameter name: "max-range-detonation"
   //! Default value: False
   DtRwBoolean myMaxRangeDetonation;
 
   //! \brief Initial munition entity type
   //!
   //! The entity type of the munition that should be set as the
   //! initial current munition for this weapon.
   //! Parameter name: "initial-munition"
   DtRwEntityType myInitialMunition;
 
   //! \brief Flag for creating flyout projectiles
   //!
   //! When true, this weapon creates visible projectile entities when fired,
   //! rather than just simulating ballistic trajectories.
   //! Parameter name: "create-flyout-projectile"
   //! Default value: False
   DtRwBoolean myCreateFlyOutProjectile;
 
   //! \brief Type of projectile to create
   //!
   //! The type of projectile entity to create when the weapon is fired.
   //! This is used when createFlyOutProjectile is set to true.
   //! Parameter name: "projectile-type"
   //! Default value: "DtProjectile"
   DtRwString myProjectileType;
 
   //! \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.
   //!
   //! Sysdef parameter: `return-gun-to-cgf-control-duration`
   //!
   //! \note Default value is 2.0 seconds
   //! \see returnGunToCGFControlDuration()
   //! \see setReturnGunToCGFControlDuration()
   DtRwReal myReturnGunToCGFControlDuration;
};
} // namespace makVre