scriptComponent.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*****************************************************************************/
 
//! \file scriptComponent.h
//! \brief Component for integrating Lua scripts into the player component system
//! \ingroup vreCommonComponents
 
#pragma once
 
#include "vreCommonComponents/export.h"
 
#include "vrePlayerStation/playerComponent.h"
 
#include <string>
 
namespace makVre
{
class DtLuaState;
 
namespace ScriptComponentConfig
{
//! \ingroup RoleConfigParams
//! \defgroup ScriptComponentRoleParams Script Component Role Parameters
//! \roleInherits{PlayerComponentRoleParams}
//! Configuration Options for script component role.
//! @{
 
//! \vreRoleParamRequired{script,string,scriptComponent,"scripts/myScript.lua",Path to the Lua script file to load and execute.}
constexpr const char* script = "script";
 
//! \vreRoleParam{scriptConfig,table,"",scriptComponent,Configuration table to pass to the script's initialize function.}
constexpr const char* scriptConfig = "scriptConfig";
 
//! @}
} // namespace ScriptComponentConfig
 
//! \brief Type identifier for DtScriptComponent component
constexpr const char* DtScriptComponentType = "DtScriptComponent";
 
//! \brief Component for executing Lua scripts as part of a player role
//!
//! DtScriptComponent loads and executes Lua scripts within the player component
//! lifecycle, allowing custom behavior implementation through scripts rather than
//! C++ code. Scripts have access to the player attribute store and can implement
//! initialize, postInitialize, tick, and shutdown callbacks that align with the
//! component lifecycle methods.
//!
//! \note Based on implementation examination, this component may be deprecated
//!       or temporarily disabled in the current codebase.
class VRECOMMONCOMPONENTS_DLL DtScriptComponent : public makVre::DtPlayerComponent
{
public:
   //! \brief Constructor for DtScriptComponent
   //!
   //! Initializes the component with the name "DtScriptedUpdater"
   DtScriptComponent();
 
   //! \brief Virtual destructor for DtScriptComponent
   virtual ~DtScriptComponent() override;
 
   //! \brief Initializes the script component
   //! \param player Pointer to the player station this component belongs to
   //! \param config Configuration table containing script settings
   //! \return True if initialization succeeded, false otherwise
   //!
   //! Loads the script file specified in the config and initializes the Lua VM.
   //! Serializes any scriptConfig table for passing to the script's initialize function.
   virtual bool initialize(makVre::DtPlayerStation* player, makVre::DtInitTable& config) override;
   //! \brief Performs post-initialization after all components are initialized
   //! \return True if post-initialization succeeded, false otherwise
   //!
   //! Calls the script's postInitialize function if it exists
   virtual bool postInitialize() override;
   //! \brief Called every frame to update the script state
   //! \param dt Delta time since the last frame in seconds
   //!
   //! Calls the script's tick function, passing the delta time
   virtual void tick(double dt) override;
   //! \brief Shuts down the script component
   //!
   //! Calls the script's shutdown function if it exists and cleans up the Lua VM
   virtual void shutdown() override;
 
   //! \brief Returns the type identifier for this component
   //! \return The type string for DtScriptComponent
   virtual const char* type() const override;
 
   //! \brief Reloads the script file
   //!
   //! Reinitializes the Lua VM and reloads the script file
   virtual void reload();
 
protected:
   //! \brief Sets up the Lua virtual machine
   //! \return True if VM setup succeeded, false otherwise
   //!
   //! Creates a new Lua VM, loads serialization library, installs VR bindings,
   //! loads the script file, and calls the script's initialize function
   virtual bool setupVm();
 
   //! \brief Shuts down and cleans up the Lua virtual machine
   virtual void shutdownVm();
 
   //! \brief Path to the Lua script file to execute
   std::string myScriptFilename;
 
   //! \brief Serialized configuration table to pass to the script
   std::string myScriptConfig;
 
   //! \brief Pointer to the Lua virtual machine instance
   DtLuaState* myVm;
};
} // namespace makVre