Script

Built-in scripting functions.

HContext

The script context

The script context


DM_LUA_STACK_CHECK

helper macro to validate the Lua stack state before leaving a function.

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.

PARAMETERS

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


DM_LUA_ERROR

helper macro to validate the Lua stack state and throw a 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.

PARAMETERS

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


dmScript::Ref(L, table)

wrapper for luaL_ref.

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

L - lua state

table - table the lua table that stores the references. E.g LUA_REGISTRYINDEX

RETURN

reference - the new reference


dmScript::Unref(L, table, reference)

wrapper for luaL_unref.

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

L - lua state

table - table the lua table that stores the references. E.g LUA_REGISTRYINDEX

reference - the reference to the object


dmScript::GetInstance(L)

Retrieve current script instance from the global t...

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

L - lua state


dmScript::SetInstance(L)

Sets the current script instance Set the value on ...

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

L - lua state


dmScript::IsInstanceValid(L)

Check if the script instance in the lua state is v...

Check if the script instance in the lua state is valid. The instance is assumed to have been previously set by dmScript::SetInstance.

PARAMETERS

L - lua state

RETURN

boolean - Returns true if the instance is valid


dmScript::GetMainThread(L)

Retrieve the main thread lua state from any lua st...

Retrieve the main thread lua state from any lua state (main thread or coroutine).

PARAMETERS

L - lua state

RETURN

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


dmScript::ToVector3(L, index)

get the value at index as a dmVMath::Vector3*

Get the value at index as a dmVMath::Vector3*

PARAMETERS

L - Lua state

index - Index of the value

RETURN

v - The pointer to the value, or 0 if not correct type


dmScript::IsVector3(L, index)

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

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

PARAMETERS

L - Lua state

index - Index of the value

RETURN

true - if value at #index is a dmVMath::Vector3*


dmScript::PushVector3(L, v)

push a dmVMath::Vector3 onto the Lua stack

Push a dmVMath::Vector3 value onto the supplied lua state, will increase the stack by 1.

PARAMETERS

L - Lua state

v - Vector3 value to push


dmScript::CheckVector3(L, index)

check if the value is a dmVMath::Vector3

Check if the value in the supplied index on the lua stack is a dmVMath::Vector3.

PARAMETERS

L - Lua state

index - Index of the value

RETURN

vector3 - The pointer to the value


dmScript::ToVector4(L, index)

get the value at index as a dmVMath::Vector4*

Get the value at index as a dmVMath::Vector4*

PARAMETERS

L - Lua state

index - Index of the value

RETURN

v - The pointer to the value, or 0 if not correct type


dmScript::IsVector4(L, index)

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

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

PARAMETERS

L - Lua state

index - Index of the value

RETURN

true - if value at #index is a dmVMath::Vector4*


dmScript::PushVector4(L, v)

push a dmVMath::Vector4 on the stack

Push a dmVMath::Vector4 value onto the supplied lua state, will increase the stack by 1.

PARAMETERS

L - Lua state

v - dmVMath::Vector4 value to push


dmScript::CheckVector4(L, index)

check if the value is a dmVMath::Vector3

Check if the value in the supplied index on the lua stack is a dmVMath::Vector3.

PARAMETERS

L - Lua state

index - Index of the value

RETURN

vector4 - The pointer to the value


dmScript::ToQuat(L, index)

get the value at index as a dmVMath::Quat*

Get the value at index as a dmVMath::Quat*

PARAMETERS

L - Lua state

index - Index of the value

RETURN

quat - The pointer to the value, or 0 if not correct type


dmScript::IsQuat(L, index)

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

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

PARAMETERS

L - Lua state

index - Index of the value

RETURN

true - if value at #index is a dmVMath::Quat*


dmScript::PushQuat(L, quat)

push a dmVMath::Quat onto the Lua stack

Push a quaternion value onto Lua stack. Will increase the stack by 1.

PARAMETERS

L - Lua state

quat - dmVMath::Quat value to push


dmScript::CheckQuat(L, index)

check if the value is a dmVMath::Vector3

Check if the value in the supplied index on the lua stack is a dmVMath::Quat.

PARAMETERS

L - Lua state

index - Index of the value

RETURN

quat - The pointer to the value


dmScript::ToMatrix4(L, index)

get the value at index as a dmVMath::Matrix4*

Get the value at index as a dmVMath::Matrix4*

PARAMETERS

L - Lua state

index - Index of the value

RETURN

quat - The pointer to the value, or 0 if not correct type


dmScript::IsMatrix4(L, index)

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

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

PARAMETERS

L - Lua state

index - Index of the value

RETURN

true - if value at #index is a dmVMath::Matrix4*


dmScript::PushMatrix4(L, matrix)

push a dmVMath::Matrix4 onto the Lua stack

Push a matrix4 value onto the Lua stack. Will increase the stack by 1.

PARAMETERS

L - Lua state

matrix - dmVMath::Matrix4 value to push


dmScript::CheckMatrix4(L, index)

check if the value is a dmVMath::Matrix4

Check if the value in the supplied index on the lua stack is a dmVMath::Matrix4.

PARAMETERS

L - Lua state

index - Index of the value

RETURN

matrix - The pointer to the value


dmScript::IsHash(L, index)

Check if the value at #index is a hash

Check if the value at #index is a hash

PARAMETERS

L - Lua state

index - Index of the value

RETURN

true - if the value at #index is a hash


dmScript::PushHash(L, hash)

Push a hash value onto the supplied lua state, wil...

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

PARAMETERS

L - Lua state

hash - dmhash_t Hash value to push


dmScript::CheckHash(L, index)

get hash value

Check if the value in the supplied index on the lua stack is a hash.

PARAMETERS

L - Lua state

index - Index of the value

RETURN

The - hash value


dmScript::CheckHashOrString(L, index)

get hash from hash or string

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

L - Lua state

index - Index of the value

RETURN

The - hash value


GetStringFromHashOrString(L, index, buffer, buffer_length)

Gets as good as possible printable string from a h...

Gets as good as possible printable string from a hash or string

PARAMETERS

L - Lua state

index - Index of the value

buffer - buffer receiving the value

buffer_length - the buffer length

RETURN

string - Returns buffer. If buffer is non null, it will always contain a null terminated string. "" if the hash could not be looked up.


dmScript::JsonToLua(L, json, json_len)

convert a Json string to a Lua table

Convert a Json string to Lua table.

PARAMETERS

L - lua state

json - json string

json_len - length of json string

RETURN

int - 1 if it succeeds. Throws a Lua error if it fails


dmScript::LuaToJson(L, json, json_len)

convert a Lua table to a Json string

Convert a Lua table to a Json string

PARAMETERS

L - lua state

json - [out] Pointer to char*, which will receive a newly allocated string. Use free().

json_len - length of json string

RETURN

int - <0 if it fails. >=0 if it succeeds.


dmScript::LuaCallbackInfo()

callback info struct

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


dmScript::CreateCallback(L, index)

Register a Lua callback.

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

RETURN

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
}


dmScript::IsCallbackValid(cbk)

Check if Lua callback is valid.

Check if Lua callback is valid.

PARAMETERS

cbk - Lua callback struct


dmScript::DestroyCallback(cbk)

Deletes the Lua callback

Deletes the Lua callback

PARAMETERS

cbk - Lua callback struct


dmScript::GetCallbackLuaContext(cbk)

Gets the Lua context from a callback struct

Gets the Lua context from a callback struct

PARAMETERS

cbk - Lua callback struct

RETURN

L - Lua state


dmScript::SetupCallback(cbk)

Setups up the Lua callback prior to a call to dmScript::PCall()

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

cbk - Lua callback struct

RETURN

true - if the setup was successful


dmScript::TeardownCallback(cbk)

Cleans up the stack after SetupCallback+PCall calls

Sets the previous instance Expects Lua stack:

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

PARAMETERS

cbk - Lua callback struct


dmScript::PCall(L, nargs, nresult)

This function wraps lua_pcall with the addition of...

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

RETURN

error - code from pcall


RefInInstance(L)

Creates a reference to the value at top of stack, ...

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

L - Lua state

RETURN

lua - ref to value or LUA_NOREF Lua stack on entry [-1] value Lua stack on exit


UnrefInInstance(L, ref)

Deletes the instance local lua reference Expects ...

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

L - Lua state

ref - ref to value or LUA_NOREF Lua stack on entry Lua stack on exit


RefInInstance(L, url, out_url, default_url)

Resolves a url in string format into a dmMessage::...

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

L - Lua state

url - url

out_url - where to store the result

default_url - default url

RETURN

result - dmMessage::RESULT_OK if the conversion succeeded


UrlToString(url, buffer, buffer_size)

Converts a URL into a readable string. Useful for ...

Converts a URL into a readable string. Useful for e.g. error messages

PARAMETERS

url - url

buffer - the output buffer

buffer_size - the output buffer size

RETURN

buffer - returns the passed in buffer


CheckTable(L, buffer, buffer_size, index)

Serialize a table to a buffer Supported types: LUA...

Serialize a table to a buffer Supported types: LUA_TBOOLEAN, LUA_TNUMBER, LUA_TSTRING, Point3, Vector3, Vector4 and Quat Keys must be strings

PARAMETERS

L - Lua state

buffer - Buffer that will be written to (must be DM_ALIGNED(16))

buffer_size - Buffer size

index - Index of the table

RETURN

result - Number of bytes used in buffer


CheckGOInstance(L)

Get current game object instance Works in both gam...

Get current game object instance Works in both gameobjects and gui scripts

PARAMETERS

L - lua state

RETURN

instance -


CheckGOInstance(L, index)

Get gameobject instance The instance reference (u...

Get gameobject instance The instance reference (url) at stack index "index" will be resolved to an instance.

PARAMETERS

L - lua state

index - lua-arg

RETURN

instance - gameobject instance

EXAMPLES

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


CheckCollection(L, index)

Get current gameobject's collection handle

Get current gameobject's collection handle

PARAMETERS

L - lua state

index - lua-arg

RETURN

instance - gameobject instance


GetComponentFromLua(L, index, component_type, world, component, url)

Get component user data from a url.

Get component user data from a url.

PARAMETERS

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


LuaBufferOwnership

buffer ownership

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

MEMBERS

dmScript::OWNER_C -

dmScript::OWNER_LUA -

dmScript::OWNER_RES -


dmScript::LuaHBuffer()

Lua wrapper for a dmBuffer::HBuffer

Holds info about the buffer and who owns it.

MEMBERS

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

EXAMPLES

See examples for dmScript::PushBuffer()


dmScript::IsBuffer(L, index)

check if the value is a dmScript::LuaHBuffer

Check if the value is a dmScript::LuaHBuffer

PARAMETERS

L - lua state

index - Index of the value

RETURN

boolean - True if value at index is a LuaHBuffer


dmScript::PushBuffer(L, buffer)

push a LuaHBuffer onto the supplied lua state

Will increase the stack by 1.

PARAMETERS

L - lua state

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);
How to push a buffer and keep ownership in C++
dmScript::LuaHBuffer luabuf(buffer, dmScript::OWNER_C);
PushBuffer(L, luabuf);


dmScript::CheckBuffer(L, index)

retrieve a LuaHBuffer from the supplied lua state

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

L - lua state

index - Index of the value

RETURN

buffer - pointer to dmScript::LuaHBuffer


dmScript::CheckBufferNoError(L, index)

retrieve a LuaHBuffer from the supplied lua state.

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

L - lua state

index - Index of the value

RETURN

buffer - pointer to dmScript::LuaHBuffer or 0 if not valid


dmScript::CheckBufferUnpack(L, index)

retrieve a HBuffer from the supplied lua state

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

L - lua state

index - Index of the value

RETURN

buffer - buffer if valid, 0 otherwise


dmScript::CheckBufferUnpackNoError(L, index)

retrieve a HBuffer from the supplied lua state

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

L - lua state

index - Index of the value

RETURN

buffer - buffer if valid, 0 otherwise