vreOccupancyDirectorController.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreOccupancyDirectorController.h
//! \ingroup vreVrfmodel
//! \brief Controller for managing entity embarkation and occupancy
//!
//! This file defines the DtVreOccupancyDirectorController class which extends
//! the occupancy director controller to provide VR-Engage specific functionality
//! for managing embarkation slots, entity roles, and ingress/egress points.
//! It handles information requests about embarkation possibilities and manages
//! slot assignments for entities.
 
#pragma once
 
#include "vreVrfmodel/export.h"
#include "vreVrfmodel/vreSimComponent.h"
 
#include "vreMessageManager/vreMessage.h"
#include "vreMessages/EntityEmbarkationInformation.h"
 
#include <vrfmodel/occupancyDirectorController.h>
 
namespace makVre
{
//! \brief Type identifier for the VRE occupancy director controller component
const char DtVreOccupancyDirectorControllerType[] = "vre-occupancy-director-controller";
 
//! \brief Controller for managing entity embarkation and occupancy within vehicles
//!
//! DtVreOccupancyDirectorController extends the base occupancy director to provide
//! VR-Engage specific functionality for managing embarkation slots and entity roles.
//! It handles entity embarkation requests, manages slot assignments, and provides
//! information about available ingress/egress points and actions.
//!
//! This controller is particularly useful for managing complex vehicles with multiple
//! occupancy positions, each with potentially different roles, such as driver, gunner,
//! commander, or passengers. It supports both scripted and interactive embarkation/disembarkation.
//!
//! Uses Descriptor Type: DtOccupancyDirectorControllerDescriptor
class VREVRFMODEL_DLL DtVreOccupancyDirectorController : public DtVreSimComponent<DtOccupancyDirectorController>
{
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 occupancy director controller component with the specified parameters.
   //! Initializes the embarkation slot management and message handling functionality.
   DtVreOccupancyDirectorController(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the occupancy director controller component.
   virtual ~DtVreOccupancyDirectorController() override;
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtVreOccupancyDirectorControllerType)
   //!
   //! Implements the DtSimComponent::type() method to return the
   //! type identifier for this component.
   virtual const char* type() const 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);
 
protected:
   //! \brief Reserves an embarkation slot for an entity
   //! \param entry Information about the embarkation slot to reserve
   //! \param uuid UUID of the entity reserving the slot
   //! \return True if the slot was successfully reserved, false otherwise
   //!
   //! Extends the base class reserveSlot to assign the slot-defined role name to the
   //! entity (typically a human player) when embarking. This allows proper role assignment
   //! for entity appearance and functionality within the vehicle.
   virtual bool reserveSlot(const DtEmbarkationSlotInformation& entry, const DtUUID& uuid) override;
   //! \brief Releases a previously reserved embarkation slot
   //! \param iSlot Index of the slot to release
   //! \param name UUID of the entity giving up the slot
   //!
   //! Releases a previously reserved embarkation slot, making it available for other
   //! entities to occupy. Also handles any role changes needed when the entity
   //! disembarks from the vehicle.
   virtual void giveUpSlot(int iSlot, const DtUUID& name) override;
 
   //! \brief Handles entity embarkation information request messages
   //! \param msg The message containing the embarkation information request
   //! \return Message processing result indicating success or failure
   //!
   //! Processes messages requesting information about embarkation possibilities
   //! for a specific entity. Generates and returns information about available
   //! slots, ingress points, and associated actions.
   virtual makVre::DtVreMessageResult handleEntityEmbarkationInformationRequestMessage(makVre::DtVreMessage* msg);
 
   //! \brief Generates a list of actionable points for an embarked entity
   //! \param forType The entity type to generate action points for
   //! \param actionPoints Output vector to be filled with generated action points
   //!
   //! Generates a list of actionable points for an entity that is already embarked
   //! in the vehicle. Points can be either unoccupied slots (for changing positions)
   //! or egress points that map to a slot with a defined egressTechnique.
   //!
   //! The egressTechnique string should be a script task name that opens the appropriate
   //! door for disembarkation. The egress point used is the first point in the route.
   virtual void generateEmbarkedActionPoints(
      const DtEntityType& forType, std::vector<EntityEmbarkationInformationMessage::ActionPoint>& actionPoints);
 
   //! \brief Generates a list of actionable points for an entity wishing to embark
   //! \param forType The entity type to generate action points for
   //! \param actionPoints Output vector to be filled with generated action points
   //! \return True if applicable points exist (even if all occupied), false if no points exist for the entity type
   //!
   //! Generates a list of actionable points for entities of the given type that wish
   //! to embark on the vehicle. Points are ingress points that either map to a single slot,
   //! or map to more than one slot where at least one slot defines an ingressTechnique.
   //!
   //! The ingressTechnique string should be a script task name that opens the appropriate
   //! door for embarkation. The egress point used is the last point in the route.
   //!
   //! Returns true if points were found, although the list may be empty if all are occupied.
   //! Returns false if no points exist for the given entity type.
   virtual bool generateUnembarkedActionPoints(
      const DtEntityType& forType, std::vector<EntityEmbarkationInformationMessage::ActionPoint>& actionPoints);
};
 
} // namespace makVre