Built-in scripting functions.
The script context
Diff is the expected difference of the stack size.
If luaL_error, or another function that executes a long-jump, is part of the executed code,
the stack guard cannot be guaranteed to execute at the end of the function.
In that case you should manually check the stack using lua_gettop
.
In the case of luaL_error, see DM_LUA_ERROR.
L - lua state
diff - Number of expected items to be on the Lua stack once this struct goes out of scope
DM_LUA_STACK_CHECK(L, 1);
lua_pushnumber(L, 42);
This macro will verify that the Lua stack size hasn't been changed before throwing a Lua error, which will long-jump out of the current function. This macro can only be used together with DM_LUA_STACK_CHECK and should be prefered over manual checking of the stack.
fmt - Format string that contains error information.
args - Format string args (variable arg list)
static int ModuleFunc(lua_State* L)
{
DM_LUA_STACK_CHECK(L, 1);
if (some_error_check(L))
{
return DM_LUA_ERROR("some error message");
}
lua_pushnumber(L, 42);
return 1;
}
Creates and returns a reference, in the table at index t, for the object at the top of the stack (and pops the object). It also tracks number of global references kept.
L - lua state
table - table the lua table that stores the references. E.g LUA_REGISTRYINDEX
reference - the new reference
Releases reference ref from the table at index t (see luaL_ref). The entry is removed from the table, so that the referred object can be collected. It also decreases the number of global references kept
L - lua state
table - table the lua table that stores the references. E.g LUA_REGISTRYINDEX
reference - the reference to the object
Retrieve current script instance from the global table and place it on the top of the stack, only valid when set. (see dmScript::GetMainThread)
L - lua state
Sets the current script instance Set the value on the top of the stack as the instance into the global table and pops it from the stack. (see dmScript::GetMainThread)
L - lua state
Check if the script instance in the lua state is valid. The instance is assumed to have been previously set by dmScript::SetInstance.
L - lua state
boolean - Returns true if the instance is valid
Retrieve the main thread lua state from any lua state (main thread or coroutine).
L - lua state
lua_State - the main thread lua state
How to create a Lua callback
dmScript::LuaCallbackInfo* g_MyCallbackInfo = 0;
static void InvokeCallback(dmScript::LuaCallbackInfo* cbk)
{
if (!dmScript::IsCallbackValid(cbk))
return;
lua_State* L = dmScript::GetCallbackLuaContext(cbk);
DM_LUA_STACK_CHECK(L, 0)
if (!dmScript::SetupCallback(cbk))
{
dmLogError("Failed to setup callback");
return;
}
lua_pushstring(L, "Hello from extension!");
lua_pushnumber(L, 76);
dmScript::PCall(L, 3, 0); // instance + 2
dmScript::TeardownCallback(cbk);
}
static int Start(lua_State* L)
{
DM_LUA_STACK_CHECK(L, 0);
g_MyCallbackInfo = dmScript::CreateCallback(L, 1);
return 0;
}
static int Update(lua_State* L)
{
DM_LUA_STACK_CHECK(L, 0);
static int count = 0;
if( count++ == 5 )
{
InvokeCallback(g_MyCallbackInfo);
if (g_MyCallbackInfo)
dmScript::DestroyCallback(g_MyCallbackInfo);
g_MyCallbackInfo = 0;
}
return 0;
}
Get the value at index as a dmVMath::Vector3*
L - Lua state
index - Index of the value
v - The pointer to the value, or 0 if not correct type
Check if the value at #index is a dmVMath::Vector3*
L - Lua state
index - Index of the value
true - if value at #index is a dmVMath::Vector3*
Push a dmVMath::Vector3 value onto the supplied lua state, will increase the stack by 1.
L - Lua state
v - Vector3 value to push
Check if the value in the supplied index on the lua stack is a dmVMath::Vector3.
L - Lua state
index - Index of the value
vector3 - The pointer to the value
Get the value at index as a dmVMath::Vector4*
L - Lua state
index - Index of the value
v - The pointer to the value, or 0 if not correct type
Check if the value at #index is a dmVMath::Vector4*
L - Lua state
index - Index of the value
true - if value at #index is a dmVMath::Vector4*
Push a dmVMath::Vector4 value onto the supplied lua state, will increase the stack by 1.
L - Lua state
v - dmVMath::Vector4 value to push
Check if the value in the supplied index on the lua stack is a dmVMath::Vector3.
L - Lua state
index - Index of the value
vector4 - The pointer to the value
Get the value at index as a dmVMath::Quat*
L - Lua state
index - Index of the value
quat - The pointer to the value, or 0 if not correct type
Check if the value at #index is a dmVMath::Quat*
L - Lua state
index - Index of the value
true - if value at #index is a dmVMath::Quat*
Push a quaternion value onto Lua stack. Will increase the stack by 1.
L - Lua state
quat - dmVMath::Quat value to push
Check if the value in the supplied index on the lua stack is a dmVMath::Quat.
L - Lua state
index - Index of the value
quat - The pointer to the value
Get the value at index as a dmVMath::Matrix4*
L - Lua state
index - Index of the value
quat - The pointer to the value, or 0 if not correct type
Check if the value at #index is a dmVMath::Matrix4*
L - Lua state
index - Index of the value
true - if value at #index is a dmVMath::Matrix4*
Push a matrix4 value onto the Lua stack. Will increase the stack by 1.
L - Lua state
matrix - dmVMath::Matrix4 value to push
Check if the value in the supplied index on the lua stack is a dmVMath::Matrix4.
L - Lua state
index - Index of the value
matrix - The pointer to the value
Check if the value at #index is a hash
L - Lua state
index - Index of the value
true - if the value at #index is a hash
Push a hash value onto the supplied lua state, will increase the stack by 1.
L - Lua state
hash - dmhash_t Hash value to push
Check if the value in the supplied index on the lua stack is a hash.
L - Lua state
index - Index of the value
The - hash value
Check if the value in the supplied index on the lua stack is a hash or string. If it is a string, it gets hashed on the fly
L - Lua state
index - Index of the value
The - hash value
Gets as good as possible printable string from a hash or string
L - Lua state
index - Index of the value
buffer - buffer receiving the value
buffer_length - the buffer length
string - Returns buffer. If buffer is non null, it will always contain a null terminated string. "
Convert a Json string to Lua table.
L - lua state
json - json string
json_len - length of json string
int - 1 if it succeeds. Throws a Lua error if it fails
Convert a Lua table to a Json string
L - lua state
json - [out] Pointer to char*, which will receive a newly allocated string. Use free().
json_len - length of json string
int - <0 if it fails. >=0 if it succeeds.
callback info struct that will hold the relevant info needed to make a callback into Lua
Stores the current Lua state plus references to the script instance (self) and the callback. Expects SetInstance() to have been called prior to using this method. The allocated data is created on the Lua stack and references are made against the instances own context table. If the callback is not explicitly deleted with DestroyCallback() the references and data will stay around until the script instance is deleted.
L - Lua state
index - Lua stack index of the function
Lua - callback struct if successful, 0 otherwise
static int SomeFunction(lua_State* L) // called from Lua
{
LuaCallbackInfo* cbk = dmScript::CreateCallback(L, 1);
... store the callback for later
}
static void InvokeCallback(LuaCallbackInfo* cbk)
{
lua_State* L = dmScript::GetCallbackLuaContext(cbk);
DM_LUA_STACK_CHECK(L, 0);
if (!dmScript::SetupCallback(callback))
{
return;
}
lua_pushstring(L, "hello");
dmScript::PCall(L, 2, 0); // self + # user arguments
dmScript::TeardownCallback(callback);
dmScript::DestroyCallback(cbk); // only do this if you're not using the callback again
}
Check if Lua callback is valid.
cbk - Lua callback struct
Deletes the Lua callback
cbk - Lua callback struct
Gets the Lua context from a callback struct
cbk - Lua callback struct
L - Lua state
The Lua stack after a successful call:
[-4] old instance
[-3] context table
[-2] callback
[-1] self
cbk - Lua callback struct
true - if the setup was successful
Sets the previous instance Expects Lua stack:
[-2] old instance
[-1] context table
cbk - Lua callback struct
This function wraps lua_pcall with the addition of specifying an error handler which produces a backtrace. In the case of an error, the error is logged and popped from the stack.
L - lua state
nargs - number of arguments
nresult - number of results
error - code from pcall
Creates a reference to the value at top of stack, the ref is done in the current instances context table. Expects SetInstance() to have been set with an value that has a meta table with META_GET_INSTANCE_CONTEXT_TABLE_REF method.
L - Lua state
lua - ref to value or LUA_NOREF Lua stack on entry [-1] value Lua stack on exit
Deletes the instance local lua reference Expects SetInstance() to have been set with an value that has a meta table with META_GET_INSTANCE_CONTEXT_TABLE_REF method.
L - Lua state
ref - ref to value or LUA_NOREF Lua stack on entry Lua stack on exit
Resolves a url in string format into a dmMessage::URL struct. Special handling for: - "." returns the default socket + path - "#" returns default socket + path + fragment
L - Lua state
url - url
out_url - where to store the result
default_url - default url
result - dmMessage::RESULT_OK if the conversion succeeded
Converts a URL into a readable string. Useful for e.g. error messages
url - url
buffer - the output buffer
buffer_size - the output buffer size
buffer - returns the passed in buffer
Serialize a table to a buffer Supported types: LUA_TBOOLEAN, LUA_TNUMBER, LUA_TSTRING, Point3, Vector3, Vector4 and Quat Keys must be strings
L - Lua state
buffer - Buffer that will be written to (must be DM_ALIGNED(16))
buffer_size - Buffer size
index - Index of the table
result - Number of bytes used in buffer
Get current game object instance Works in both gameobjects and gui scripts
L - lua state
instance -
Get gameobject instance The instance reference (url) at stack index "index" will be resolved to an instance.
L - lua state
index - lua-arg
instance - gameobject instance
How to get the position of a gameobject in a script extension
static int get_position(lua_State* L)
{
DM_LUA_STACK_CHECK(L, 3);
dmGameObject::HInstance instance = dmScript::CheckGOInstance(L, 1);
dmVMath::Point3 position = dmGameObject::GetPosition(instance);
lua_pushnumber(L, position.getX());
lua_pushnumber(L, position.getY());
lua_pushnumber(L, position.getZ());
return 3;
}
Get current gameobject's collection handle
L - lua state
index - lua-arg
instance - gameobject instance
Get component user data from a url.
L - Lua state
index - index to argument (a url)
component_type - E.g. "factoryc". The call will fail if the found component does not have the specified extension
world - The world associated owning the component. May be 0
component - The component data associated with the url. May be 0
url - The resolved url. May be 0
Buffer ownership. - OWNER_C - m_Buffer is owned by C side, should not be destroyed when GCed - OWNER_LUA - m_Buffer is owned by Lua side, will be destroyed when GCed - OWNER_RES - m_Buffer not used, has a reference to a buffer resource instead. m_BufferRes is owned by C side, will be released when GCed
dmScript::OWNER_C -
dmScript::OWNER_LUA -
dmScript::OWNER_RES -
Holds info about the buffer and who owns it.
Union - of - m_BufferRes void* A buffer resource - m_Buffer dmBuffer::HBuffer A buffer
m_Buffer - The buffer (or resource)
m_Owner - What ownership the pointer has
See examples for dmScript::PushBuffer()
Check if the value is a dmScript::LuaHBuffer
L - lua state
index - Index of the value
boolean - True if value at index is a LuaHBuffer
Will increase the stack by 1.
L - lua state
buffer - buffer to push
How to push a buffer and give Lua ownership of the buffer (GC)
dmScript::LuaHBuffer luabuf(buffer, dmScript::OWNER_LUA);
PushBuffer(L, luabuf);
dmScript::LuaHBuffer luabuf(buffer, dmScript::OWNER_C);
PushBuffer(L, luabuf);
Retrieve a LuaHBuffer from the supplied lua state. Check if the value in the supplied index on the lua stack is a LuaHBuffer and returns it.
L - lua state
index - Index of the value
buffer - pointer to dmScript::LuaHBuffer
Retrieve a LuaHBuffer from the supplied lua state. Check if the value in the supplied index on the lua stack is a LuaHBuffer and returns it.
L - lua state
index - Index of the value
buffer - pointer to dmScript::LuaHBuffer or 0 if not valid
Retrieve a HBuffer from the supplied lua state Check if the value in the supplied index on the lua stack is a LuaHBuffer and it's valid, returns the HBuffer.
L - lua state
index - Index of the value
buffer - buffer if valid, 0 otherwise
Retrieve a HBuffer from the supplied lua state Check if the value in the supplied index on the lua stack is a LuaHBuffer and it's valid, returns the HBuffer.
L - lua state
index - Index of the value
buffer - buffer if valid, 0 otherwise