vreHumanDamageActuator.h

Go to the documentation of this file.

/******************************************************************************
 * Copyright (c) 2025 MAK Technologies
 * All rights reserved.
 ******************************************************************************/
 
//! \file vreHumanDamageActuator.h
//! \ingroup vreVrfmodel
//! \brief Actuator for processing damage to human entities
//!
//! This file defines the DtVreHumanDamageActuator class which handles damage
//! adjudication for human entities. It defines different areas of the human body
//! and calculates the amount of damage received when hit in those areas based on
//! posture, hit location, and weapon characteristics.
 
#pragma once
 
// Local Includes
#include "vreVrfmodel/export.h"
#include "vreVrfmodel/vreSimComponent.h"
 
#include <vrfmodel/humanDamageActuator.h>
 
// Class Forward Declarations
 
namespace makVre
{
//! \brief Type identifier for the VRE human damage actuator component
const char DtVreHumanDamageActuatorType[] = "vre-human-damage-actuator";
 
//! \brief Actuator for processing damage to human entities
//!
//! DtVreHumanDamageActuator handles damage adjudication for human entities. It defines
//! different areas of the human body and calculates the amount of damage received when
//! hit in those areas based on posture, hit location, and weapon characteristics.
//! The actuator maintains separate health values for overall health, mobility, and
//! firepower, which can be affected differently depending on the hit location.
class VREVRFMODEL_DLL DtVreHumanDamageActuator : public DtVreSimComponent<DtHumanDamageActuator>
{
public: // public typedefs and enumerations
public: // public constructors and destructors
   //! \brief Constructor
   //! \param name The name of this component
   //! \param owner The local object that owns this component
   //! \param simManager The simulation services manager
   //! \param desc Component descriptor with configuration parameters
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //!
   //! Creates a new human damage actuator component with the specified parameters.
   DtVreHumanDamageActuator(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the human damage actuator component.
   virtual ~DtVreHumanDamageActuator() override;
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtVreHumanDamageActuatorType)
   //!
   //! Implements the DtSimComponent::type() method to return the
   //! type identifier for this component.
   virtual const char* type() const override;
 
   //! \brief Initializes the human damage actuator
   //! \return True if initialization is successful, false otherwise
   //!
   //! Performs initial setup of the human damage actuator, including setting up
   //! body zone damage maps and connecting to entity state variables. This method
   //! is called during component initialization.
   virtual bool init() override;
 
   //! \brief Updates the actuator state each simulation frame
   //!
   //! Processes the human entity's damage state during each simulation frame.
   //! This includes checking current health values and updating the entity's
   //! state accordingly, such as changing posture when health drops below
   //! certain thresholds.
   virtual void tick() override;
 
   //! \brief Processes direct damage from a detonation
   //! \param detonationContext Information about the detonation that hit the entity
   //! \return True if damage was applied, false otherwise
   //!
   //! Determines damage from a direct impact on the entity and decrements the
   //! hit points on the entity if appropriate. The amount of damage depends on
   //! the hit location, entity posture, and weapon characteristics.
   virtual bool adjudicateDirectDamage(const DtDetonationContext& detonationContext) override;
 
   //! \brief Processes collateral damage from a nearby detonation
   //! \param detonationContext Information about the detonation that occurred near the entity
   //! \return True if damage was applied, false otherwise
   //!
   //! Determines collateral damage from an impact near the entity, based on the
   //! distance from the detonation, weapon type, and other factors. Applies
   //! appropriate health reductions based on the blast effects.
   virtual bool adjudicateCollateralDamage(const DtDetonationContext& detonationContext) override;
 
   //! \brief Factory method to create a new instance of this component
   //! \param name The name for the new component
   //! \param owner The local object that will own this component
   //! \param simManager The simulation services manager
   //! \param desc Optional component descriptor
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //! \return Pointer to the newly created component
   //!
   //! Static factory method used by the component creation system to instantiate
   //! new instances of this component type.
   static DtSimComponent* creator(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
protected:
   //! \brief Updates the damage state of the entity
   //! \param state The new damage state to apply to the entity
   //!
   //! Updates the entity's damage state and applies appropriate visual and
   //! functional effects based on the new state. This may include changing
   //! appearance, posture, or mobility capabilities.
   virtual void updateState(DtDamageState state) override;
   //! \brief Sets the entity to a destroyed state
   //!
   //! Sets the entity to a destroyed state when health reaches zero.
   //! This includes updating visual appearance, disabling mobility,
   //! and potentially triggering death animations.
   virtual void setDestroyed() override;
 
private:
   //! \brief Copy constructor (not implemented)
   //!
   //! Copy constructor is private and not implemented to prevent
   //! copy construction.
   DtVreHumanDamageActuator(const DtVreHumanDamageActuator& other);
   //! \brief Assignment operator (not implemented)
   //! \return Reference to this object
   //!
   //! Assignment operator is private and not implemented to prevent assignment.
   DtVreHumanDamageActuator& operator=(const DtVreHumanDamageActuator& other);
 
public:    // public methods
public:    // public static methods
public:    // public static data
protected: // protected methods
   //! \brief Restores an entity to a functional state
   //!
   //! Re-registers the entity to receive detonations since it is now restored.
   //! This is called when an entity's health is reset or restored after
   //! being damaged or destroyed.
   //! \see registerForDetonations
   virtual void setRestored() override;
 
protected: // protected data
   //! \brief Changes the entity's posture
   //! \param post The new posture to set for the entity
   //!
   //! Changes the entity's posture, typically used to knock the entity to the
   //! ground when significantly damaged. This sends the appropriate commands
   //! to update the entity's visual representation and movement capabilities.
   void sendSetPosture(DtLifeformState post);
 
   //! \brief Initializes the posture-specific damage maps
   //!
   //! Sets up the damage maps for different postures, defining how much damage
   //! is applied to different body zones in each posture. This is a temporary
   //! implementation until damage maps can be read from configuration files.
   void initPostureDamageMaps();
 
   //! \brief Information about a body zone and its damage characteristics
   //!
   //! Specifies amount of damage caused when a specific body zone is hit.
   //! Each body zone can affect different health aspects differently.
   using DtDamageZoneInfo = struct DtDamageZoneInfo
   {
      std::string bodyZoneName;        //!< Name of the body zone
      DtVector bodyZoneCenter;         //!< Point used to determine distance to the detonation
      bool useSurfaceData;             //!< If true, the surface name must match for a hit to count
                                       //!< If set to true, the surface name specified in the surfaceName
                                       //!< field must match the surface name that was hit by the detonation
                                       //!< in order for a hit on this part to be true
      std::string surfaceName;         //!< Surface name to match when useSurfaceData is true
      int overallHealthLoss;           //!< Amount of overall health lost when this zone is hit
      int overallHealthLossModifier;   //!< Modifier to overall health loss (+/-)
      int mobilityHealthLoss;          //!< Amount of mobility health lost when this zone is hit
      int mobilityHealthLossModifier;  //!< Modifier to mobility health loss (+/-)
      int firepowerHealthLoss;         //!< Amount of firepower health lost when this zone is hit
      int firepowerHealthLossModifier; //!< Modifier to firepower health loss (+/-)
   };
 
   //! \brief Damage map for body parts indexed by body zone name
   //!
   //! Maps body zone names to their corresponding damage information.
   //! The key is the bodyZoneName string.
   using DtDamageMap = std::map<std::string, DtDamageZoneInfo>;
 
   //! \brief Map of damage maps for different postures
   //!
   //! Each posture (standing, prone, etc.) has its own damage map defining
   //! how much damage is applied to different body zones in that posture.
   std::map<DtLifeformState, DtDamageMap> myPostureDamageMap;
 
   //! \brief Entity's overall health value
   //!
   //! State property defined in the Human OPE file, representing the
   //! entity's overall health status.
   DtRwInt* myOverallHealth;
 
   //! \brief Entity's mobility health value
   //!
   //! State property defined in the Human OPE file, representing the
   //! entity's ability to move effectively.
   DtRwInt* myMobilityHealth;
 
   //! \brief Entity's firepower health value
   //!
   //! State property defined in the Human OPE file, representing the
   //! entity's ability to use weapons effectively.
   DtRwInt* myFirepowerHealth;
 
   //! \brief Flag indicating if OPE access is valid
   //!
   //! Indicates whether the component was able to successfully access the
   //! OPE (Object Property Editor) state variables.
   bool myOpeOk;
};
} // namespace makVre