vreEmbeddedEntitiesController.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreEmbeddedEntitiesController.h
//! \ingroup vreVrfmodel
//! \brief Controller for managing embedded entities
//!
//! This file defines the DtVreEmbeddedEntitiesController class which handles all
//! operations related to embedded entities, including state transitions, name resolution,
//! task forwarding, recovery, deployment, and other management functions.
 
#pragma once
 
#include "vreVrfmodel/export.h"
#include "vreVrfmodel/vreSimComponent.h"
 
#include <vrfmodel/embeddedEntitiesController.h>
 
namespace makVre
{
//! \brief Type identifier for the VRE embedded entities controller component
const char DtVreEmbeddedEntitiesControllerType[] = "vre-embedded-entities-controller";
 
//! \brief Controller for managing embedded entities and their operations
//!
//! DtVreEmbeddedEntitiesController handles all tasking and name resolution of embedded entities.
//! It manages state transitions, name resolution, task/set forwarding to embedded entities,
//! recovery, deployment, and other related operations. This VRE extension includes fixes for
//! handling static embedded entities and preventing crashes during deployment.
class VREVRFMODEL_DLL DtVreEmbeddedEntitiesController : public DtVreSimComponent<DtEmbeddedEntitiesController>
{
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 embedded entities controller component with the specified parameters.
   DtVreEmbeddedEntitiesController(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the embedded entities controller component.
   virtual ~DtVreEmbeddedEntitiesController() override;
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtVreEmbeddedEntitiesControllerType)
   //!
   //! 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 Recovers embedded entities
   //! \return True if the recovery operation was successful, false otherwise
   //!
   //! Overridden to properly handle static embedded entities, such as tripod-mounted
   //! launchers. This method implements the recovery process for embedded entities,
   //! bringing them back to their parent entity when required.
   virtual bool performRecovery() override;
 
   //! \brief Deploys embedded entities
   //! \return True if the deployment operation was successful, false otherwise
   //!
   //! Overridden to fix a crash that occurs when the embedded entity cannot be
   //! created during deployment. This method safely handles deployment failures
   //! and prevents simulation crashes.
   virtual bool performDeployment() override;
 
   //! \brief Commands an embedded entity to return to its parent
   //! \param entityName The name of the embedded entity to return
   //! \return True if the command was successfully issued, false otherwise
   //!
   //! Overridden to properly handle static embedded entities when commanding
   //! them to return to their parent entity. This ensures proper behavior for
   //! entities that don't normally move or navigate.
   virtual bool commandEeToReturn(const DtString& entityName) override;
 
   //! \brief Restores an embedded entity to its parent
   //! \param eeStatus Pointer to the embedded entity status to restore
   //!
   //! Overridden to reset resources on deployed embedded entities during
   //! the restoration process. This ensures proper resource management
   //! when embedded entities are returned to their parent entity.
   virtual void restoreEmbedded(DtRwEmbeddedEntityStatus* const eeStatus) override;
 
   //! \brief Updates the controller state each simulation frame
   //!
   //! Adds embedded entity status information into extended data during
   //! each simulation frame. This allows other components and systems to
   //! access current information about embedded entities.
   virtual void tick() override;
 
   //! \brief Calculates the spawn position for an embedded entity
   //! \return Vector containing the calculated spawn position coordinates
   //!
   //! Overridden to adjust the spawn point if the host entity is embarked in another entity.
   //! Increases the release altitude by the embarkation parent entity's altitude, ensuring
   //! that embedded entities are spawned at the correct position relative to both the
   //! immediate parent and any carrier entity.
   virtual DtVector calculateSpawnPosOfTarget() override;
};
 
} // namespace makVre