playerCreationPalette.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
#pragma once
 
//! \file playerCreationPalette.h
//! \brief Defines the DtPlayerCreationPalette class for managing available entity roles
//!
//! This file contains the DtPlayerCreationPalette class, which manages information about
//! all available roles and entities that users can engage with in VR-Engage. It serves
//! as a catalog of the playable options and provides methods for finding and accessing
//! role definitions and configuration data.
//!
//! The class maintains its own DtInitializer for accessing Lua role files, as the
//! initializer is not thread-safe and must be accessed from multiple threads.
 
#include "vrePlayerStation/export.h"
 
#include "vreUtil/roleTemplateUtilities.h"
 
#include "vreUtil/initializer.h"
 
#include <vlpi/entityType.h>
#include <vlpi/disEnums.h>
 
#include <string>
#include <vector>
#include <set>
 
#include <tbb/mutex.h>
#include <tbb/task_arena.h>
#include <memory>
 
namespace makVre
{
//! \brief Forward declaration of the initialization table class
class DtInitTable;
 
//! \brief Forward declaration of the player station application class
class DtPlayerStationApp;
 
//! \brief Forward declaration of the SMS load complete message class
class SmsLoadCompleteMessage;
 
class DtVreModelSetEntry;
 
//! \brief Class for managing available entities and roles for engagement
//!
//! DtPlayerCreationPalette serves as a catalog of all entities and roles that
//! can be played in VR-Engage. It loads entity definitions from simulation model
//! sets (SMS) files and provides methods for accessing role configurations, display
//! layouts, and other metadata necessary for creating player stations.
//!
//! This class maintains its own thread-safe access to role definition files and
//! provides asynchronous loading capabilities for better performance.
class PLAYERSTATION_DLL DtPlayerCreationPalette
{
public:
   //! \brief Structure containing information about an entity in the palette
   //!
   //! DtPaletteEntry stores all metadata about a specific entity type that can
   //! be engaged with in VR-Engage, including its roles, categories, and origin.
   struct DtPaletteEntry
   {
      std::string myLabel;                   //!< Display name for the entity
      std::vector<DtForceType> myForceTypes; //!< Force types this entity belongs to
      std::vector<DtString> myCategories;    //!< Categories this entity belongs to
      std::vector<DtString> myCountries;     //!< Countries this entity is associated with
      DtEntityRoleMap myRoles;               //!< Map of roles available for this entity
      std::string myFilename;                //!< Source filename (for hot-reloading)
   };
 
   //! \brief Type definition for a map of entity types to palette entries
   using DtEntityMap = std::map<DtEntityType, std::shared_ptr<DtPaletteEntry>>;
 
   //! \brief Type definition for an iterator over the entity map
   using DtIterator = DtEntityMap::iterator;
 
public:
   //! \brief Constructor
   //! \param app Pointer to the player station application
   //!
   //! Creates a new palette instance associated with the application.
   //! Initializes the palette but does not load entity data automatically.
   DtPlayerCreationPalette(DtPlayerStationApp* app);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources, including the initializer and any loaded entity data.
   virtual ~DtPlayerCreationPalette();
 
   //! \brief Updates the palette state
   //!
   //! Called once per frame to update the palette, handling any asynchronous
   //! loading operations and processing completed loads.
   virtual void tick();
 
   //! \brief Sets the list of simulation model sets (SMS) to load
   //! \param smsList Vector of SMS filenames to load
   //!
   //! Updates the list of simulation model sets from which to load entity
   //! definitions. This will trigger an asynchronous reload of the palette.
   virtual void setSmsList(const std::vector<DtFilename>& smsList);
 
   //! \brief Gets an iterator to the beginning of the entity map
   //! \return Iterator positioned at the start of the entity map
   //!
   //! Returns an iterator for traversing all entities in the palette.
   virtual DtIterator getIterator();
 
   //! \brief Advances to the next entity in the palette
   //! \param iter Iterator to advance
   //! \param nextType Optional pointer to receive the next entity type
   //! \param nextEntry Optional pointer to receive the next palette entry
   //! \return True if advanced successfully, false if reached the end
   //!
   //! Advances the iterator to the next entity and optionally retrieves the
   //! type and entry information for that entity.
   virtual bool getNext(
      DtIterator& iter, DtEntityType* nextType = NULL, std::shared_ptr<DtPaletteEntry>* nextEntry = NULL);
 
   //! \brief Finds an entity by its type
   //! \param type Entity type to search for
   //! \return Shared pointer to the palette entry, or null if not found
   //!
   //! Looks up an entity in the palette by its entity type identifier.
   std::shared_ptr<DtPaletteEntry> findEntry(const DtEntityType& type);
 
   //! \brief Checks if an entity type, role, and display layout combination is valid
   //! \param type Entity type to check
   //! \param role Optional role name to check (empty to check only entity type)
   //! \param display Optional display layout to check (empty to check only entity and role)
   //! \return True if the combination is valid, false otherwise
   //!
   //! Verifies whether a specific entity type exists in the palette and optionally
   //! whether it supports the specified role and display layout.
   virtual bool isValid(const DtEntityType& type, const std::string& role = "", const std::string& display = "");
 
   //! \brief Gets the list of available roles for an entity type
   //! \param type Entity type to get roles for
   //! \return Vector of role names available for the entity
   //!
   //! Returns a list of all roles that can be played for the specified entity type.
   virtual const std::vector<std::string> getRoleList(const DtEntityType& type);
 
   //! \brief Finds a role that corresponds to a slot name
   //! \param type Entity type to search in
   //! \param slotName Name of the slot to find the role for
   //! \return Role name that corresponds to the slot, or empty string if not found
   //!
   //! Maps from a slot name (used in embarkation) to the corresponding role name.
   virtual std::string findRoleForSlot(const DtEntityType& type, const std::string& slotName);
 
   //! \brief Finds a slot that corresponds to a role name
   //! \param type Entity type to search in
   //! \param roleName Name of the role to find the slot for
   //! \return Slot name that corresponds to the role, or empty string if not found
   //!
   //! Maps from a role name to the corresponding slot name (used in embarkation).
   virtual std::string findSlotForRole(const DtEntityType& type, const std::string& roleName);
 
   //! \brief Gets the descriptor for a specific role
   //! \param type Entity type to look up
   //! \param role Role name to get the descriptor for
   //! \return Shared pointer to the role descriptor, or null if not found
   //!
   //! Returns detailed information about a specific role, including file paths,
   //! display layouts, and other configuration metadata.
   virtual std::shared_ptr<DtEntityRoleDescriptor> getRoleDescriptor(const DtEntityType& type, const std::string& role);
 
   //! \brief Gets the base template for a role
   //! \param type Entity type to look up
   //! \param role Role name to get the template for
   //! \return Initialization table containing the role template
   //!
   //! Returns the base template configuration for a role before any display-specific
   //! settings are applied.
   virtual DtInitTable getRoleTemplate(const DtEntityType& type, const std::string& role);
 
   //! \brief Gets the complete configuration for a player station
   //! \param type Entity type to configure
   //! \param role Role name to configure
   //! \param display Display layout to use
   //! \return Initialization table with the complete player configuration
   //!
   //! Returns the complete configuration for a player station, combining the
   //! role template with display-specific settings and other overrides.
   virtual DtInitTable getPlayerConfiguration(
      const DtEntityType& type, const std::string& role, const std::string& display);
 
   //! \brief Gets all categories in the palette
   //! \return Reference to the set of all categories
   //!
   //! Returns a set of all unique categories across all entities in the palette.
   //! Categories are used for filtering and organizing entities in the UI.
   virtual const std::set<std::string>& categories() const { return myAllCategories; }
 
   //! \brief Gets all countries in the palette
   //! \return Reference to the set of all countries
   //!
   //! Returns a set of all unique countries across all entities in the palette.
   //! Countries are used for filtering and organizing entities in the UI.
   virtual const std::set<std::string>& countries() const { return myAllCountries; }
 
   //! \brief Reloads the role configuration for an entity type
   //! \param entityType Entity type to reload
   //!
   //! Reloads the role configuration data found in the .entity file for a specific
   //! entity type. This is used for hot-reloading when entity files are modified.
   virtual void reloadRoleConfig(const DtEntityType& entityType);
 
   //! \brief Gets the current list of simulation model sets
   //! \return Reference to the vector of SMS filenames
   //!
   //! Returns the list of simulation model set (SMS) files that are currently
   //! being used to populate the palette.
   virtual const std::vector<DtFilename>& getSMSList() const;
 
   //! \brief Finds a file in the SMS directories
   //! \param file Name of the file to find
   //! \return Full path to the file, or empty if not found
   //!
   //! Searches for a file in all SMS directories and returns its full path.
   //! This is used to locate role definition files, entity files, and other resources.
   virtual DtFilename findFile(const std::string& file);
 
   //! \brief Gets the palette's initializer
   //! \return Pointer to the initializer
   //!
   //! Returns a pointer to the DtInitializer owned by this class, which is used for
   //! interfacing with Lua role definitions. This initializer can be accessed from
   //! both the player creation palette and the choose role panel.
   virtual DtInitializer* initializer();
 
protected:
   //! \brief Initiates asynchronous building of the palette from SMS files
   //!
   //! Starts an asynchronous task to rebuild the palette from the current
   //! set of SMS files. This is used to avoid blocking the main thread during
   //! palette loading.
   virtual void buildFromSMSAsync();
 
   //! \brief Builds the palette from SMS files
   //! \param app Pointer to the player station application
   //! \param smsList List of SMS files to load from
   //! \return True if building was successful, false otherwise
   //!
   //! Loads all entity definitions from the specified SMS files and
   //! populates the palette with the resulting entities and roles.
   virtual bool buildFromSMS(DtPlayerStationApp*, const std::vector<DtFilename>& smsList);
 
   //! \brief Lua callback to get data paths for SMS
   //! \param L Lua state pointer
   //! \return Number of return values on the Lua stack
   //!
   //! Callback function for Lua to retrieve the SMS data paths.
   static int getDataPathsForSms(lua_State* L);
 
   //! \brief Sets the data paths for SMS
   //! \param paths Vector of path strings to set
   //!
   //! Sets the list of data paths used for locating SMS resources.
   void setDataPathsForSms(std::vector<std::string> paths);
 
   //! \brief Adds a data path for SMS
   //! \param path Path string to add
   //!
   //! Appends a new data path to the list of SMS resource locations.
   void appendDataPathsForSms(std::string path);
 
   //! \brief Removes all SMS data paths
   //!
   //! Clears the list of data paths used for locating SMS resources.
   void clearDataPathsForSms();
 
   //! \brief Gets the list of SMS files to search
   //! \param smsList Vector to populate with SMS file names
   //!
   //! Populates the provided vector with the list of SMS files to search when
   //! loading an entity file. Returns the contents of mySmsList if specified,
   //! or the app's default SMS list otherwise.
   virtual void getSMSList(std::vector<DtString>& smsList) const;
 
   //! \brief Gets the search paths for model set entries
   //! \param searchPaths Vector to populate with search paths
   //!
   //! Populates the provided vector with the list of SMS paths (including inherited ones)
   //! to search when loading a model set entry.
   virtual void getSMSSearchPaths(std::vector<DtFilename>& searchPaths) const;
 
   //! \brief Loads a model set entry
   //! \param filename Name of the file to load
   //! \return Shared pointer to the loaded model set entry
   //!
   //! Loads and parses a model set entry from the specified filename.
   virtual std::shared_ptr<makVre::DtVreModelSetEntry> loadModelSetEntry(const std::string& filename);
 
   //! \brief Finds a role in a palette entry by name
   //! \param entry Palette entry to search in
   //! \param role Name of the role to find
   //! \return Shared pointer to the role descriptor, or null if not found
   //!
   //! Searches for a specific role within a palette entry by name.
   std::shared_ptr<DtEntityRoleDescriptor> findRole(const DtPaletteEntry& entry, const std::string& role);
 
   //! \brief Finds any role in a palette entry
   //! \param entry Palette entry to search in
   //! \return Shared pointer to the first role descriptor, or null if none exist
   //!
   //! Returns the first available role within a palette entry.
   std::shared_ptr<DtEntityRoleDescriptor> findRole(const DtPaletteEntry& entry);
 
protected:
   //! \brief Static instance of SMS role search paths (for Lua access)
   static std::vector<std::string> theSmsRoleSearchPaths;
 
   //! \brief Map of entity types to palette entries
   DtEntityMap myCreationPaletteMap;
 
   //! \brief Default palette entry (used when a specific entry is not found)
   std::shared_ptr<DtPaletteEntry> myDefaultPaletteEntry;
 
   //! \brief Set of all unique categories across all entities
   std::set<std::string> myAllCategories;
 
   //! \brief Set of all unique countries across all entities
   std::set<std::string> myAllCountries;
 
   //! \brief Pointer to the player station application
   DtPlayerStationApp* myApp;
 
   //! \brief Initializer for Lua role definitions
   DtInitializer* myInitializer;
 
   //! \brief Current list of SMS files to load from
   std::vector<DtFilename> mySmsList;
 
   //! \brief Incoming list of SMS files for the next rebuild
   std::vector<DtFilename> myIncomingSmsList;
 
   //! \brief Mutex for synchronizing build operations
   tbb::mutex myBuildMutex;
 
   //! \brief Flag indicating whether an asynchronous build is in progress
   bool myAsyncBuilding;
 
   //! \brief Message to send when SMS loading completes
   std::unique_ptr<SmsLoadCompleteMessage> mySmsLoadCompleteMessage;
 
   //! \brief Task arena for asynchronous operations
   tbb::task_arena myArena;
};
} // namespace makVre