projectile.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file projectile.h
//! \ingroup vreVrfobjcore
//! \brief Projectile class for VREngage
//!
//! This file defines the DtProjectile class, which represents objects fired from weapons
//! in VREngage simulations. It models projectiles that follow ballistic trajectories,
//! taking into account the effects of gravity and drag.
 
#pragma once
#include "vreVrfobjcore/export.h"
#include "vreVrfobjcore/projectileDetonationResult.h"
#include "vreVrfobjcore/projectileFactory.h"
 
#include <readerWriter/rwReal.h>
#include <readerWriter/rwVector.h>
 
#include <vrfobjcore/simObjectReference.h>
 
#include <vrfutil/rwEntityType.h>
 
class DtPhysicalWorld;
 
namespace makVre
{
class DtProjectileFactory;
 
//! \brief Type identifier string for the projectile class
const char DtProjectileType[] = "DtProjectile";
 
//! \brief Class representing ballistic projectiles in simulations
//!
//! This class represents objects fired from weapons that follow ballistic trajectories,
//! taking into account effects such as gravity and drag. Projectiles are updated each
//! simulation frame to calculate their position based on physics, and can be used to
//! detect collisions with terrain or other entities.
class VREVRFOBJCORE_DLL DtProjectile : public DtReaderWriter
{
public:
   //! \brief Constructor with string name
   //! \param name The name of this projectile
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new projectile with the specified name.
   DtProjectile(const DtString& name, DtReaderWriterRegistry* const parentRegistry = NULL);
 
   //! \brief Constructor with symbol string name
   //! \param name The name of this projectile as a symbol string
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new projectile with the specified name.
   DtProjectile(const DtSymbolString& name, DtReaderWriterRegistry* const parentRegistry = NULL);
 
   //! \brief Copy constructor
   //! \param orig The source projectile to copy from
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new projectile as a copy of the provided original.
   DtProjectile(const DtProjectile& orig, DtReaderWriterRegistry* const parentRegistry = NULL);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the projectile.
   virtual ~DtProjectile() override {}
 
   //! \brief Assignment operator
   //! \param orig The source projectile to copy from
   //! \return Reference to this projectile after assignment
   //!
   //! Assigns the contents of the provided projectile to this one.
   DtProjectile& operator=(const DtProjectile& orig);
 
   //! \brief Creates a clone of this projectile
   //! \return Pointer to a new projectile that is a clone of this one
   //!
   //! Creates a new projectile as a deep copy of this one.
   virtual DtProjectile* clone() const;
 
   //! \brief Equality operator
   //! \param other The projectile to compare with (unnamed parameter)
   //! \return True if the projectiles are equal, false otherwise
   //!
   //! Compares this projectile with another to determine if they are equal.
   bool operator==(const DtProjectile&) const;
 
   //! \brief Inequality operator
   //! \param rhs The projectile to compare with
   //! \return True if the projectiles are not equal, false otherwise
   //!
   //! Compares this projectile with another to determine if they are not equal.
   bool operator!=(const DtProjectile& rhs) { return !(*this == rhs); };
 
   //! Returns the class type of projectile.  Used to create the correct class type
   //! of projectile object on read from an mtl file.  Derived classes should
   //! return their own unqiue type string to identify themselves.  Returns
   //! DtProjectileType.
   virtual DtString type() const;
 
   //! \brief Structure containing projectile update results
   //!
   //! This structure contains the results of updating a projectile's position,
   //! including the distance traveled in the current frame and the last position.
   struct ProjectileUpdateResult
   {
      //! \brief Distance traveled in the current frame in meters
      double distanceTraveledInFrame;
 
      //! \brief Last position of the projectile before the update
      DtVector lastPosition;
   };
 
   //! \brief Updates the projectile's state for the current frame
   //! \param deltaTime Time elapsed since the last update in seconds
   //! \return Result of the update, including detonation information if applicable
   //!
   //! Updates the projectile's position and velocity based on physics calculations,
   //! and checks for collisions with terrain or entities. If a collision is detected,
   //! the returned result will contain information about the detonation.
   virtual DtProjectileDetonationResult update(double deltaTime);
 
   //! \brief Sets the munition type
   //! \param munitionType The DIS entity type of the munition
   //!
   //! Sets the entity type that identifies this munition in DIS communications.
   virtual void setMunitionType(const DtEntityType& munitionType);
 
   //! \brief Sets the projectile cross-section
   //! \param crossSection The cross-sectional area in square meters
   //!
   //! Sets the cross-sectional area of the projectile, which affects drag calculations.
   virtual void setCrossSection(double crossSection);
 
   //! \brief Sets the drag coefficient
   //! \param dragCoefficient The dimensionless drag coefficient
   //!
   //! Sets the drag coefficient of the projectile, which affects how much air resistance
   //! slows down the projectile in flight.
   virtual void setDragCoefficient(double dragCoefficient);
 
   //! \brief Sets the projectile mass
   //! \param mass The mass in kilograms
   //!
   //! Sets the mass of the projectile in kilograms, which affects trajectory calculations.
   virtual void setMass(double mass);
 
   //! \brief Sets the maximum range
   //! \param maxRange The maximum range in meters
   //!
   //! Sets the maximum range the projectile can travel before being removed from the simulation.
   virtual void setMaxRange(double maxRange);
 
   //! \brief Sets the projectile position
   //! \param position The position vector in local coordinates
   //!
   //! Sets the current position of the projectile in local coordinates.
   virtual void setPosition(DtVector position);
 
   //! \brief Sets the projectile velocity
   //! \param velocity The velocity vector in meters per second
   //!
   //! Sets the current velocity of the projectile in meters per second.
   virtual void setVelocity(DtVector velocity);
 
   //! \brief Sets the distance traveled
   //! \param distanceTraveled The distance traveled in meters
   //!
   //! Sets the total distance the projectile has traveled since being fired.
   virtual void setDistanceTraveled(double distanceTraveled);
 
   //! \brief Sets the firing entity
   //! \param firingEntity Pointer to the entity that fired this projectile
   //!
   //! Sets the entity that fired this projectile.
   virtual void setFiringEntity(DtSimObject* firingEntity);
 
   //! \brief Sets the physical world
   //! \param physicalWorld Pointer to the physical world for terrain queries
   //!
   //! Sets the physical world used for terrain queries and gravity direction.
   virtual void setPhysicalWorld(DtPhysicalWorld* physicalWorld);
   //! \brief Gets the munition type
   //! \return Reference to the DIS entity type of the munition
   //!
   //! Returns the entity type that identifies this munition in DIS communications.
   virtual const DtEntityType& munitionType() { return myMunitionType; }
 
   //! \brief Gets the projectile velocity
   //! \return The current velocity vector in meters per second
   //!
   //! Returns the current velocity of the projectile in meters per second.
   virtual DtVector velocity() { return myVelocity; }
 
   //! Adds a given projectile creation function and corresponding
   //! type to the DtProjectileFactory.
   static void addProjectileCreatorFcn(const std::string& type, makVre::DtProjectileCreatorFcn fcn);
 
   //! Overrides base class putData to output our type.
   virtual void putData(std::string& fp, int indentLevel = 0) override;
 
   //! getData is just used to get us past the type in the data stream,
   //! since it's not actually stored.
   virtual DtlObjPtr getData(DtlObjPtr args,
      const DtReaderWriter::SearchPaths& searchPaths,
      const DtVariableBindingsList& variableBindings) override;
 
   //! The factory for creating objects of type DtProjectile.  The
   //! factory is used to generate projectiles on demand, when reading
   //! in from file (say from a process state repository entry in an
   //! order of battle file).
   //! @{
   static DtProjectileFactory* factory();
   static void setFactory(DtProjectileFactory* factory);
   //! @}
 
   //! Creates and initializes a projectile when reading in from an
   //! MTL (MAK Technologies Lisp) file (i.e. an order of battle file).
   //! \param mtlStream Input stream from an MTL file.
   //! \return Newly created and initialized instance of this class, with data
   //! read in from the MTL stream.
   static DtProjectile* createProjectile(DtlObjPtr mtlStream);
 
   //! Creates and initializes a new instance of this class
   //! \param type The projectile type identifier string
   //! \param pName DtReaderWriter name of the component
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //! \return Newly created and initialized instance of this class
   static DtProjectile* createProjectile(
      const char* type, const char* pName, DtReaderWriterRegistry* const parentRegistry = NULL);
 
   //! \return Newly created instance of this class, with an empty
   //! DtReaderWriter name. Creation methods are registered with a
   //! DtComponentDescriptorFactory, so they can be created on demand as they
   //! are read in from a parameter database file.
   static DtProjectile* creator(const DtString& name, DtReaderWriterRegistry* const parentRegistry = NULL);
 
protected:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is protected and not implemented to prevent
   //! creation of instances without proper initialization.
   DtProjectile();
 
   //! \brief Updates the projectile's position based on physics
   //! \param deltaTime Time elapsed since the last update in seconds
   //! \return Structure containing update results
   //!
   //! Internal method that calculates the projectile's new position and velocity
   //! based on physics, including gravity and drag effects.
   virtual ProjectileUpdateResult updateProjectilePosition(double deltaTime);
 
   //! \brief Checks if the projectile has collided with anything
   //! \param projectUpdateResult Results from the position update
   //! \return Information about the collision and detonation
   //!
   //! Internal method that checks if the projectile has collided with terrain
   //! or entities based on its updated position.
   virtual DtProjectileDetonationResult checkForProjectileCollision(const ProjectileUpdateResult& projectUpdateResult);
 
protected:
   //! \brief The DIS entity type of the munition
   //!
   //! Stores the entity type that identifies this munition in DIS communications.
   DtRwEntityType myMunitionType;
 
   //! \brief The cross-sectional area of the projectile
   //!
   //! Stores the cross-sectional area of the projectile in square meters,
   //! which affects drag calculations.
   DtRwReal myCrossSection;
 
   //! \brief The drag coefficient of the projectile
   //!
   //! Stores the dimensionless drag coefficient, which affects how much
   //! air resistance slows down the projectile in flight.
   DtRwReal myDragCoefficient;
 
   //! \brief The mass of the projectile in kilograms
   //!
   //! Stores the mass of the projectile, which affects trajectory calculations.
   DtRwReal myMass;
 
   //! \brief The maximum range of the projectile in meters
   //!
   //! Stores the maximum range the projectile can travel before being removed
   //! from the simulation. This is technically a weapon property but is stored
   //! with the projectile to determine the maximum flight distance.
   DtRwReal myMaxRange;
 
   //! \brief The current position of the projectile
   //!
   //! Stores the current position of the projectile in local coordinates.
   //! This is updated every frame.
   DtRwVector myPosition;
 
   //! \brief The current velocity of the projectile
   //!
   //! Stores the current velocity of the projectile in meters per second.
   //! This is updated every frame based on physics calculations.
   DtRwVector myVelocity;
 
   //! \brief The total distance the projectile has traveled
   //!
   //! Stores the total distance the projectile has traveled since being fired.
   //! This is used to test against the maximum range to determine when to
   //! remove the projectile if it hasn't collided with anything.
   DtRwReal myDistanceTraveled;
 
   //! \brief Pointer to the entity that fired this projectile
   //!
   //! Stores a pointer to the entity that fired this projectile.
   DtSimObject* myFiringEntity;
 
   //! \brief Pointer to the physical world
   //!
   //! Stores a pointer to the physical world for terrain queries and
   //! to retrieve the world's gravity direction.
   DtPhysicalWorld* myPhysicalWorld;
 
   //! \brief Factory for creating projectile instances
   //!
   //! Static pointer to the factory used to construct projectiles. Used to create
   //! the appropriate type of DtProjectile object when reading from files.
   static DtProjectileFactory* theFactory;
};
} // namespace makVre