driverControlLogic.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file driverControlLogic.h
//! \brief Defines the DtDriverControlLogic component for controlling ground vehicle operation.
//!
//! This component provides comprehensive vehicle control functionality including steering,
//! throttle, braking, gear shifting, and auxiliary systems (headlights, differential lock, etc.)
//!
//! \ingroup vreCommonComponents
 
#pragma once
 
#include "vreCommonComponents/export.h"
 
#include "vrePlayerStation/entityControlLogic.h"
 
#include "vreMessageManager/vreMessage.h"
 
namespace makVre
{
//! \brief Forward declaration of the initialization table class
class DtInitTable;
 
namespace DriverControlLogicConfig
{
//! \ingroup RoleConfigParams
//! \defgroup DriverControlLogicRoleParams Driver Control Logic Role Parameters
//! \roleInherits{EntityControlLogicRoleParams}
//! Configuration Options for driver role.
//! @{
 
//! \vreRoleParam{hasDifferentialLock,bool,false,driverControlLogic,Determines whether or not this role will have diff lock.}
constexpr const char* hasDifferentialLock = "hasDifferentialLock";
 
//! \vreRoleParam{canPivot,bool,false,driverControlLogic,Determines whether or not this role has the ability to pivot.}
constexpr const char* canPivot = "canPivot";
 
//! \vreRoleParam{hasTowHook,bool,false,driverControlLogic,Does this role have the ability for towing.}
constexpr const char* hasTowHook = "hasTowHook";
 
//! \vreRoleParam{showInclinometer,bool,false,driverControlLogic,Determines whether to show the inclinometer instrument displaying entity pitch and roll.}
constexpr const char* showInclinometer = "showInclinometer";
//! @}
} // namespace DriverControlLogicConfig
 
//! \brief Type identifier for DtDriverControlLogic component
constexpr const char* DtDriverControlLogicType = "DtDriverControlLogic";
 
//! \brief Component for controlling ground vehicle operation
//!
//! The DtDriverControlLogic provides functionality for controlling various aspects of ground
//! vehicles. This includes basic driving controls (steering, throttle, braking), transmission
//! controls (gear shifting), and auxiliary systems (engine, differential lock, parking brake,
//! headlights, pivot steering, and towing hook).
//!
//! It also maintains vehicle state information through attributes and handles resource
//! updates for systems like fuel levels and towing targets.
class VRECOMMONCOMPONENTS_DLL DtDriverControlLogic : public makVre::DtEntityControlLogic
{
public:
   //! \brief Constructor for DtDriverControlLogic
   //!
   //! Initializes the component with default values and checks out the required
   //! VR Engage Ground license.
   DtDriverControlLogic();
 
   //! \brief Virtual destructor for DtDriverControlLogic
   virtual ~DtDriverControlLogic() override;
 
   //! \brief Initializes the component with configuration from Lua
   //!
   //! Sets up input handlers, initializes state attributes, and subscribes to resource updates.
   //! Configures vehicle capabilities based on Lua settings (differential lock, pivot steering,
   //! and tow hook availability).
   //!
   //! \param player Pointer to the player station this component belongs to
   //! \param config Configuration table containing initialization parameters
   //! \return True if initialization succeeds, false otherwise
   virtual bool initialize(makVre::DtPlayerStation* player, makVre::DtInitTable& config) override;
 
   //! \brief Updates the component state
   //!
   //! Updates the headlight state attribute based on the vehicle's current appearance.
   //!
   //! \param dt Delta time in seconds since the last tick
   virtual void tick(double dt) override;
 
   //! \brief Shuts down the component
   //!
   //! Unsubscribes from resource updates, removes callbacks, and cleans up input handlers.
   virtual void shutdown() override;
 
   //! \brief Returns the component type identifier
   //! \return The component type string
   virtual const char* type() const override;
 
   //! \brief Input handler functions
   //! @{
 
   //! \brief Handles left steering input
   //!
   //! Inverts the value and passes it to setSteering().
   //!
   //! \param val The input value, typically from 0.0 to 1.0
   virtual void steerLeft(float val);
 
   //! \brief Handles right steering input
   //!
   //! Passes the value directly to setSteering().
   //!
   //! \param val The input value, typically from 0.0 to 1.0
   virtual void steerRight(float val);
 
   //! \brief Sets the vehicle's steering value
   //!
   //! Sends a "Steering" joystick message with the provided value.
   //!
   //! \param val The steering value, from -1.0 (full left) to 1.0 (full right)
   virtual void setSteering(double val);
 
   //! \brief Sets the vehicle's throttle value
   //!
   //! Sends a "Throttle" joystick message with the provided value.
   //!
   //! \param val The throttle value, typically from 0.0 to 1.0
   virtual void setThrottle(double val);
 
   //! \brief Sets the vehicle's brake value
   //!
   //! Sends a "Brake" joystick message with the provided value.
   //!
   //! \param val The brake value, typically from 0.0 to 1.0
   virtual void setBrake(double val);
 
   //! \brief Shifts up to the next gear
   //!
   //! Sends a "GearUp" joystick message with the provided value.
   //!
   //! \param val The input value, a value of 1.0 triggers the gear shift
   virtual void setGearUp(double val);
 
   //! \brief Shifts down to the previous gear
   //!
   //! Sends a "GearDown" joystick message with the provided value.
   //!
   //! \param val The input value, a value of 1.0 triggers the gear shift
   virtual void setGearDown(double val);
 
   //! \brief Toggles the engine on/off
   //!
   //! Sends an "EngineEnable" joystick message with the provided value.
   //!
   //! \param val The input value, a value of 1.0 typically toggles the engine state
   virtual void setEngineEnable(double val);
 
   //! \brief Toggles the differential lock
   //!
   //! Sends a "DifferentialLock" joystick message with the provided value.
   //! Only applies to vehicles with differential lock capability.
   //!
   //! \param val The input value, a value of 1.0 typically toggles the differential lock
   virtual void setDifferentialLock(double val);
 
   //! \brief Toggles the parking brake
   //!
   //! Sends a "ParkingBrake" joystick message with the provided value.
   //!
   //! \param val The input value, a value of 1.0 typically toggles the parking brake
   virtual void setParkingBrake(double val);
 
   //! \brief Toggles the headlights
   //!
   //! Sends a "Headlights" joystick message with the provided value.
   //!
   //! \param val The input value, a value of 1.0 typically toggles the headlights
   virtual void setHeadlights(double val);
 
   //! \brief Controls pivot steering
   //!
   //! Sends a "Pivot" joystick message with the provided value.
   //! Only applies to vehicles with pivot steering capability.
   //!
   //! \param val The input value
   virtual void setPivot(double val);
 
   //! \brief Controls the towing hook
   //!
   //! Sends a "Hook" joystick message with the provided value.
   //! Only applies to vehicles with towing hook capability.
   //!
   //! \param val The input value, typically toggles hook engagement
   virtual void setHook(double val);
 
   //! @}
 
   //! \brief Sends a joystick message to the simulation
   //!
   //! Helper function called by the various control functions to send
   //! joystick messages with the appropriate parameters.
   //!
   //! \param function The function name to include in the message
   //! \param val The function value to include in the message
   //! \param delay Optional delay before sending the message (defaults to 0)
   virtual void sendJoystickMessage(const std::string& function, double val, double delay = 0);
 
protected:
   //! \brief Handles resource update messages
   //!
   //! Processes resource updates, particularly for fuel levels.
   //! Updates the "fuel" state attribute with the current amount.
   //!
   //! \param msg The resource update message to process
   //! \return HANDLED if the message was processed
   virtual makVre::DtVreMessageResult handleResourceUpdate(makVre::DtVreMessage* msg);
 
   //! \brief Callback for changes to the hook target UUID
   //!
   //! When a nearby towing target is found, its entity ID (UUID) is published.
   //! This callback updates the "hasHookTarget" and "hook-target-marking-text"
   //! state attributes accordingly.
   //!
   //! \param hookTargetUuid The UUID of the potential hook target
   virtual void onHookTargetUuidChanged(const std::string& hookTargetUuid);
 
protected:
   //! \brief Marking text for the current entity used in resource subscription
   std::string myMarkingText;
 
   //! \brief Input handler logic for processing input device events
   DtInputLogic myDriverInputLogic;
 
   //! \brief Main joystick function group name from configuration
   //!
   //! Used to identify the function group when sending joystick messages.
   std::string myMainJoystickGroup;
 
   //! \brief Flag indicating if this vehicle is capable of pivot steering
   //!
   //! When true, enables pivot steering functionality. This value is stored in
   //! the "canPivot" state attribute. Defaults to false.
   bool myCanPivot;
 
   //! \brief Flag indicating if this vehicle has a differential lock
   //!
   //! When true, enables differential lock functionality. This value is stored in
   //! the "hasDifferentialLock" state attribute. Defaults to false.
   bool myHasDifferentialLock;
 
   //! \brief Flag indicating if this vehicle has a tow hook
   //!
   //! When true, enables towing hook functionality. This value is stored in
   //! the "hasTowHook" state attribute. Defaults to false.
   bool myHasTowHook;
 
   // Sets whether to show the inclinometer instrument. This shows the entity's pitch and roll.
   bool myShowInclinometer;
};
 
} // namespace makVre