vreHumanMovementActuatorDescriptor.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreHumanMovementActuatorDescriptor.h
//! \ingroup vreVrfobjparam
//! \brief Human movement actuator descriptor for VREngage
//!
//! This file defines the DtVreHumanMovementActuatorDescriptor class, which configures
//! human movement actuator components in VREngage with additional fatigue-related parameters.
//! Fatigue affects movement speed and recovery rates based on various thresholds and conditions.
 
#pragma once
 
#include "vreVrfobjparam/export.h"
#include <vrfobjparam/humanMovementActuatorDescriptor.h>
#include <readerWriter/rwReal.h>
 
namespace makVre
{
//! \brief Type identifier string for the human movement actuator descriptor
const char DtVreHumanMovementActuatorDescriptorType[] = "vre-human-movement-actuator-descriptor";
 
//! \brief Human movement actuator descriptor with fatigue modeling for VREngage
//!
//! This class extends the base human movement actuator descriptor to add
//! configuration for fatigue modeling. Fatigue affects entity movement speed
//! based on activity levels, with different increase and recovery rates for
//! different intensity levels, and thresholds that determine when fatigue
//! starts to accumulate or how it affects movement capabilities.
class VREVRFOBJPARAM_DLL DtVreHumanMovementActuatorDescriptor : public DtHumanMovementActuatorDescriptor
{
private:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is private and not implemented to prevent
   //! creation of instances without proper initialization.
   DtVreHumanMovementActuatorDescriptor();
 
public:
   //! \brief Constructor with component name
   //! \param componentName The name of this component
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new human movement actuator descriptor with the specified name.
   DtVreHumanMovementActuatorDescriptor(const DtString& componentName, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Copy constructor
   //! \param orig The source descriptor to copy from
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new human movement actuator descriptor as a copy of the provided original.
   DtVreHumanMovementActuatorDescriptor(
      const DtVreHumanMovementActuatorDescriptor& orig, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the descriptor.
   virtual ~DtVreHumanMovementActuatorDescriptor() override;
 
   //! \brief Assignment operator
   //! \param orig The source descriptor to copy from
   //! \return Reference to this descriptor after assignment
   //!
   //! Assigns the contents of the provided descriptor to this one.
   DtVreHumanMovementActuatorDescriptor& operator=(const DtVreHumanMovementActuatorDescriptor& orig);
 
   //! \brief Gets the type identifier for this descriptor
   //! \return String identifying this descriptor type
   //!
   //! Returns a unique type identifier string for this descriptor type.
   //! Will return DtVreHumanMovementActuatorDescriptorType.
   virtual DtString type() const override;
 
   //! \brief Creates a clone of this descriptor
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //! \return Pointer to a new descriptor that is a clone of this one
   //!
   //! Creates a new human movement actuator descriptor as a deep copy of this one.
   virtual DtComponentDescriptor* clone(DtReaderWriterRegistry* parentRegistry = 0) const override;
 
   //! \brief Factory function to create a new instance of this descriptor
   //! \return Pointer to a newly created descriptor
   //!
   //! Static factory function used by the descriptor creation system to instantiate
   //! new instances of this descriptor type.
   static DtComponentDescriptor* creator();
 
   //! \brief Gets the fatigue increase rate for low-intensity activity
   //! \return The fatigue increase rate in fatigue points per second
   //!
   //! Returns the rate at which fatigue increases during low-intensity activity.
   //! Units are fatigue points per second, with maximum fatigue being 100 points.
   DtReal fatigueIncreaseRateLow() const;
 
   //! \brief Sets the fatigue increase rate for low-intensity activity
   //! \param fatigueIncreaseRateLow The fatigue increase rate in fatigue points per second
   //!
   //! Sets the rate at which fatigue increases during low-intensity activity.
   //! Units are fatigue points per second, with maximum fatigue being 100 points.
   void setFatigueIncreaseRateLow(DtReal fatigueIncreaseRateLow);
 
   //! \brief Gets the fatigue increase rate for medium-intensity activity
   //! \return The fatigue increase rate in fatigue points per second
   //!
   //! Returns the rate at which fatigue increases during medium-intensity activity.
   //! Units are fatigue points per second, with maximum fatigue being 100 points.
   DtReal fatigueIncreaseRateMedium() const;
 
   //! \brief Sets the fatigue increase rate for medium-intensity activity
   //! \param fatigueIncreaseRateMedium The fatigue increase rate in fatigue points per second
   //!
   //! Sets the rate at which fatigue increases during medium-intensity activity.
   //! Units are fatigue points per second, with maximum fatigue being 100 points.
   void setFatigueIncreaseRateMedium(DtReal fatigueIncreaseRateMedium);
 
   //! \brief Gets the fatigue increase rate for high-intensity activity
   //! \return The fatigue increase rate in fatigue points per second
   //!
   //! Returns the rate at which fatigue increases during high-intensity activity.
   //! Units are fatigue points per second, with maximum fatigue being 100 points.
   DtReal fatigueIncreaseRateHigh() const;
 
   //! \brief Sets the fatigue increase rate for high-intensity activity
   //! \param fatigueIncreaseRateHigh The fatigue increase rate in fatigue points per second
   //!
   //! Sets the rate at which fatigue increases during high-intensity activity.
   //! Units are fatigue points per second, with maximum fatigue being 100 points.
   void setFatigueIncreaseRateHigh(DtReal fatigueIncreaseRateHigh);
 
   //! \brief Gets the fatigue recovery rate for low-intensity rest
   //! \return The fatigue recovery rate in fatigue points per second
   //!
   //! Returns the rate at which fatigue recovers during low-intensity rest periods.
   //! Units are fatigue points per second, with maximum fatigue being 100 points.
   DtReal fatigueRecoveryRateLow() const;
 
   //! \brief Sets the fatigue recovery rate for low-intensity rest
   //! \param fatigueRateLow The fatigue recovery rate in fatigue points per second
   //!
   //! Sets the rate at which fatigue recovers during low-intensity rest periods.
   //! Units are fatigue points per second, with maximum fatigue being 100 points.
   void setFatigueRecoveryRateLow(DtReal fatigueRateLow);
 
   //! \brief Gets the fatigue recovery rate for medium-intensity rest
   //! \return The fatigue recovery rate in fatigue points per second
   //!
   //! Returns the rate at which fatigue recovers during medium-intensity rest periods.
   //! Units are fatigue points per second, with maximum fatigue being 100 points.
   DtReal fatigueRecoveryRateMedium() const;
 
   //! \brief Sets the fatigue recovery rate for medium-intensity rest
   //! \param fatigueRateMedium The fatigue recovery rate in fatigue points per second
   //!
   //! Sets the rate at which fatigue recovers during medium-intensity rest periods.
   //! Units are fatigue points per second, with maximum fatigue being 100 points.
   void setFatigueRecoveryRateMedium(DtReal fatigueRateMedium);
 
   //! \brief Gets the fatigue recovery rate for high-intensity rest
   //! \return The fatigue recovery rate in fatigue points per second
   //!
   //! Returns the rate at which fatigue recovers during high-intensity rest periods.
   //! Units are fatigue points per second, with maximum fatigue being 100 points.
   DtReal fatigueRecoveryRateHigh() const;
 
   //! \brief Sets the fatigue recovery rate for high-intensity rest
   //! \param fatigueRateHigh The fatigue recovery rate in fatigue points per second
   //!
   //! Sets the rate at which fatigue recovers during high-intensity rest periods.
   //! Units are fatigue points per second, with maximum fatigue being 100 points.
   void setFatigueRecoveryRateHigh(DtReal fatigueRateHigh);
 
   //! \brief Gets the maximum fatigue limit for movement capabilities
   //! \return The maximum fatigue points that still allow movement
   //!
   //! Returns the maximum fatigue value that still allows movement. This prevents
   //! movement from completely stopping at maximum fatigue (100 points).
   DtReal fatigueMaxForMovement() const;
 
   //! \brief Sets the maximum fatigue limit for movement capabilities
   //! \param fatigueMaxForMovement The maximum fatigue points that still allow movement
   //!
   //! Sets the maximum fatigue value that still allows movement. This prevents
   //! movement from completely stopping at maximum fatigue (100 points).
   void setFatigueMaxForMovment(DtReal fatigueMaxForMovement);
 
   //! \brief Gets the fatigue threshold percentage
   //! \return The fatigue threshold as a percentage of maximum speed
   //!
   //! Returns the speed threshold (as a percentage of the adjusted maximum speed)
   //! above which fatigue starts to accumulate. The adjusted maximum speed takes
   //! into account the effects of overall health and mobility health.
   DtReal fatigueThresholdPercent() const;
 
   //! \brief Sets the fatigue threshold percentage
   //! \param fatigueThresholdPercent The fatigue threshold as a percentage of maximum speed
   //!
   //! Sets the speed threshold (as a percentage of the adjusted maximum speed)
   //! above which fatigue starts to accumulate. The adjusted maximum speed takes
   //! into account the effects of overall health and mobility health.
   void setFatigueThresholdPercent(DtReal fatigueThresholdPercent);
 
protected:
   //! \brief Fatigue increase rate for low-intensity activity
   //!
   //! Rate at which fatigue increases during low-intensity activity.
   //! Units are fatigue points per second, with maximum fatigue being 100 points.
   DtRwReal myFatigueIncreaseRateLow;
 
   //! \brief Fatigue increase rate for medium-intensity activity
   //!
   //! Rate at which fatigue increases during medium-intensity activity.
   //! Units are fatigue points per second, with maximum fatigue being 100 points.
   DtRwReal myFatigueIncreaseRateMedium;
 
   //! \brief Fatigue increase rate for high-intensity activity
   //!
   //! Rate at which fatigue increases during high-intensity activity.
   //! Units are fatigue points per second, with maximum fatigue being 100 points.
   DtRwReal myFatigueIncreaseRateHigh;
 
   //! \brief Fatigue recovery rate for low-intensity rest
   //!
   //! Rate at which fatigue recovers during low-intensity rest periods.
   //! Units are fatigue points per second, with maximum fatigue being 100 points.
   DtRwReal myFatigueRecoveryRateLow;
 
   //! \brief Fatigue recovery rate for medium-intensity rest
   //!
   //! Rate at which fatigue recovers during medium-intensity rest periods.
   //! Units are fatigue points per second, with maximum fatigue being 100 points.
   DtRwReal myFatigueRecoveryRateMedium;
 
   //! \brief Fatigue recovery rate for high-intensity rest
   //!
   //! Rate at which fatigue recovers during high-intensity rest periods.
   //! Units are fatigue points per second, with maximum fatigue being 100 points.
   DtRwReal myFatigueRecoveryRateHigh;
 
   //! \brief Maximum fatigue limit for movement capabilities
   //!
   //! The maximum fatigue value that still allows movement. This prevents
   //! movement from completely stopping at maximum fatigue (100 points).
   DtRwReal myFatigueMaxForMovement;
 
   //! \brief Fatigue threshold percentage
   //!
   //! The speed threshold (as a percentage of the adjusted maximum speed)
   //! above which fatigue starts to accumulate. The adjusted maximum speed takes
   //! into account the effects of overall health and mobility health.
   DtRwReal myFatigueThresholdPercent;
};
} // namespace makVre