Cuberite
A lightweight, fast and extensible game server for Minecraft
Classes | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Static Protected Member Functions | Protected Attributes | List of all members
cLuaState Class Reference

Encapsulates a Lua state and provides some syntactic sugar for common operations. More...

#include <LuaState.h>

Collaboration diagram for cLuaState:
Collaboration graph
[legend]

Classes

class  cCallback
 Represents a stored callback to Lua that C++ code can call. More...
 
class  cLock
 Provides a RAII-style locking for the LuaState. More...
 
class  cNil
 A dummy class that's used only to push a constant nil as a function parameter in Call(). More...
 
class  cOptionalCallback
 Same thing as cCallback, but GetStackValue() won't fail if the callback value is nil. More...
 
class  cOptionalParam
 Represents a parameter that is optional - calling a GetStackValue() with this object will not fail if the value on the Lua stack is nil. More...
 
class  cRef
 Used for storing references to object in the global registry. More...
 
class  cRet
 A dummy class that's used only to delimit function args from return values for cLuaState::Call() More...
 
class  cStackBalanceCheck
 Asserts that the Lua stack has the same amount of entries when this object is destructed, as when it was constructed. More...
 
class  cStackBalancePopper
 Makes sure that the Lua state's stack has the same number of elements on destruction as it had on construction of this object (RAII). More...
 
class  cStackTable
 Represents a table on the Lua stack. More...
 
class  cStackValue
 A RAII class for values pushed onto the Lua stack. More...
 
class  cTableRef
 Represents a stored Lua table with callback functions that C++ code can call. More...
 
class  cTrackedRef
 Represents a reference to a Lua object that has a tracked lifetime -. More...
 

Public Types

typedef std::unique_ptr< cCallbackcCallbackPtr
 
typedef std::shared_ptr< cCallbackcCallbackSharedPtr
 
typedef std::unique_ptr< cOptionalCallbackcOptionalCallbackPtr
 
typedef std::unique_ptr< cStackTablecStackTablePtr
 
typedef std::unique_ptr< cTableRefcTableRefPtr
 
typedef std::unique_ptr< cTrackedRefcTrackedRefPtr
 
typedef std::shared_ptr< cTrackedRefcTrackedRefSharedPtr
 

Public Member Functions

void AddPackagePath (const AString &a_PathVariable, const AString &a_Path)
 Adds the specified path to package. More...
 
int ApiParamError (std::string_view a_Msg)
 Prints the message, prefixed with the current function name, then logs the stack contents and raises a Lua error. More...
 
void Attach (lua_State *a_State)
 Attaches the specified state. More...
 
template<typename FnT , typename... Args>
bool Call (const FnT &a_Function, Args &&... args)
 Call the specified Lua function. More...
 
int CallFunctionWithForeignParams (const AString &a_FunctionName, cLuaState &a_SrcLuaState, int a_SrcParamStart, int a_SrcParamEnd)
 Calls the function specified by its name, with arguments copied off the foreign state. More...
 
bool CheckParamBool (int a_StartParam, int a_EndParam=-1)
 Returns true if the specified parameters on the stack are bools; also logs warning if not. More...
 
bool CheckParamEnd (int a_Param)
 Returns true if the specified parameter on the stack is nil (indicating an end-of-parameters) More...
 
bool CheckParamFunction (int a_StartParam, int a_EndParam=-1)
 Returns true if the specified parameters on the stack are functions; also logs warning if not. More...
 
bool CheckParamFunctionOrNil (int a_StartParam, int a_EndParam=-1)
 Returns true if the specified parameters on the stack are functions or nils; also logs warning if not. More...
 
bool CheckParamNumber (int a_StartParam, int a_EndParam=-1)
 Returns true if the specified parameters on the stack are numbers; also logs warning if not. More...
 
bool CheckParamSelf (const char *a_SelfClassName)
 Returns true if the first parameter is an instance of the expected class name. More...
 
bool CheckParamStaticSelf (const char *a_SelfClassName)
 Returns true if the first parameter is the expected class (static). More...
 
bool CheckParamString (int a_StartParam, int a_EndParam=-1)
 Returns true if the specified parameters on the stack are strings; also logs warning if not. More...
 
bool CheckParamTable (int a_StartParam, int a_EndParam=-1)
 Returns true if the specified parameters on the stack are tables; also logs warning if not. More...
 
bool CheckParamUserTable (int a_StartParam, const char *a_UserTable, int a_EndParam=-1)
 Returns true if the specified parameters on the stack are of the specified usertable type; also logs warning if not. More...
 
bool CheckParamUserType (int a_StartParam, const char *a_UserType, int a_EndParam=-1)
 Returns true if the specified parameters on the stack are of the specified usertype; also logs warning if not. More...
 
bool CheckParamUUID (int a_StartParam, int a_EndParam=-1)
 Returns true if the specified parameters on the stack are UUIDs; also logs warning if not Accepts either cUUID instances or strings that contain UUIDs. More...
 
bool CheckParamVector3 (int a_StartParam, int a_EndParam=-1)
 Returns true if the specified parameters on the stack are Vector3s; also logs warning if not. More...
 
void Close (void)
 Closes the m_LuaState, if not closed already. More...
 
 cLuaState (const AString &a_SubsystemName)
 Creates a new instance. More...
 
 cLuaState (lua_State *a_AttachState)
 Creates a new instance. More...
 
bool CopySingleValueFrom (cLuaState &a_SrcLuaState, int a_StackIdx, int a_NumAllowedNestingLevels)
 Copies a single value from the specified stack index of the source Lua state to the top of this Lua state's stack. More...
 
int CopyStackFrom (cLuaState &a_SrcLuaState, int a_SrcStart, int a_SrcEnd, int a_NumAllowedNestingLevels=16)
 Copies objects on the stack from the specified state. More...
 
bool CopyTableFrom (cLuaState &a_SrcLuaState, int a_TableIdx, int a_NumAllowedNestingLevels)
 Copies a table at the specified stack index of the source Lua state to the top of this Lua state's stack. More...
 
void Create (void)
 Creates the m_LuaState, if not created already. More...
 
void Detach (void)
 Detaches a previously attached state. More...
 
template<typename T >
bool GetNamedGlobal (const AString &a_Name, T &a_Value)
 Retrieves the named global value. More...
 
template<typename T >
bool GetNamedValue (const AString &a_Name, T &a_Value)
 Retrieves the named value in the table at the top of the Lua stack. More...
 
bool GetStackValue (int a_StackPos, AString &a_Value)
 
bool GetStackValue (int a_StackPos, AStringMap &a_Value)
 
bool GetStackValue (int a_StackPos, AStringVector &a_Value)
 
bool GetStackValue (int a_StackPos, bool &a_Value)
 
bool GetStackValue (int a_StackPos, cCallback &a_Callback)
 
bool GetStackValue (int a_StackPos, cCallbackPtr &a_Callback)
 
bool GetStackValue (int a_StackPos, cCallbackSharedPtr &a_Callback)
 
bool GetStackValue (int a_StackPos, ContiguousByteBuffer &a_Data)
 
bool GetStackValue (int a_StackPos, cOptionalCallback &a_Callback)
 
bool GetStackValue (int a_StackPos, cOptionalCallbackPtr &a_Callback)
 
template<typename T >
bool GetStackValue (int a_StackPos, cOptionalParam< T > &&a_ReturnedVal)
 Retrieves an optional value on the stack - doesn't fail if the stack contains nil instead of the value. More...
 
bool GetStackValue (int a_StackPos, cPluginManager::CommandResult &a_Result)
 
bool GetStackValue (int a_StackPos, cRef &a_Ref)
 
bool GetStackValue (int a_StackPos, cStackTablePtr &a_StackTable)
 
bool GetStackValue (int a_StackPos, cTableRef &a_TableRef)
 
bool GetStackValue (int a_StackPos, cTableRefPtr &a_TableRef)
 
bool GetStackValue (int a_StackPos, cTrackedRef &a_Ref)
 
bool GetStackValue (int a_StackPos, cTrackedRefPtr &a_Ref)
 
bool GetStackValue (int a_StackPos, cTrackedRefSharedPtr &a_Ref)
 
bool GetStackValue (int a_StackPos, CustomStatistic &a_Value)
 
bool GetStackValue (int a_StackPos, cUUID &a_Value)
 
bool GetStackValue (int a_StackPos, double &a_Value)
 
bool GetStackValue (int a_StackPos, eBlockFace &a_Value)
 
bool GetStackValue (int a_StackPos, eWeather &a_Value)
 
bool GetStackValue (int a_StackPos, float &a_ReturnedVal)
 
bool GetStackValue (int a_StackPos, std::string_view &a_Value)
 
template<class T , typename = std::enable_if_t<std::is_integral_v<T>>>
bool GetStackValue (int a_StackPos, T &a_ReturnedVal)
 
template<typename T >
bool GetStackValue (int a_StackPos, Vector3< T > &a_ReturnedVal)
 Retrieves any Vector3 value and coerces it into a Vector3<T>. More...
 
template<typename Arg1 , typename... Args>
bool GetStackValues (int a_StartStackPos, Arg1 &&a_Arg1, Args &&... args)
 Retrieves a list of values from the Lua stack, starting at the specified index. More...
 
AString GetSubsystemName (void) const
 Returns the name of the subsystem, as specified when the instance was created. More...
 
AString GetTypeText (int a_StackPos)
 Returns the type of the item on the specified position in the stack. More...
 
bool HasFunction (const char *a_FunctionName)
 Returns true if a_FunctionName is a valid Lua function that can be called. More...
 
bool IsParamNumber (int a_ParamIdx)
 Returns true if the specified parameter is a number. More...
 
bool IsParamUserType (int a_ParamIdx, const AString &a_UserType)
 Returns true if the specified parameter is of the specified class. More...
 
bool IsParamVector3 (int a_ParamIdx)
 Returns true if the specified parameter is any of the Vector3 types. More...
 
bool IsValid (void) const
 Returns true if the m_LuaState is valid. More...
 
bool LoadFile (const AString &a_FileName, bool a_LogWarnings=true)
 Loads the specified file Returns false and optionally logs a warning to the console if not successful (but the LuaState is kept open). More...
 
bool LoadString (const AString &a_StringToLoad, const AString &a_FileName, bool a_LogWarnings=true)
 Loads the specified string. More...
 
void LogApiCallParamFailure (const char *a_FnName, const char *a_ParamNames)
 Outputs to log a warning about API call being unable to read its parameters from the stack, logs the stack trace and stack values. More...
 
void LogStackTrace (int a_StartingDepth=0)
 Logs all items in the current stack trace to the server console. More...
 
void LogStackValues (const char *a_Header=nullptr)
 Logs all the elements' types on the API stack, with an optional header for the listing. More...
 
 operator lua_State * (void)
 Allows this object to be used in the same way as a lua_State *, for example in the LuaLib functions. More...
 
void Pop (int a_NumValuesToPop=1)
 Pops the specified number of values off the top of the Lua stack. More...
 
template<typename Arg1 , typename Arg2 , typename... Args>
void Push (Arg1 &&a_Arg1, Arg2 &&a_Arg2, Args &&... a_Args)
 Pushes multiple arguments onto the Lua stack. More...
 
void Push (bool a_Value)
 
void Push (cEntity *a_Entity)
 
void Push (cLuaServerHandle *a_ServerHandle)
 
void Push (cLuaTCPLink *a_TCPLink)
 
void Push (cLuaUDPEndpoint *a_UDPEndpoint)
 
void Push (const AString &a_String)
 
void Push (const AStringMap &a_Dictionary)
 
void Push (const AStringVector &a_Vector)
 
void Push (const cEntity *a_Entity)
 
void Push (const char *a_Value)
 
void Push (const cItem &a_Item)
 
void Push (const cNil &a_Nil)
 
void Push (const cRef &a_Ref)
 
void Push (const UInt32 a_Value)
 
void Push (const Vector3d &a_Vector)
 
void Push (const Vector3i &a_Vector)
 
void Push (ContiguousByteBufferView a_Data)
 
void Push (double a_Value)
 
void Push (int a_Value)
 
void Push (long a_Value)
 
void Push (std::chrono::milliseconds a_time)
 
cLuaStateQueryCanonLuaState (void) const
 Returns the canon Lua state (the primary cLuaState instance that was used to create, rather than attach, the lua_State structure). More...
 
void RegisterAPILibs (void)
 Registers all the API libraries that MCS provides into m_LuaState. More...
 
bool ReportErrors (int status)
 If the status is nonzero, prints the text on the top of Lua stack and returns true. More...
 
void ToString (int a_StackPos, AString &a_String)
 Reads the value at the specified stack position as a string and sets it to a_String. More...
 
void TrackInDeadlockDetect (cDeadlockDetect &a_DeadlockDetect)
 Adds this object's CS to the DeadlockDetect's tracked CSs. More...
 
void UntrackInDeadlockDetect (cDeadlockDetect &a_DeadlockDetect)
 Removes this object's CS from the DeadlockDetect's tracked CSs. More...
 
cStackValue WalkToNamedGlobal (const AString &a_Name)
 Pushes the named value in the global table to the top of the stack. More...
 
cStackValue WalkToValue (const AString &a_Name)
 Pushes the named value in the table at the top of the stack. More...
 
 ~cLuaState ()
 

Static Public Member Functions

static void LogStackTrace (lua_State *a_LuaState, int a_StartingDepth=0)
 Logs all items in the current stack trace to the server console. More...
 
static void LogStackValues (lua_State *a_LuaState, const char *a_Header=nullptr)
 Logs all the elements' types on the API stack, with an optional header for the listing. More...
 
static bool ReportErrors (lua_State *a_LuaState, int status)
 If the status is nonzero, prints the text on the top of Lua stack and returns true. More...
 

Static Public Attributes

static const cNil Nil = {}
 
static const cRet Return = {}
 

Protected Member Functions

bool CallFunction (int a_NumReturnValues)
 Pushes a usertype of the specified class type onto the stack. More...
 
template<typename... Args>
bool CallTableFn (const cRef &a_TableRef, const char *a_FnName, Args &&... args)
 Call the Lua function specified by name in the table stored as a reference. More...
 
bool GetStackValues (int a_StartingStackPos)
 Variadic template terminator: If there are no more values to get, bail out. More...
 
template<typename... Args>
bool PushCallPop (cLuaState::cRet, Args &&... args)
 Variadic template terminator: If there's nothing more to push, but return values to collect, call the function and collect the returns. More...
 
template<typename T , typename... Args>
bool PushCallPop (T &&a_Param, Args &&... args)
 Variadic template recursor: More params to push. More...
 
bool PushCallPop (void)
 Variadic template terminator: If there's nothing more to push / pop, just call the function. More...
 
bool PushFunction (const char *a_FunctionName)
 Pushes the function of the specified name onto the stack. More...
 
bool PushFunction (const cRef &a_FnRef)
 Pushes a function that has been saved as a reference. More...
 
bool PushFunction (const cRef &a_TableRef, const char *a_FnName)
 Pushes a function that is stored under the specified name in a table that has been saved as a reference. More...
 
void TrackRef (cTrackedRef &a_Ref)
 Adds the specified reference to tracking. More...
 
void UntrackRef (cTrackedRef &a_Ref)
 Removes the specified reference from tracking. More...
 

Static Protected Member Functions

static int BreakIntoDebugger (lua_State *a_LuaState)
 Tries to break into the MobDebug debugger, if it is installed. More...
 
static int ReportFnCallErrors (lua_State *a_LuaState)
 Used as the error reporting function for function calls. More...
 

Protected Attributes

cCriticalSection m_CS
 
cCriticalSection m_CSTrackedRefs
 Protects m_TrackedRefs against multithreaded access. More...
 
AString m_CurrentFunctionName
 Name of the currently pushed function (for the Push / Call chain) More...
 
bool m_IsOwned
 If true, the state is owned by this object and will be auto-Closed. More...
 
lua_State * m_LuaState
 
int m_NumCurrentFunctionArgs
 Number of arguments currently pushed (for the Push / Call chain) More...
 
AString m_SubsystemName
 The subsystem name is used for reporting errors to the console, it is either "plugin %s" or "LuaScript" whatever is given to the constructor. More...
 
std::vector< cTrackedRef * > m_TrackedRefs
 The tracked references. More...
 

Detailed Description

Encapsulates a Lua state and provides some syntactic sugar for common operations.

Definition at line 55 of file LuaState.h.

Member Typedef Documentation

◆ cCallbackPtr

typedef std::unique_ptr<cCallback> cLuaState::cCallbackPtr

Definition at line 326 of file LuaState.h.

◆ cCallbackSharedPtr

typedef std::shared_ptr<cCallback> cLuaState::cCallbackSharedPtr

Definition at line 327 of file LuaState.h.

◆ cOptionalCallbackPtr

Definition at line 356 of file LuaState.h.

◆ cStackTablePtr

typedef std::unique_ptr<cStackTable> cLuaState::cStackTablePtr

Definition at line 542 of file LuaState.h.

◆ cTableRefPtr

typedef std::unique_ptr<cTableRef> cLuaState::cTableRefPtr

Definition at line 419 of file LuaState.h.

◆ cTrackedRefPtr

typedef std::unique_ptr<cTrackedRef> cLuaState::cTrackedRefPtr

Definition at line 272 of file LuaState.h.

◆ cTrackedRefSharedPtr

typedef std::shared_ptr<cTrackedRef> cLuaState::cTrackedRefSharedPtr

Definition at line 273 of file LuaState.h.

Constructor & Destructor Documentation

◆ cLuaState() [1/2]

cLuaState::cLuaState ( const AString a_SubsystemName)

Creates a new instance.

The LuaState is not initialized. a_SubsystemName is used for reporting problems in the console, it is "plugin %s" for plugins, or "LuaScript" for the cLuaScript template

Definition at line 437 of file LuaState.cpp.

◆ cLuaState() [2/2]

cLuaState::cLuaState ( lua_State *  a_AttachState)
explicit

Creates a new instance.

The a_AttachState is attached. Subsystem name is set to "<attached>".

Definition at line 449 of file LuaState.cpp.

◆ ~cLuaState()

cLuaState::~cLuaState ( )

Definition at line 461 of file LuaState.cpp.

Member Function Documentation

◆ AddPackagePath()

void cLuaState::AddPackagePath ( const AString a_PathVariable,
const AString a_Path 
)

Adds the specified path to package.

<a_PathVariable>

Definition at line 611 of file LuaState.cpp.

◆ ApiParamError()

int cLuaState::ApiParamError ( std::string_view  a_Msg)

Prints the message, prefixed with the current function name, then logs the stack contents and raises a Lua error.

To be used for bindings when they detect bad parameters. Doesn't return, but a dummy return type is provided so that Lua API functions may do "return ApiParamError(...)".

Definition at line 2161 of file LuaState.cpp.

◆ Attach()

void cLuaState::Attach ( lua_State *  a_State)

Attaches the specified state.

Operations will be carried out on this state, but it will not be closed in the destructor

Definition at line 567 of file LuaState.cpp.

◆ BreakIntoDebugger()

int cLuaState::BreakIntoDebugger ( lua_State *  a_LuaState)
staticprotected

Tries to break into the MobDebug debugger, if it is installed.

Definition at line 2517 of file LuaState.cpp.

◆ Call()

template<typename FnT , typename... Args>
bool cLuaState::Call ( const FnT &  a_Function,
Args &&...  args 
)
inline

Call the specified Lua function.

Returns true if call succeeded, false if there was an error. A special param of cRet & signifies the end of param list and the start of return values. Example call: Call(Fn, Param1, Param2, Param3, cLuaState::Return, Ret1, Ret2)

Definition at line 751 of file LuaState.h.

◆ CallFunction()

bool cLuaState::CallFunction ( int  a_NumReturnValues)
protected

Pushes a usertype of the specified class type onto the stack.

Calls the function that has been pushed onto the stack by PushFunction(), with arguments pushed by PushXXX(). Returns true if successful, returns false and logs a warning on failure. Pops the function params, the function itself and the error handler off the stack. If successful, leaves a_NumReturnValues new values on Lua stack, corresponding to the return values. On failure, leaves no new values on the Lua stack.

Definition at line 1623 of file LuaState.cpp.

◆ CallFunctionWithForeignParams()

int cLuaState::CallFunctionWithForeignParams ( const AString a_FunctionName,
cLuaState a_SrcLuaState,
int  a_SrcParamStart,
int  a_SrcParamEnd 
)

Calls the function specified by its name, with arguments copied off the foreign state.

If successful, keeps the return values on the stack and returns their number. If unsuccessful, returns a negative number and keeps the stack position unchanged.

Definition at line 2194 of file LuaState.cpp.

◆ CallTableFn()

template<typename... Args>
bool cLuaState::CallTableFn ( const cRef a_TableRef,
const char *  a_FnName,
Args &&...  args 
)
inlineprotected

Call the Lua function specified by name in the table stored as a reference.

Returns true if call succeeded, false if there was an error (not a table ref, function name not found). A special param of cRet & signifies the end of param list and the start of return values. Example call: CallTableFn(TableRef, "FnName", Param1, Param2, Param3, cLuaState::Return, Ret1, Ret2)

Definition at line 931 of file LuaState.h.

◆ CheckParamBool()

bool cLuaState::CheckParamBool ( int  a_StartParam,
int  a_EndParam = -1 
)

Returns true if the specified parameters on the stack are bools; also logs warning if not.

Definition at line 1796 of file LuaState.cpp.

◆ CheckParamEnd()

bool cLuaState::CheckParamEnd ( int  a_Param)

Returns true if the specified parameter on the stack is nil (indicating an end-of-parameters)

Definition at line 1998 of file LuaState.cpp.

◆ CheckParamFunction()

bool cLuaState::CheckParamFunction ( int  a_StartParam,
int  a_EndParam = -1 
)

Returns true if the specified parameters on the stack are functions; also logs warning if not.

Definition at line 1865 of file LuaState.cpp.

◆ CheckParamFunctionOrNil()

bool cLuaState::CheckParamFunctionOrNil ( int  a_StartParam,
int  a_EndParam = -1 
)

Returns true if the specified parameters on the stack are functions or nils; also logs warning if not.

Definition at line 1898 of file LuaState.cpp.

◆ CheckParamNumber()

bool cLuaState::CheckParamNumber ( int  a_StartParam,
int  a_EndParam = -1 
)

Returns true if the specified parameters on the stack are numbers; also logs warning if not.

Definition at line 1763 of file LuaState.cpp.

◆ CheckParamSelf()

bool cLuaState::CheckParamSelf ( const char *  a_SelfClassName)

Returns true if the first parameter is an instance of the expected class name.

Returns false and logs a special warning ("wrong calling convention") if not.

Definition at line 2018 of file LuaState.cpp.

◆ CheckParamStaticSelf()

bool cLuaState::CheckParamStaticSelf ( const char *  a_SelfClassName)

Returns true if the first parameter is the expected class (static).

Returns false and logs a special warning ("wrong calling convention") if not.

Definition at line 2043 of file LuaState.cpp.

◆ CheckParamString()

bool cLuaState::CheckParamString ( int  a_StartParam,
int  a_EndParam = -1 
)

Returns true if the specified parameters on the stack are strings; also logs warning if not.

Definition at line 1829 of file LuaState.cpp.

◆ CheckParamTable()

bool cLuaState::CheckParamTable ( int  a_StartParam,
int  a_EndParam = -1 
)

Returns true if the specified parameters on the stack are tables; also logs warning if not.

Definition at line 1727 of file LuaState.cpp.

◆ CheckParamUserTable()

bool cLuaState::CheckParamUserTable ( int  a_StartParam,
const char *  a_UserTable,
int  a_EndParam = -1 
)

Returns true if the specified parameters on the stack are of the specified usertable type; also logs warning if not.

Used for static functions

Definition at line 1661 of file LuaState.cpp.

◆ CheckParamUserType()

bool cLuaState::CheckParamUserType ( int  a_StartParam,
const char *  a_UserType,
int  a_EndParam = -1 
)

Returns true if the specified parameters on the stack are of the specified usertype; also logs warning if not.

Used for regular functions

Definition at line 1694 of file LuaState.cpp.

◆ CheckParamUUID()

bool cLuaState::CheckParamUUID ( int  a_StartParam,
int  a_EndParam = -1 
)

Returns true if the specified parameters on the stack are UUIDs; also logs warning if not Accepts either cUUID instances or strings that contain UUIDs.

Definition at line 1957 of file LuaState.cpp.

◆ CheckParamVector3()

bool cLuaState::CheckParamVector3 ( int  a_StartParam,
int  a_EndParam = -1 
)

Returns true if the specified parameters on the stack are Vector3s; also logs warning if not.

Accepts any Vector3 type instances or tables.

Definition at line 1931 of file LuaState.cpp.

◆ Close()

void cLuaState::Close ( void  )

Closes the m_LuaState, if not closed already.

Definition at line 529 of file LuaState.cpp.

◆ CopySingleValueFrom()

bool cLuaState::CopySingleValueFrom ( cLuaState a_SrcLuaState,
int  a_StackIdx,
int  a_NumAllowedNestingLevels 
)

Copies a single value from the specified stack index of the source Lua state to the top of this Lua state's stack.

a_NumAllowedNestingLevels specifies how many table nesting levels are allowed, copying fails if there's a deeper table. Returns true if the value was copied, false on failure.

Definition at line 2334 of file LuaState.cpp.

◆ CopyStackFrom()

int cLuaState::CopyStackFrom ( cLuaState a_SrcLuaState,
int  a_SrcStart,
int  a_SrcEnd,
int  a_NumAllowedNestingLevels = 16 
)

Copies objects on the stack from the specified state.

Only numbers, bools, strings, API classes and simple tables containing these (recursively) are copied. a_NumAllowedNestingLevels specifies how many table nesting levels are allowed, copying fails if there's a deeper table. If successful, returns the number of objects copied. If failed, returns a negative number and rewinds the stack position.

Definition at line 2257 of file LuaState.cpp.

◆ CopyTableFrom()

bool cLuaState::CopyTableFrom ( cLuaState a_SrcLuaState,
int  a_TableIdx,
int  a_NumAllowedNestingLevels 
)

Copies a table at the specified stack index of the source Lua state to the top of this Lua state's stack.

a_NumAllowedNestingLevels specifies how many table nesting levels are allowed, copying fails if there's a deeper table. Returns true if successful, false on failure. Can copy only simple values - numbers, bools, strings and recursively simple tables.

Definition at line 2280 of file LuaState.cpp.

◆ Create()

void cLuaState::Create ( void  )

Creates the m_LuaState, if not created already.

This state will be automatically closed in the destructor. The regular Lua libs are registered, but the MCS API is not registered (so that Lua can be used as lite-config as well), use RegisterAPILibs() to do that.

Definition at line 480 of file LuaState.cpp.

◆ Detach()

void cLuaState::Detach ( void  )

Detaches a previously attached state.

Definition at line 589 of file LuaState.cpp.

◆ GetNamedGlobal()

template<typename T >
bool cLuaState::GetNamedGlobal ( const AString a_Name,
T &  a_Value 
)
inline

Retrieves the named global value.

a_Name may be a path containing multiple table levels, such as "_G.cChatColor.Blue". Returns true if the value was successfully retrieved, false on error.

Definition at line 733 of file LuaState.h.

◆ GetNamedValue()

template<typename T >
bool cLuaState::GetNamedValue ( const AString a_Name,
T &  a_Value 
)
inline

Retrieves the named value in the table at the top of the Lua stack.

a_Name may be a path containing multiple table levels, such as "_G.cChatColor.Blue". Returns true if the value was successfully retrieved, false on error.

Definition at line 720 of file LuaState.h.

◆ GetStackValue() [1/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
AString a_Value 
)

Definition at line 1119 of file LuaState.cpp.

◆ GetStackValue() [2/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
AStringMap a_Value 
)

Definition at line 1135 of file LuaState.cpp.

◆ GetStackValue() [3/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
AStringVector a_Value 
)

Definition at line 1166 of file LuaState.cpp.

◆ GetStackValue() [4/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
bool &  a_Value 
)

Definition at line 1197 of file LuaState.cpp.

◆ GetStackValue() [5/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
cCallback a_Callback 
)

Definition at line 1207 of file LuaState.cpp.

◆ GetStackValue() [6/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
cCallbackPtr a_Callback 
)

Definition at line 1216 of file LuaState.cpp.

◆ GetStackValue() [7/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
cCallbackSharedPtr a_Callback 
)

Definition at line 1251 of file LuaState.cpp.

◆ GetStackValue() [8/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
ContiguousByteBuffer a_Data 
)

Definition at line 1362 of file LuaState.cpp.

◆ GetStackValue() [9/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
cOptionalCallback a_Callback 
)

Definition at line 1229 of file LuaState.cpp.

◆ GetStackValue() [10/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
cOptionalCallbackPtr a_Callback 
)

Definition at line 1238 of file LuaState.cpp.

◆ GetStackValue() [11/28]

template<typename T >
bool cLuaState::GetStackValue ( int  a_StackPos,
cOptionalParam< T > &&  a_ReturnedVal 
)
inline

Retrieves an optional value on the stack - doesn't fail if the stack contains nil instead of the value.

Definition at line 692 of file LuaState.h.

◆ GetStackValue() [12/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
cPluginManager::CommandResult a_Result 
)

Definition at line 1264 of file LuaState.cpp.

◆ GetStackValue() [13/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
cRef a_Ref 
)

Definition at line 1278 of file LuaState.cpp.

◆ GetStackValue() [14/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
cStackTablePtr a_StackTable 
)

Definition at line 1288 of file LuaState.cpp.

◆ GetStackValue() [15/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
cTableRef a_TableRef 
)

Definition at line 1305 of file LuaState.cpp.

◆ GetStackValue() [16/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
cTableRefPtr a_TableRef 
)

Definition at line 1314 of file LuaState.cpp.

◆ GetStackValue() [17/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
cTrackedRef a_Ref 
)

Definition at line 1327 of file LuaState.cpp.

◆ GetStackValue() [18/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
cTrackedRefPtr a_Ref 
)

Definition at line 1336 of file LuaState.cpp.

◆ GetStackValue() [19/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
cTrackedRefSharedPtr a_Ref 
)

Definition at line 1349 of file LuaState.cpp.

◆ GetStackValue() [20/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
CustomStatistic a_Value 
)

Definition at line 1378 of file LuaState.cpp.

◆ GetStackValue() [21/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
cUUID a_Value 
)

Definition at line 1455 of file LuaState.cpp.

◆ GetStackValue() [22/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
double &  a_Value 
)

Definition at line 1393 of file LuaState.cpp.

◆ GetStackValue() [23/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
eBlockFace a_Value 
)

Definition at line 1407 of file LuaState.cpp.

◆ GetStackValue() [24/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
eWeather a_Value 
)

Definition at line 1424 of file LuaState.cpp.

◆ GetStackValue() [25/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
float &  a_ReturnedVal 
)

Definition at line 1441 of file LuaState.cpp.

◆ GetStackValue() [26/28]

bool cLuaState::GetStackValue ( int  a_StackPos,
std::string_view &  a_Value 
)

Definition at line 1489 of file LuaState.cpp.

◆ GetStackValue() [27/28]

template<class T , typename = std::enable_if_t<std::is_integral_v<T>>>
bool cLuaState::GetStackValue ( int  a_StackPos,
T &  a_ReturnedVal 
)
inline

Definition at line 671 of file LuaState.h.

◆ GetStackValue() [28/28]

template<typename T >
bool cLuaState::GetStackValue ( int  a_StackPos,
Vector3< T > &  a_ReturnedVal 
)

Retrieves any Vector3 value and coerces it into a Vector3<T>.

Definition at line 1506 of file LuaState.cpp.

◆ GetStackValues() [1/2]

bool cLuaState::GetStackValues ( int  a_StartingStackPos)
inlineprotected

Variadic template terminator: If there are no more values to get, bail out.

This function is not available in the public API, because it's an error to request no values directly; only internal functions can do that. If you get a compile error saying this function is not accessible, check your calling code, you aren't reading any stack values.

Definition at line 981 of file LuaState.h.

◆ GetStackValues() [2/2]

template<typename Arg1 , typename... Args>
bool cLuaState::GetStackValues ( int  a_StartStackPos,
Arg1 &&  a_Arg1,
Args &&...  args 
)
inline

Retrieves a list of values from the Lua stack, starting at the specified index.

Definition at line 766 of file LuaState.h.

◆ GetSubsystemName()

AString cLuaState::GetSubsystemName ( void  ) const
inline

Returns the name of the subsystem, as specified when the instance was created.

Definition at line 583 of file LuaState.h.

◆ GetTypeText()

AString cLuaState::GetTypeText ( int  a_StackPos)

Returns the type of the item on the specified position in the stack.

Definition at line 2185 of file LuaState.cpp.

◆ HasFunction()

bool cLuaState::HasFunction ( const char *  a_FunctionName)

Returns true if a_FunctionName is a valid Lua function that can be called.

Definition at line 709 of file LuaState.cpp.

◆ IsParamNumber()

bool cLuaState::IsParamNumber ( int  a_ParamIdx)

Returns true if the specified parameter is a number.

Definition at line 2080 of file LuaState.cpp.

◆ IsParamUserType()

bool cLuaState::IsParamUserType ( int  a_ParamIdx,
const AString a_UserType 
)

Returns true if the specified parameter is of the specified class.

Definition at line 2068 of file LuaState.cpp.

◆ IsParamVector3()

bool cLuaState::IsParamVector3 ( int  a_ParamIdx)

Returns true if the specified parameter is any of the Vector3 types.

Definition at line 2092 of file LuaState.cpp.

◆ IsValid()

bool cLuaState::IsValid ( void  ) const
inline

Returns true if the m_LuaState is valid.

Definition at line 580 of file LuaState.h.

◆ LoadFile()

bool cLuaState::LoadFile ( const AString a_FileName,
bool  a_LogWarnings = true 
)

Loads the specified file Returns false and optionally logs a warning to the console if not successful (but the LuaState is kept open).

m_SubsystemName is displayed in the warning log message.

Definition at line 637 of file LuaState.cpp.

◆ LoadString()

bool cLuaState::LoadString ( const AString a_StringToLoad,
const AString a_FileName,
bool  a_LogWarnings = true 
)

Loads the specified string.

Returns false and optionally logs a warning to the console if not successful (but the LuaState is kept open). a_FileName is the original filename from where the string was read, and is used only for logging. It may be empty. m_SubsystemName is displayed in the warning log message.

Definition at line 673 of file LuaState.cpp.

◆ LogApiCallParamFailure()

void cLuaState::LogApiCallParamFailure ( const char *  a_FnName,
const char *  a_ParamNames 
)

Outputs to log a warning about API call being unable to read its parameters from the stack, logs the stack trace and stack values.

Definition at line 2476 of file LuaState.cpp.

◆ LogStackTrace() [1/2]

void cLuaState::LogStackTrace ( int  a_StartingDepth = 0)

Logs all items in the current stack trace to the server console.

Definition at line 2134 of file LuaState.cpp.

◆ LogStackTrace() [2/2]

void cLuaState::LogStackTrace ( lua_State *  a_LuaState,
int  a_StartingDepth = 0 
)
static

Logs all items in the current stack trace to the server console.

Definition at line 2143 of file LuaState.cpp.

◆ LogStackValues() [1/2]

void cLuaState::LogStackValues ( const char *  a_Header = nullptr)

Logs all the elements' types on the API stack, with an optional header for the listing.

Definition at line 2418 of file LuaState.cpp.

◆ LogStackValues() [2/2]

void cLuaState::LogStackValues ( lua_State *  a_LuaState,
const char *  a_Header = nullptr 
)
static

Logs all the elements' types on the API stack, with an optional header for the listing.

Definition at line 2427 of file LuaState.cpp.

◆ operator lua_State *()

cLuaState::operator lua_State * ( void  )
inline

Allows this object to be used in the same way as a lua_State *, for example in the LuaLib functions.

Definition at line 559 of file LuaState.h.

◆ Pop()

void cLuaState::Pop ( int  a_NumValuesToPop = 1)

Pops the specified number of values off the top of the Lua stack.

Definition at line 1108 of file LuaState.cpp.

◆ Push() [1/22]

template<typename Arg1 , typename Arg2 , typename... Args>
void cLuaState::Push ( Arg1 &&  a_Arg1,
Arg2 &&  a_Arg2,
Args &&...  a_Args 
)
inline

Pushes multiple arguments onto the Lua stack.

Definition at line 604 of file LuaState.h.

◆ Push() [2/22]

void cLuaState::Push ( bool  a_Value)

Definition at line 945 of file LuaState.cpp.

◆ Push() [3/22]

void cLuaState::Push ( cEntity a_Entity)

Definition at line 966 of file LuaState.cpp.

◆ Push() [4/22]

void cLuaState::Push ( cLuaServerHandle a_ServerHandle)

Definition at line 1020 of file LuaState.cpp.

◆ Push() [5/22]

void cLuaState::Push ( cLuaTCPLink a_TCPLink)

Definition at line 1031 of file LuaState.cpp.

◆ Push() [6/22]

void cLuaState::Push ( cLuaUDPEndpoint a_UDPEndpoint)

Definition at line 1042 of file LuaState.cpp.

◆ Push() [7/22]

void cLuaState::Push ( const AString a_String)

Definition at line 821 of file LuaState.cpp.

◆ Push() [8/22]

void cLuaState::Push ( const AStringMap a_Dictionary)

Definition at line 832 of file LuaState.cpp.

◆ Push() [9/22]

void cLuaState::Push ( const AStringVector a_Vector)

Definition at line 850 of file LuaState.cpp.

◆ Push() [10/22]

void cLuaState::Push ( const cEntity a_Entity)

Definition at line 956 of file LuaState.cpp.

◆ Push() [11/22]

void cLuaState::Push ( const char *  a_Value)

Definition at line 868 of file LuaState.cpp.

◆ Push() [12/22]

void cLuaState::Push ( const cItem a_Item)

Definition at line 879 of file LuaState.cpp.

◆ Push() [13/22]

void cLuaState::Push ( const cNil a_Nil)

Definition at line 890 of file LuaState.cpp.

◆ Push() [14/22]

void cLuaState::Push ( const cRef a_Ref)

Definition at line 901 of file LuaState.cpp.

◆ Push() [15/22]

void cLuaState::Push ( const UInt32  a_Value)

Definition at line 1086 of file LuaState.cpp.

◆ Push() [16/22]

void cLuaState::Push ( const Vector3d a_Vector)

Definition at line 923 of file LuaState.cpp.

◆ Push() [17/22]

void cLuaState::Push ( const Vector3i a_Vector)

Definition at line 934 of file LuaState.cpp.

◆ Push() [18/22]

void cLuaState::Push ( ContiguousByteBufferView  a_Data)

Definition at line 912 of file LuaState.cpp.

◆ Push() [19/22]

void cLuaState::Push ( double  a_Value)

Definition at line 1053 of file LuaState.cpp.

◆ Push() [20/22]

void cLuaState::Push ( int  a_Value)

Definition at line 1064 of file LuaState.cpp.

◆ Push() [21/22]

void cLuaState::Push ( long  a_Value)

Definition at line 1075 of file LuaState.cpp.

◆ Push() [22/22]

void cLuaState::Push ( std::chrono::milliseconds  a_time)

Definition at line 1097 of file LuaState.cpp.

◆ PushCallPop() [1/3]

template<typename... Args>
bool cLuaState::PushCallPop ( cLuaState::cRet  ,
Args &&...  args 
)
inlineprotected

Variadic template terminator: If there's nothing more to push, but return values to collect, call the function and collect the returns.

Definition at line 959 of file LuaState.h.

◆ PushCallPop() [2/3]

template<typename T , typename... Args>
bool cLuaState::PushCallPop ( T &&  a_Param,
Args &&...  args 
)
inlineprotected

Variadic template recursor: More params to push.

Push them and recurse.

Definition at line 950 of file LuaState.h.

◆ PushCallPop() [3/3]

bool cLuaState::PushCallPop ( void  )
inlineprotected

Variadic template terminator: If there's nothing more to push / pop, just call the function.

Note that there are no return values either, because those are prefixed by a cRet value, so the arg list is never empty.

Definition at line 943 of file LuaState.h.

◆ PushFunction() [1/3]

bool cLuaState::PushFunction ( const char *  a_FunctionName)
protected

Pushes the function of the specified name onto the stack.

Returns true if successful. Logs a warning on failure (incl. m_SubsystemName)

Definition at line 728 of file LuaState.cpp.

◆ PushFunction() [2/3]

bool cLuaState::PushFunction ( const cRef a_FnRef)
protected

Pushes a function that has been saved as a reference.

Returns true if successful. Logs a warning on failure

Definition at line 757 of file LuaState.cpp.

◆ PushFunction() [3/3]

bool cLuaState::PushFunction ( const cRef a_TableRef,
const char *  a_FnName 
)
protected

Pushes a function that is stored under the specified name in a table that has been saved as a reference.

Returns true if successful.

Definition at line 780 of file LuaState.cpp.

◆ QueryCanonLuaState()

cLuaState * cLuaState::QueryCanonLuaState ( void  ) const

Returns the canon Lua state (the primary cLuaState instance that was used to create, rather than attach, the lua_State structure).

Returns nullptr if the canon Lua state cannot be queried.

Definition at line 2467 of file LuaState.cpp.

◆ RegisterAPILibs()

void cLuaState::RegisterAPILibs ( void  )

Registers all the API libraries that MCS provides into m_LuaState.

Definition at line 498 of file LuaState.cpp.

◆ ReportErrors() [1/2]

bool cLuaState::ReportErrors ( int  status)

If the status is nonzero, prints the text on the top of Lua stack and returns true.

Definition at line 2108 of file LuaState.cpp.

◆ ReportErrors() [2/2]

bool cLuaState::ReportErrors ( lua_State *  a_LuaState,
int  status 
)
static

If the status is nonzero, prints the text on the top of Lua stack and returns true.

Definition at line 2117 of file LuaState.cpp.

◆ ReportFnCallErrors()

int cLuaState::ReportFnCallErrors ( lua_State *  a_LuaState)
staticprotected

Used as the error reporting function for function calls.

Definition at line 2505 of file LuaState.cpp.

◆ ToString()

void cLuaState::ToString ( int  a_StackPos,
AString a_String 
)

Reads the value at the specified stack position as a string and sets it to a_String.

Definition at line 2404 of file LuaState.cpp.

◆ TrackInDeadlockDetect()

void cLuaState::TrackInDeadlockDetect ( cDeadlockDetect a_DeadlockDetect)

Adds this object's CS to the DeadlockDetect's tracked CSs.

Definition at line 2487 of file LuaState.cpp.

◆ TrackRef()

void cLuaState::TrackRef ( cTrackedRef a_Ref)
protected

Adds the specified reference to tracking.

The reference will be invalidated when this Lua state is about to be closed.

Definition at line 2539 of file LuaState.cpp.

◆ UntrackInDeadlockDetect()

void cLuaState::UntrackInDeadlockDetect ( cDeadlockDetect a_DeadlockDetect)

Removes this object's CS from the DeadlockDetect's tracked CSs.

Definition at line 2496 of file LuaState.cpp.

◆ UntrackRef()

void cLuaState::UntrackRef ( cTrackedRef a_Ref)
protected

Removes the specified reference from tracking.

The reference will no longer be invalidated when this Lua state is about to be closed.

Definition at line 2558 of file LuaState.cpp.

◆ WalkToNamedGlobal()

cLuaState::cStackValue cLuaState::WalkToNamedGlobal ( const AString a_Name)

Pushes the named value in the global table to the top of the stack.

a_Name may be a path containing multiple table levels, such as "cChatColor.Blue". If the value is found in the global table, it is pushed to the top of the stack and the returned cStackValue is valid. If the value is not found, the stack is unchanged and the returned cStackValue is invalid.

Definition at line 1591 of file LuaState.cpp.

◆ WalkToValue()

cLuaState::cStackValue cLuaState::WalkToValue ( const AString a_Name)

Pushes the named value in the table at the top of the stack.

a_Name may be a path containing multiple table levels, such as "cChatColor.Blue". If the value is found, it is pushed on top of the stack and the returned cStackValue is valid. If the value is not found, the stack is unchanged and the returned cStackValue is invalid.

Definition at line 1556 of file LuaState.cpp.

Member Data Documentation

◆ m_CS

cCriticalSection cLuaState::m_CS
protected

Definition at line 900 of file LuaState.h.

◆ m_CSTrackedRefs

cCriticalSection cLuaState::m_CSTrackedRefs
protected

Protects m_TrackedRefs against multithreaded access.

Definition at line 923 of file LuaState.h.

◆ m_CurrentFunctionName

AString cLuaState::m_CurrentFunctionName
protected

Name of the currently pushed function (for the Push / Call chain)

Definition at line 912 of file LuaState.h.

◆ m_IsOwned

bool cLuaState::m_IsOwned
protected

If true, the state is owned by this object and will be auto-Closed.

False => attached state

Definition at line 905 of file LuaState.h.

◆ m_LuaState

lua_State* cLuaState::m_LuaState
protected

Definition at line 902 of file LuaState.h.

◆ m_NumCurrentFunctionArgs

int cLuaState::m_NumCurrentFunctionArgs
protected

Number of arguments currently pushed (for the Push / Call chain)

Definition at line 915 of file LuaState.h.

◆ m_SubsystemName

AString cLuaState::m_SubsystemName
protected

The subsystem name is used for reporting errors to the console, it is either "plugin %s" or "LuaScript" whatever is given to the constructor.

Definition at line 909 of file LuaState.h.

◆ m_TrackedRefs

std::vector<cTrackedRef *> cLuaState::m_TrackedRefs
protected

The tracked references.

The cLuaState will invalidate all of these when it is about to be closed. Protected against multithreaded access by m_CSTrackedRefs.

Definition at line 920 of file LuaState.h.

◆ Nil

const cLuaState::cNil cLuaState::Nil = {}
static

Definition at line 452 of file LuaState.h.

◆ Return

const cLuaState::cRet cLuaState::Return = {}
static

Definition at line 445 of file LuaState.h.


The documentation for this class was generated from the following files: