bullseyeController.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file bullseyeController.h
//! \ingroup vreVrfmodel
//! \brief Controller for managing bullseye reference point targets
//!
//! This file defines the DtBullseyeController class which handles player selection
//! of bullseye targets in VR Engage stations and manages the bullseye reference point
//! used for tactical position reporting.
 
#pragma once
#include "vreVrfmodel/export.h"
#include "vreVrfmodel/vreSimComponent.h"
#include <vreVrfobjcore/bullseyePSR.h>
#include <vreMessageManager/vreMessage.h>
#include <vrfobjcore/controllerComponent.h>
 
//! \brief Special controller for managing bullseye targets in VR Engage
//!
//! This controller handles player selection of bullseye targets in VR Engage stations.
//! It is responsible for saving the selected bullseye entity ID and sending BullseyeStatus
//! messages to other simulation components. The controller connects to GUI definitions in
//! pilot.lua for the "Select Bullseye" functionality.
 
namespace makVre
{
//! \brief Type identifier for the bullseye controller component
const char DtBullseyeControllerType[] = "bullseye-controller";
 
//! \brief Controller component for managing bullseye reference points
//!
//! The DtBullseyeController provides functionality for selecting, tracking, and
//! reporting bullseye reference points in tactical simulations. It handles user
//! selection of bullseye targets and communicates position updates to other
//! simulation components.
class VREVRFMODEL_DLL DtBullseyeController : public DtVreSimComponent<DtControllerComponent>
{
private:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is private and not implemented to prevent
   //! creation of instances without proper initialization.
   DtBullseyeController();
 
   //! \brief Copy constructor (not implemented)
   //!
   //! Copy constructor is private and not implemented to prevent
   //! copy construction.
   DtBullseyeController(const DtBullseyeController& orig);
 
   //! \brief Assignment operator (not implemented)
   //! \return Reference to this object
   //!
   //! Assignment operator is private and not implemented to prevent assignment.
   const DtBullseyeController& operator=(const DtBullseyeController& orig);
 
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 Optional component descriptor
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //!
   //! Creates a new bullseye controller component with the specified parameters.
   DtBullseyeController(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the bullseye controller component.
   virtual ~DtBullseyeController() override;
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtBullseyeControllerType)
   //!
   //! Implements the DtSimComponent::type() method to return the
   //! type identifier for this component.
   virtual const char* type() const override;
 
   //! \brief Initializes the component
   //! \return True if initialization is successful, false otherwise
   //!
   //! Registers message handlers for bullseye-related messages, particularly
   //! vrfSetBullseyeIdMessage which is sent by pilotSimLogic.
   virtual bool init() 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);
 
   //! \brief Creates the process state repository for this component
   //! \return Pointer to the newly created bullseye process state repository
   //!
   //! Creates the myProcessState data member and adds it to the process state
   //! repository manager. Passes the name and type specified in the component
   //! descriptor (if they exist) to the DtVrfProcessStateRepository::createRepository
   //! factory method. If name and/or type are not specified, uses the appropriate
   //! default strings defined in procSRTypes.h.
   virtual DtBullseyePSR* createPSR();
 
   //! \brief Updates bullseye status when the target entity's location changes
   //! \param obj Pointer to the local object that has changed location
   //!
   //! Called when the bullseye target entity's location is updated.
   //! Updates the stored bullseye world position and sends status updates.
   void processSetLocationComplete(const DtLocalObject* obj);
 
   //! \brief Handles simulation object addition events
   //! \param obj Pointer to the newly added local object
   //!
   //! Handles the case where a VRF scenario reloads. VR Engage will reset the
   //! bullseye target according to the saved bullseyeID when the target object
   //! is added to the simulation.
   void processSimObjectAdded(const DtLocalObject* obj);
 
   //! \brief Handles simulation object removal events
   //! \param obj Pointer to the local object being removed
   //!
   //! Removes all callbacks related to the bullseye object when it's
   //! about to be removed from the simulation.
   void processSimObjectToBeRemoved(const DtLocalObject* obj);
 
protected:
   //! \brief Handles bullseye target selection messages
   //! \param msg Pointer to the SetBullseyeIdMessage
   //! \return Message processing result
   //!
   //! Processes SetBullseyeIdMessage sent from the user interface and updates
   //! the current bullseye object based on the selected entity ID.
   virtual DtVreMessageResult handleSetBullseyeId(DtVreMessage* msg);
 
   //! \brief Handles bullseye status request messages
   //! \param msg Pointer to the BullseyeStatusRequestMessage
   //! \return Message processing result
   //!
   //! Processes BullseyeStatusRequestMessage sent from GUI components and
   //! responds with a BullseyeStatusUpdateMessage containing current bullseye information.
   virtual DtVreMessageResult handleBullseyeStatusRequest(DtVreMessage* msg);
 
   //! \brief Sends bullseye status update to interested components
   //!
   //! Sends a BullseyeStatusUpdateMessage to the controlling entity with
   //! the selected bullseye's geocentric world location. Used to update
   //! HUD displays and other tactical information systems.
   virtual void sendBullseyeStatusUpdate();
 
   //! \brief Sets a new bullseye target
   //! \param obj Reference to the simulation object to use as the bullseye target
   //!
   //! Updates the current bullseye object, stores its location, and sends
   //! a bullseye status update to all interested components.
   virtual void setNewBullseye(DtSimObjectReference obj);
 
   //! \brief Performs initialization before the first tick
   //!
   //! Sets up initial state and connections needed before the first
   //! simulation tick is processed.
   virtual void preFirstTickInit() override;
   //! \brief Updates the controller state each simulation frame
   //!
   //! Performs periodic updates and processing during each simulation cycle.
   virtual void tick() override;
 
   //! \brief Gets the default process state repository type
   //! \return String identifying the default PSR type (DtBullseyePSRType)
   //!
   //! Returns the default process state repository type for this component.
   const char* defaultPSRType() const;
 
protected:
   //! \brief Flag indicating if the bullseye reference is currently valid
   bool myBullseyeIsValid;
 
   //! \brief Last known geocentric position of the bullseye target
   DtVector myLastBullseyeWorldPosition;
 
   //! \brief Pointer to the bullseye process state repository
   DtBullseyePSR* myProcessState;
};
} // namespace makVre