vreVrfBalGunPSR.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreVrfBalGunPSR.h
//! \ingroup vreVrfobjcore
//! \brief Ballistic gun process state repository for VREngage
//!
//! This file defines the DtVreVrfBalGunPSR class, which extends the basic ballistic gun PSR
//! to provide VREngage-specific functionality for ballistic gun weapons. It adds support for
//! managing projectiles in flight, including tracking and updating their positions and handling
//! detonation events.
 
#pragma once
#include "vreVrfobjcore/export.h"
#include "vreVrfobjcore/projectileDetonationResult.h"
#include "vreVrfobjcore/projectileList.h"
 
#include <vrfobjcore/vrfTurretedBalGunPSR.h>
 
namespace makVre
{
class DtVreVrfBalGunPSR;
 
//! \brief Type identifier string for the VREngage ballistic gun PSR
const char DtVreVrfBalGunPSRType[] = "vre-vrf-bal-gun-psr";
 
//! \brief Extended ballistic gun process state repository for VREngage
//!
//! This class extends the basic turreted ballistic gun PSR to provide VREngage-specific
//! functionality for ballistic gun weapons. It adds support for managing projectiles
//! in flight, including tracking and updating their positions and handling detonation
//! events. This is used to implement more realistic ballistic behavior in VREngage.
class VREVRFOBJCORE_DLL DtVreVrfBalGunPSR : public DtVrfTurretedBalGunPSR
{
public:
   //! \brief Constructor with VRF object and optional name
   //! \param vrfObject Pointer to the local object this PSR is associated with
   //! \param rwName Optional reader/writer name
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //!
   //! Creates a new ballistic gun PSR for the specified VRF object.
   DtVreVrfBalGunPSR(DtLocalObject* vrfObject, const DtString& rwName = DtString::nullString(),
      DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Copy constructor
   //! \param orig The source PSR to copy from
   //! \param rwName Optional reader/writer name
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //!
   //! Creates a new ballistic gun PSR as a copy of the provided original.
   DtVreVrfBalGunPSR(const DtVreVrfBalGunPSR& orig, const DtString& rwName = DtString::nullString(),
      DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the PSR.
   virtual ~DtVreVrfBalGunPSR() override {}
 
   //! \brief Assignment operator
   //! \param orig The source PSR to copy from
   //! \return Reference to this PSR after assignment
   //!
   //! Assigns the contents of the provided PSR to this one.
   DtVreVrfBalGunPSR& operator=(const DtVreVrfBalGunPSR& orig);
 
   //! \brief Creates a clone of this PSR
   //! \param rwName Optional reader/writer name for the clone
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //! \return Pointer to a new PSR that is a clone of this one
   //!
   //! Creates a new ballistic gun PSR as a deep copy of this one.
   virtual DtVrfProcessStateRepository* clone(const DtString& rwName = DtString::nullString(),
      DtReaderWriterRegistry* parentRegistry = 0) const override;
 
   //! \brief Gets the type identifier for this PSR
   //! \return String identifying this PSR type
   //!
   //! Returns a unique type identifier string for this PSR type.
   //! Will return DtVreVrfBalGunPSRType.
   virtual DtString type() const override;
 
   //! \brief Sets the physical world pointer
   //! \param physicalWorld Pointer to the physical world
   //!
   //! Sets a pointer to the physical world, caching it so it can be passed on to
   //! any DtProjectile objects the PSR is maintaining. This is needed when reading
   //! in the contents of the projectile list from the order of battle, and for
   //! projectile collision detection with terrain.
   virtual void setPhysicalWorld(DtPhysicalWorld* physicalWorld);
 
   //! \brief Sets the firing entity
   //! \param firingEntity Pointer to the entity that is firing the weapon
   //!
   //! Sets the identity of the firing entity, caching it so it can be passed on to
   //! any DtProjectile objects the PSR is maintaining. This is needed when reading
   //! in the contents of the projectile list from the order of battle, and for
   //! tracking which entity fired each projectile.
   virtual void setFiringEntity(DtSimObject* firingEntity);
 
   //! \brief Adds a projectile to the tracking list
   //! \param projectile The projectile to add
   //!
   //! Adds a new projectile to the set of projectiles being tracked by this PSR.
   //! The projectile's position will be updated during calls to updateProjectiles().
   //! A copy of the projectile is made and stored in the internal projectile list.
   virtual void addProjectile(const DtProjectile& projectile);
 
   //! \brief Removes all tracked projectiles
   //!
   //! Removes and destroys all projectiles currently being tracked by this PSR.
   //! This is typically called when the weapon is destroyed or when clearing
   //! the simulation state.
   virtual void removeAllProjectiles();
 
   //! \brief Updates all tracked projectiles
   //! \param deltaTime Time elapsed since the last update in seconds
   //! \return List of detonation results for projectiles that detonated during this update
   //!
   //! Iterates over the list of active projectiles, calling their update() function to
   //! update their positions based on physics. For any projectiles that detonate (hit
   //! something or reach maximum range), they are removed from the list and information
   //! about their detonation is returned.
   virtual std::list<DtProjectileDetonationResult> updateProjectiles(double deltaTime);
 
   //! \brief Processes an MTL stream to initialize this PSR
   //! \param args Input stream from an MTL file
   //! \param searchPaths Search paths for resolving references
   //! \param variableBindings Variable bindings for resolving references
   //!
   //! Overrides the base class getSelf method to handle reading the projectile list
   //! and other VREngage-specific ballistic gun state from an MTL stream.
   virtual void getSelf(DtlObjPtr args,
      const DtReaderWriter::SearchPaths& searchPaths,
      const DtVariableBindingsList& variableBindings) override;
 
   //! \brief Factory function to create a new instance of this PSR
   //! \param rwName The reader/writer name for the new instance
   //! \param vrfObject Pointer to the local object this PSR will be associated with
   //! \param parentRegistry Parent registry for reader/writer functionality
   //! \return Pointer to a newly created PSR instance
   //!
   //! Static factory function used by the PSR creation system to instantiate
   //! new instances of this PSR type.
   static DtVrfProcessStateRepository* creator(
      const DtString& rwName, DtLocalObject* vrfObject, DtReaderWriterRegistry* parentRegistry);
 
protected:
   //! \brief List of tracked projectiles
   //!
   //! Stores the list of projectiles whose positions are updated every frame.
   //! This list is managed by addProjectile(), removeAllProjectiles(), and updateProjectiles().
   DtProjectileList myProjectileList;
 
   //! \brief Pointer to the physical world
   //!
   //! Stores a pointer to the physical world for terrain queries and gravity direction.
   //! This is passed to projectiles so they can detect collisions with terrain.
   DtPhysicalWorld* myPhysicalWorld;
 
   //! \brief Pointer to the firing entity
   //!
   //! Stores a pointer to the entity that is firing the weapon.
   //! This is passed to projectiles so they know which entity fired them.
   DtSimObject* myFiringEntity;
};
} // namespace makVre