Built-in scripting functions.
Namespace: | dmScript |
Include: | #include <dmsdk/script/script.h> |
TYPES | |
---|---|
HContext | The script context |
ENUMS | |
---|---|
LuaBufferOwnership | buffer ownership |
STRUCTS | |
---|---|
struct dmScript::LuaCallbackInfo | callback info struct |
struct dmScript::LuaHBuffer | Lua wrapper for a dmBuffer::HBuffer |
MACROS | |
---|---|
DM_LUA_ERROR(fmt, args) | helper macro to validate the Lua stack state and throw a lua error. |
DM_LUA_STACK_CHECK(L, diff) | helper macro to validate the Lua stack state before leaving a function. |
lua_State* CheckCollection(lua_State* L, int index)
Get current gameobject's collection handle
PARAMETERS
lua_State* |
L |
lua state |
int |
index |
lua-arg |
RETURNS
lua_State* |
gameobject instance |
dmGameObject::HInstance CheckGOInstance(lua_State* L)
Get current game object instance Works in both gameobjects and gui scripts
PARAMETERS
lua_State* |
L |
lua state |
RETURNS
dmGameObject::HInstance |
dmGameObject::HInstance CheckGOInstance(lua_State* L, int index)
Get gameobject instance The instance reference (url) at stack index "index" will be resolved to an instance.
PARAMETERS
lua_State* |
L |
lua state |
int |
index |
lua-arg |
RETURNS
dmGameObject::HInstance |
gameobject instance |
EXAMPLES
How to get the position of a gameobject in a script extensionstatic 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;
}
uint32_t CheckTable(lua_State* L, char* buffer, uint32_t buffer_size, int index)
Serialize a table to a buffer Supported types: LUA_TBOOLEAN, LUA_TNUMBER, LUA_TSTRING, Point3, Vector3, Vector4 and Quat Keys must be strings
PARAMETERS
lua_State* |
L |
Lua state |
char* |
buffer |
Buffer that will be written to (must be DM_ALIGNED(16)) |
uint32_t |
buffer_size |
Buffer size |
int |
index |
Index of the table |
RETURNS
uint32_t |
Number of bytes used in buffer |
LuaHBuffer* dmScript::CheckBuffer(lua_State* L, int index)
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.
PARAMETERS
lua_State* |
L |
lua state |
int |
index |
Index of the value |
RETURNS
LuaHBuffer* |
pointer to dmScript::LuaHBuffer |
LuaHBuffer* dmScript::CheckBufferNoError(lua_State* L, int index)
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.
PARAMETERS
lua_State* |
L |
lua state |
int |
index |
Index of the value |
RETURNS
LuaHBuffer* |
pointer to dmScript::LuaHBuffer or 0 if not valid |
dmBuffer::HBuffer dmScript::CheckBufferUnpack(lua_State* L, int index)
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.
PARAMETERS
lua_State* |
L |
lua state |
int |
index |
Index of the value |
RETURNS
dmBuffer::HBuffer |
buffer if valid, 0 otherwise |
dmBuffer::HBuffer dmScript::CheckBufferUnpackNoError(lua_State* L, int index)
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.
PARAMETERS
lua_State* |
L |
lua state |
int |
index |
Index of the value |
RETURNS
dmBuffer::HBuffer |
buffer if valid, 0 otherwise |
dmScript::CheckHash(lua_State* L, int index)
Check if the value in the supplied index on the lua stack is a hash.
PARAMETERS
lua_State* |
L |
Lua state |
int |
index |
Index of the value |
RETURNS
|
hash value |
dmScript::CheckHashOrString(lua_State* L, int index)
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
PARAMETERS
lua_State* |
L |
Lua state |
int |
index |
Index of the value |
RETURNS
|
hash value |
dmVMath::Matrix4* dmScript::CheckMatrix4(lua_State* L, int index)
Check if the value in the supplied index on the lua stack is a dmVMath::Matrix4.
PARAMETERS
lua_State* |
L |
Lua state |
int |
index |
Index of the value |
RETURNS
dmVMath::Matrix4* |
The pointer to the value |
dmVMath::Quat* dmScript::CheckQuat(lua_State* L, int index)
Check if the value in the supplied index on the lua stack is a dmVMath::Quat.
PARAMETERS
lua_State* |
L |
Lua state |
int |
index |
Index of the value |
RETURNS
dmVMath::Quat* |
The pointer to the value |
dmVMath::Vector3* dmScript::CheckVector3(lua_State* L, int index)
Check if the value in the supplied index on the lua stack is a dmVMath::Vector3.
PARAMETERS
lua_State* |
L |
Lua state |
int |
index |
Index of the value |
RETURNS
dmVMath::Vector3* |
The pointer to the value |
dmVMath::Vector4* dmScript::CheckVector4(lua_State* L, int index)
Check if the value in the supplied index on the lua stack is a dmVMath::Vector3.
PARAMETERS
lua_State* |
L |
Lua state |
int |
index |
Index of the value |
RETURNS
dmVMath::Vector4* |
The pointer to the value |
dmScript::CreateCallback( L, index)
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.
PARAMETERS
|
L |
Lua state |
|
index |
Lua stack index of the function |
RETURNS
|
callback struct if successful, 0 otherwise |
EXAMPLES
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
}
void dmScript::DestroyCallback( cbk)
Deletes the Lua callback
PARAMETERS
|
cbk |
Lua callback struct |
dmScript::GetCallbackLuaContext( cbk)
Gets the Lua context from a callback struct
PARAMETERS
|
cbk |
Lua callback struct |
RETURNS
|
Lua state |
void dmScript::GetInstance(lua_State* L)
Retrieve current script instance from the global table and place it on the top of the stack, only valid when set. (see dmScript::GetMainThread)
PARAMETERS
lua_State* |
L |
lua state |
lua_State* dmScript::GetMainThread(lua_State* L)
Retrieve the main thread lua state from any lua state (main thread or coroutine).
PARAMETERS
lua_State* |
L |
lua state |
RETURNS
lua_State* |
the main thread lua state |
EXAMPLES
How to create a Lua callbackdmScript::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;
}
boolean dmScript::IsBuffer(lua_State* L, int index)
Check if the value is a dmScript::LuaHBuffer
PARAMETERS
lua_State* |
L |
lua state |
int |
index |
Index of the value |
RETURNS
boolean |
True if value at index is a LuaHBuffer |
void dmScript::IsCallbackValid( cbk)
Check if Lua callback is valid.
PARAMETERS
|
cbk |
Lua callback struct |
dmScript::IsHash(lua_State* L, int index)
Check if the value at #index is a hash
PARAMETERS
lua_State* |
L |
Lua state |
int |
index |
Index of the value |
RETURNS
|
if the value at #index is a hash |
bool dmScript::IsInstanceValid(lua_State* L)
Check if the script instance in the lua state is valid. The instance is assumed to have been previously set by dmScript::SetInstance.
PARAMETERS
lua_State* |
L |
lua state |
RETURNS
bool |
Returns true if the instance is valid |
dmScript::IsMatrix4( L, index)
Check if the value at #index is a dmVMath::Matrix4*
PARAMETERS
|
L |
Lua state |
|
index |
Index of the value |
RETURNS
|
if value at #index is a dmVMath::Matrix4* |
dmScript::IsQuat( L, index)
Check if the value at #index is a dmVMath::Quat*
PARAMETERS
|
L |
Lua state |
|
index |
Index of the value |
RETURNS
|
if value at #index is a dmVMath::Quat* |
dmScript::IsVector3( L, index)
Check if the value at #index is a dmVMath::Vector3*
PARAMETERS
|
L |
Lua state |
|
index |
Index of the value |
RETURNS
|
if value at #index is a dmVMath::Vector3* |
dmScript::IsVector4( L, index)
Check if the value at #index is a dmVMath::Vector4*
PARAMETERS
|
L |
Lua state |
|
index |
Index of the value |
RETURNS
|
if value at #index is a dmVMath::Vector4* |
int dmScript::JsonToLua(lua_State* L, const char* json, size_t json_len)
Convert a Json string to Lua table.
PARAMETERS
lua_State* |
L |
lua state |
const char* |
json |
json string |
size_t |
json_len |
length of json string |
RETURNS
int |
1 if it succeeds. Throws a Lua error if it fails |
int dmScript::LuaToJson(lua_State* L, char** json, size_t* json_len)
Convert a Lua table to a Json string
PARAMETERS
lua_State* |
L |
lua state |
char** |
json |
[out] Pointer to char*, which will receive a newly allocated string. Use free(). |
size_t* |
json_len |
length of json string |
RETURNS
int |
<0 if it fails. >=0 if it succeeds. |
dmScript::PCall( L, nargs, nresult)
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.
PARAMETERS
|
L |
lua state |
|
nargs |
number of arguments |
|
nresult |
number of results |
RETURNS
|
code from pcall |
void dmScript::PushBuffer(lua_State* L, dmScript::LuaHBuffer buffer)
Will increase the stack by 1.
PARAMETERS
lua_State* |
L |
lua state |
dmScript::LuaHBuffer |
buffer |
buffer to push |
EXAMPLES
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);
void dmScript::PushHash(lua_State* L, hash)
Push a hash value onto the supplied lua state, will increase the stack by 1.
PARAMETERS
lua_State* |
L |
Lua state |
|
hash |
dmhash_t Hash value to push |
void dmScript::PushMatrix4(lua_State* L, dmVMath::Matrix4 matrix)
Push a matrix4 value onto the Lua stack. Will increase the stack by 1.
PARAMETERS
lua_State* |
L |
Lua state |
dmVMath::Matrix4 |
matrix |
dmVMath::Matrix4 value to push |
void dmScript::PushQuat(lua_State* L, dmVMath::Quat quat)
Push a quaternion value onto Lua stack. Will increase the stack by 1.
PARAMETERS
lua_State* |
L |
Lua state |
dmVMath::Quat |
quat |
dmVMath::Quat value to push |
void dmScript::PushVector3(lua_State* L, dmVMath::Vector3 v)
Push a dmVMath::Vector3 value onto the supplied lua state, will increase the stack by 1.
PARAMETERS
lua_State* |
L |
Lua state |
dmVMath::Vector3 |
v |
Vector3 value to push |
void dmScript::PushVector4(lua_State* L, dmVMath::Vector4 v)
Push a dmVMath::Vector4 value onto the supplied lua state, will increase the stack by 1.
PARAMETERS
lua_State* |
L |
Lua state |
dmVMath::Vector4 |
v |
dmVMath::Vector4 value to push |
int dmScript::Ref(lua_State* L, int table)
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.
PARAMETERS
lua_State* |
L |
lua state |
int |
table |
table the lua table that stores the references. E.g LUA_REGISTRYINDEX |
RETURNS
int |
the new reference |
void dmScript::SetInstance(lua_State* L)
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)
PARAMETERS
lua_State* |
L |
lua state |
dmScript::SetupCallback( cbk)
The Lua stack after a successful call:
[-4] old instance
[-3] context table
[-2] callback
[-1] self
PARAMETERS
|
cbk |
Lua callback struct |
RETURNS
|
if the setup was successful |
void dmScript::TeardownCallback( cbk)
Sets the previous instance Expects Lua stack:
[-2] old instance
[-1] context table
PARAMETERS
|
cbk |
Lua callback struct |
dmVMath::Matrix4* dmScript::ToMatrix4(lua_State* L, int index)
Get the value at index as a dmVMath::Matrix4*
PARAMETERS
lua_State* |
L |
Lua state |
int |
index |
Index of the value |
RETURNS
dmVMath::Matrix4* |
The pointer to the value, or 0 if not correct type |
dmVMath::Quat* dmScript::ToQuat(lua_State* L, int index)
Get the value at index as a dmVMath::Quat*
PARAMETERS
lua_State* |
L |
Lua state |
int |
index |
Index of the value |
RETURNS
dmVMath::Quat* |
The pointer to the value, or 0 if not correct type |
dmVMath::Vector3* dmScript::ToVector3(lua_State* L, int index)
Get the value at index as a dmVMath::Vector3*
PARAMETERS
lua_State* |
L |
Lua state |
int |
index |
Index of the value |
RETURNS
dmVMath::Vector3* |
The pointer to the value, or 0 if not correct type |
dmVMath::Vector4* dmScript::ToVector4(lua_State* L, int index)
Get the value at index as a dmVMath::Vector4*
PARAMETERS
lua_State* |
L |
Lua state |
int |
index |
Index of the value |
RETURNS
dmVMath::Vector4* |
The pointer to the value, or 0 if not correct type |
void dmScript::Unref(lua_State* L, int table, int 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
PARAMETERS
lua_State* |
L |
lua state |
int |
table |
table the lua table that stores the references. E.g LUA_REGISTRYINDEX |
int |
reference |
the reference to the object |
void GetComponentFromLua(lua_State* L, int index, const char* component_type, dmGameObject::HComponentWorld* world, dmGameObject::HComponent* component, dmMessage::URL* url)
Get component user data from a url.
PARAMETERS
lua_State* |
L |
Lua state |
int |
index |
index to argument (a url) |
const char* |
component_type |
E.g. "factoryc". The call will fail if the found component does not have the specified extension |
dmGameObject::HComponentWorld* |
world |
The world associated owning the component. May be 0 |
dmGameObject::HComponent* |
component |
The component data associated with the url. May be 0 |
dmMessage::URL* |
url |
The resolved url. May be 0 |
const char* GetStringFromHashOrString(lua_State* L, int index, char* buffer, uint32_t buffer_length)
Gets as good as possible printable string from a hash or string
PARAMETERS
lua_State* |
L |
Lua state |
int |
index |
Index of the value |
char* |
buffer |
buffer receiving the value |
uint32_t |
buffer_length |
the buffer length |
RETURNS
const char* |
Returns buffer. If buffer is non null, it will always contain a null terminated string. " |
int RefInInstance(lua_State* L)
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.
PARAMETERS
lua_State* |
L |
Lua state |
RETURNS
int |
ref to value or LUA_NOREF Lua stack on entry [-1] value Lua stack on exit |
dmMessage::Result RefInInstance(lua_State* L, const char* url, dmMessage::URL* out_url, dmMessage::URL* default_url)
Resolves a url in string format into a dmMessage::URL struct. Special handling for: - "." returns the default socket + path - "#" returns default socket + path + fragment
PARAMETERS
lua_State* |
L |
Lua state |
const char* |
url |
url |
dmMessage::URL* |
out_url |
where to store the result |
dmMessage::URL* |
default_url |
default url |
RETURNS
dmMessage::Result |
dmMessage::RESULT_OK if the conversion succeeded |
void UnrefInInstance(lua_State* L, int ref)
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.
PARAMETERS
lua_State* |
L |
Lua state |
int |
ref |
ref to value or LUA_NOREF Lua stack on entry Lua stack on exit |
const char* UrlToString(dmMessage::URL* url, char* buffer, uint32_t buffer_size)
Converts a URL into a readable string. Useful for e.g. error messages
PARAMETERS
dmMessage::URL* |
url |
url |
char* |
buffer |
the output buffer |
uint32_t |
buffer_size |
the output buffer size |
RETURNS
const char* |
returns the passed in buffer |
TYPE
struct dmScript::LuaCallbackInfo
callback info struct that will hold the relevant info needed to make a callback into Lua
TYPE
struct dmScript::LuaHBuffer
Holds info about the buffer and who owns it.
MEMBERS
|
Union |
of - m_BufferRes void* A buffer resource - m_Buffer dmBuffer::HBuffer A buffer |
dmBuffer::HBuffer |
m_Buffer |
The buffer (or resource) |
dmScript::LuaBufferOwnership |
m_Owner |
What ownership the pointer has |
The script context
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 |
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) |
EXAMPLES
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;
}
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 |
EXAMPLES
DM_LUA_STACK_CHECK(L, 1);
lua_pushnumber(L, 42);