vreChatCommandsManager.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file vreChatCommandsManager.h
//! \brief Defines the chat command system for VR-Engage
//!
//! This file contains the DtChatCommand and DtChatCommandsManager classes
//! which provide the infrastructure for processing text commands entered
//! in the chat window. These commands allow users to execute various
//! actions through a simple command-line interface within the application.
 
#pragma once
 
#include "vrePlayerStation/export.h"
 
namespace makVre
{
//! \brief Forward declaration of the player station application class
class DtPlayerStationApp;
 
//! \brief Abstract base class for chat commands in VR-Engage
//!
//! DtChatCommand defines the interface for all executable chat commands
//! in the application. Derived classes implement specific command functionality
//! through the execute method. Commands can be entered in the chat window
//! with a leading slash followed by the command name and any parameters.
class PLAYERSTATION_DLL DtChatCommand : public std::enable_shared_from_this<DtChatCommand>
{
public:
   //! \brief Virtual destructor
   //!
   //! Default destructor for proper cleanup of derived command classes.
   ~DtChatCommand() = default;
 
   //! \brief Executes the command with given parameters
   //! \param parameters String containing parameters passed to the command
   //! \return True if the command executed successfully, false otherwise
   //!
   //! Pure virtual method that must be implemented by derived classes to
   //! provide the actual command functionality. The parameters string
   //! contains everything after the command name.
   virtual bool execute(const std::string& parameters) = 0;
 
   //! \brief Gets a weak pointer to this command
   //! \return Weak pointer to this command instance
   //!
   //! Returns a weak_ptr to this command instance, which helps
   //! prevent circular references while allowing access to the command.
   virtual std::weak_ptr<DtChatCommand> getWeak() { return shared_from_this(); }
 
   //! \brief Gets help text for the command
   //! \param parameters Optional parameters to customize help output
   //! \return String containing help text for the command
   //!
   //! Returns documentation about how to use the command. The default
   //! implementation simply returns the parameters string, but derived
   //! classes should override this to provide meaningful help text.
   virtual std::string help(const std::string& parameters) { return parameters; };
 
   //! \brief Checks if this command should be visible in help listings
   //! \return True if the command should appear in help, false otherwise
   //!
   //! Determines whether this command should be included in the list of
   //! available commands when users request help. The default implementation
   //! returns false, meaning the command is hidden unless overridden.
   virtual bool showInHelp() const { return false; };
 
   //! \brief Utility function to split a string into tokens
   //! \param stringToSplit String to be split
   //! \param tokenized Vector to store the resulting tokens
   //! \param delimiter Character to use as the splitting delimiter
   //! \return True if the string was successfully split, false otherwise
   //!
   //! Splits a string into tokens based on the specified delimiter.
   //! This is useful for parsing command parameters into individual arguments.
   static bool splitString(
      const std::string& stringToSplit, std::vector<std::string>& tokenized, const char delimiter = ' ');
};
 
//! \brief Manager class for chat commands in VR-Engage
//!
//! DtChatCommandsManager provides a centralized registry of available
//! chat commands. It handles command registration, execution, and help
//! text generation. When a user enters a command in the chat window,
//! this manager locates and executes the appropriate command handler.
class PLAYERSTATION_DLL DtChatCommandsManager
{
public:
   //! \brief Constructor
   //! \param app Reference to the player station application
   //!
   //! Creates a new chat commands manager associated with the given application.
   //! The manager starts with no registered commands.
   DtChatCommandsManager(DtPlayerStationApp& app);
 
   //! \brief Destructor
   //!
   //! Cleans up resources, including any owned command objects.
   ~DtChatCommandsManager();
 
   //! \brief Deleted copy constructor and assignment operator
   //! @{
   //! These operations are not supported for the command manager.
   DtChatCommandsManager(const DtChatCommandsManager& orig) = delete;
   DtChatCommandsManager& operator=(const DtChatCommandsManager& orig) = delete;
   //! @}
 
   //! \brief Registers a new chat command
   //! \param commandString String that triggers this command (without the leading slash)
   //! \param command Shared pointer to the command implementation
   //! \param takeOwnership If true, the manager takes ownership of the command object
   //! \return True if the command was successfully added, false otherwise
   //!
   //! Adds a new command to the registry. If takeOwnership is true, the manager
   //! will maintain a strong reference to the command and handle its lifetime.
   //! If false, the manager only keeps a weak reference, and the caller must
   //! ensure the command object remains valid for as long as it's registered.
   virtual bool addCommand(
      std::string commandString, std::shared_ptr<DtChatCommand> command, bool takeOwnership = false);
 
   //! \brief Unregisters a chat command
   //! \param commandString String that triggers the command to remove
   //!
   //! Removes a command from the registry. The command string is case-insensitive,
   //! so commands with the same spelling but different capitalization will be
   //! treated as identical. If the manager owned the command, it will be released.
   virtual void removeCommand(std::string commandString);
 
   //! \brief Executes a command from a console input string
   //! \param consoleString Full string entered in the chat/console
   //! \return True if a valid command was found and executed, false otherwise
   //!
   //! Parses the input string to extract the command and its parameters,
   //! then executes the command if found. Commands are case-insensitive.
   //! The expected format is "/command parameters", where the leading
   //! slash identifies it as a command rather than normal chat text.
   virtual bool runCommand(std::string consoleString);
 
   //! \brief Generates help text for available commands
   //! \param parameters Optional parameters to filter or customize help output
   //! \return String containing help text for all visible commands
   //!
   //! Creates a formatted string containing help information for all
   //! registered commands that have showInHelp() returning true.
   //! This is typically shown when the user enters "/help" in the chat.
   virtual std::string helpText(const std::string& parameters) const;
 
protected:
   //! \brief Map of command strings to weak pointers to commands
   //!
   //! Contains all registered commands that are not owned by the manager.
   //! The weak pointers prevent circular references but require external
   //! lifetime management for the command objects.
   std::unordered_map<std::string, std::weak_ptr<DtChatCommand>> myCommandMap;
 
   //! \brief Map of command strings to shared pointers to commands
   //!
   //! Contains all registered commands that are owned by the manager.
   //! The shared pointers ensure the command objects remain valid as
   //! long as they are registered.
   std::unordered_map<std::string, std::shared_ptr<DtChatCommand>> myOwnedCommandMap;
 
   //! \brief Reference to the player station application
   //!
   //! Provides access to application services and state needed by commands.
   DtPlayerStationApp& myApp;
};
 
} // namespace makVre