LuaMachine

Unreal Engine Plugin for adding Lua scripting to your projects.

If you want modders to customize your game/project, or you need to allow game designers to script parts of the logic, or more generally you want a framework for adding lua scripting capabilities to your projects, this plugin is for you.

Note: The master branch is focused on Unreal Engine 5, if you need Unreal Engine 4 support use the ue4 branch.

Experimental LuaU (https://luau.org/) support is available (for Windows) in the "luau" branch.

How it works

Contrary to the other Unreal Engine Lua plugins, this one does not try to automatically expose the Unreal Engine api, but completely hides it giving to the user/scripter only the features the developer decided to include (via Blueprints or C++). An advanced api for using/abusing Unreal Engine Reflection is included too.

Currently Windows 64bit, Mac, Linux x86_64 (both Runtime and Editor), Linux AArch64, Android (32 and 64 bit) and iOS are supported. Minimal supported Engine version is 4.20.

Discord Channel

Join the LuaMachine Discord channel: https://discord.gg/eTXDfEU

Marketplace

Albeit fully open source and free, you can find the plugin in the Unreal Engine Marketplace for about 30$. If you want to sponsor the project consider buying it:

https://www.unrealengine.com/marketplace/en-US/product/luamachine

Becoming a patron

Consider sponsoring the project using patreon: https://www.patreon.com/rdeioris

Quickstart

In this fast (and useless) example we will print a string generated by a Lua script.

Install the LuaMachine plugin by downloading it from the official github releases page (free, but you need to compile it) or from the Marketplace (ready to use, about 30$):

https://github.com/rdeioris/LuaMachine/releases/

https://www.unrealengine.com/marketplace/luamachine

To compile from sources, decompress the zip file in the Plugins/ directory of your project (create it if it does not exist) and restart the Unreal Editor. (if you want to manually compile it, ensure C++ is enabled in your project and regenerate the solution/xcode file)

Open your favourite editor for lua scripting and create a file into the project Content/ directory (call it hello.lua) with the following code:

current_time = os.date()
return "Hello, i am a lua script, current time is: " .. current_time

Now you need to create a new LuaState, it is a special Blueprint representing a Lua Virtual Machine (you can have multiple Lua virtual machines in the same project). Just add a new blueprint inheriting from LuaState and name as you want (QuickLuaState is a good candidate).

Finally open your Level Blueprint and add the following nodes:

If you play the game, you will see the Lua string printed on top.

The LuaRunFile node will execute a lua file (relative to the Content/ directory) in the specified LuaState (QuickLuaState in our case) and will return the value returned by the script itself as a LuaValue UStruct. The plugin offers a bunch of operations you can apply to LuaValue's, in this example we simply converted the value to an Unreal String.

Time to something more complex, edit your hello.lua script:

function call_me_from_unreal(number)
  return number * 2
end

current_time = os.date()
return "Hello, i am a lua script, current time is: " .. current_time

Now the script will add the call_me_from_unreal function to the global table:

The LuaGlobalCall node calls a function from the global table passing arguments as an array of LuaValue's.

So, now we know how to call lua functions from Unreal, time to do the opposite.

Open the QuickLuaState Blueprint you created before. This Blueprint exposes lot of different fields to configure your Lua Virtual Machine:

The Table 'TMap' allows you to add items to the Lua global table. We will first try by adding a string and a number (float):

Note that we set the "Lua Filename" field to hello.lua, in this way we can avoid to call the LuaRunFile node as hello.lua will be executed during the spawn of the QuickLuaState.

Let's modify our Level Blueprint:

The hello.lua script is loaded automatically, while the LuaGetGlobal nodes, retrieve the specific fields from the Lua global table, and return them as LuaValue's

Time to expose an Unreal UFunction to Lua: just add a Function to QuickLuaState:

and expose it in the Table TMap:

calling get_player_location() from lua, will trigger the QuickLuaState's GetPlayerPawnLocation(). Note that not all of the UFunction's can be exposed: if they take or return values they must be LuaValue's

Let's update hello.lua

function call_me_from_unreal(number)
    location = get_player_location()
    print(location.x, location.y, location.z)
    return number * 2 + location.x + location.y + location.z
end

current_time = os.date()
return "Hello, i am a lua script, current time is: " .. current_time

and the Level Blueprint:

Please check the print() function: it is automatically mapped to the Unreal Output Log by the plugin.

Now you should have an idea of the plugin potential, continue reading for more infos.

LuaState

A LuaState (ULuaState C++ class) represents a single Lua virtual machine (there can be multiple, each one isolated from the others). This is a "singleton" as each LuaState class can have a single instance for the whole process life. (Note that while in the Editor, LuaState's are constantly recreated whenever you enter PIE mode to simplify development)

Having multiple LuaState's allows clean separation of domains: as an example you may want a state for game configuration, another one for game logic and one for the modders. More complex examples include having states dedicated to specific Actors, GameModes or Levels.

LuaState's are loaded on-demand, so you can create dozens of them but they will not start Lua VMs until you need them.

LuaState's can load and execute scripts automatically if you specify the fields "LuaCodeAsset" and/or "LuaFilename". You can load scripts (both in text and bytecode format) from your filesystem (via "LuaFilename"), or from a specific asset exposed by the plugin, named LuaCode (you can specify it with the "LuaCodeAsset" field). The advantage of using filesystem scripts is that you can change them even after the project has been packaged (unless you package them too), while LuaCode assets are directly built in your pak files (as bytecode by default).

LuaState Properties

• LuaCodeAsset: specify a LuaCode asset to automatically load an execute on spawn
• LuaFileName: specify a script path (relative to Content/) to load and execute on spawn
• Table: TMap<FString, FLuaValue> allows adding FLuaValue's to the Lua VM global table
• RequireTable: TMap<FString, ULuaCode> allows to map LuaCode assets to specific name, so you can call require('name') from your code
• LuaOpenLibs: if true, automatically load the lua standard library on spawn
• AddProjectContentDirToPackage: if true, when doing require('name') will search for 'name.lua' in the Content/ directory
• AppendProjectContentDirToPackage: TArray<FString> allows specifying a list of Content/ subdirectories to search for packages (while doing require('name'))
• OverridePackagePath: (advanced users) allows to modify package.path
• OverridePackageCPath: (advanced users) allows to modify package.cpath
• LogError: enable/disable logging of Lua errors

LuaState Events

The "LuaError" event is exposed by ULuaState.

If defined, it will be triggered whenever the Lua VM generates an error. The Error message is passed as an argument. This is really useful for adding in-game consoles, or to catch specific errors.

LuaMachine Debugger

A Simple Lua Debugger is included in the plugin (you can find it under the Window/Developer Tools menu)

You can control/monitor active LuaStates as well as triggering both Unreal and Lua GC's

LuaMachine Console

As a great companion for the debugger, each LuaState automatically activates a lua console in your output log window:

LuaConsoles allow multiline input (shift-return for newlines, return for submitting the commands) and are automatically destroyed when the state is destroyed.

Obviously they are only available in the editor.

LuaState in C++

You can define your LuaState's as C++ classes, this is handy for exposing functions that would be hard to define with blueprints:

#pragma once

#include "CoreMinimal.h"
#include "LuaState.h"
#include "AdvancedLuaState.generated.h"

/**
 * 
 */
UCLASS()
class LUATEST420_API UAdvancedLuaState : public ULuaState
{
	GENERATED_BODY()
public:
	UAdvancedLuaState();

	UFUNCTION()
	FLuaValue GetPlayerPawnLocation();

	UFUNCTION()
	FLuaValue GetSimpleString();
	
};

#include "AdvancedLuaState.h"
#include "Kismet/GameplayStatics.h"
#include "Engine/World.h"
#include "GameFramework/Pawn.h"

UAdvancedLuaState::UAdvancedLuaState()
{
	Table.Add("simple_string", FLuaValue("Test string"));
	Table.Add("get_player_location", FLuaValue::Function(GET_FUNCTION_NAME_CHECKED(UAdvancedLuaState, GetPlayerPawnLocation)));
	Table.Add("get_simple_string", FLuaValue::Fun