humanJoystickMovementController.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file humanJoystickMovementController.h
//! \ingroup vreVrfmodel
//! \brief Joystick controller for human entity movement
//!
//! This file defines the DtHumanJoystickMovementController class which enables joystick
//! control of human entity movement. It provides capabilities for controlling walking,
//! running, strafing, turning, and posture changes through joystick inputs.
 
#pragma once
 
#include "vreVrfmodel/export.h"
#include <vrfobjcore/controllerComponent.h>
#include <vrfmodel/joystickControllerInterface.h>
 
#include <vreVrfobjparam/vreHumanJoystickMovementControllerDescriptor.h>
 
class DtString;
class DtSimulationServices;
class DtJoyDeviceControllerDescriptor;
class DtJoyDevice;
class DtHumanMovementControlOutputPortGroup;
class DtHumanStateRepository;
class DtBooleanOutputPort;
class DtIntegerOutputPort;
class DtAnalogOutputPort;
 
namespace makVre
{
//! \brief Type identifier for the human joystick movement controller component
const char DtVreHumanJoystickMovementControllerType[] = "vre-human-joystick-movement-controller";
 
//! \brief Controller for joystick-based movement control of human entities
//!
//! DtHumanJoystickMovementController enables joystick control of a human entity's
//! movement capabilities. It manages walking, running, strafing, turning, and
//! posture changes through joystick inputs. This controller works alongside combat
//! controllers to provide comprehensive control of human entities.
//!
//! Uses Descriptor Type: DtVreHumanJoystickMovementControllerDescriptor
class VREVRFMODEL_DLL DtHumanJoystickMovementController : public 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 joystick movement controller component with the specified parameters.
   DtHumanJoystickMovementController(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the human joystick movement controller component.
   virtual ~DtHumanJoystickMovementController() override;
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtVreHumanJoystickMovementControllerType)
   //!
   //! Implements the DtSimComponent::type() method to return the
   //! type identifier for this component.
   virtual const char* type() const override;
 
   //! \brief Creates port groups for this component
   //! \return True if port groups were created successfully, false otherwise
   //!
   //! Creates and initializes the output port groups used by this controller,
   //! particularly the human movement control port group.
   virtual bool createPortGroups() 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 movement-related functions, including ports for movement state and posture.
   virtual bool createPorts() 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.
   DtHumanJoystickMovementController();
 
   //! \brief Copy constructor (not implemented)
   //!
   //! Copy constructor is private and not implemented to prevent
   //! copy construction.
   DtHumanJoystickMovementController(const DtHumanJoystickMovementController& orig);
 
   //! \brief Assignment operator (not implemented)
   //! \return Reference to this object
   //!
   //! Assignment operator is private and not implemented to prevent assignment.
   DtHumanJoystickMovementController& operator=(const DtHumanJoystickMovementController& 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 movement 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 movement functions.
   virtual void joystickConnected() override;
 
   //! \brief Handles joystick disconnection event
   //!
   //! Called when a joystick is disconnected from the system.
   //! Deactivates joystick control mode for movement functions.
   virtual void joystickDisconnected() override;
 
   //! \brief Updates the controller state each simulation frame
   //!
   //! Processes movement-related controls and updates the human entity's
   //! movement state and posture based on current joystick inputs.
   virtual void tick() override;
 
protected:
   //! \name Ports and Port Groups
   //! @{
 
   //! \brief Output port group for human movement control
   //!
   //! Contains all output ports related to human movement control, including
   //! forward/backward movement, strafing, turning, and running states.
   DtHumanMovementControlOutputPortGroup* myHumanMovementControlOutputPortGroup;
 
   //! \brief Output port indicating movement state
   //!
   //! When true, indicates that the entity is being actively moved
   //! by this controller. Used to synchronize animations and other
   //! movement-dependent systems.
   DtBooleanOutputPort* myIsMovingPort;
   //! @}
 
   //! \brief Output port for static posture control
   //!
   //! Controls the static posture of the entity (standing, crouching, prone, etc.)
   //! using integer values to represent different postures.
   DtIntegerOutputPort* myStaticPostureOutputPort;
 
   //! \brief Pointer to the human state repository
   //!
   //! Provides access to the human entity's state information for
   //! reading and modifying state based on movement inputs.
   DtHumanStateRepository* myHumanStateRepository;
 
   //! \brief Pointer to the movement controller descriptor
   //!
   //! Provides access to component-specific configuration parameters
   //! defined for this human joystick movement controller.
   const DtVreHumanJoystickMovementControllerDescriptor* myComponentDescriptor;
 
   //! \brief Rate of turning in response to inputs
   //!
   //! Controls how quickly the human entity turns in response to yaw inputs.
   double myTurningRate;
 
   //! \brief Speed multiplier for movement
   //!
   //! Adjusts the speed of forward/backward and strafe movement relative
   //! to the base movement speeds defined for the entity.
   double mySpeedFactor;
 
   //! \brief Current forward/backward movement input value
   //!
   //! Ranges from -1.0 (full backward) to 1.0 (full forward).
   double myForward;
 
   //! \brief Current strafe (sideways) movement input value
   //!
   //! Ranges from -1.0 (full left) to 1.0 (full right).
   double myStrafe;
 
   //! \brief Current yaw (turning) input value from joystick
   //!
   //! Controls the rate of turning, with positive values for turning right
   //! and negative values for turning left.
   double myYaw;
 
   //! \brief Current yaw (turning) input value from mouse
   //!
   //! Additional turning input from mouse movements, added to joystick input.
   double myMouseYaw;
 
   //! \brief Current frontend (view) yaw angle
   //!
   //! The yaw angle used by the frontend/view system, which may differ
   //! from the entity's actual orientation.
   double myFrontendYaw;
 
   //! \brief Current frontend (view) pitch angle
   //!
   //! The pitch angle used by the frontend/view system, which controls
   //! the up/down view direction.
   double myFrontendPitch;
 
   //! \brief Current posture state of the human entity
   //!
   //! Integer representation of the current posture (standing, crouching, etc.)
   int myCurrentPosture;
 
   //! \brief Flag indicating whether to force posture state
   //!
   //! When true, the controller will assert the current posture value
   //! even if it conflicts with other movement states.
   bool myAssertCurrentPosture;
 
   //! \brief Flag indicating whether to set an absolute yaw value
   //!
   //! When true, the controller will set the entity's yaw to the specific
   //! value in mySetYawValue instead of using incremental turning.
   bool mySetYaw;
 
   //! \brief Absolute yaw value to set when mySetYaw is true
   //!
   //! The absolute yaw angle (in radians) to set for the entity when
   //! mySetYaw is true.
   double mySetYawValue;
};
 
} // namespace makVre