Skip to content

LuaAPI

Description

The LuaAPI class is used to interact with Lua from GDScript.

This class provides the methods to execute Lua code; to call Lua functions from GDScript; to read and write the value of global Lua variables; to create a Lua constructor for a GDScript class and more.

Enumerations

HookMask

Name Value Description
HOOK_MASK_CALL 1 Bitmask to specify which events the hook will be called for.
HOOK_MASK_RETURN 2 Bitmask to specify which events the hook will be called for.
HOOK_MASK_LINE 4 Bitmask to specify which events the hook will be called for.
HOOK_MASK_COUNT 8 Bitmask to specify which events the hook will be called for.

GCOption

Name Value Description
GC_STOP 0 Stops the garbage collector.
GC_RESTART 1 Restarts the garbage collector.
GC_COLLECT 2 Performs a full garbage-collection cycle.
GC_COUNT 3 Returns the current amount of memory (in Kbytes) in use by Lua.
GC_COUNTB 4 Returns the remainder of dividing the current amount of bytes of memory in use by Lua by 1024.
GC_STEP 5 Performs an incremental step of garbage collection.
GC_SETPAUSE 6 Sets data as the new value for the pause of the collector.
GC_SETSTEPMUL 7 Sets data as the new value for the step multiplier of the collector.

Properties

object_metatable LuaObjectMetatable

This defines the default object metatable to be used when an object does not define a lua_metatable field.

Default value is a LuaDefaultObjectMetatable instance.

memory_limit int

This defines the maximum amount of memory the Lua state can use in bytes. When 0 there is no limit. When the Lua state reaches the memory limit, it will throw a memory allocation error.

Default value is 0.

Methods

bind_libraries void

Takes an array of strings and binds the Lua state to each library. It is case insensitive.

Danger

The IO, Debug, Package and OS libraries have some dangerous methods such as os.execute, require or io.write. Make these libraries available to the end user at your own risk.

Info

You can learn more about the available libraries and their methods in the official Lua manual.

Parameters

Parameters Description
libraries: Array Array of all Lua libraries you would like to make available. The libraries are "base", "coroutine", "debug", "table", "string", "math", "io", "os", "utf8" and "package".

Returns

void

Example

1
2
3
4
5
6
7
8
9
extends Node2D

var lua: LuaAPI

func _ready():
    lua = LuaAPI.new()
    # All libraries are available.
    # Use the OS and IO libraries at your own risk.
    lua.bind_libraries(["base", "table", "string"])

call_function Variant

Calls a global Lua function from GDscript.

You can pass any number of arguments to the Lua function by adding them to the array parameter.

Parameters

Parameters Description
luaFunctionName: String Name of the Lua function to be invoked.
args: Array Array of arguments to be passed to the Lua function.

Returns

Variant

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
extends Node2D

var lua: LuaAPI

func _ready():
    lua = LuaAPI.new()
    lua.bind_libraries(["base"])
    lua.do_file("user://file.lua")

    # Call the "test" Lua function with "Val1", 2 and true as arguments.
    lua.call_function("test", ["Val1", 2, true])
Example: user://file.lua

user://file.lua
function test(myString, myNumber, myBoolean)
    print("I got "..myString..", "..tostring(myNumber)..", "..tostring(myBoolean))
end
Output
I got Val1, 2, true

do_file LuaError?

Loads a file by its absolute path into the Lua state.

Warning

You might experience issues when loading a file in the "res://" directory after the game has been exported. In this case, it is recommended to load the file's contents as a string and use the do_string method instead.

Parameters

Parameters Description
filePath: String Absolute path to the file.

Returns

LuaError or null depending on whether there is an error or not.

Example

1
2
3
4
5
6
7
extends Node2D

var lua: LuaAPI

func _ready():
    lua = LuaAPI.new()
    lua.do_file("user://luaFile.lua")

do_string LuaError?

Loads the content of a string into the Lua state, executing it.

Parameters

Parameters Description
content: String A string containing Lua code to be executed.

Returns

LuaError or null depending on whether there is an error or not.

Examples

1
2
3
4
5
6
7
extends Node2D

var lua: LuaAPI

func _ready():
    lua = LuaAPI.new()
    lua.do_string("for i=1,10,1 do print('Hello lua!') end")

expose_constructor LuaError?

Exposes the constructor of a class to Lua as a global method.

Parameters

Parameters Description
constructorName: String The name of the constructor in Lua.
gdscriptClass: Object A GDScript class or any Object that can be created with the .new method.

Returns

LuaError or null depending on whether there is an error or not.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
extends Node2D
var lua: LuaAPI

class Player:
    var pos = Vector2(0, 0)
    # By default, lua_fields will act as a blacklist. But by setting permissive to false we can make it function as a whitelist.
    func lua_fields():
        return ["pos", "move_forward"]

    func move_forward():
        pos.x += 1

func _ready():
    lua = LuaAPI.new()
        lua.permissive = false
    lua.expose_constructor("Player", Player)
    lua.do_string("player = Player() player.move_forward() print(player.pos.x)")
    var player = lua.pull_variant("player")
    print(player.pos)

The string passed to lua.do_string is the following Lua code:

player = Player()
player.move_forward()
print(player.pos.x)

function_exists bool

Returns true if there is a Lua function with the provided name.

Parameters

Parameters Description
functionName: String The name of the Lua function to check.

Returns

bool

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
extends Node2D

var lua: LuaAPI

func _ready():
    lua = LuaAPI.new()
    lua.do_file("user://file.lua")

    # Check if the "test" Lua function is defined.
    if(lua.function_exists("test")):
        print("yes")
    else:
        print("no")
Example: user://file.lua

user://file.lua
-- The "test" function is defined in Lua.
function test()
    -- Code here...
end
Output
yes

pull_variant Variant

Reads the value of a variable by its name from the Lua state.

Parameters

Parameters Description
variableName: String The name of the Lua variable to read.

Returns

Variant

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
extends Node2D

var lua: LuaAPI

func _ready():
    lua = LuaAPI.new()
    lua.do_string("myNumber = 10")

    # Read the value of myNumber.
    var my_number = lua.pull_variant("myNumber")
    print(my_number)
Output
10

push_variant LuaError?

Pushes a copy of a variant (value) to the Lua stack as the global variable variableName.

Parameters

Parameters Description
variableName: String The name of the Lua variable to write to.
value: Variant The value to be written.

Returns

LuaError or null depending on whether there is an error or not.

Example

1
2
3
4
5
6
7
8
9
extends Node2D

var lua: LuaAPI
var test = "Hello Lua!"

func _ready():
    lua = LuaAPI.new()
    lua.push_variant("str", test)
    lua.do_string("print(str)")
Output
Hello Lua!

set_hook void

Sets the hook for the state. The hook will be called on the events specified by the mask. The count specifies how many instructions should be executed before the hook is called. If count is 0, the hook will be called on every instruction. The hook will be called with the following arguments: hook(parent, event, line). The parent is the LuaAPI object that owns the current state.

This is useful for preventing infinite loops, but it should be kept in mind there will be a large performance tax.

Parameters

Parameters Description
hook: Callable The function to be called as a hook.
mask: int The hook even mask.
count: int Specifies how many instructions should be executed before the hook.

Returns

void

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
extends Node2D

var lua: LuaAPI
var coroutine: LuaCoroutine

func _lua_hook(lua: LuaAPI, event: int, line: int):
    var co: LuaCoroutine = lua.get_running_coroutine()
    co.yield_state([1])

func _ready():
    lua = LuaAPI.new()
    # Despite the name, this is not like a OS coroutine. It is a coroutine.
    coroutine = lua.new_coroutine()
    coroutine.set_hook(_lua_hook, lua.HOOK_MASK_COUNT, 8)
    coroutine.load_string("
    for i=1,2,1 do
        print('Hello world!')
    end
    ")

var yieldTime = 0
var timeSince = 0
var goodBye = false
func _process(delta):
    timeSince += delta
    # If the coroutine has finished executing or if not enough time has passed, do not resume the coroutine.
    if coroutine.is_done() || timeSince <= yieldTime:
        if !goodBye:
            lua.do_string("""
            for i = 0,4,1 do 
                print('Good Bye World!')
            end
            """)
            goodBye=true
        return
    goodBye=false
    # coroutine.resume will either return a LuaError or an Array.
    var ret = coroutine.resume([])
    if ret is LuaError:
        print("ERROR %d: " % ret.type + ret.message)
        return
    if coroutine.is_done():
        return

    yieldTime = ret[0]
    timeSince = 0
Output
Hello world!
Good Bye World!
Good Bye World!
Good Bye World!
Good Bye World!
Good Bye World!
Hello world!
Good Bye World!
Good Bye World!
Good Bye World!
Good Bye World!
Good Bye World!

configure_gc int

Controls the garbage collector. The option can be one of the following: GC_STOP, GC_RESTART, GC_COLLECT, GC_COUNT, GC_STEP, GC_SETPAUSE, GC_SETSTEPMUL. The data is the argument for the option. Returns the result of the option.

For more info, see the lua manual https://www.lua.org/manual/5.4/manual.html#lua_gc

Parameters

Parameters Description
option: int The GCOption.
data: int Argument for the specific option.

Returns

int

new_coroutine LuaCoroutine

Creates and binds a LuaCoroutine object to a LuaAPI object. This method is equivalent to creating a new coroutine object and then calling its bind method.

Returns

LuaCoroutine

get_running_coroutine LuaCoroutine

Intended to be called from a lua hook. Returns the current running coroutine.

Returns

LuaCoroutine

get_memory_usage int

Returns the current memory usage of the Lua state in bytes.

Returns

int