vreBullseyeController.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreBullseyeController.h
//! \ingroup vreVrfmodel
//! \brief Controller for managing bullseye target selection
//!
//! This file defines the DtVreBullseyeController class which handles player selection
//! of bullseye targets in VRE stations. It manages saving the selected bullseye entity
//! ID and updating the BullseyeLocation state data accordingly. This controller works
//! in conjunction with the GUI definitions in pilot.lua for the "Select Bullseye" feature.
 
#pragma once
 
#include "vreVrfmodel/export.h"
#include "vreVrfmodel/vreSimComponent.h"
#include <vrfobjcore/simObjectReference.h>
#include "vreMessageManager/vreMessage.h"
#include <boost/signals2.hpp>
 
//! \brief Special controller for handling bullseye targeting in VRE stations
//!
//! This controller enables players to select a bullseye target in VRE stations and
//! maintains that selection. It is responsible for saving the selected bullseye entity ID
//! and updating the BullseyeLocation state-data accordingly. This component integrates
//! with the GUI definitions in pilot.lua for the "Select Bullseye" functionality.
 
namespace makVre
{
//! \brief Type identifier for the VRE bullseye controller component
const char DtVreBullseyeControllerType[] = "vre-bullseye-controller";
 
//! \brief Controller for managing bullseye target selection and location
//!
//! DtVreBullseyeController handles player selections of bullseye targets in VRE stations.
//! It manages the reference to the selected bullseye entity and updates the BullseyeLocation
//! state data whenever the entity's location changes or when a new bullseye is selected.
//! This controller also properly handles scenario reloads and entity removal events to
//! maintain consistent bullseye targeting.
class VREVRFMODEL_DLL DtVreBullseyeController : public DtVreSimComponent<DtSimComponent>
{
private:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is private and not implemented to prevent
   //! creation of instances without proper initialization.
   DtVreBullseyeController();
 
   //! \brief Copy constructor (not implemented)
   //!
   //! Copy constructor is private and not implemented to prevent
   //! copy construction.
   DtVreBullseyeController(const DtVreBullseyeController& orig);
 
   //! \brief Assignment operator (not implemented)
   //! \return Reference to this object
   //!
   //! Assignment operator is private and not implemented to prevent assignment.
   const DtVreBullseyeController& operator=(const DtVreBullseyeController& 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 Component descriptor with configuration parameters
   //! \param parentRegistry Optional parent registry for reader/writer functionality
   //!
   //! Creates a new bullseye controller component with the specified parameters.
   DtVreBullseyeController(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,
   //! including any signal connections.
   virtual ~DtVreBullseyeController() override;
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtVreBullseyeControllerType)
   //!
   //! Implements the DtSimComponent::type() method to return the
   //! type identifier for this component.
   virtual const char* type() const override;
 
   //! \brief Initializes the bullseye controller
   //! \return True if initialization is successful, false otherwise
   //!
   //! Registers message handlers to process vrfSetBullseyeIdMessage messages
   //! sent by pilotSimLogic. Also sets up entity event connections.
   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 Updates the controller state each simulation frame
   //!
   //! Checks if VRE has just received control over the entity and, if so,
   //! sets the "BullseyeLocation" value based on the current bullseye target.
   //! This ensures proper bullseye tracking when player control changes.
   virtual void tick() override;
 
   //! \brief Processes simulation object added events
   //! \param simObject Reference to the simulation object that was added
   //!
   //! Handles the case where a VRF scenario is reloaded. When this happens,
   //! VRE will reset the bullseye target according to the saved bullseye ID.
   //! This ensures continuity of bullseye targeting across scenario reloads.
   void processSimObjectAdded(DtSimObjectReference simObject);
 
   //! \brief Processes simulation object removal events
   //! \param simObject Reference to the simulation object that will be removed
   //!
   //! Removes all callbacks related to the bullseye object if it is the one being removed
   //! and resets the "BullseyeLocation" value to 0. This ensures proper cleanup when
   //! the current bullseye entity is removed from the simulation.
   void processSimObjectToBeRemoved(DtSimObjectReference simObject);
 
protected:
   //! \brief Handles bullseye ID set messages from the user
   //! \param message Pointer to the message containing the bullseye ID information
   //! \return Message processing result indicating success or failure
   //!
   //! Processes SetBullseyeIdMessage messages sent from the user interface
   //! and updates the current bullseye object based on the entity ID in the message.
   virtual makVre::DtVreMessageResult handleSetBullseyeId(makVre::DtVreMessage* message);
 
private:
   //! \brief Updates the BullseyeLocation state data with the entity's position
   //! \param simObject Reference to the bullseye simulation object
   //!
   //! Sets the "BullseyeLocation" value to be the geocentric world location
   //! of the specified DtLocalObject. This is used to track the current position
   //! of the bullseye entity for navigation and targeting purposes.
   void updateLocation(DtSimObjectReference simObject);
 
   //! \brief Sets a new bullseye target and updates its location
   //! \param simObject Reference to the new bullseye simulation object
   //!
   //! Updates the current bullseye object reference and the "BullseyeLocation" value
   //! to reflect the new bullseye entity. This method is called when the player
   //! selects a new bullseye target or when restoring a previously selected target.
   void setNewBullseye(DtSimObjectReference simObject);
 
private:
   //! \brief Reference to the currently selected bullseye entity
   //!
   //! Holds a reference to the simulation object that is currently selected
   //! as the bullseye target. This reference is updated when the player
   //! selects a new bullseye entity.
   DtRwSimObjectReference myBullseyeEntity;
 
   //! \brief Flag tracking the entity's player-controlled state
   //!
   //! Saves the last known state of whether the owning entity is player-controlled.
   //! This is used to detect when player control changes, which triggers an update
   //! of the bullseye location.
   bool myIsPlayerControlled;
 
   //! \brief Connection for simulation object added events
   //!
   //! Manages the connection to simulation object added events, which is used
   //! to handle scenario reloads and re-establish bullseye targeting.
   boost::signals2::scoped_connection mySimObjectAddedConnection;
 
   //! \brief Connection for simulation object deleted events
   //!
   //! Manages the connection to simulation object deleted events, which is used
   //! to handle cleanup when bullseye entities are removed from the simulation.
   boost::signals2::scoped_connection mySimObjectDeletedConnection;
};
} // namespace makVre