playerComponent.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file playerComponent.h
//! \brief Defines the DtPlayerComponent base class for VR-Engage role components
//!
//! This file contains the base class that all role components in VR-Engage must
//! inherit from. Components provide specific functionality for roles, such as
//! movement, weapons, sensors, and user interface elements. The component system
//! allows roles to be composed from reusable building blocks.
 
#pragma once
 
#include "vrePlayerStation/export.h"
 
#include "vreUtil/attribute.h"
 
#include "vreUtil/initializer.h"
#include <vrvUtil/DtProfiler.h>
 
#include <string>
 
namespace makVrv
{
class DtDe;
}
 
namespace makVre
{
//! \brief Forward declaration of the initialization table class
class DtInitTable;
 
//! \brief Forward declaration of the player station class
class DtPlayerStation;
 
//! \brief Forward declaration of the entity resolver class
class DtEntityResolver;
 
namespace PlayerComponentConfig
{
//! \defgroup RoleConfigParams Role Configuration Parameters
//! \brief Parameters used to configure player station role components.
//!
//! Role configuration parameters control the behavior of components within a player role.
//! Each component type defines its own set of parameters that can be specified in role
//! configuration files to customize component behavior.
//! @hidegroupgraph
//! \ingroup RoleConfigParams
//! \defgroup PlayerComponentRoleParams Player Component Role Parameters
//! \brief Base configuration options inherited by all player components.
//!
//! These parameters are available to all component types that inherit from DtPlayerComponent.
//! They provide common configuration options for component identification and initialization.
//! Component-specific parameters are documented in each component's own parameter group.
//! @{
 
//! \vreRoleParam{initAttributes,string,"",playerComponent,Table of initial attribute values to set during component initialization.}
constexpr const char* initAttributes = "initAttributes";
 
//! \vreRoleParam{name,string,"",playerComponent,Name to assign to this component instance for identification purposes.}
constexpr const char* name = "name";
 
//! @}
} // namespace PlayerComponentConfig
 
//! \brief Base class for all role components in VR-Engage
//!
//! DtPlayerComponent serves as the foundation for all components that can be
//! added to player roles. Components encapsulate specific functionality, such as
//! movement control, weapons systems, sensor management, and user interface elements.
//!
//! Components are instantiated by the player station during initialization based on
//! the role definition. They have access to the player attribute store for sharing
//! data with other components, and they receive tick calls for regular updates.
class PLAYERSTATION_DLL DtPlayerComponent
{
public:
   //! \brief Constructor
   //!
   //! Creates a component
   //! Called from DtPlayerStation::initializeComponents during player station initialization.
   //! Each component has a unique type that identifies its functionality.
   DtPlayerComponent();
 
   //! \brief Virtual destructor
   //!
   //! Ensures proper cleanup of derived component classes.
   virtual ~DtPlayerComponent();
 
   //! \brief Initializes the component
   //! \param player Pointer to the player station that owns this component
   //! \param config Configuration table with component settings
   //! \return True if initialization was successful, false otherwise
   //!
   //! Called when the component is first created during player station initialization.
   //! This method performs initial setup and calls initializeStateAttributes().
   //! Components should override this method to perform type-specific initialization,
   //! but must call the base class implementation first.
   virtual bool initialize(DtPlayerStation* player, DtInitTable& config);
 
   //! \brief Performs post-initialization setup
   //! \return True if post-initialization was successful, false otherwise
   //!
   //! Called after all components have been created and initialized. This is when
   //! required but not owned state attributes can be looked up in the state, or
   //! dependent components can be located. Components can use this phase to establish
   //! connections with other components in the player station.
   virtual bool postInitialize();
 
   //! \brief Updates the component
   //! \param dt Time in seconds since the last tick
   //!
   //! Called once per frame to update the component's state.
   //! All concrete component classes must implement this method.
   virtual void tick(double dt) = 0;
 
   //! \brief Shuts down the component
   //!
   //! Called when the player station is shutting down. Components should
   //! override this method to release resources and perform cleanup operations.
   virtual void shutdown();
 
   //! \brief Gets the component type identifier
   //! \return Reference to the component type string
   //!
   //! Returns the unique type identifier for this component class. The type string
   //! is used by the component system to identify and instantiate components based
   //! on role configuration. Each component class should return a consistent,
   //! descriptive type name (e.g., "DtDriverControlLogic", "DtObserverUpdater").
   //!
   //! \note This is a pure virtual method that must be implemented by all derived classes.
   virtual const char* type() const = 0;
 
   //! \brief Sets the component name
   //! \param name The name to assign to this component
   //!
   //! Sets a name for this component instance, which can be used to distinguish
   //! between multiple components of the same type in a player station.
   virtual void setName(const std::string& name);
 
   //! \brief Gets the component name
   //! \return Reference to the component name string
   //!
   //! Returns the name of this component instance, which may be empty if
   //! no name was explicitly assigned.
   virtual const std::string& name();
 
   //! \brief Gets the player station
   //! \return Reference to the player station that owns this component
   //!
   //! Provides access to the player station that this component belongs to.
   virtual DtPlayerStation& player();
 
   //! \brief Gets the player attribute store
   //! \return Reference to the attribute store
   //!
   //! Provides access to the attribute store of the player station, which
   //! contains shared data that can be accessed by all components.
   virtual DtAttributeHandle& playerAttributeStore();
 
   //! \brief Gets the player attribute store (const version)
   //! \return Const reference to the attribute store
   virtual const DtAttributeHandle& playerAttributeStore() const;
 
protected:
   //! \brief Initializes component state attributes
   //!
   //! Creates and initializes any player state attributes required by this component.
   //! Derived component classes should override this method if they need to add
   //! custom state attributes to the player attribute store.
   virtual void initializeStateAttributes();
 
   //! \brief Component instance name
   std::string myName;
 
   //! \brief Component configuration table
   DtInitTable myConfig;
 
   //! \brief Pointer to the owning player station
   DtPlayerStation* myPlayer;
 
   //! \brief Pointer to the display engine (common to all components)
   makVrv::DtDe* myDe;
 
   //! \brief Pointer to the entity resolver (common to all components)
   DtEntityResolver* myResolver;
 
   //! \brief Member-scope instance of Attribute callback manager
   //!
   //! Used to manage Attribute change callback connections and ensure that all
   //! callbacks are unregistered when this class instance is destroyed.
   DtAttributeCallbackManager myAttributeCallbacks;
};
 
} // namespace makVre