customProjectile.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/
 
//! \file customProjectile.h
//! \brief Custom projectile class demonstrating VR-Forces projectile extension pattern
//!
//! DtCustomProjectile extends the standard DtProjectile class to add custom behavior
//! and an internal time-in-flight state. This example demonstrates the complete
//! pattern for creating custom munition types in VR-Forces, including update logic
//! and factory integration.
//!
//! Key Patterns Demonstrated:
//! - Extending VR-Forces projectile base class
//! - Tracking additional runtime state in a custom projectile
//! - Overriding update() for custom physics or behavior
//! - Factory creator pattern for projectile instantiation
 
#pragma once
#include <vreVrfobjcore/projectile.h>
 
//! Type identifier string for custom projectile class
//! Used by factory system to create instances and for MTL file serialization
constexpr char DtCustomProjectileType[] = "DtCustomProjectile";
 
//! \brief Custom projectile class with additional time-in-flight tracking
//!
//! PATTERN: Extending VR-Forces Projectile Classes
//! To create custom munition types in VR-Forces:
//! 1. Derive from makVre::DtProjectile (or DtBallistic, DtGuided for specific types)
//! 2. Add any additional state needed for your behavior (for example, accumulated
//!    time in flight)
//! 3. Override update() to implement custom physics or behavior
//! 4. Implement clone(), operator==, type(), and static creator() methods
//! 5. Register with projectile factory in plugin initialization
//!
//! This Example:
//! Adds a time-in-flight value that accumulates the total flight time at runtime.
//! The value is not configurable in data files and is not serialized; it exists
//! only while the projectile is active in the simulation. This simple example can
//! be extended with:
//! - Custom guidance algorithms (target tracking, waypoint following)
//! - Environmental effects (wind, gravity variations)
//! - Special detonation logic (proximity fuze, timed fuze)
//! - Visual effects (smoke trails, exhaust plumes)
//! - Performance characteristics (fuel consumption, thrust curves)
//!
//! REUSABLE: This class structure is directly reusable for any custom projectile type.
//! Replace myTimeInFlight with your custom parameters and update() logic with your
//! custom behavior.
//!
class DtCustomProjectile : public makVre::DtProjectile
{
public:
   //! \brief Construct projectile with string name
   //!
   //! PATTERN: Projectile Construction
   //! Projectiles are constructed with a name (used for identification and debugging)
   //! and an optional parent registry (for hierarchical parameter organization used
   //! by the base class).
   //!
   //! The constructor must:
   //! 1. Initialize the base class (DtProjectile)
   //! 2. Initialize any custom state
   //!
   //! \param name Unique identifier for this projectile instance
   //! \param parentRegistry Optional parent registry for hierarchical organization
   //!
   DtCustomProjectile(const DtString& name, DtReaderWriterRegistry* const parentRegistry = nullptr);
 
   //! \brief Construct projectile with symbol string name
   //! \param name Symbol string identifier for this projectile instance
   //! \param parentRegistry Optional parent registry for hierarchical organization
   DtCustomProjectile(const DtSymbolString& name, DtReaderWriterRegistry* const parentRegistry = nullptr);
 
   //! \brief Copy constructor for projectile cloning
   //!
   //! PATTERN: Projectile Copying
   //! Projectiles must be copyable for cloning (for example, when creating multiple
   //! rounds from a template). The copy constructor must:
   //! 1. Copy base class state
   //! 2. Copy all custom state
   //!
   //! \param orig Source projectile to copy
   //! \param parentRegistry Optional parent registry for the copy
   //!
   DtCustomProjectile(const DtCustomProjectile& orig, DtReaderWriterRegistry* const parentRegistry = nullptr);
 
   //! \brief Destructor - base class handles cleanup
   virtual ~DtCustomProjectile() override {}
 
   //! \brief Assignment operator for projectile state copying
   //!
   //! Must copy both base class state and all custom parameters.
   //!
   //! \param orig Source projectile to copy from
   //! \return Reference to this projectile for assignment chaining
   //!
   DtCustomProjectile& operator=(const DtCustomProjectile& orig);
 
   //! \brief Create a deep copy of this projectile
   //!
   //! Required by VR-Forces framework for projectile instantiation from templates.
   //! When multiple rounds of the same munition type are fired, the framework clones
   //! a template projectile rather than re-reading configuration files.
   //!
   //! \return New projectile instance with copied state
   //!
   virtual makVre::DtProjectile* clone() const override;
 
   //! \brief Equality comparison for projectile state
   //! \param rhs Projectile to compare against
   //! \return true if all parameters match, false otherwise
   bool operator==(const DtCustomProjectile&) const;
 
   //! \brief Inequality comparison for projectile state
   //! \param rhs Projectile to compare against
   //! \return true if any parameters differ, false if all match
   bool operator!=(const DtCustomProjectile& rhs) const { return !(*this == rhs); };
 
   //! \brief Return the class type identifier string
   //!
   //! PATTERN: Projectile Type Identification
   //! The type() method returns a unique string identifying this projectile class.
   //! This string is used by:
   //! - Factory system to create correct class instances
   //! - MTL file serialization to identify projectile class on load
   //! - Runtime type identification (alternative to dynamic_cast)
   //!
   //! The type string must match the string used in factory registration.
   //!
   //! \return Type identifier string (DtCustomProjectileType constant)
   //!
   virtual DtString type() const override;
 
   //! \brief Update projectile state for one simulation frame
   //!
   //! PATTERN: Custom Projectile Update Logic
   //! The update() method is called once per simulation frame to advance projectile
   //! physics and behavior. Custom projectiles override this to implement:
   //! - Custom guidance algorithms (updating velocity/orientation)
   //! - Time-based effects (fuel depletion, stage separation)
   //! - Environmental interactions (wind drift, drag calculations)
   //! - Custom detonation conditions (proximity detection, time fuzes)
   //!
   //! This Example:
   //! Increments the time-in-flight parameter by deltaTime, then calls the base
   //! class update() to perform standard projectile physics (position integration,
   //! collision detection, detonation logic).
   //!
   //! REUSABLE: This override pattern applies to any custom update logic. Always
   //! call the base class update() unless completely replacing default physics.
   //!
   //! \param deltaTime Time elapsed since last update in seconds
   //! \return Detonation result indicating if projectile should be removed
   //!
   virtual makVre::DtProjectileDetonationResult update(double deltaTime) override;
 
   //! \brief Static factory creator method
   //!
   //! PATTERN: Projectile Factory Pattern
   //! VR-Forces uses factory methods to instantiate projectiles by type name.
   //! The creator() method must be static and return a new instance of this class.
   //!
   //! This method is registered with the projectile factory during plugin initialization:
   //!   DtProjectileFactory::instance().registerProjectile(
   //!      DtCustomProjectileType, &DtCustomProjectile::creator);
   //!
   //! When MTL files reference this projectile type, the factory uses this creator
   //! to instantiate objects.
   //!
   //! REUSABLE: This exact signature is required for all custom projectiles.
   //!
   //! \param name Name for the new projectile instance
   //! \param parentRegistry Optional parent registry for the new instance
   //! \return Newly created projectile instance
   //!
   static makVre::DtProjectile* creator(const DtString& name, DtReaderWriterRegistry* const parentRegistry = nullptr);
 
protected:
   //! Default constructor - not implemented (projectiles require names)
   DtCustomProjectile();
 
protected:
   //! Custom time-in-flight parameter
   //!
   //! The time-in-flight value is internal simulation state. It is not configured
   //! from data files and is not serialized; it is reset to zero when the projectile
   //! is constructed and accumulates while the projectile is active.
   double myTimeInFlight;
};