vreSuppressionActuator.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreSuppressionActuator.h
//! \ingroup vreVrfmodel
//! \brief Actuator for modeling entity suppression due to nearby detonations
//!
//! This file defines the DtVreSuppressionActuator class which is responsible
//! for calculating and setting the suppression level for an entity based on
//! nearby detonations. It provides a simple suppression model that registers
//! callbacks with the detonation manager to be notified of relevant events.
 
#pragma once
 
#include "vreVrfmodel/export.h"
#include "vreVrfmodel/vreSimComponent.h"
 
#include <vrfmodel/suppressionActuator.h>
 
namespace makVre
{
//! \brief Type identifier for the VRE suppression actuator component
const char DtVreSuppressionActuatorType[] = "vre-suppression-actuator";
 
//! \brief Actuator for modeling entity suppression due to nearby detonations
//!
//! DtVreSuppressionActuator extends the base suppression actuator to provide
//! VR-Engage specific functionality for calculating and applying suppression
//! effects to entities based on nearby detonations. The component registers callbacks
//! with the DtDetonationManager to be notified of relevant detonations, and then
//! calculates appropriate suppression levels based on distance and munition type.
//!
//! Suppression effects can impact entity behavior and performance, simulating
//! the psychological and physiological effects of nearby weapon impacts.
//!
//! Uses Descriptor Type: DtSuppressionComponentDescriptor
class VREVRFMODEL_DLL DtVreSuppressionActuator : public DtVreSimComponent<DtSuppressionActuator>
{
public:
   //! \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 suppression actuator component with the specified parameters.
   //! Initializes the suppression state and registers with the detonation manager.
   DtVreSuppressionActuator(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtVreSuppressionActuatorType)
   //!
   //! Implements the DtSimComponent::type() method to return the
   //! type identifier for this component.
   virtual const char* type() const override;
 
   //! \brief Processes a detonation to determine its suppression effect on the entity
   //! \param detonationContext Context information about the detonation event
   //! \return True if the detonation was successfully processed, false otherwise
   //!
   //! When a detonation context is received from the detonation manager,
   //! it is processed to determine the appropriate suppression effect on the entity.
   //! The calculation uses the distance to the detonation along with information
   //! in the damage model to determine the insult from the detonation. If this is zero,
   //! then it computes the distance to the munition trajectory to possibly
   //! determine an additional insult.
   //!
   //! \note If this returns false, then the detonation could not be processed
   //! for some reason, such as missing information or invalid parameters.
   virtual bool processDetonationInsult(const DtDetonationContext& detonationContext) override;
 
   //! \brief Updates the suppression state each simulation frame
   //!
   //! Determines how the suppression effects may be wearing off over time.
   //! Suppression levels gradually decrease according to a configured decay rate,
   //! simulating the entity's recovery from the psychological effects of nearby
   //! detonations.
   virtual void tick() 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);
};
 
} // namespace makVre