Godot Lua PluginScript

GDNative + PluginScript library that adds support for Lua as a scripting language in Godot.

Being a GDNative library, recompiling the engine is not required, so anyone with a built release copied to their project can use it. Being a PluginScript language, Lua can seamlessly communicate with scripts written in GDScript / C# / Visual Script and vice-versa. Since the Godot object model is dynamic at runtime, any Godot objects' properties/methods can be accessed from Lua, including singletons like OS, ClassDB and custom singleton nodes. This way, one can use the language that best suits the implementation for each script and all of them can understand each other.

This plugin is available in the Asset Library as Lua PluginScript.

For some usage examples, check out lps_coroutine.lua and plugin/lua_repl.lua.

Currently, only LuaJIT is supported, since the implementation is based on its FFI library.

Installing

Either:

In Godot Editor, open the Asset Library tab, search for the Lua PluginScript asset, download and install it.
Put a built release of the library into the project folder and restart Godot. Make sure the lua_pluginscript.gdnlib file is located at the res://addons/godot-lua-pluginscript folder.
Clone this repository as the project's res://addons/godot-lua-pluginscript folder and build for the desired platforms.

Documentation

Goals

Provide support for Lua as a scripting language in Godot in a way that does not require compiling the engine from scratch
Be able to seamlessly communicate with any other language supported by Godot, like GDScript, Visual Script and C#, in an idiomatic way. This includes being able to dynamically access any Godot object's properties and methods using Lua's index/method notation
Have automatic global access to Godot's singleton objects and custom singleton nodes
Simple script description interface that doesn't need requireing anything
Support for LuaJIT and Lua 5.2+
Support paths relative to res://* and exported game/app executable path for requireing Lua modules
Have a simple build process, where anyone with the cloned source code and installed build system + toolchain can build the project in a single step

Non-goals

Provide calls to core Godot classes' methods via native method bindings
Support multithreading on the Lua side

Articles

Designing Godot Lua PluginScript
Implementing the library's skeleton
Integrating LuaJIT and FFI
Initializing and finalizing scripts (TODO)

Script example

This is an example of how a Lua script looks like.

-- Class definitions are regular Lua tables, to be returned from the script
local MyClass = {}

-- Optional: set class as tool, defaults to false
MyClass.is_tool = true

-- Optional: set base class by name, defaults to 'Reference'
MyClass.extends = Node

-- Optional: give your class a name
MyClass.class_name = 'MyClass'

-- Declare signals
MyClass.something_happened = signal()
MyClass.something_happened_with_args = signal("arg1", "arg2")

-- Values defined in table are registered as properties of the class
-- By default, properties are not exported to the editor
MyClass.some_prop = 42

-- The property function adds metadata to defined properties,
-- like setter and getter functions
MyClass.some_prop_with_details = property {
  -- ["default_value"] or ["default"] or [1] = property default value
  5,
  -- ["type"] or [2] = variant type, optional, inferred from default value
  -- All Godot variant type names are defined globally as written in
  -- GDScript, like bool, int, float, String, Array, Vector2, etc...
  -- Notice that Lua <= 5.2 does not differentiate integers from float
  -- numbers, so we should always specify int where appropriate
  -- or use int(5) in the default value instead
  type = int,
  -- ["get"] or ["getter"] = getter function or method name, optional
  get = function(self)
    return self.some_prop_with_details
  end,
  -- ["set"] or ["setter"] = setter function or method name, optional
  set = 'set_some_prop_with_details',
  -- ["usage"] = property usage, from enum godot_property_usage_flags
  -- optional, default to PropertyUsage.NOEDITOR
  usage = PropertyUsage.NOEDITOR,
  -- ["hint"] = property hint, from enum godot_property_hint
  -- optional, default to PropertyHint.NONE
  hint = PropertyHint.RANGE,
  -- ["hint_string"] = property hint text, only required for some hints
  hint_string = '1,10',
  -- ["rset_mode"] = property remote set mode, from enum godot_method_rpc_mode
  -- optional, default to RPCMode.DISABLED
  rset_mode = RPCMode.MASTER,
}
-- The export function is an alias for property that always exports
-- properties to the editor
MyClass.exported_prop = export { "This property appears in the editor" }
MyClass.another_exported_prop = export {
  [[This one also appears in the editor,
now with a multiline TextArea for edition]],
  hint = PropertyHint.MULTILINE_TEXT,
}

-- Functions defined in table are public methods
function MyClass:_ready()  -- function t:f(...) is an alias for function t.f(self, ...)
  -- Singletons are available globally
  local os_name = OS:get_name()
  print("MyClass instance is ready! Running on a " .. os_name .. " system")

  -- There is no onready keyword like in GDScript
  -- Just get the needed values on _ready method
  -- Also, Lua doesn't have the $child_node syntax, use get_node instead
  self.some_grandchild_node = self:get_node("some/grandchild_node")
end

function MyClass:set_some_prop_with_details(value)
    self.some_prop_with_details = value
    -- Indexing self with keys undefined in script will search base
    -- class for methods and properties
    self:emit_signal("something_happened_with_args", "some_prop_with_details", value)
end

function MyClass:get_some_prop_doubled()
  return self.some_prop * 2
end

-- In the end, table with class declaration must be returned from script
return MyClass

Status

[X] LuaJIT support
[ ] Lua 5.2+ support
[X] Useful definitions for all GDNative objects, with methods and metamethods
[X] A yield function similar to GDScript's, to resume after a signal is emitted (GD.yield)
[X] Working PluginScript language definition
[X] PluginScript script validation and template source code
[ ] PluginScript code editor callbacks
[ ] PluginScript debug callbacks
[ ] PluginScript profiling callbacks
[X] Package searcher for Lua and C modules that work with paths relative to the res:// folder and/or exported games' executable path
[X] Lua REPL
[X] API documentation
[ ] Unit tests
[ ] Example projects
[X] Export plugin to minify Lua scripts
[X] Drop-in binary release in GitHub
[X] Submit to Asset Library

Third-party software

This project uses the following software:

godot-headers: headers for GDNative, distributed under the MIT license
LuaJIT: Just-In-Time Compiler (JIT) for the Lua programming language, distributed under the MIT license
High Level GDNative (HGDN): higher level GDNative API header, released to the Public Domain
LuaSrcDiet: compresses Lua source code by removing unnecessary characters, distributed under the MIT license
LuaUnit: unit-testing framework for Lua, distributed under the BSD license
debugger.lua: dependency free, single file embeddable debugger for Lua, distributed under the MIT license

Other projects for using Lua in Godot

https://github.com/perbone/luascript
https://github.com/Trey2k/lua
https://github.com/zozer/godot-lua-module

Godot Lua PluginScript

Contents

Topics

Modules

Scripts

Classes

Examples

Godot Lua PluginScript

Installing

Documentation

Goals

Non-goals

Articles

Script example

Status

Third-party software

Other projects for using Lua in Godot