humanLadderClimbingController.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file humanLadderClimbingController.h
//! \ingroup vreVrfmodel
//! \brief Joystick controller for human ladder climbing interactions
//!
//! This file defines the DtHumanLadderClimbingController class which enables joystick
//! control of human entity ladder climbing. It provides capabilities for detecting
//! and interacting with ladders, managing climbing movement, and transitioning between
//! ground and ladder states.
 
#pragma once
 
#include "vreVrfmodel/export.h"
#include "vreVrfmodel/vreSimComponent.h"
 
#include "vreVrfobjcore/vreLadderClimbingPSR.h"
 
#include <vrfobjcore/controllerComponent.h>
 
#include <vrfmodel/joystickControllerInterface.h>
 
class DtString;
class DtSimulationServices;
class DtJoyDeviceControllerDescriptor;
class DtJoyDevice;
class DtHumanMovementControlOutputPortGroup;
class DtHumanStateRepository;
class DtBooleanOutputPort;
class DtIntegerOutputPort;
class DtAnalogOutputPort;
class DtSetDataRequest;
 
namespace makVre
{
class DtVreLadderClimbingPSR;
class DtLadderLocator;
 
//! \brief Type identifier for the human ladder climbing controller component
const char DtHumanLadderClimbingControllerType[] = "human-ladder-climbing-controller";
 
//! \brief Controller for joystick-based ladder climbing interactions for human entities
//!
//! DtHumanLadderClimbingController enables joystick control of a human entity's
//! ladder climbing capabilities. It manages detection of nearby ladders, movement
//! up and down ladders, and transitions between ground movement and ladder climbing states.
//! This controller provides realistic ladder interaction behavior including positioning,
//! orientation, and animation control.
//!
//! Uses Descriptor Type: DtVreHumanJoystickMovementControllerDescriptor
class VREVRFMODEL_DLL DtHumanLadderClimbingController : public DtVreSimComponent<DtControllerComponent>,
                                                        public DtJoystickControllerInterface
{
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 ladder climbing controller component with the specified parameters.
   DtHumanLadderClimbingController(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the human ladder climbing controller component.
   virtual ~DtHumanLadderClimbingController() override;
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtHumanLadderClimbingControllerType)
   //!
   //! Implements the DtSimComponent::type() method to return the
   //! type identifier for this component.
   virtual const char* type() const override;
 
   //! \brief Creates input and output ports for this component
   //! \return True if ports were created successfully, false otherwise
   //!
   //! Creates and initializes all input and output ports used by this controller
   //! for ladder climbing-related functions.
   virtual bool createPorts() override;
 
   //! \brief Initializes the component
   //! \return True if initialization is successful, false otherwise
   //!
   //! Performs component initialization, setting up internal state and
   //! configuring initial ladder climbing parameters.
   virtual bool init() override;
 
   //! \brief Updates the controller state each simulation frame
   //!
   //! Processes ladder climbing-related controls and updates the human entity's
   //! movement on ladders based on current joystick inputs. Also handles detection
   //! of ladders and transitions between ground and ladder states.
   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);
 
private:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is private and not implemented to prevent
   //! creation of instances without proper initialization.
   DtHumanLadderClimbingController();
 
   //! \brief Copy constructor (not implemented)
   //!
   //! Copy constructor is private and not implemented to prevent
   //! copy construction.
   DtHumanLadderClimbingController(const DtHumanLadderClimbingController& orig);
 
   //! \brief Assignment operator (not implemented)
   //! \return Reference to this object
   //!
   //! Assignment operator is private and not implemented to prevent assignment.
   DtHumanLadderClimbingController& operator=(const DtHumanLadderClimbingController& orig);
 
protected:
   //! \brief Processes joystick input and updates output ports
   //! \param functionGroup The function group identifier for the input
   //! \param function The specific function identifier within the group
   //! \param value The input value from the joystick
   //! \param repeat Flag indicating if this is a repeated input
   //!
   //! Implements the DtJoystickControllerInterface method to process joystick
   //! input and update the controller's output ports for ladder climbing functions.
   virtual void calcAndSetPortValues(
      const DtString& functionGroup, const DtString& function, double value, bool repeat) override;
 
   //! \brief Handles joystick connection event
   //!
   //! Called when a joystick is connected to the system.
   //! Activates joystick control mode for ladder climbing functions.
   virtual void joystickConnected() override;
 
   //! \brief Handles joystick disconnection event
   //!
   //! Called when a joystick is disconnected from the system.
   //! Deactivates joystick control mode for ladder climbing functions.
   virtual void joystickDisconnected() override;
 
   //! \brief Retrieves and caches the ladder climbing process state repository
   //!
   //! Gets a pointer to the DtVreLadderClimbingPSR which is created by another component.
   //! This process state repository contains the ladder climbing state information
   //! that is shared between multiple components.
   virtual void lookupAndCacheProcessSR();
 
   //! \brief Performs initialization after all entity components are created
   //! \return True if post-initialization is successful, false otherwise
   //!
   //! Called after all entity components have been created and initialized.
   //! Calls lookupAndCacheProcessSR() to retrieve a pointer to the ladder climbing
   //! process state repository.
   virtual bool postAddComponentsInit() override;
 
   //! \brief Initializes ladder movement control
   //! \return True if initialization is successful, false otherwise
   //!
   //! Sets up the initial state for ladder movement control, including
   //! configuration parameters and movement limits.
   virtual bool initLadderMovementControl();
 
   //! \brief Updates ladder movement control each simulation frame
   //!
   //! Performs the per-frame update of ladder climbing movement based on
   //! current inputs and entity state. Handles movement up and down ladders.
   virtual void tickLadderMovementControl();
   //! \brief Checks if the entity is at a ladder position
   //! \param ladder Reference to the ladder to check
   //! \param accessPoint Output parameter to store the ladder access point
   //! \return True if entity is at the ladder, false otherwise
   //!
   //! Determines if the entity is at a position where it can access the ladder.
   //! Updates the accessPoint parameter with the closest ladder access point.
   virtual bool atLadder(DtLadder& ladder, DtVector& accessPoint);
   //! \brief Checks if the entity is at a specific ladder access point
   //! \param localPosition The entity's current local position
   //! \param ladderAccessPoint The ladder access point to check against
   //! \param radiusSquared The squared radius to consider as "at" the access point
   //! \return True if entity is at the ladder access point, false otherwise
   //!
   //! Determines if the entity is close enough to a ladder access point to
   //! be considered "at" that point based on the specified distance threshold.
   virtual bool atLadderAccessPoint(
      const DtVector& localPosition, const DtVector& ladderAccessPoint, double radiusSquared);
   //! \brief Checks if the entity is at a ladder exit point
   //! \param ladder The ladder to check
   //! \param ladderAccessPoint Output parameter to store the ladder access point
   //! \param ladderTerrainAccessPoint Output parameter to store the terrain access point
   //! \return True if entity is at a ladder exit point, false otherwise
   //!
   //! Determines if the entity is at a position where it can exit the ladder.
   //! Updates the output parameters with the access and terrain points.
   virtual bool atLadderExitPoint(
      const DtLadder& ladder, DtVector& ladderAccessPoint, DtVector& ladderTerrainAccessPoint);
   //! \brief Sets the nearest ladder information and updates access point
   //! \param ladder The ladder to set as nearest
   //! \param ladderAccessPoint The access point for the ladder
   //!
   //! Updates the process state with information about the nearest ladder
   //! and the access point that the entity should use to get on that ladder.
   virtual void setNearestLadderAndGetOnLadderPoint(const DtLadder& ladder, const DtVector& ladderAccessPoint);
   //! \brief Sets the entity's position
   //! \param localPosition The new local position for the entity
   //!
   //! Updates the entity's position, typically used when snapping the entity
   //! to a specific position on a ladder.
   virtual void setEntityLocation(const DtVector& localPosition);
   //! \brief Sets the entity's heading/orientation
   //! \param heading The new heading angle in radians
   //!
   //! Updates the entity's heading, typically used to orient the entity
   //! to face the ladder properly during climbing.
   virtual void setEntityHeading(double heading);
   //! \brief Sends a data request to update entity state
   //! \param setRequest Pointer to the data request to send
   //!
   //! Sends a data request to modify entity state, typically used to update
   //! position, orientation, or other properties during ladder interaction.
   virtual void sendDataRequest(DtSetDataRequest* setRequest);
   //! \brief Instructs the entity to stow its weapon
   //!
   //! Requests that the entity stow its weapon during ladder climbing,
   //! since weapons cannot be used while climbing a ladder.
   virtual void stowWeapon();
   //! \brief Enables ladder climbing animation
   //!
   //! Sets the appropriate animation state to show the entity
   //! climbing a ladder.
   virtual void enableLadderClimbingAnimation();
 
   //! \brief Disables ladder climbing animation
   //!
   //! Reverts to normal movement animations when the entity is no
   //! longer climbing a ladder.
   virtual void disableLadderClimbingAnimation();
   //! \brief Checks if the entity is facing a ladder
   //! \param ladder The ladder to check
   //! \param ladderAccessPoint The access point for the ladder
   //! \return True if the entity is facing the ladder, false otherwise
   //!
   //! Determines if the entity's current heading/orientation has it
   //! facing toward the ladder, which is required to begin climbing.
   virtual bool facingLadder(const DtLadder& ladder, const DtVector& ladderAccessPoint);
   //! \brief Snaps the entity to a ladder position
   //! \param ladderAccessPoint The access point on the ladder
   //! \param offset The offset from the access point to position the entity
   //! \param heading The heading to set for the entity
   //!
   //! Positions the entity precisely on a ladder with the correct orientation
   //! for climbing. Applies the specified offset to prevent clipping with the ladder.
   virtual void snapToLadder(const DtVector& ladderAccessPoint, const DtVector& offset, double heading);
   //! \brief Calculates the local standoff vector from a ladder
   //! \param ladder The ladder to calculate standoff from
   //! \return The local standoff vector
   //!
   //! Calculates the appropriate standoff vector to position the entity at
   //! the correct distance from the ladder during climbing. This prevents the
   //! entity from clipping through the ladder geometry.
   virtual DtVector localStandoffFromLadder(const DtLadder& ladder) const;
 
protected:
   //! \name Ports and Port Groups
   //! @{
 
   //! \brief Output port for ladder climbing movement direction
   //!
   //! Indicates the direction of climbing movement on a ladder. Negative values
   //! indicate climbing down, positive values indicate climbing up, with the range
   //! from -1.0 to 1.0. Used to control the animation and movement speed.
   DtAnalogOutputPort* myLadderClimbingMovementDirectionPort;
 
   //!@}
 
   //! \brief Current forward/backward movement input value
   //!
   //! Stores the value for joystick input, with values ranging from
   //! -1.0 (climbing down) to 1.0 (climbing up).
   double myForward;
 
   //! \brief Pointer to the ladder climbing process state repository
   //!
   //! Stores state data associated with ladder climbing. This process state
   //! repository is shared with other components and is created and destroyed
   //! by another component. The state is saved and restored as part of a
   //! scenario or checkpoint.
   DtVreLadderClimbingPSR* myProcessState;
 
 
   //! \brief Maximum speed when climbing ladders
   //!
   //! The maximum speed at which the entity can climb up or down ladders,
   //! cached from the component descriptor.
   double myMaxLadderClimbingSpeed;
 
   //! \brief Helper class for locating ladders
   //!
   //! Utility object used to find the nearest ladder and access points
   //! around the entity's current position.
   DtLadderLocator* myLadderLocator;
 
protected:
   //! \brief Search radius for finding nearby ladders
   //!
   //! The radius (in meters) within which to search for ladders around
   //! the entity's current position. Default is 5 meters.
   static double theLadderSearchRadius;
 
   //! \brief Squared distance threshold for being on a ladder
   //!
   //! The squared distance (in meters squared) threshold for determining if an
   //! entity is at a ladder access point when already on the ladder. Default is
   //! 0.25 m² (equivalent to a 0.5 m distance).
   static double theOnLadderAtLadderPointDistanceSqr;
 
   //! \brief Squared distance threshold when approaching ladders
   //!
   //! The squared distance (in meters squared) threshold for determining if an
   //! entity is at a ladder access point when approaching the ladder. Default is
   //! 1.0 m². Must be less than theLeavingAtLadderPointDistanceSqr to allow the
   //! entity to escape a ladder without automatically re-engaging.
   static double theApproachingAtLadderPointDistanceSqr;
 
   //! \brief Squared distance threshold when leaving ladders
   //!
   //! The squared distance (in meters squared) threshold for determining if an
   //! entity is at a ladder access point when leaving the ladder. Default is
   //! 1.25 m². Must be greater than theApproachingAtLadderPointDistanceSqr to allow
   //! the entity to escape a ladder without automatically re-engaging.
   static double theLeavingAtLadderPointDistanceSqr;
 
   //! \brief Half-angle for determining if entity is facing a location
   //!
   //! If a given location falls within this angle of the entity's current heading,
   //! the entity is considered to be facing that location. Measured in radians.
   //! Default is 22.5 degrees (approximately 0.393 radians).
   static double theFacingHalfAzimuthAngle;
 
   //! \brief Time required to get on/off a ladder at the top
   //!
   //! The time (in seconds) it takes for an entity to complete the transition
   //! animation and state change when getting on or off a ladder at the top.
   static double theTimeItTakesToGetOnOffLadderAtTop;
 
   //! \brief Distance to maintain between entity and ladder
   //!
   //! The offset distance (in meters) from the ladder needed to prevent the
   //! entity's body from appearing embedded in the ladder geometry when
   //! climbing up or down.
   static double theStandoffDistanceFromLadder;
 
   //! \brief Squared half-length of a typical ladder
   //!
   //! The squared value of half the maximum ladder length (in meters squared).
   //! Assuming a maximum ladder length of 16ft (≈5m), half-length is 8ft (≈2.5m),
   //! so this value is 6.25 m². Used in distance calculations during climbing.
   static double theHalfLadderLengthSquared;
};
 
} // namespace makVre