vreHumanMovementActuator.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreHumanMovementActuator.h
//! \ingroup vreVrfmodel
//! \brief Actuator for human entity movement
//!
//! This file defines the DtVreHumanMovementActuator class which handles movement
//! for human entities. It manages speed, orientation, terrain interactions, fatigue,
//! and collision detection for natural human movement in the simulation.
 
#pragma once
 
#include "vreVrfmodel/export.h"
#include "vreVrfmodel/vreSimComponent.h"
 
#include <vrfmodel/humanMovementActuator.h>
#include <vrfobjcore/compositePredicate.h>
 
class DtAnalogOutputPort;
 
namespace makVre
{
class DtVreHumanMovementActuatorDescriptor;
 
//! \brief Type identifier for the VRE human movement actuator component
const char DtVreHumanMovementActuatorType[] = "vre-human-movement-actuator";
 
//! \brief Actuator for human entity movement
//!
//! DtVreHumanMovementActuator handles movement for human entities in the simulation.
//! It moves the entity at the requested speed (clamped by the maximum speed limit)
//! and direction, with appropriate terrain interaction and collision detection.
//! The actuator also models fatigue effects, health impacts on mobility, and terrain
//! suitability for different postures.
//!
//! The implementation includes realistic limitations based on terrain slope, soil type,
//! entity health status, and obstacles. It also handles special cases like ladder climbing
//! and entity embarkation.
//!
//! Uses Descriptor Type: DtVreHumanMovementActuatorDescriptor
class VREVRFMODEL_DLL DtVreHumanMovementActuator : public DtVreSimComponent<DtHumanMovementActuator>
{
private:
   //! \brief Assignment operator (not implemented)
   //! \return Reference to this object
   //!
   //! Assignment operator is private and not implemented to prevent assignment.
   DtVreHumanMovementActuator& operator=(const DtVreHumanMovementActuator& orig);
   //! \brief Copy constructor (not implemented)
   //!
   //! Copy constructor is private and not implemented to prevent
   //! copy construction.
   DtVreHumanMovementActuator(const DtVreHumanMovementActuator& orig);
 
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 human movement actuator component with the specified parameters.
   DtVreHumanMovementActuator(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the human movement actuator component.
   virtual ~DtVreHumanMovementActuator() override;
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtVreHumanMovementActuatorType)
   //!
   //! Implements the DtSimComponent::type() method to return the
   //! type identifier for this component.
   virtual const char* type() const override;
 
   //! \brief Initializes the human movement actuator
   //! \return True if initialization is successful, false otherwise
   //!
   //! Looks up and caches health-related state properties including "MobilityHealth",
   //! "FirepowerHealth", "OverallHealth", and "Fatigue". These properties are used
   //! to modulate movement capabilities based on entity status.
   virtual bool init() override;
 
   //! \brief Updates the actuator state each simulation frame
   //!
   //! Processes movement for the human entity during each simulation frame.
   //! This includes calculating appropriate speed based on health status,
   //! terrain conditions, and fatigue. Overridden to set the maximum speed
   //! to 9.0 m/s for better user experience in first-person mode.
   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);
 
   //! \brief Callback for entity restoration events
   //! \param msg The message containing restoration information
   //! \param usrData User data pointer, typically pointing to the instance of this class
   //!
   //! Static callback function invoked when an entity is restored (e.g., after being damaged).
   //! This function calls the instance's setRestored() method to reinitialize health properties.
   static void setRestoredCallback(DtSimMessage* msg, void* usrData);
 
   //! \brief Enumeration of different fatigue modification rates
   //!
   //! Defines different rates at which fatigue can be modified based on
   //! activity level and recovery. These rates are configured in the human.sysdef file.
   //! The decrease amounts are for recovery when resting or moving slowly.
   //! The increase amounts are for when the human is exerting and becoming tired.
   enum FatigueEffect
   {
      FatigueEffect_None,           //!< No change in fatigue
      FatigueEffect_DecreaseLow,    //!< Slow fatigue recovery
      FatigueEffect_DecreaseMedium, //!< Medium fatigue recovery
      FatigueEffect_DecreaseHigh,   //!< Fast fatigue recovery
      FatigueEffect_IncreaseLow,    //!< Slow fatigue increase
      FatigueEffect_IncreaseMedium, //!< Medium fatigue increase
      FatigueEffect_IncreaseHigh,   //!< Fast fatigue increase
   };
 
   //! \brief Checks if this entity can block other entities' movement
   //! \param object Pointer to the object to check against
   //! \return True if this entity can block the movement of the given object
   //!
   //! Determines whether this entity should be considered a physical obstacle
   //! that can block the movement of other entities in the simulation.
   virtual bool canBlockMovement(const DtSimObject* object) const;
 
protected:
   //! \brief Restricts posture based on terrain conditions
   //! \param desiredPosture The posture the entity wants to adopt
   //! \return The static posture closest to the desired posture that is allowed on the current terrain
   //!
   //! Determines if the desired posture is appropriate for the current terrain.
   //! For example, standing upright on a steep hill is not allowed, so the
   //! return would be prone. This ensures realistic posture constraints based
   //! on environmental conditions.
   virtual DtLifeformStaticPosture restrictPostureForTerrain(DtLifeformStaticPosture desiredPosture) override;
 
   //! \brief Checks if entity can embark onto another entity at the given position
   //! \param localPosition The local position to check for embarkation opportunities
   //! \return True if there is an entity at the specified position that can be embarked upon
   //!
   //! Checks if there are any entities at the given location that can be moved onto
   //! for embarkation. If such entities exist, checks if the current entity intersects
   //! with them, which would allow embarkation.
   virtual bool checkIfMoveOntoEmbarked(const DtVector& localPosition) override;
   //! \brief Performs embarkation check against specific objects
   //! \param localPosition The local position to check for embarkation opportunities
   //! \param hit Output parameter that will contain the hit object if one is found
   //! \param additionalIgnore List of object UUIDs to ignore during the check
   //! \return True if there is an object at the specified position that can be embarked upon
   //!
   //! Implementation method that performs the detailed embarkation check against
   //! specific objects. It allows for additional objects to be ignored in the check
   //! and returns the hit object through an output parameter.
   bool vrfObjectCheckIfMoveOntoEmbarked(
      const DtVector& localPosition, const DtSimObject*& hit, const std::list<DtUUID>& additionalIgnore);
 
   //! \brief Sets the radio receiver for simulation messages
   //! \param radio Pointer to the simulation radio for message communication
   //!
   //! Overrides the base class implementation to register interest in the
   //! set restored message. This allows the component to receive notifications
   //! when the entity is restored after being damaged.
   virtual void setRadio(DtSimRadio* radio) override;
 
   //! \brief Handles entity restoration after damage
   //!
   //! Overridden to look up myMobilityHealth and other health-related state properties again.
   //! State properties are reset when an entity is damaged and then restored, so this
   //! method re-caches the necessary properties to ensure correct health-based movement
   //! modulation after restoration.
   virtual void setRestored();
 
   //! \brief Modulates the desired speed based on environmental factors
   //! \param[out] newDesiredSpeed Output parameter that will contain the modulated desired speed
   //! \param[out] newMaxSpeed Output parameter that will contain the modulated maximum speed
   //! \param[in] desiredSpeed The current desired speed of the human
   //!
   //! Calculates the current maximum speed based on terrain pitch, soil type, and
   //! capabilities of the entity. Modifies both the desired speed and maximum speed
   //! to account for these environmental factors.
   //!
   //! \note Any modifications to the desiredSpeed parameter in this function must also be
   //!       applied to newMaxSpeed. This is needed so that the percentage of maximum
   //!       speed can be computed correctly.
   virtual void modulateDesiredSpeed(double& newDesiredSpeed, double& newMaxSpeed, double desiredSpeed);
 
   //! \brief Determines if terrain collision checks should be performed
   //! \return True if terrain collision checks should be performed, false otherwise
   //!
   //! Always returns true if the entity is player-controlled, ensuring that
   //! player-controlled entities always check for terrain collisions. For non-player
   //! entities, delegates to the base class implementation.
   virtual bool checkForTerrainCollisions() const override;
 
   //! \brief Checks if movement is blocked by terrain features
   //! \param oldLocalPosition The current position of the entity
   //! \param newLocalProjectedLocation The desired new position (modified if blocked)
   //! \param heightFraction Optional fraction of entity height to use for collision check
   //! \return True if movement is blocked by terrain, false otherwise
   //!
   //! Checks for terrain polygons between the specified old and new positions.
   //! If blocking terrain is found, the newLocalProjectedLocation parameter is
   //! modified to position the entity just before the collision would occur.
   virtual bool checkBlockedByTerrain(
      const DtVector& oldLocalPosition, DtVector& newLocalProjectedLocation, double heightFraction = -1.0) override;
 
   //! \brief Checks if movement is blocked by other entities
   //! \param oldLocalPosition The current position of the entity
   //! \param newLocalProjectedLocation The desired new position (modified if blocked)
   //! \return True if movement is blocked by another entity, false otherwise
   //!
   //! Checks for other entities between the specified old and new positions.
   //! If blocking entities are found, the newLocalProjectedLocation parameter is
   //! modified to position the entity just before the collision would occur.
   virtual bool checkBlockedByEntities(const DtVector& oldLocalPosition, DtVector& newLocalProjectedLocation) override;
 
   //! \brief Determines if entity collision checks should be performed
   //! \return True if entity collision checks should be performed, false otherwise
   //!
   //! Overridden to return false when non-player-controlled and embarked on air objects.
   //! This special case allows entities to disembark past other lifeforms on aircraft
   //! like the Chinook helicopter, preventing entities from getting stuck during disembarkation.
   virtual bool checkForEntityCollisions() const override;
 
   //! \brief Determines if a specific object can be ignored for collision detection
   //! \param hitObject The object to check for collision ignorability
   //! \return True if the object can be safely ignored, false otherwise
   //!
   //! Returns true if the given object can be safely ignored for collisions. This includes
   //! the entity that the current entity is embarked on, and tactical ladders (which need
   //! to be approachable for climbing, handled by a different movement actuator).
   //! Returns false for all other objects. This method is called by checkForEntityCollision().
   virtual bool canIgnoreCollisionWith(const DtSimObject& hitObject) const;
 
   //! \brief Calculates new orientation and position for the entity
   //! \param newLocalProjectedLocation The target projected location for the entity
   //! \param newHeading The new heading direction
   //! \param newFacingOrientation The new facing orientation
   //! \param newLocalOrientation Output parameter for the calculated orientation
   //! \param newLocalDirectionOfMovement Output parameter for the calculated movement direction
   //! \param newLocalPosition Output parameter for the calculated position
   //!
   //! Calculates the new orientation and position for the entity based on the
   //! projected location and heading information. This method handles the proper
   //! calculation of orientation matrices and position vectors for entity movement.
   virtual void calculateOrientationAndPosition(const DtVector& newLocalProjectedLocation, double newHeading,
      double newFacingOrientation, DtDcm& newLocalOrientation, DtDcm& newLocalDirectionOfMovement,
      DtVector& newLocalPosition) override;
 
   //! \brief Calculates a movement chord considering entity bounding volume
   //! \param oldLocalPosition The current position of the entity
   //! \param newLocalProjectedLocation The desired new position
   //! \param intersectionVec Output parameter for the vector between positions in local coordinates
   //! \param bvCenterStartFromOldPos Output parameter for the vector from old position to chord start
   //! \return The calculated movement chord
   //!
   //! Calculates a movement vector based on the two input positions, using the bounding volume
   //! of the entity. The resulting vector is not directly between the positions, but rather
   //! offset to the front face of the bounding volume. This method helps determine the
   //! actual movement path considering the entity's physical dimensions.
   virtual DtChord movementChord(const DtVector& oldLocalPosition,
      const DtVector& newLocalProjectedLocation,
      DtVector& intersectionVec,
      DtVector& bvCenterStartFromOldPos) override;
 
   //! \brief Calculates a movement chord at a specific height fraction
   //! \param oldLocalPosition The current position of the entity
   //! \param newLocalProjectedLocation The desired new position
   //! \param heightFraction The fraction of entity height to use for chord calculation
   //! \param intersectionVec Output parameter for the vector between positions in local coordinates
   //! \param offsetFromOldPosition Output parameter for the vector from old position to chord start
   //! \return The calculated movement chord
   //!
   //! Similar to movementChord, but rather than using the bounding volume center to define
   //! the height of the chord, this method uses a specified fraction of the entity height.
   //! This allows for more precise collision detection at different heights of the entity.
   virtual DtChord movementChordAtHeight(const DtVector& oldLocalPosition,
      const DtVector& newLocalProjectedLocation,
      double heightFraction,
      DtVector& intersectionVec,
      DtVector& offsetFromOldPosition) override;
 
   //! \brief Initializes the Above Ground Level (AGL) port
   //! \return True if the AGL port was successfully initialized, false otherwise
   //!
   //! Overridden to use closestIntersection instead of terrainHeight when determining
   //! the entity's height above ground. This is because terrainHeight doesn't take into
   //! account geometry from feature replacement, which can lead to inaccurate height
   //! calculations in areas with complex terrain features.
   virtual bool initializeAglPort() override;
 
   //! \brief Determines if and how fatigue should change based on movement
   //! \param[out] fatigueEffect Output parameter that will contain the type of fatigue change
   //! \param desiredSpeed The speed after health effects have modified the original desired speed
   //! \param maxSpeed The maximum speed after health effects have modified the original max speed
   //! \return True if fatigue should change, false otherwise
   //!
   //! Evaluates current movement conditions to determine if fatigue should change, and
   //! if so, what type of change should occur. The desiredSpeed and maxSpeed parameters
   //! reflect speeds after health effects have already been applied. These values must
   //! remain relative to each other so a percentage can be calculated to determine
   //! if the human is running or walking. If the return value is true, fatigue should
   //! increase or decrease based on the value of the fatigueEffect parameter.
   virtual bool shouldFatigueChange(FatigueEffect& fatigueEffect, double desiredSpeed, double maxSpeed) const;
 
   //! \brief Computes the increase in fatigue based on movement speed
   //! \param fatigueEffect The type of fatigue change to apply
   //! \param currentTopSpeed The current computed speed for the entity
   //! \param maxSpeed The fastest speed this entity can move
   //! \return The new fatigue value
   //!
   //! Calculates the increase in fatigue based on the entity's movement speed relative
   //! to its maximum speed. Fatigue is used to realistically modify the speed at which
   //! an entity can move over time. The fatigue rate is calibrated based on movement at
   //! maximum speed, with reduced fatigue effects for lower speeds. The function returns
   //! the new fatigue value after applying the appropriate increase based on the specified
   //! fatigueEffect and the entity's movement parameters.
   virtual double computeFatigueIncrease(FatigueEffect fatigueEffect, double currentTopSpeed, double maxSpeed) const;
 
   //! \brief Computes the decrease in fatigue during recovery
   //! \param fatigueEffect The type of fatigue recovery to apply
   //! \return The new fatigue value after recovery
   //!
   //! Calculates the decrease in fatigue when the entity is resting or moving slowly.
   //! The rate of recovery depends on the specified fatigueEffect parameter, which
   //! determines how quickly the entity recovers from fatigue. This function is typically
   //! called when the entity is stationary or moving at low speeds.
   virtual double computeFatigueDecrease(FatigueEffect fatigueEffect) const;
 
   //! \brief Computes speed modifications based on all health effects
   //! \param[out] newDesiredSpeed Output parameter for the new desired speed after health effects
   //! \param[out] newMaxSpeed Output parameter for the new maximum speed after health effects
   //! \param desiredSpeed The input desired speed after terrain factors
   //! \param maxSpeed The input maximum speed before fatigue effects
   //!
   //! Computes modifications to both desired and maximum speed based on all factors
   //! that affect entity performance: overall health, mobility health, and accumulated
   //! fatigue. Both output speed values are modified proportionally to maintain their
   //! relationship, ensuring that percentage calculations (like determining if the entity
   //! is running or walking) remain valid. The input desiredSpeed parameter already
   //! accounts for terrain type and slope effects.
   virtual void computeAllHealthEffectsOnSpeed(
      double& newDesiredSpeed, double& newMaxSpeed, double desiredSpeed, double maxSpeed) const;
 
   //! \brief Determines if movement should be allowed based on injury state
   //! \return True if movement should be allowed, false otherwise
   //!
   //! Evaluates whether the entity should be allowed to move based on its injury state.
   //! When a human entity is severely injured and on the ground, it should not be able
   //! to crawl or rotate. This method enforces realistic movement limitations for
   //! injured entities.
   virtual bool shouldAllowMovement();
 
   //! \brief Updates the entity's fatigue level
   //! \param fatigueEffect How fatigue should increase/decrease and by how much
   //! \param newDesiredSpeed The speed after damage model and fatigue effects
   //! \param newMaxSpeed The maximum speed after damage model and fatigue effects
   //!
   //! Updates the entity's fatigue level based on the specified fatigueEffect and
   //! current movement parameters. The newDesiredSpeed and newMaxSpeed parameters
   //! reflect speeds after both damage model and existing fatigue effects have been
   //! applied. These parameters are used to determine the percentage of maximum speed
   //! the entity is moving at, which affects how quickly fatigue changes.
   virtual void updateFatigue(FatigueEffect fatigueEffect, double newDesiredSpeed, double newMaxSpeed) const;
 
protected:
   //! \brief Callback for terrain change notifications
   //! \param terrainChangeInfo Information about the terrain change
   //! \param usr User data pointer, typically pointing to the instance of this class
   //!
   //! Static callback function invoked when terrain changes occur in the simulation.
   //! This allows the movement actuator to respond to changes in the terrain that
   //! might affect movement capabilities, such as new obstacles or changes in
   //! terrain slope or soil type.
   static void vreTerrainChangeNotification(const DtTerrainChangeNotificationInfo& terrainChangeInfo, void* usr);
 
   //! \brief Processes terrain change notifications
   //! \param terrainChangeInfo Information about the terrain change
   //!
   //! Instance method that processes terrain change notifications received through
   //! the static callback. This method analyzes the terrain changes and updates
   //! the movement capabilities accordingly, such as adjusting available postures
   //! or movement speeds based on new terrain conditions.
   void processVreTerrainChangeNotification(const DtTerrainChangeNotificationInfo& terrainChangeInfo);
 
protected:
   //! \brief Pointer to the human movement actuator descriptor
   //!
   //! Contains the configuration parameters for this human movement actuator.
   DtVreHumanMovementActuatorDescriptor* myVreHumanMovementDescriptor;
 
   //! \brief Desired velocity vector for the entity
   //!
   //! Stores the current desired velocity vector for the entity, which is
   //! used to determine movement direction and speed.
   DtVector myDesiredVelocity;
 
   //! \brief Entity's mobility health value
   //!
   //! References the entity's mobility health state property, which affects
   //! movement speed and capabilities.
   DtRwInt* myMobilityHealth;
 
   //! \brief Entity's fatigue value
   //!
   //! References the entity's fatigue state property, which represents
   //! accumulated exertion and affects movement speed.
   DtRwReal* myFatigue;
 
   //! \brief Entity's percentage of maximum speed
   //!
   //! References the state property that tracks what percentage of maximum
   //! speed the entity is currently moving at.
   DtRwReal* myPercentOfMaxSpeed;
 
   //! \brief Entity's firepower health value
   //!
   //! References the entity's firepower health state property, which affects
   //! weapon capabilities but may also influence overall movement.
   DtRwInt* myFirepowerHealth;
 
   //! \brief Entity's overall health value
   //!
   //! References the entity's overall health state property, which provides
   //! a general indication of the entity's condition.
   DtRwInt* myOverallHealth;
 
   //! \brief Predicate for movement blocking object types
   //!
   //! Composite predicate that defines which types of objects should
   //! be checked for movement blocking during collision detection.
   DtCompositePredicate myObjectsToCheckForMovementBlock;
};
 
} // namespace makVre