Awaiting Godot function called form Lua

[TennoAntenno]

I am working on a game where you can code a robot to perform automation tasks.
I have encountered an issue where if I await a function I have made in Godot from Lua, it doesn't wait for it to finish and the script continues running.

For example, I have this code to run the move function. Notice that at the end of the function there's a cooldown

lua.globals["move"] = await func(dir: String):
	if dir != "forward" and dir != "backward":
		print_console("Error: move() direction must be 'forward' or 'backward'\n")
		return
	await call_deferred("move", dir)

func move(dir: String):
	print_console("moving %s\n" % dir)
	var direction := robot.transform.basis.z.normalized()
	robot.position += (-direction if dir == "forward" else direction) * 2
	await get_tree().create_timer(0.5).timeout # 0.5 second  cooldown

If I run this script, the player will move 10 times instantly, instead of waiting for the move function to finish

for i = 1,10 do
	move("forward")
end

The full script:

extends CodeEdit

@export var robot: Node3D
@export var console: Label

func _on_button_pressed() -> void:
	console.text = "" # reset console
	
	var lua = LuaState.new()

	lua.open_libraries(LuaState.LUA_BASE)
	lua.open_libraries(LuaState.LUA_MATH)
	lua.open_libraries(LuaState.GODOT_VARIANT)

	lua.globals["move"] = await func(dir: String):
		if dir != "forward" and dir != "backward":
			print_console("Error: move() direction must be 'forward' or 'backward'")
			return
		await call_deferred("move", dir)
	
	lua.globals["turn"] = await func(dir: String):
		if dir != "left" and dir != "right":
			print_console("Error: turn() direction must be 'left' or 'right'")
			return
		await call_deferred("turn", dir)
	
	lua.globals["print"] = func(text):
		print_console(str(text))
	
	var result = lua.do_string(text)
	if result is LuaError:
		print_console("Lua Error: " + str(result))


func move(dir: String):
	print_console("moving %s" % dir)
	var direction := robot.transform.basis.z.normalized()
	robot.position += (-direction if dir == "forward" else direction) * 2
	await get_tree().create_timer(0.5).timeout


func turn(dir: String):
	print_console("turning %s" % dir)
	robot.rotate_y(PI / 2 if dir == "left" else -PI / 2)
	await get_tree().create_timer(0.5).timeout


func print_console(txt):
	console.text += txt + "\n"

[gilzoide]

Hey @TennoAntenno, thanks for the question.

Unfortunately, right now there's no mechanism in Lua that mimics GDScript's await (it's in the plans, not sure when this will happen though).
I think theoretically you could use a Coroutine and yield when calling the GDScript methods, then resuming the coroutine when the timers end, but this is certainly not ideal and I'm not sure there are sufficient infrastructure for doing this in GDScript (although one could always open the LUA_COROUTINE library and call coroutine.yield() for yielding).

[gilzoide]

Either way, I'd say that blocking Lua scripts by awaiting GDScript coroutines by default is not in the plans, because people could want to run GDScript coroutines async and should be able to choose wether or not they want to await for them.

[TennoAntenno]

Thanks for the help!

I'll try to mess around with the coroutines and see if that's what I'm looking for.

[gilzoide]

Hey @TennoAntenno, so I've been trying to implement the await function in Lua and I think I got it to a usable state. It's in branch feature/await, you can try it out by downloading the lua-gdextension artifact from GitHub Actions and extracting it into your project.

The await Lua function requires opening the GODOT_UTILITY_FUNCTIONS library and should be called from Lua instead of GDScript. You pass either a signal or a GDScript coroutine (the result of a function that calls await in GDScript) to it just like in GDScript and it will automatically yield the current Lua coroutine. When that signal is emitted or the GDScript coroutine completes, the Lua coroutine automatically resumes execution.

First of all, you'd need to run the script in a coroutine instead of using do_string (it's easy, please let me know if you need help with this).
Then you'd need to define the "move" and "turn" functions in Lua to be able to call await from within Lua. You could define a "_move" and "_turn" containing the Callables defined in GDScript, then the Lua counterparts just call them and await afterwards.
Since await is a utility function, you may want to change how you make sandboxing in Lua. I suggest opening whatever libraries you need without worrying too much, then create an environment table containing only the things you want scripts to have access to. Such table will be used as _ENV when running Lua code, you can pass this env table to LuaState.do_string / Lua's load.
Please let me know if you need any further help.

[TennoAntenno]

Hey, Thanks a lot for taking the time to work on this.

I've been trying to run the script in a coroutine, but I haven't had much success. Here's what I've tried:

var main_function = lua.load_string(text)
var result = LuaCoroutine.create(main_function.invoke())
if result is LuaError:
print_console("Lua Error: " + str(result))

I’m also a bit confused about how to define the move and turn functions in Lua. Should they look something like this?

function _move()
        await(move("forward"))
end

And just to confirm, is this the correct way to await a function in Lua? await(move("forward"))
Thanks again!

[gilzoide]

To create a coroutine, you must pass the LuaFunction itself, without invoking it.
After that, you must resume the Coroutine at least once, which would invoke the function for the first time

var coroutine = LuaCoroutine.create(main_function)
var result = coroutine.resume()

I’m also a bit confused about how to define the move and turn functions in Lua. Should they look something like this?

Yes, pretty much something like that =]
You'll want to pass the dir argument to it as well.

GDScript:

# Notice the new name: _move
lua.globals["_move"] = func(dir: String):
	if dir != "forward" and dir != "backward":
		print_console("Error: move() direction must be 'forward' or 'backward'")
		return
	# I think you'll need to inline the "move" function here, or `await(_move())`
	# `call_deferred` returns `null` and is not really awaitable
	# await call_deferred("move", dir)
	print_console("moving %s" % dir)
	var direction := robot.transform.basis.z.normalized()
	robot.position += (-direction if dir == "forward" else direction) * 2
	await get_tree().create_timer(0.5).timeout

Then in Lua:

function move(dir)
	await(_move(dir))
end

Then do the same for "turn".

[gilzoide]

Oh, by the way, LuaCoroutines in this branch also have a "completed" and "failed" signals, so you can hook the "print_console" for the error without worrying about when the coroutine will fail (it could fail after the await and you would not know in the first check for the result).

lua_coroutine.failed.connect(func(err): print_console("Lua Error: " + str(err)))