topAndDirectAttackMissileController.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/
 
//! \file topAndDirectAttackMissileController.h
//! \ingroup vreVrfmodel
//! \brief Controller for modeling FGM-148 Javelin missile flight paths
//!
//! This file defines the DtTopAndDirectAttackMissileController class which models
//! the movement of a Javelin missile along a path to its target. It handles both
//! top-attack and direct-attack flight modes, managing the different phases of
//! flight for each mode.
//!
// The Javelin missile has two modes of flight:  top-attack and direct-attack.
//
// In top-attack mode, the flight has three phases:
// 1. Climb-out - missile flights out at a steep angle.
// 2. Altitude-hold - missile flies toward the target at maximum
//    altitude.
// 3. Terminal - missile flies directly toward a target.  The terminal angle is
//    the angle at which the missile will hit the target (inclination angle
//    from the target to the missile).
// Note that if the target is close enough, the missile may not reach the altitude
// hold phase and proceed directly to terminal phase.
//
// In direct-attack mode, the flight has two phases:
// 1. Climb-out - missile flights out at a steep angle.
// 3. Terminal - missile flies directly toward a target.  The terminal angle is
//    the angle at which the missile will hit the target (inclination angle
//    from the target to the missile).
 
#pragma once
 
 
#include <vreVrfmodel/export.h>
#include <vreVrfmodel/vreSimComponent.h>
#include <vreMessageManager/vreMessageManager.h>
 
#include <vrfmodel/missileMoveToControllerComponent.h>
 
#include <vlutil/vlString.h>
#include <matrix/vlVector.h>
 
class DtString;
class DtSimulationServices;
class DtConstrainedAnalogPort;
class boolPort;
class DtSimMessage;
 
 
//! \brief Controller for missile flight paths with different attack modes
//!
//! Manages missile movement with specialized flight paths based on the selected
//! attack mode (top-attack or direct-attack).
namespace makVre
{
//! \brief Type identifier for the top and direct attack missile controller component
const char DtTopAndDirectAttackMissileControllerType[] = "top-and-direct-attack-missile-controller";
 
class DtTopAndDirectAttackMissileControllerDescriptor;
class DtTopAndDirectMissileFlightPSR;
 
//! \brief Controller for FGM-148 Javelin missile flight paths
//!
//! DtTopAndDirectAttackMissileController models the movement of a Javelin missile
//! along a path to its target, supporting two different attack modes:
//! - Top-attack mode: Missile climbs to maximum altitude, then descends on target
//! - Direct-attack mode: Missile follows a more direct path to the target
//!
//! Each mode has different flight phases, and the controller manages transitions
//! between phases based on altitude, distance to target, and attack angles.
class VREVRFMODEL_DLL DtTopAndDirectAttackMissileController
   : public DtVreSimComponent<DtMissileMoveToControllerComponent>
{
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 top and direct attack missile controller component with the specified parameters.
   DtTopAndDirectAttackMissileController(const DtString& name, DtLocalObject* owner, DtSimulationServices* simManager,
      DtComponentDescriptor* desc = 0, DtReaderWriterRegistry* parentRegistry = 0);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the top and direct attack missile controller component.
   virtual ~DtTopAndDirectAttackMissileController() override;
 
   //! \brief Gets the type identifier for this component
   //! \return String identifying the component type (DtTopAndDirectAttackMissileControllerType)
   //!
   //! Implements the DtSimComponent::type() method to return the
   //! type identifier for this component.
   virtual const char* type() const override;
 
   //! \brief Performs initialization before the first simulation tick
   //!
   //! Gets the missile attack mode (top-attack or direct-attack) from the entity's
   //! extended data and sets it in the process state repository. Also caches the
   //! appropriate flight parameters based on the selected mode.
   virtual void preFirstTickInit() override;
 
   //! \brief Sets the target entity that the missile should fly to
   //! \param entity UUID of the target entity
   //!
   //! Sets the target entity the missile should fly to. The flight path will
   //! depend on the current attack mode (top-attack or direct-attack). The
   //! trajectory is not direct but follows the phases defined for the selected mode.
   virtual void setTargetEntity(const DtUUID& entity) override;
 
   //! \brief Gets the currently set target entity
   //! \return Reference to the current target entity
   //!
   //! Returns a reference to the entity currently set as the missile's target.
   virtual DtSimObjectReference targetEntity() const override;
 
   //! \brief Calculates steering parameters to guide the missile to target
   //! \param relativeVelocity Relative velocity vector between missile and target
   //! \param localPosition Current position of the missile
   //! \param targetVelocity Velocity vector of the target
   //! \param targetPoint Target position vector
   //! \param maneuverAccelXOut Output parameter for X-axis maneuver acceleration
   //! \param maneuverAccelYOut Output parameter for Y-axis maneuver acceleration
   //! \param maneuverAccelZOut Output parameter for Z-axis maneuver acceleration
   //!
   //! Overrides the base class implementation to calculate steering parameters
   //! for guiding the missile along its multi-phase flight path to the target.
   //! Updates the output acceleration parameters to achieve the desired trajectory.
   virtual void calculateSteering(const DtVector& relativeVelocity, const DtVector& localPosition,
      const DtVector& targetVelocity, const DtVector& targetPoint, double& maneuverAccelXOut, double& maneuverAccelYOut,
      double& maneuverAccelZOut) override;
 
   //! \brief Static callback function for target point messages
   //! \param msg The simulation message containing the target point information
   //! \param usr User data pointer (contains the controller instance)
   //!
   //! Static function registered as a callback to handle target point messages.
   //! Instances of this component register this callback with their own 'this'
   //! pointer as user data with the message executive to receive notification
   //! of move-to tasks.
   static void targetPointCallback(DtSimMessage* msg, void* usr);
 
   //! \brief Processes a target point task message
   //! \param msg The simulation message containing the target point task
   //!
   //! Extracts the target entity information from the DtTargetPointTask message
   //! and calls setTargetEntity() with the UUID of the specified target entity.
   virtual void processTargetPointTask(DtSimMessage* msg) 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 Default constructor (protected, not for direct use)
   //!
   //! This constructor is protected and not meant to be called directly.
   //! It exists because the compiler would otherwise generate an unprotected one.
   DtTopAndDirectAttackMissileController();
 
   //! \brief Copy constructor (protected, performs shallow copy)
   //! \param orig The original object to copy from
   //!
   //! Performs a shallow copy operation that does not copy the ports.
   //! This constructor is protected and not meant for general use.
   DtTopAndDirectAttackMissileController(const DtTopAndDirectAttackMissileController& orig);
 
   //! \brief Assignment operator (protected, performs shallow copy)
   //! \param orig The original object to assign from
   //! \return Reference to this object
   //!
   //! Performs a shallow assignment operation similar to the copy constructor.
   //! This operator is protected and not meant for general use.
   const DtTopAndDirectAttackMissileController& operator=(const DtTopAndDirectAttackMissileController& orig);
 
   //! \brief Registers message callbacks for handling task messages
   //!
   //! Registers the callback targetPointCallback() for handling
   //! DtTargetPointTask messages sent to this missile controller.
   virtual void registerTaskMsgCallbacks() override;
 
   //! \brief Sets up the current control point for missile guidance
   //! \return True if a valid control point was established, false otherwise
   //!
   //! Determines the appropriate working target point based on the current
   //! flight phase (climb-out, altitude-hold, or terminal) and then calls
   //! setTargetPoint() to update the missile's guidance system.
   virtual bool setupControlPoint() override;
 
   //! \brief Calculates the endpoint for the climb-out flight phase
   //! \return Vector position for the end of the climb-out phase
   //!
   //! Determines the position that marks the end of the climb-out phase
   //! based on the current missile position, target position, and configured
   //! climb-out angle.
   virtual DtVector calculateClimbOutPoint();
 
   //! \brief Checks if the missile has reached its climb-out altitude
   //! \return True if the missile has reached or exceeded the climb-out altitude
   //!
   //! Compares the missile's current altitude with the configured climb-out
   //! altitude to determine if the missile should transition to the next flight phase.
   virtual bool reachedClimbOutAltitude();
 
   //! \brief Calculates the control point for the altitude-hold flight phase
   //! \return Vector position for the altitude-hold phase
   //!
   //! Returns a position directly above the target at the maximum altitude
   //! configured for the missile. This point is used for guidance during the
   //! altitude-hold phase of top-attack mode.
   virtual DtVector calculateAltitudeHoldPoint();
 
   //! \brief Checks if the missile has reached the terminal angle to target
   //! \return True if the missile has reached or exceeded the terminal angle
   //!
   //! Calculates the inclination angle from the target to the missile and
   //! determines if it has reached the configured terminal angle, indicating
   //! that the missile should transition to the terminal phase of flight.
   virtual bool reachedTerminalAngleToTarget();
 
   //! \brief Calculates the endpoint for the terminal flight phase
   //! \return Vector position for the terminal phase targeting
   //!
   //! Determines the position of the target entity, accounting for any
   //! movement during flight. This is the final aim point for the missile
   //! during the terminal phase of flight.
   virtual DtVector calculateTerminalPoint();
 
   //! Moves the missile's target waypoint based on the VRE message.
   //! Waypoint will have its position updated or be attached to a target entity.
   //! Processes UpdateMissileTargetMessage events.
   //! This message can either set the target to a new location or an entity.
   virtual makVre::DtVreMessageResult handleUpdateMissileTarget(makVre::DtVreMessage* msg);
 
protected:
   //! \brief Retrieves and caches the missile flight process state repository
   //!
   //! Looks up the missile flight process state repository and caches it for
   //! efficient access during simulation updates. The PSR contains the state
   //! information for the missile's flight phases and attack mode.
   virtual void lookupAndCacheProcessSR() override;
 
   //! This callback is necessary to make sure the handleUpdateMissileTarget callback
   //! is registered in the main thread. It needs to be registered in that thread because
   //! the sim's component worker threads don't tick the DtVreMessageManager.
   static void objectAddedCallback(const DtLocalObject* simObject, void* usr);
   virtual void processObjectAdded(const DtLocalObject* simObject);
 
protected:
   //! \brief Reference to the current target entity
   //!
   //! Reference to the current target entity that the missile is tracking.
   //! This is updated each frame by the setupControlPoint() method.
   DtSimObjectReference myTargetPointer;
 
   //! \brief Flag to prevent repeated warning messages
   //!
   //! When true, prevents the component from repeatedly sending
   //! 'failed to find target' warnings to the log. Ensures that
   //! warning messages are only sent once per missile instance.
   bool myLookupWarningSent;
 
   //! \brief Cached pointer to the missile flight process state repository
   //!
   //! Cached pointer to the derived type of process state repository used
   //! to store missile flight state information. This avoids repeated lookups
   //! and type casting during the missile's flight.
   DtTopAndDirectMissileFlightPSR* myVreMissileFlightPSR;
 
   //! \brief Cached pointer to the component descriptor
   //!
   //! Cached pointer to the derived type of component descriptor that contains
   //! configuration parameters specific to this missile controller. This allows
   //! efficient access to configuration settings without repeated type casting.
   DtTopAndDirectAttackMissileControllerDescriptor* myTopAndDirectAttackMissileControllerDescriptor;
 
   //! \brief Cached climb-out angle for the current attack mode
   //!
   //! The angle used during the climb-out phase of flight. This value is set
   //! in preFirstTickInit() based on the attack mode and remains constant
   //! for the lifetime of the missile.
   double myClimbOutAngle;
 
   //! \brief Cached terminal angle for the current attack mode
   //!
   //! The angle used to determine transition to the terminal phase of flight.
   //! This value is set in preFirstTickInit() based on the attack mode and
   //! remains constant for the lifetime of the missile.
   double myTerminalAngle;
 
   //! \brief Cached maximum altitude for the current attack mode
   //!
   //! The maximum altitude the missile should reach during flight. This value
   //! is set in preFirstTickInit() based on the attack mode and remains
   //! constant for the lifetime of the missile.
   double myMaxAltitude;
 
   bool myCallbackAdded;
};
} // namespace makVre