vreMunitionLoader.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreMunitionLoader.h
//! \ingroup vreVrfobjcore
//! \brief Munition loader class for VREngage
//!
//! This file defines the DtVreMunitionLoader class, which extends the basic VRF munition
//! loader to provide VREngage-specific munition loading behavior. It manages weapon
//! ammunition loading states and related state properties for displaying ammunition
//! counts in user interfaces.
#pragma once
 
#include "vreVrfobjcore/export.h"
 
#include <vrfobjcore/vrfMunitionLoader.h>
 
namespace makVre
{
//! \brief Extended munition loader with VREngage-specific functionality
//!
//! This class extends the basic VRF munition loader to provide VREngage-specific
//! munition loading behavior. It adds support for controlling weapon state during
//! loading (such as lowering/raising the weapon), managing ammunition-related
//! state properties for UI display, and handling weapon state restoration when
//! loading from saved scenarios.
class VREVRFOBJCORE_DLL DtVreMunitionLoader : public DtVrfMunitionLoader
{
public:
   //! \brief Constructor with optional name
   //! \param rwName Optional reader/writer name
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //!
   //! Creates a new munition loader with the specified name.
   DtVreMunitionLoader(const DtString& rwName = DtString::nullString(), DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Copy constructor
   //! \param orig The source munition loader to copy from
   //! \param rwName Optional reader/writer name
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //!
   //! Creates a new munition loader as a copy of the provided original.
   DtVreMunitionLoader(const DtVreMunitionLoader& orig, const DtString& rwName = DtString::nullString(),
      DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Assignment operator
   //! \param orig The source munition loader to copy from
   //! \return Reference to this munition loader after assignment
   //!
   //! Assigns the contents of the provided munition loader to this one.
   const DtVreMunitionLoader& operator=(const DtVreMunitionLoader& orig);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the munition loader.
   virtual ~DtVreMunitionLoader() override;
 
   //! \brief Initializes the munition loader with an entity
   //! \param entity Pointer to the entity this loader is associated with
   //! \return True if initialization was successful, false otherwise
   //!
   //! Initializes the munition loader and sets up callbacks for state restoration.
   //! Adds the setRestoredCallback to reinitialize AmmoInClips state properties
   //! when the entity is restored from a saved scenario.
   virtual bool init(DtLocalObject* entity);
 
   //! \brief Updates the munition loader state
   //! \param correctMunition The current munition type
   //! \param correctFuze The current fuze type
   //! \param currentTime The current simulation time
   //! \param roundsAvailable Number of rounds available to load (default: 1)
   //!
   //! Updates the munition loader state based on the current time and availability.
   //! Overridden to implement VREngage-specific behavior such as lowering the gun
   //! while loading and raising it once done.
   virtual void tick(const DtSimMunition& correctMunition,
      DtDetonatorFuze correctFuze,
      DtTime currentTime,
      int roundsAvailable = 1) override;
 
   //! \brief Uses a specified number of rounds from the magazine
   //! \param nRounds The number of rounds to consume
   //!
   //! Decrements the ammunition count by the specified number of rounds.
   //! Overridden to update the state properties with the number of rounds
   //! left in the clip for UI display and networking purposes.
   virtual void useRounds(const int nRounds) override;
 
   //! \brief Initializes a clip state property
   //! \param name The name of the weapon system for this clip
   //!
   //! Initializes the state property used to track and display the ammunition count
   //! for the specified weapon system. This property will be used for UI display
   //! and networking to clients.
   virtual void initializeClipStateProperty();
 
   //! \brief Disables thresholding for ammunition state properties
   //!
   //! Disables the thresholding setting for clip state properties to send updates
   //! every frame. This ensures that player-controlled entities receive the most
   //! accurate data for displaying ammunition counts in the HUD.
   virtual void disableAmmoStatePropertiesThresholding();
 
   //! \brief Enables thresholding for ammunition state properties
   //!
   //! Enables the thresholding setting for clip state properties to reduce network
   //! traffic. Updates are not sent as frequently for entities that are not under
   //! player control since precise ammunition display is less critical.
   virtual void enableAmmoStatePropertiesThresholding();
 
   //! \brief Begins loading a munition into the weapon system.
   //! \param startLoadTime The simulation time at which loading begins.
   //! \param munition The munition type to be loaded.
   //! \param fuze The fuze type to be used with the munition.
   //!
   //! Starts the loading process for the specified munition and fuze at the given simulation time.
   //! This overrides the base implementation to also initialize the clip state property, ensuring
   //! that ammunition counts are properly tracked and updated for UI and networking. This is
   //! important for accurate display of ammunition status in the HUD and for synchronizing state
   //! across clients.
   virtual void load(DtTime startLoadTime, const DtSimMunition& munition, DtDetonatorFuze fuze) override;
 
protected:
   //! \brief Sets the thresholding algorithm for ammunition state properties
   //! \param thresholdAlgorithm The threshold algorithm to use (DtThresholdPercent or DtThresholdNone)
   //!
   //! Sets the thresholding approach for clip state properties. Set thresholdAlgorithm
   //! to DtThresholdPercent to throttle sending of state updates, or DtThresholdNone
   //! to send updates every frame.
   virtual void setAmmoStatePropertiesThresholdAlgorithm(int thresholdAlgorithm);
 
   //! \brief Static callback for state restoration
   //! \param msg Pointer to the simulation message
   //! \param usrData User data pointer containing the munition loader instance
   //!
   //! Static callback function called when the entity is restored from a saved
   //! scenario. Sets the myReinitialize flag to true to trigger state property
   //! reinitialization on the next tick.
   static void setRestoredCallback(DtSimMessage* msg, void* usrData);
 
   //! \brief Processes a state restoration message
   //! \param msg Pointer to the simulation message
   //!
   //! Processes a state restoration message by setting the reinitialization flag.
   virtual void processSetRestored(DtSimMessage* msg);
 
   //! \brief Pointer to the associated entity
   //!
   //! Stores a pointer to the entity this munition loader is associated with.
   DtLocalObject* myEntity;
 
   //! \brief Reinitialization flag
   //!
   //! When true, the state properties will be reinitialized on the next tick.
   //! This is typically set after a state restoration operation.
   bool myReinitialize;
};
} // namespace makVre