Home

Awesome

Godot Lua API

Table of contents:

About

Logo Art created by Alex

This is a Godot addon that adds Lua API support via GDScript, C# or GDExtension. Importantly this is NOT meant to be a replacement for or alternative to GDScript. This addon provides no functionality to program your game out of the box. This addon allows you to create custom Modding API's in a sandboxed environment. You have control of what people can and can not do within that sandbox.

To use you can either Compile from source or you can download one of the release builds.

By default the Lua print function is set to print to the GDEditor console. This can be changed by exposing your own print function as it will overwrite the existing one.

Some things to note, this is not the only way to support Modding in your game. It's also not the only way to support Lua Modding in your game. In fact, using this mod to create your Modding API will likely take a lot more work than using native scripts for Modding. However, the advantage using luaAPI over native scripts is that the Lua code is sandboxed. No one can access parts of the engine that you don't explicitly give access to.

If you are looking to make your game using Lua or would like to support Modding without worrying about a sandbox, check out one of these projects:

We will supply a brief overview here. But for more info check out the wiki.

For discussion related to this project feel free to join the Weasel Games Discord or Matrix.

Features

local v1 = Vector2(1,2)
local v2 = Vector2(100.52,100.83)
v2 = v2.floor()
print(v2.x) -- "100"
print(v1+v2) -- "(101,102)"
change_my_sprite_color(Color(1,0,0,1)) -- If "change_my_sprite_color" was exposed, in GDScript it will receive a Color variant.

If a feature is missing that you would like to see feel free to create a Feature Request or submit a PR

Release Builds

Compiling

This build is for godot 4.1.

Getting Started

If you are looking for more in depth information please refer to our wiki.

Pro Tip: Be sure to download the Export Templates! The Export Templates that come with Godot will not work with this Editor/Add-on. Please see Installing Export Templates for more information.

Dotnet users will also want to refer to DOTNET.md For additional information and steps that are needed to make the Editor/Add-on work.

Running Lua for you first time:

extends Node

var lua: LuaAPI = LuaAPI.new()

func _lua_print(message: String) -> void:
	print(message)

func _ready() -> void:
	lua.push_variant("print", _lua_print)
	lua.push_variant("message", "Hello lua!")

	# All builtin libraries are available to bind with. Use OS and IO at your own risk.
	lua.bind_libraries(["base", "table", "string"])

	# Most methods return a LuaError in case of an error
	var err: LuaError = lua.do_string("""
	for i=1,10,1 do
		print(message)
	end
	function get_message()
		return "Hello gdScript!"
	end
	""")
	if err is LuaError:
		print("ERROR %d: %s" % [err.type, err.message])
		return

	var val = lua.pull_variant("get_message")
	if val is LuaError:
		print("ERROR %d: %s" % [val.type, val.message])
		return

	var message = val.call([])
	print(message)

Dotnet (mono) users see example redone in C# in DOTNET.md.

Contributing And Feature Requests

All contributions are welcome, if you would like to contribute submit a PR. <br /> Additionally if you do not have the time and or the knowledge you can create a Feature Request.

lua logo