LuaMachine: an Unreal Engine plugin that hides the engine API from scripts

The plugin deliberately hides the engine API

LuaMachine is an Unreal Engine plugin for adding Lua scripting to your projects, and the design decision that defines it is stated plainly.

Contrary to the other Unreal Engine Lua plugins, this one does not try to automatically expose the Unreal Engine API. It completely hides it, giving the user or the scripter only the features the developer decided to include, through Blueprints or C++. An advanced API for using, in the wording of the readme, abusing Unreal Engine Reflection is included too.

That is a security and stability decision as much as a design one. A script that can call any reflected function can spawn actors, touch the save system and read any property the engine exposes. A script that can only call what you exposed runs in a box you control, which is what makes the plugin viable for modders and for game designers who are not engine programmers.

The target audience is spelled out in the readme's opening lines: people who want modders to customise their game or project, people who need game designers to script parts of the logic, and anyone who wants a framework for adding Lua scripting capabilities to their projects.

The supported platforms are broad: Windows 64-bit, Mac, Linux x86_64 for both runtime and editor, Linux AArch64, Android in 32 and 64 bit, and iOS. The minimum supported engine version is 4.20.

Three branches, and the version of Lua you get depends on which

The branch layout matters more here than in most plugins, because the features you might want are split across them.

The master branch is focused on Unreal Engine 5, and if you need Unreal Engine 4 support you use the ue4 branch instead. That split is a common pattern for plugins that have to support two engine generations, and it means the version of the plugin you use depends on your engine version rather than on your needs.

A third branch, dev, carries the newer Lua implementations. Experimental Luau support is available there, as well as Lua 5.4, Lua 5.5 and LuaJIT. Luau is the dialect Roblox developed, and its inclusion is the reason to look at the dev branch at all if you are coming from that ecosystem.

The release tags follow a date-based scheme rather than semantic versioning, with tags named 20260921, 20260828 and 20250604 for the three most recent releases, dated 2026-09-21, 2026-08-28 and 2025-06-04. The last push was on 2026-09-21, the same day as the newest tag, and the repository is not archived with master as the default branch.

The licensing is MIT with the LICENSE file at the root, and the readme is explicit that the project is fully open source and free while also being available on the Unreal Engine Marketplace for about 30 dollars, with the purchase framed as a way to sponsor the project. There is also a Patreon option for sponsorship.

So there are two ways to get it, and the commercial one exists to fund the work rather than to unlock features.

The quickstart is a Lua file and a Blueprint subclass

The getting started path is short enough to follow in a sitting, and it shows the shape of the whole API.

You install the plugin, either by downloading it from the GitHub releases page, which is free but needs compiling, or from the Marketplace, which is ready to use. From source, you decompress the zip into the Plugins/ directory of your project, creating it if it does not exist, and restart the Unreal Editor. The documentation notes that for a manual compile you need C++ enabled in the project and the solution or Xcode file regenerated.

Then you write a Lua file into the project Content/ directory. The example is deliberately trivial:

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

The next step is the concept that makes the plugin different from a scripting add-on. You create a new Blueprint that inherits from LuaState, which is described as a special Blueprint representing a Lua virtual machine. You can have several of these in the same project, and the readme names one good candidate for the first one.

From there you open the Level Blueprint and add the LuaRunFile node, which executes a Lua file relative to the Content/ directory in the specified LuaState and returns whatever the script returned, as a LuaValue struct. The plugin provides a set of operations on LuaValue, and in the example the value is simply converted to an Unreal String. When you play the game, the Lua string is printed.

The readme calls this example fast and useless, which is a fair description. It exists to show the four moving parts: a Lua file, a LuaState Blueprint, a node in the level Blueprint, and a value coming back.

Calling in both directions, and the constraint on exposed functions

The tutorial then walks through the two directions of the bridge, and the second direction carries a rule that will bite you if you miss it.

Calling from Unreal into Lua is the easy half. A Lua script adds a function to the global table:

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

The LuaGlobalCall node calls a function from the global table, passing arguments as an array of LuaValues.

The other direction, exposing Unreal to Lua, is where the rule is. You add a Function to the LuaState Blueprint, and you expose it in the Blueprint's Table TMap, which is how items are added to the Lua global table. Calling get_player_location() from Lua then triggers the QuickLuaState's GetPlayerPawnLocation(). But not all UFunctions can be exposed: if they take or return values, they must be LuaValues.

That constraint is the price of the hiding design. Since the API is not reflected automatically, values crossing the boundary have to be marshalled explicitly, and the plugin's choice is a single struct type rather than a general conversion of any reflected type. The readme also notes that the LuaState exposes many fields for configuring the virtual machine, including the Table TMap for globals and the Lua Filename field, and that setting the filename means the script is executed during the spawn of the LuaState, so the LuaRunFile node is not needed.

One small convenience is documented at the end. The print function is automatically mapped to the Unreal Output Log by the plugin, so a script debugging itself does not need its own log plumbing.

Multiple isolated virtual machines, loaded on demand

The LuaState model is the structural idea behind the plugin, and it does more than save a variable.

A LuaState, backed by the ULuaState C++ class, represents a single Lua virtual machine. There can be multiple, and each one is isolated from the others. The readme describes each LuaState class as a singleton in the sense that it can have a single instance for the whole process life, and it notes that in the Editor, LuaStates are constantly recreated whenever you enter PIE mode, to simplify development.

The reason to have several is domain separation, and the examples given are concrete: a state for game configuration, another for game logic, and one for the modders. More complex arrangements include states dedicated to specific Actors, GameModes or Levels.

That separation is a real security boundary, not just tidiness. If modders get their own LuaState and the configuration state is separate, then a modder script that goes wrong cannot corrupt the game configuration or the logic state, and a mistake in one domain does not take the others down with it. Combined with the decision to hide the engine API, the isolation is what makes the plugin safe to point at user-supplied content.

The states are loaded on demand, so you can create dozens of them without paying for dozens of running VMs. They only start when something needs them.

Scripts can come from two places, and the choice matters for deployment. You can load scripts in text and bytecode format from the filesystem via the LuaFilename field, or from a plugin-specific asset named LuaCode via the LuaCodeAsset field. The readme begins to explain the advantage of the filesystem route when the text is cut off in the excerpt available here, but the distinction between a cooked asset and a loose file on disk is the kind of thing that determines whether a mod can ship a script without repackaging the game.

Editorial conclusion

LuaMachine suits a studio or modding community that wants designers or players scripting in Lua without handing them the whole Unreal API, and that wants separate Lua virtual machines per domain. It does not suit a project that wants the entire engine reflected into Lua automatically, because the plugin deliberately does the opposite, and the Luau and newer Lua support sits on a dev branch rather than in the release you would ship. Before adopting it, read BuildingNotes.md for the build, decide whether the dev branch is acceptable, and plan how the exposed UFunctions will be validated, since a UFunction that takes or returns values must use LuaValue types.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. rdeioris/LuaMachine on GitHub
4. README
5. Releases