Lua Scripting

Description

Execute lightweight lua code within the engine.

Typedefs
using	tz::lua_fn = int(*)()
	Represents the signature for a function that can be called from lua.

Function Documentation

lua_execute_file()

tz::error_code tz::lua_execute_file

(

std::filesystem::path

path

)

Attempt to execute a local lua file on the current thread.

Parameters

path	Path to a local file containing lua code.

Returns

tz::error_code::precondition_failure If the provided path was invalid.

tz::error_code::unknown_error If the executed code caused an error.

lua_execute()

tz::error_code tz::lua_execute

(

std::string_view

lua_src

)

Attempt to execute some lua code on the current thread.

Parameters

lua_src

String containing lua code to execute.

Returns

tz::error_code::unknown_error If the executed code caused an error.

lua_set_nil()

tz::error_code tz::lua_set_nil

(

std::string_view

varname

)

Set a variable in lua to be nil.

Parameters

varname

Name of the variable to set.

Returns

tz::error_code::unknown_error If an error occurred.

lua_set_emptytable()

tz::error_code tz::lua_set_emptytable

(

std::string_view

varname

)

Set a variable in lua to be the empty table "{}".

Parameters

varname

Name of the variable to set.

Returns

tz::error_code::unknown_error If an error occurred.

lua_set_bool()

tz::error_code tz::lua_set_bool	(	std::string_view	varname,
		bool	v )

Set a variable in lua to a new bool value.

Parameters

varname	Name of the variable to set.
v	Value to set

Returns

tz::error_code::unknown_error If an error occurred.

lua_set_int()

tz::error_code tz::lua_set_int	(	std::string_view	varname,
		std::int64_t	v )

Set a variable in lua to a new int value.

Parameters

varname	Name of the variable to set.
v	Value to set

Returns

tz::error_code::unknown_error If an error occurred.

lua_set_number()

tz::error_code tz::lua_set_number	(	std::string_view	varname,
		double	v )

Set a variable in lua to a new number value.

Parameters

varname	Name of the variable to set.
v	Value to set

Returns

tz::error_code::unknown_error If an error occurred.

lua_set_string()

tz::error_code tz::lua_set_string	(	std::string_view	varname,
		std::string	str )

Set a variable in lua to a new string value.

Parameters

varname	Name of the variable to set.
str	Value to set

Returns

tz::error_code::unknown_error If an error occurred.

lua_define_function()

tz::error_code tz::lua_define_function	(	std::string_view	varname,
		lua_fn	fn )

Define a new function in lua.

Parameters

varname	Name of the function when called in lua code.
fn	Pointer to an existing function to expose to lua.

Returns

tz::error_code::unknown_error If an error occurred.

lua_get_bool()

std::expected< bool, tz::error_code > tz::lua_get_bool

(

std::string_view

varname

)

Retrieve the value of a bool variable.

Parameters

varname

Name of the variable to retrieve.

Returns

tz::error_code::precondition_failure If such a variable does not exist, or does not match the type you requested.

lua_get_int()

std::expected< std::int64_t, tz::error_code > tz::lua_get_int

(

std::string_view

varname

)

Retrieve the value of a int variable.

Parameters

varname

Name of the variable to retrieve.

Returns

tz::error_code::precondition_failure If such a variable does not exist, or does not match the type you requested.

lua_get_number()

std::expected< double, tz::error_code > tz::lua_get_number

(

std::string_view

varname

)

Retrieve the value of a number variable.

Parameters

varname

Name of the variable to retrieve.

Returns

tz::error_code::precondition_failure If such a variable does not exist, or does not match the type you requested.

lua_get_string()

std::expected< std::string, tz::error_code > tz::lua_get_string

(

std::string_view

varname

)

Retrieve the value of a string variable.

Parameters

varname

Name of the variable to retrieve.

Returns

tz::error_code::precondition_failure If such a variable does not exist, or does not match the type you requested.

lua_stack_get_bool()

std::expected< bool, tz::error_code > tz::lua_stack_get_bool

(

std::size_t

id

)

Retrieve a bool from the stack at the given index.

Parameters

id	Position on the stack to retrieve.

Returns

tz::error_code::precondition_failure If the stack is too small, or the value at the position you specifies does not match the type you asked for.

lua_stack_get_int()

std::expected< std::int64_t, tz::error_code > tz::lua_stack_get_int

(

std::size_t

id

)

Retrieve a int from the stack at the given index.

Parameters

id	Position on the stack to retrieve.

Returns

tz::error_code::precondition_failure If the stack is too small, or the value at the position you specifies does not match the type you asked for.

lua_stack_get_number()

std::expected< double, tz::error_code > tz::lua_stack_get_number

(

std::size_t

id

)

Retrieve a number from the stack at the given index.

Parameters

id	Position on the stack to retrieve.

Returns

tz::error_code::precondition_failure If the stack is too small, or the value at the position you specifies does not match the type you asked for.

lua_stack_get_string()

std::expected< std::string, tz::error_code > tz::lua_stack_get_string

(

std::size_t

id

)

Retrieve a string from the stack at the given index.

Parameters

id	Position on the stack to retrieve.

Returns

tz::error_code::precondition_failure If the stack is too small, or the value at the position you specifies does not match the type you asked for.

lua_push_nil()

void tz::lua_push_nil

(

)

Push a nil value onto the stack.

lua_push_bool()

void tz::lua_push_bool

(

bool

v

)

Push a bool value onto the stack.

lua_push_int()

void tz::lua_push_int

(

std::int64_t

v

)

Push an int value onto the stack.

lua_push_number()

void tz::lua_push_number

(

double

v

)

Push a number value onto the stack.

lua_push_string()

void tz::lua_push_string

(

std::string

v

)

Push a string value onto the stack.

lua_stack_size()

std::size_t tz::lua_stack_size

(

)

Retrieve the number of values on the stack currently.

lua_debug_callstack()

std::string tz::lua_debug_callstack

(

)

Retreieve a string describing the lua callstack right now.

This might be useful for debugging purposes.

lua_debug_stack()

std::string tz::lua_debug_stack

(

)

Retreieve a string describing the entire lua stack right now.

This might be useful for debugging purposes.

lua_parse_args()

template<typename... Ts>

std::tuple< Ts... > tz::lua_parse_args

(

)

Retreve a set of arguments from the stack.

Precondition

The values on the top of the stack must perfectly correspond to the type parameters you pass in, otherwise a runtime error will occur. You are recommended to use this in your own lua_fn functions that you expose to lua via lua_define_function.

Typedef Documentation

lua_fn

using tz::lua_fn = int(*)()

Represents the signature for a function that can be called from lua.

You might be expecting int(lua_State*) if you're used to using Lua directly. However, lua headers are not available to you, so this is the only signature you will worry about. Like in default lua, the return value of any lua function represents how many values you have returned (put onto the stack). To retrieve an argument in a lua function, you can either:

• Call lua_stack_get_bool or similar. This is useful if you conditionally need only a particular argument.
• Call lua_parse_args to retrieve all the arguments of your function at once. This is recommended for most use-cases.

Example: C function callable in lua:

int fnimpl()
{
     auto [arg1, arg2] = tz::lua_parse_args<int, std::string>();
     lua_push_int(arg1 * 2);
     lua_push_string(arg2 + " is cool");
     return 2;
}
// In your application initialisation code:
tz::lua_define_function("my_cool_function", fnimpl);

In your lua code:

ret1, ret2 = my_cool_function(123, "Bob" .. " Marley")