vreEmbarkationController.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreEmbarkationController.h
//! \ingroup vreVrfmodel
//! \brief Controller for managing entity embarkation and disembarkation
//!
//! This file defines the DtVreEmbarkationController class which extends the base
//! embarkation controller with VRE-specific functionality. It manages entity
//! embarkation and disembarkation operations, with fixes for VRF bugs such as
//! lifeforms staying in sitting posture while moving to egress points.
 
#pragma once
 
#include "vreVrfmodel/export.h"
#include "vreVrfModel/vreSimComponent.h"
 
#include "vreVrfobjcore/vreVrfEmbarkationPSR.h"
 
#include <vrfmodel/embarkationController.h>
 
class DtHumanStateRepository;
 
namespace makVre
{
//! \brief Type identifier for the VRE embarkation controller component
const char DtVreEmbarkationControllerType[] = "vre-embarkation-controller";
 
//! \brief Controller for managing entity embarkation and disembarkation
//!
//! DtVreEmbarkationController extends the base embarkation controller with
//! VRE-specific functionality. It manages the embarkation and disembarkation
//! of entities into and out of vehicles or other carrier entities. This controller
//! includes fixes for VRF bugs such as lifeforms staying in sitting posture while
//! moving to egress points, and adds additional capabilities for weapon state
//! management during embarkation operations.
class VREVRFMODEL_DLL DtVreEmbarkationController : public DtVreSimComponent<DtEmbarkationController>
{
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 embarkation controller component with the specified parameters.
   DtVreEmbarkationController(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the embarkation controller component,
   //! including any signal connections.
   virtual ~DtVreEmbarkationController() override;
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtVreEmbarkationControllerType)
   //!
   //! 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 Updates the controller state each simulation frame
   //!
   //! Checks for slot position changes, updates postures during embarkation
   //! and disembarkation, and fixes the VRF bug where lifeforms stay sitting
   //! while moving to egress points.
   virtual void tick() override;
 
   //! \brief Performs initialization before the first simulation tick
   //!
   //! Sets up initial states and caches references to required components
   //! before the simulation begins. This includes setting up the VRE-specific
   //! embarkation process state repository.
   virtual void preFirstTickInit() override;
 
   //! \brief Initializes the embarkation controller
   //! \return True if initialization is successful, false otherwise
   //!
   //! Overridden to register callback for object deleted signals, which
   //! are needed to properly handle cases where the carrier entity is deleted
   //! while this entity is embarked.
   virtual bool init() override;
 
   //! \brief Handles embarkation information receipt and clearance to embark
   //! \param embarkInfo Pointer to embarkation information for the target slot
   //!
   //! Called when embarkation information has been received and the entity
   //! has been cleared to embark. Overridden to provide VRE-specific handling
   //! of embarkation operations, including weapon state management.
   virtual void completeEmbarkationInformationRequest(const DtIfEmbarkationInformation* embarkInfo) override;
 
   //! \brief Handles disembarkation information receipt and clearance to disembark
   //! \param disembarkInfo Pointer to disembarkation information for the egress point
   //!
   //! Called when disembarkation information has been received and the entity
   //! has been cleared to disembark. Overridden to provide VRE-specific handling
   //! of disembarkation operations, including restoring cached weapon states.
   virtual void completeDisembarkationInformationRequest(const DtIfEmbarkationInformation* disembarkInfo) override;
 
   //! \brief Provides a fallback disembarkation position
   //! \return Vector containing the fallback offload point coordinates
   //!
   //! Overridden to offer a better fallback disembarkation position when
   //! the normal disembarkation process cannot determine a suitable egress point.
   //! This improves the reliability of the disembarkation process.
   virtual DtVector fallbackOffloadPoint() override;
 
   //! \brief Updates lifeform appearance and animation when embarked
   //! \param slotNum The embarkation slot number
   //! \param animationHintName Animation hint for the embarked state
   //!
   //! Overridden to include weapon state management from slot appearance
   //! settings. Ensures the correct appearance and animation when an entity
   //! is embarked in a vehicle or other carrier entity.
   virtual void updateLifeformEmbarkedAppearanceAndAnimation(int slotNum, const DtString& animationHintName) override;
 
   //! \brief Caches the current weapon state before embarkation
   //!
   //! Stores the current weapon state and hand item information before
   //! embarkation, so it can be restored later when the entity disembarks.
   //! This ensures continuity of equipment across embarkation operations.
   virtual void cacheWeaponState();
 
   //! \brief Restores the cached weapon state after disembarkation
   //!
   //! Restores the previously cached weapon state and hand item after
   //! disembarkation. This ensures the entity returns to its proper equipped
   //! state after leaving a vehicle or other carrier entity.
   virtual void restoreWeaponState();
 
   //! \brief Handles simulation object deletion events
   //! \param simObject Reference to the simulation object being deleted
   //!
   //! If the deleted object is the entity this entity is currently embarked on,
   //! this method restores the posture, weapon status, and clears the embarkation slot.
   //! This ensures proper cleanup when carrier entities are removed from the simulation.
   virtual void processSimObjectDeleted(DtSimObjectReference simObject);
 
   //! \brief Pointer to the VRE embarkation process state repository
   //!
   //! References the VRE-specific embarkation PSR which adds slotPoint to watch
   //! for entity leaving slot position and free slot. This extended PSR provides
   //! additional capabilities beyond the base embarkation PSR.
   DtVreVrfEmbarkationPSR* myVreEmbarkPSR;
 
   //! \brief Cached weapon state from before embarkation
   //!
   //! Stores the entity's weapon state (DIS appearance) before embarkation
   //! so it can be restored after disembarkation (addresses issue VRE-1220).
   DtWeaponState myUnembarkedWeaponState;
 
   //! \brief Cached hand item from before embarkation
   //!
   //! Stores the type of weapon being held before embarkation so it can
   //! be restored after disembarkation. This ensures weapon continuity.
   DtString myHandItem;
 
   //! \brief Flag indicating whether weapon state is cached
   //!
   //! When true, indicates that weapon state has been cached and can be
   //! restored during disembarkation. Controls when the cached state is restored.
   bool myWeaponStateCached;
 
   //! \brief Flag indicating whether entity is in its embarkation slot
   //!
   //! When true, indicates that the entity has reached its assigned slot position.
   //! Used to detect when the entity leaves the slot, which may require cleanup actions.
   bool myAmInSlotPosition;
 
   //! \brief Connection for simulation object deleted events
   //!
   //! Manages the connection to simulation object deleted events, which is used
   //! to handle cleanup when carrier entities are removed from the simulation.
   boost::signals2::scoped_connection mySimObjectDeletedConnection;
 
private:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is private and not implemented to prevent
   //! creation of instances without proper initialization.
   DtVreEmbarkationController();
 
   //! \brief Copy constructor (not implemented)
   //!
   //! Copy constructor is private and not implemented to prevent
   //! copy construction.
   DtVreEmbarkationController(const DtVreEmbarkationController& orig);
 
   //! \brief Assignment operator (not implemented)
   //! \return Reference to this object
   //!
   //! Assignment operator is private and not implemented to prevent assignment.
   const DtVreEmbarkationController& operator=(const DtVreEmbarkationController& orig);
};
 
} // namespace makVre