entityControlLogic.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file entityControlLogic.h
//! \brief Defines the logic for controlling entities in VR-Engage
//!
//! This file contains the DtEntityControlLogic class which provides the core
//! functionality for controlling entities in the simulation. It handles user
//! input mapping, entity state updates, and simulation control operations.
 
#pragma once
 
#include "vrePlayerStation/export.h"
#include "vrePlayerStation/playerComponent.h"
#include "vrePlayerStation/inputLogic.h"
 
#include "vreMessageManager/vreMessage.h"
 
#include <string>
#include <vector>
 
namespace makVre
{
namespace EntityControlLogicConfig
{
//! \ingroup RoleConfigParams
//! \defgroup EntityControlLogicRoleParams Entity Control Logic Role Parameters
//! Configuration Options for Entity Control Logic.
//! @{
 
//! \vreRoleParamRequired{inputConfigFile,string,entityControlLogic,"driverInput.lua",The input file to reference to get all keybinds and actions.}
constexpr const char* inputConfigFile = "inputConfigFile";
 
//! \vreRoleParam{mouseControlSupport,bool,false,entityControlLogic,Determines whether or not this role has mouse control enabled.}
constexpr const char* mouseControlSupport = "mouseControlSupport";
 
//! \vreRoleParamRequired{joystickFunctionGroups,DtInitTable,entityControlLogic,{"Human Movement";},The function groups to reference for sending inputs to the backend}
constexpr const char* joystickFunctionGroups = "joystickFunctionGroups";
//! @}
} // namespace EntityControlLogicConfig
 
//! \brief Type identifier constant for DtEntityControlLogic components
//!
//! This constant defines the string identifier used to identify DtEntityControlLogic
//! component types within the VR-Engage framework. It is used for component
//! registration, type checking, and serialization operations.
constexpr const char* DtEntityControlLogicType = "DtEntityControlLogic";
 
//! \brief Component that provides entity control functionality
//!
//! DtEntityControlLogic is responsible for translating user input into entity control commands and managing the state
//! of player-controlled entities. It handles input mapping for different control modes (mouse, joystick, etc.), entity
//! state synchronization, and specific control operations like reset.
//!
//! This component serves as the primary interface between user input and
//! entity behavior in the simulation.
class PLAYERSTATION_DLL DtEntityControlLogic : public makVre::DtPlayerComponent
{
public:
   //! \brief Constructor
   //! \param type Type identifier for the component
   //!
   //! Creates a new entity control logic component with the specified type.
   //! The default type is "DtEntityControlLogic".
   DtEntityControlLogic();
 
   //! \brief Virtual destructor
   //!
   //! Ensures proper cleanup of entity control resources.
   virtual ~DtEntityControlLogic() override;
 
   //! \brief Initializes the entity control logic
   //! \param player Pointer to the player station this component belongs to
   //! \param config Configuration table with initialization parameters
   //! \return True if initialization was successful, false otherwise
   //!
   //! Initializes the entity control component with the specified player station
   //! and configuration. Registers message handlers and sets up input mappings.
   virtual bool initialize(DtPlayerStation* player, DtInitTable& config) override;
 
   //! \brief Performs post-initialization setup
   //! \return True if post-initialization was successful, false otherwise
   //!
   //! Completes initialization tasks that require other components to be
   //! already initialized. This typically includes setting up connections
   //! to other components and starting entity control.
   virtual bool postInitialize() override;
 
   //! \brief Updates the entity control logic each frame
   //! \param dt Time in seconds since the last update
   //!
   //! Handles per-frame updates for entity control, including processing
   //! input and updating entity states. This is called once per frame.
   virtual void tick(double dt) override;
 
   //! \brief Shuts down the entity control logic
   //!
   //! Cleans up resources, disconnects from input handlers, and releases
   //! control of entities. Called when the player station is shutting down.
   virtual void shutdown() override;
 
   //! \brief Returns the component type identifier
   //! \return String identifier for this component type
   //!
   //! Returns the type identifier string for this component, which is used
   //! by the VR-Engage framework for component identification and management.
   //! The returned value matches DtEntityControlLogicType.
   virtual const char* type() const override;
 
   //! \brief Message handlers
   //! @{
 
   //! \brief Handles simulation state update messages
   //! \param msg Pointer to the simulation state message
   //! \return Message handling result
   //!
   //! Processes simulation state messages, updating the component's
   //! understanding of the current entity state in the simulation.
   virtual makVre::DtVreMessageResult handleSimState(makVre::DtVreMessage* msg);
 
   //! \brief Handles general state messages
   //! \param message Pointer to the state message
   //! \return Message handling result
   //!
   //! Processes various state-related messages that affect entity control.
   virtual makVre::DtVreMessageResult handleStateMessages(makVre::DtVreMessage* message);
 
   //! \brief Handles reset messages
   //! \param message Pointer to the reset message
   //! \return Message handling result
   //!
   //! Processes messages requesting an entity reset, either in place
   //! or to a default position/state.
   virtual makVre::DtVreMessageResult handleReset(makVre::DtVreMessage* message);
   //! @}
 
   //! \brief Sets extended data for an entity
   //! \param key Key identifier for the data being set
   //! \param value Value to set for the specified key
   //! \param entity Entity identifier to set data for (defaults to ownship entity)
   //!
   //! Sets extended data values for an entity, typically used for custom
   //! properties or state information that isn't part of the standard entity state.
   //! If no entity is specified, applies to the player's own entity (ownship).
   virtual void setExtendedData(
      const std::string& key, const std::string& value, DtEntityIdentifier entity = DtEntityIdentifier::nullId());
 
   //! \brief Entity reset methods
   //! @{
 
   //! \brief Resets the entity to its default state
   //! \param val Input value (typically 1.0 for pressed actions)
   //!
   //! Resets the player's entity to its default position and state.
   //! This is typically triggered by a user input action.
   virtual void reset(float val);
 
   //! \brief Resets the entity while maintaining its current position
   //! \param val Input value (typically 1.0 for pressed actions)
   //!
   //! Resets the player's entity to its default state except for position,
   //! which remains unchanged. Useful for clearing problems without relocating.
   virtual void resetInPlace(float val);
   //! @}
 
   //! \brief Mouse control methods
   //! @{
 
   //! \brief Toggles mouse control mode on/off
   //! \param val Input value (typically 1.0 for pressed actions)
   //!
   //! Toggles between mouse control being enabled and disabled.
   //! This is typically triggered by a user input action.
   virtual void toggleMouseControl(float val);
 
   //! \brief Enables mouse control mode
   //! \param val Input value (typically 1.0 for pressed actions)
   //!
   //! Explicitly enables mouse control without toggling.
   //! This is typically triggered by a user input action.
   virtual void enableMouseControl(float val);
 
   //! \brief Handles application focus change messages
   //! \param message Pointer to the focus message
   //! \return Message handling result
   //!
   //! Processes messages about application focus changes, which may
   //! affect how input control works (e.g., disabling control when
   //! the application loses focus).
   virtual makVre::DtVreMessageResult handleFocusMessage(makVre::DtVreMessage* message);
   //! @}
 
   //! \brief Sets whether mouse control is enabled
   //! \param enabled True to enable mouse control, false to disable it
   //!
   //! Controls whether mouse input is used for entity control.
   //! When disabled, other input methods like joystick may still work.
   virtual void setMouseControlEnabled(bool enabled);
 
   //! \brief Checks if mouse control is currently enabled
   //! \return True if mouse control is enabled, false otherwise
   //!
   //! Determines whether mouse input is currently being used for entity control.
   virtual bool isMouseControlEnabled();
 
   //! \brief Checks if mouse control support is allowed
   //! \return True if mouse control is allowed, false if explicitly disallowed
   //!
   //! Determines whether mouse control is allowed for the current entity or mode.
   //! Some entity types or control modes may not support mouse control.
   virtual bool isMouseControlSupportAllowed() const;
 
   //! \brief Sets whether mouse control support is allowed
   //! \param enable True to allow mouse control, false to disallow it
   //!
   //! Controls whether mouse control is allowed as an option for the current
   //! entity or mode. This affects whether mouse control can be enabled at all.
   virtual void setMouseControlSupportAllowed(bool enable);
 
   //! \brief Gets the joystick function groups
   //! \return Reference to the vector of joystick function group names
   //!
   //! Retrieves the list of joystick function groups used by this entity controller.
   //! These groups organize joystick input mappings by function.
   virtual const std::vector<std::string>& joystickGroups() const;
 
protected:
   //! \brief Takes control of the player's entity
   //!
   //! Establishes control over the player's assigned entity, enabling
   //! input to affect the entity's state and behavior. Typically called
   //! during initialization or when a new entity is assigned.
   virtual void takeControlOfPlayerEntity();
 
   //! \brief Releases control of the player's entity
   //!
   //! Relinquishes control over the player's assigned entity, preventing
   //! further input from affecting the entity. Typically called during
   //! shutdown or when changing entities.
   virtual void releaseControlOfPlayerEntity();
 
 
   //! \brief List of joystick function groups used by this controller
   std::vector<std::string> myJoystickFunctionGroups;
 
   //! \brief Input logic handler for common controls
   //!
   //! Manages input mappings and action handlers for general entity control.
   DtInputLogic myCommonInputLogic;
 
   //! \brief Name of the input configuration file
   //!
   //! Identifies the configuration file containing input mappings for this controller.
   std::string myInputConfigFile;
 
   //! \brief Flag indicating whether mouse control is currently enabled
   bool myMouseControlEnabled;
 
   //! \brief Flag indicating whether mouse control is allowed for the current entity/mode
   bool myMouseControlSupportAllowed;
};
 
} // namespace makVre