Script

Built-in scripting functions.

Namespace: dmScript
Include: #include <dmsdk/script/script.h>
TYPES
HContext The script context
STRUCTS
struct LuaCallbackInfo callback info struct
FUNCTIONS
hash CheckHash(lua_State* L, int index) get hash value
hash CheckHashOrString(lua_State* L, int index) get hash from hash or string
dmVMath::Matrix4* CheckMatrix4(lua_State* L, int index) check if the value is a dmVMath::Matrix4
dmVMath::Quat* CheckQuat(lua_State* L, int index) check if the value is a dmVMath::Vector3
uint32_t CheckTable(lua_State* L, char* buffer, uint32_t buffer_size, int index) Serialize a table to a buffer Supported types: LUA...
dmMessage::URL* CheckURL(lua_State* L, int index) Check if the value in the supplied index on the lu...
bool CheckURL(lua_State* L, dmMessage::URL* out_url) Get the current game object URL
dmVMath::Vector3* CheckVector3(lua_State* L, int index) check if the value is a dmVMath::Vector3
dmVMath::Vector4* CheckVector4(lua_State* L, int index) check if the value is a dmVMath::Vector3
LuaCallbackInfo* CreateCallback(lua_State* L, int index) Register a Lua callback.
void DestroyCallback(LuaCallbackInfo* cbk) Deletes the Lua callback
lua_State* GetCallbackLuaContext(LuaCallbackInfo* cbk) Gets the Lua context from a callback struct
void GetInstance(lua_State* L) Retrieve current script instance from the global t...
lua_State* GetLuaState(HContext context) Retrieve Lua state from the context
lua_State* GetMainThread(lua_State* L) Retrieve the main thread lua state from any lua st...
const char* GetStringFromHashOrString(lua_State* L, int index, char* buffer, uint32_t buffer_length) Gets as good as possible printable string from a h...
void IsCallbackValid(LuaCallbackInfo* cbk) Check if Lua callback is valid.
bool IsHash(lua_State* L, int index) Check if the value at #index is a hash
bool IsInstanceValid(lua_State* L) Check if the script instance in the lua state is v...
bool IsMatrix4(lua_State* L, int index) Check if the value at #index is a dmVMath::Matrix4...
bool IsQuat(lua_State* L, int index) Check if the value at #index is a dmVMath::Quat*
bool IsURL(lua_State* L, int index) Check if the value at #index is a URL
bool IsVector3(lua_State* L, int index) Check if the value at #index is a dmVMath::Vector3...
bool IsVector4(lua_State* L, int index) Check if the value at #index is a dmVMath::Vector4...
int JsonToLua(lua_State* L, const char* json, size_t json_len) convert a Json string to a Lua table
int LuaToJson(lua_State* L, char** json, size_t* json_len) convert a Lua table to a Json string
int PCall(lua_State* L, int nargs, int nresult) This function wraps lua_pcall with the addition of...
void PushDDF(lua_State* L, const dmDDF::Descriptor* descriptor, const char* data, bool pointers_are_offsets) Push DDF message to Lua stack
void PushHash(lua_State* L, dmhash_t hash) Push a hash value onto the supplied lua state, wil...
void PushMatrix4(lua_State* L, dmVMath::Matrix4 matrix) push a dmVMath::Matrix4 onto the Lua stack
void PushQuat(lua_State* L, dmVMath::Quat quat) push a dmVMath::Quat onto the Lua stack
void PushURL(lua_State* L, dmMessage::URL& url) Push a URL value onto the supplied lua state, will...
void PushVector3(lua_State* L, dmVMath::Vector3 v) push a dmVMath::Vector3 onto the Lua stack
void PushVector4(lua_State* L, dmVMath::Vector4 v) push a dmVMath::Vector4 on the stack
int Ref(lua_State* L, int table) wrapper for luaL_ref.
int RefInInstance(lua_State* L) Creates a reference to the value at top of stack, ...
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::...
int ResolveURL(lua_State* L, dmMessage::URL* out_url, dmMessage::URL* out_default_url) Resolves the value in the supplied index on the lu...
void SetInstance(lua_State* L) Sets the current script instance Set the value on ...
bool SetupCallback(LuaCallbackInfo* cbk) Setups up the Lua callback prior to a call to dmScript::PCall()
void TeardownCallback(LuaCallbackInfo* cbk) Cleans up the stack after SetupCallback+PCall calls
dmhash_t* ToHash(lua_State* L, int index) Check if the value at #index is a hash
dmVMath::Matrix4* ToMatrix4(lua_State* L, int index) get the value at index as a dmVMath::Matrix4*
dmVMath::Quat* ToQuat(lua_State* L, int index) get the value at index as a dmVMath::Quat*
dmhash_t* ToURL(lua_State* L, int index) get the value at index as a dmMessage::URL*
dmVMath::Vector3* ToVector3(lua_State* L, int index) get the value at index as a dmVMath::Vector3*
dmVMath::Vector4* ToVector4(lua_State* L, int index) get the value at index as a dmVMath::Vector4*
void Unref(lua_State* L, int table, int reference) wrapper for luaL_unref.
void UnrefInInstance(lua_State* L, int ref) Deletes the instance local lua reference Expects ...
const char* UrlToString(dmMessage::URL* url, char* buffer, uint32_t buffer_size) Converts a URL into a readable string. Useful for ...
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.

Functions

CheckHash

hash 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 The hash value

CheckHashOrString

hash 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 The hash value

CheckMatrix4

dmVMath::Matrix4* 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

CheckQuat

dmVMath::Quat* 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

CheckTable

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

CheckURL

dmMessage::URL* CheckURL(lua_State* L, int index)

Check if the value in the supplied index on the lua stack is a dmMessage::URL and returns it if so.

PARAMETERS

lua_State* L Lua state
int index Index of the value

RETURNS

dmMessage::URL* The pointer to the value

CheckURL

bool CheckURL(lua_State* L, dmMessage::URL* out_url)

Get the current game object URL

PARAMETERS

lua_State* L Lua state
dmMessage::URL* out_url where to store the result

RETURNS

bool true if successful

CheckVector3

dmVMath::Vector3* 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

CheckVector4

dmVMath::Vector4* 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

CreateCallback

LuaCallbackInfo* CreateCallback(lua_State* L, int 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

lua_State* L Lua state
int index Lua stack index of the function

RETURNS

LuaCallbackInfo* Lua 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
}

DestroyCallback

void DestroyCallback(LuaCallbackInfo* cbk)

Deletes the Lua callback

PARAMETERS

LuaCallbackInfo* cbk Lua callback struct

GetCallbackLuaContext

lua_State* GetCallbackLuaContext(LuaCallbackInfo* cbk)

Gets the Lua context from a callback struct

PARAMETERS

LuaCallbackInfo* cbk Lua callback struct

RETURNS

lua_State* Lua state

GetInstance

void 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

GetLuaState

lua_State* GetLuaState(HContext context)

Retrieve Lua state from the context

PARAMETERS

HContext context the script context

RETURNS

lua_State* the lua state

GetMainThread

lua_State* 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 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;
}

GetStringFromHashOrString

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. "" if the hash could not be looked up.

IsCallbackValid

void IsCallbackValid(LuaCallbackInfo* cbk)

Check if Lua callback is valid.

PARAMETERS

LuaCallbackInfo* cbk Lua callback struct

IsHash

bool 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

bool true if the value at #index is a hash

IsInstanceValid

bool 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

IsMatrix4

bool IsMatrix4(lua_State* L, int index)

Check if the value at #index is a dmVMath::Matrix4*

PARAMETERS

lua_State* L Lua state
int index Index of the value

RETURNS

bool if value at #index is a dmVMath::Matrix4*

IsQuat

bool IsQuat(lua_State* L, int index)

Check if the value at #index is a dmVMath::Quat*

PARAMETERS

lua_State* L Lua state
int index Index of the value

RETURNS

bool if value at #index is a dmVMath::Quat*

IsURL

bool IsURL(lua_State* L, int index)

Check if the value at #index is a URL

PARAMETERS

lua_State* L Lua state
int index Index of the value

RETURNS

bool true if the value at #index is a URL

IsVector3

bool IsVector3(lua_State* L, int index)

Check if the value at #index is a dmVMath::Vector3*

PARAMETERS

lua_State* L Lua state
int index Index of the value

RETURNS

bool if value at #index is a dmVMath::Vector3*

IsVector4

bool IsVector4(lua_State* L, int index)

Check if the value at #index is a dmVMath::Vector4*

PARAMETERS

lua_State* L Lua state
int index Index of the value

RETURNS

bool if value at #index is a dmVMath::Vector4*

JsonToLua

int 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

LuaToJson

int 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.

PCall

int PCall(lua_State* L, int nargs, int 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

lua_State* L lua state
int nargs number of arguments
int nresult number of results

RETURNS

int error code from pcall

PushDDF

void PushDDF(lua_State* L, const dmDDF::Descriptor* descriptor, const char* data, bool pointers_are_offsets)

Push DDF message to Lua stack

PARAMETERS

lua_State* L the Lua state
const dmDDF::Descriptor* descriptor field descriptor
const char* data the message data (i.e. the message struct)
bool pointers_are_offsets True if pointers are offsets

PushHash

void PushHash(lua_State* L, dmhash_t hash)

Push a hash value onto the supplied lua state, will increase the stack by 1.

PARAMETERS

lua_State* L Lua state
dmhash_t hash Hash value to push

PushMatrix4

void 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

PushQuat

void 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

PushURL

void PushURL(lua_State* L, dmMessage::URL& url)

Push a URL value onto the supplied lua state, will increase the stack by 1.

PARAMETERS

lua_State* L Lua state
dmMessage::URL& url URL reference to push

PushVector3

void 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

PushVector4

void 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

Ref

int 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

RefInInstance

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

RefInInstance

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

ResolveURL

int ResolveURL(lua_State* L, dmMessage::URL* out_url, dmMessage::URL* out_default_url)

Resolves the value in the supplied index on the lua stack to a URL. It long jumps (calls luaL_error) on failure. It also gets the current (caller) url if the a pointer is passed to out_default_url

PARAMETERS

lua_State* L Lua state
dmMessage::URL* out_url where to store the result
dmMessage::URL* out_default_url default URL used in the resolve, can be 0x0 (not used)

RETURNS

int 0 if successful. Throws Lua error on failure

SetInstance

void 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

SetupCallback

bool SetupCallback(LuaCallbackInfo* cbk)

The Lua stack after a successful call: 

   [-4] old instance
   [-3] context table
   [-2] callback
   [-1] self
In the event of an unsuccessful call, the Lua stack is unchanged

PARAMETERS

LuaCallbackInfo* cbk Lua callback struct

RETURNS

bool if the setup was successful

TeardownCallback

void TeardownCallback(LuaCallbackInfo* cbk)

Sets the previous instance Expects Lua stack: 

   [-2] old instance
   [-1] context table
Both values are removed from the stack

PARAMETERS

LuaCallbackInfo* cbk Lua callback struct

ToHash

dmhash_t* ToHash(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

dmhash_t* pointer to hash or 0 if it's not a hash

ToMatrix4

dmVMath::Matrix4* 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

ToQuat

dmVMath::Quat* 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

ToURL

dmhash_t* ToURL(lua_State* L, int index)

get the value at index as a dmMessage::URL*

PARAMETERS

lua_State* L Lua state
int index Index of the value

RETURNS

dmhash_t* pointer to URL or 0 if it's not a URL

ToVector3

dmVMath::Vector3* 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

ToVector4

dmVMath::Vector4* 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

Unref

void 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

UnrefInInstance

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

UrlToString

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

Structs

LuaCallbackInfo

TYPE

struct LuaCallbackInfo

callback info struct that will hold the relevant info needed to make a callback into Lua

Types

HContext

The script context

Macros

DM_LUA_ERROR

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;
}

DM_LUA_STACK_CHECK

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);