sampleComponent.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/
 
//! \file sampleComponent.h
//! \brief Example component demonstrating attribute monitoring and callback patterns in VR-Engage
//!
//! This header defines the DtPlayerStateAttributeSampleComponent which shows how to monitor
//! player attribute store changes using the callback system. It demonstrates event-driven
//! component design and proper callback lifecycle management patterns.
 
#pragma once
 
#include "vrePlayerStation/playerComponent.h"
 
#include "vreUtil/attribute.h"
 
 
//! \brief Type identifier string for DtNotifyLogic component registration.
//!
//! This string is used when registering the component with the component factory
//! and must match the componentType value used in role configuration files.
constexpr auto DtPlayerStateAttributeSampleComponentType = "DtPlayerStateAttributeSampleComponent";
 
//! \brief Example component demonstrating player attribute monitoring and callback patterns.
//!
//! This component shows how to use the VR-Engage player attribute store callback system
//! to monitor state changes using event-driven patterns. It specifically monitors the
//! "set-gear" attribute and logs changes when the player's gear selection changes,
//! demonstrating both polling (in tick()) and event-driven (via callbacks) approaches.
//!
//! Key VR-Engage patterns demonstrated:
//! - Subscribing to attribute changes via attribute callbacks
//! - Accessing the player attribute store for centralized state management
//! - Using DtAttributeConnectionList for automatic callback lifetime management
//! - Component lifecycle (initialize, postInitialize, tick, shutdown)
//! - Proper callback cleanup during shutdown to prevent dangling pointers
//! - Comparing polling (tick) vs. event-driven (callback) approaches
//!
//! This class inherits from DtPlayerComponent and is registered with the player
//! station's component factory for role-based instantiation.
class DtPlayerStateAttributeSampleComponent : public makVre::DtPlayerComponent
{
public:
   //! \brief Default constructor.
   //!
   //! Initializes the player state attribute sample component. The actual setup is performed
   //! in initialize() following the VR-Engage component lifecycle pattern.
   DtPlayerStateAttributeSampleComponent();
 
   //! \brief Virtual destructor.
   //!
   //! Cleanup is performed in shutdown() rather than the destructor to ensure
   //! proper framework ordering during component destruction.
   virtual ~DtPlayerStateAttributeSampleComponent() override = default;
 
   //! \brief Initializes the component with player station and configuration.
   //!
   //! This method demonstrates the VR-Engage pattern for component initialization:
   //! 1. Call base class initialize() first to set up inherited members
   //! 2. Access player attribute store to retrieve attribute handles
   //!
   //! The "set-gear" attribute is accessed from the player attribute store,
   //! which is a centralized repository for player-specific state. The attribute
   //! handle is stored for later use in postInitialize() when callbacks are registered.
   //!
   //! PATTERN: Attribute handles should be retrieved in initialize(), but callbacks
   //! should be registered in postInitialize() to ensure all components and attributes
   //! are fully initialized.
   //!
   //! \param player The player station instance this component belongs to
   //! \param config Configuration table containing role parameters (not used in this example)
   //! \return true if initialization succeeds, false otherwise
   virtual bool initialize(makVre::DtPlayerStation* player, makVre::DtInitTable& config) override;
 
   //! \brief Performs post-initialization after all components are initialized.
   //!
   //! This method demonstrates the VR-Engage pattern for registering attribute callbacks:
   //! 1. Call base class postInitialize() first
   //! 2. Register callbacks using the connection manager
   //!
   //! PATTERN: Register attribute callbacks in postInitialize() rather than initialize()
   //! to ensure all components are fully initialized and all attributes exist. This
   //! prevents race conditions where callbacks might be invoked before the component
   //! is fully ready.
   //!
   //! The myAttributeCallbacks connection manager automatically tracks all registered
   //! callbacks and provides disconnectAll() for cleanup during shutdown.
   //!
   //! \return true if post-initialization succeeded, false otherwise
   virtual bool postInitialize() override;
 
   //! \brief Per-frame update callback.
   //!
   //! Called every frame by the player station framework. This example demonstrates
   //! the polling approach to attribute access by retrieving and logging the current
   //! gear value every frame using get<T>().
   //!
   //! PATTERN COMPARISON:
   //! - Polling (this method): Retrieves attribute value every frame, even if unchanged
   //! - Event-driven (onGearChanged): Callback invoked only when value actually changes
   //!
   //! For attributes that change infrequently, callbacks are more efficient. For attributes
   //! that need to be sampled every frame (like analog inputs), polling in tick() is appropriate.
   //!
   //! \param dt Delta time in seconds since last update
   virtual void tick(double dt) override;
 
   //! \brief Shutdown callback for cleanup.
   //!
   //! Performs cleanup before component destruction. This method demonstrates
   //! the VR-Engage pattern for proper callback cleanup:
   //! 1. Call base class shutdown() first
   //! 2. Disconnect all attribute callbacks to prevent dangling pointers
   //!
   //! The myAttributeCallbacks.disconnectAll() call ensures all registered
   //! callbacks are properly removed from the attribute store before the
   //! component is destroyed.
   virtual void shutdown() override;
 
   //! \brief Returns the component type identifier.
   //!
   //! This string is used by the component factory for instantiation and
   //! must match the registration in initPlayerStationModule().
   //!
   //! \return The component type string "DtPlayerStateAttributeSampleComponent"
   virtual const char* type() const override;
 
protected:
   //! \brief Callback invoked when the "set-gear" attribute changes.
   //!
   //! This method demonstrates the event-driven approach to attribute monitoring.
   //! It is automatically called by the attribute store whenever the gear attribute
   //! changes, receiving the new value as a parameter.
   //!
   //! PATTERN: Attribute callbacks receive the new value as a parameter with a type
   //! matching the attribute's type. The signature must match:
   //!   void methodName(const AttributeType& newValue)
   //!
   //! This is more efficient than polling in tick() for infrequent changes, as it
   //! only executes when the value actually changes.
   //!
   //! \param newGear The new gear value (e.g., "Neutral", "1st", "2nd", "Reverse")
   virtual void onGearChanged(const std::string& newGear);
 
   //! \brief Handle to the "set-gear" player attribute.
   //!
   //! This handle provides typed access to the gear attribute value via get<T>()
   //! and is used to register callbacks via the connection manager. Attribute handles
   //! are lightweight value types that can be safely stored as member variables.
   //!
   //! PATTERN: Store attribute handles as members for repeated access rather than
   //! looking up attributes by name each time they're needed.
   makVre::DtAttributeHandle myGearAttributeHandle;
};