# Tencent/UnLua: Lua Scripting for Unreal Engine Without Glue Code

> UnLua is a Lua scripting plugin for Unreal Engine that exposes UCLASS, UPROPERTY, UFUNCTION, USTRUCT and UENUM directly to Lua and lets scripts replace Blueprint implementations. It suits UE programmers who already know the engine's programming model; it is not a general-purpose Lua runtime.

**Tencent/UnLua** — A feature-rich, easy-learning and highly optimized Lua scripting plugin for UE.

- Repository: https://github.com/Tencent/UnLua
- Stars: 2,787 · Forks: 727
- Language: C++
- License: NOASSERTION
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/tencent-unlua

## What UnLua solves for Unreal Engine teams

Unreal Engine projects mix C++ and Blueprint. UnLua adds a third option: Lua scripts that reach the same UCLASS, UPROPERTY, UFUNCTION, USTRUCT and UENUM types the engine already exposes, with no glue code written by hand. The README states this directly, and it is the reason the plugin exists. A gameplay programmer who knows UE's programming model can move logic into Lua without a binding layer between the two.

The second job is replacing Blueprint implementations. The README lists replacing Event and Function implementations defined in Blueprint, plus handling event notifications for replication, animation and input. That means a designer-facing Blueprint can keep its shape while the body of a function lives in a Lua file. The audience is therefore Unreal Engine programmers and technical designers, not Lua developers looking for a host language. The README's own framing is that UE programmers can use it with zero learning cost, which is a claim about the engine side of the boundary, not about Lua itself.

## How the binding and override mechanism works

The README describes two overriding mechanisms and links to Docs/CN/How_To_Implement_Overriding.md for the detail. What the top-level description makes clear is the direction of the bridge: UnLua follows UE's programming model rather than inventing its own object system, so Lua code manipulates engine objects directly. Binding happens per Blueprint through the UnLua toolbar, and the GetModule interface function supplies the Lua file path, for example GameModes.BP_MyGameMode. That path is what connects an engine asset to a script file.

The optimization section is the most concrete part of the README. UFUNCTION calls use persistent parameter caching, optimized parameter passing, and handling for non-const references and return values. Container access for TArray, TSet and TMap keeps the engine's memory layout, and the README states Lua tables and containers need no conversion between them. Struct creation, access and GC are described as efficient. These are the parts that matter at runtime, because a scripting layer that copies every array into a Lua table would show up in profiles. Custom static export of classes, member variables, member functions, global functions and enums is also supported, which is how a project extends the binding surface beyond what ships in the plugin.

## Installing UnLua and running a first script

The README's install section is two steps and no build commands. Copy the Plugins directory into the root of your UE project, then restart the project. There is no package manager step, no environment variable, and no version pinned in the instructions. The repository layout matches this: a Plugins directory sits at the top level next to Content, Config, Source and the TPSProject.uproject file. The README gives no shell command for the copy, so do it with your file manager or your own tooling.

After restarting, the UnLua toolbar appears in the Blueprint editor. The README's quick start then walks through binding: open a Blueprint, choose 绑定 (Bind) from the UnLua toolbar, and optionally hold Alt to auto-generate the path used in the next step. The path you enter looks like this:

```text
GameModes.BP_MyGameMode
```

That string goes into the interface's GetModule function. Then choose 创建Lua模版文件 (Create Lua template file) from the same toolbar, which produces a file at Content/Script/GameModes/BP_MyGameMode.lua. That path is where you write code, and it is the file the binding resolves to at runtime.

```text
Content/Script/GameModes/BP_MyGameMode.lua
```

The repository ships runnable examples under Content/Script/Tutorials, including 01_HelloWorld.lua, 02_OverrideBlueprintEvents.lua, 03_BindInputs.lua, 05_BindDelegates.lua, 06_NativeContainers.lua and 12_CustomLoader.lua. Reading 01_HelloWorld.lua alongside the template file is the fastest way to see the expected shape of a script before writing your own. The README also points UE newcomers at Docs/CN/Quickstart_For_UE_Newbie.md, which is an illustrated walkthrough of the same steps.

## Engine version, platform and build constraints

UnLua supports Unreal Engine 4.17.x through Unreal Engine 5.x, and runs on Windows, Android, iOS, Linux and OSX. Those are the runtime platforms listed in the README; the editor side is not broken out separately, so if you develop on one platform and ship to another, check the plugin's own configuration rather than assuming the list describes the editor.

The README carries one explicit warning: 4.17.x and 4.18.x need modifications to Build.cs. It does not say which modifications. That is a real gap for anyone pinned to those engine versions, and it is the kind of detail you would normally find in a changelog or an issue thread. The CHANGELOG.md file exists at the repository root, but the README does not point at it for this. If your project is on 4.17 or 4.18, plan to read the source before you plan the integration.

The release history is another constraint worth noting. The most recent release listed is v2.3.6 from 2023-11-07, preceded by v2.3.5 in 2023-05-29 and v2.3.3 in 2023-02-02. The repository itself is not archived and the last push was on 2026-04-02, so work continues on the default branch, but the tagged releases are older than the branch activity. Projects that track tags rather than commits are effectively on a 2023 snapshot. The licence is listed as NOASSERTION in the repository metadata while the README badge and the LICENSE.TXT file point to MIT; treat that discrepancy as something to resolve with your own legal review rather than taking either signal alone.

## Where UnLua is the wrong choice

UnLua is a plugin for Unreal Engine. If your host application is not UE, the plugin has nothing to attach to, and the engine-specific features that make it useful (UCLASS access, Blueprint replacement, replication events) do not exist outside that runtime. A project that wants scripting in a custom C++ engine should look at embedding Lua directly instead.

Inside UE, the trade-off is different. The README's optimization claims are about avoiding conversion overhead, which implies the default expectation in a scripting layer is that overhead. UnLua's approach of keeping engine memory layout and exposing containers without conversion means Lua code can hold references to engine-side data. That is a performance decision with a lifetime consequence: the README ships a tutorial named 11_ReleaseUMG.lua specifically about releasing UMG-related objects, which tells you that object lifetime in the Lua layer is something the project expects you to manage. If your team is not prepared to reason about when engine objects become collectable, the scripting layer will surface that as leaks or stale references rather than as a clean error.

The other limitation is documentation language. The README is largely in Chinese, and the detailed documents it links (Settings, Debugging, IntelliSense, ConsoleCommand, FAQ, the programming guide, the API reference, the overriding explanation) are under Docs/CN. The repository does contain README_EN.md, but the README does not list an English equivalent for the deeper guides. An English-speaking team can follow the quick start from the README, but the reference material for settings and debugging is in Chinese.

## How UnLua differs from other UE scripting options

The related searches around this project name several other approaches: Slua, Puerts, UnrealJS, LuaMachine and Luadec. The meaningful split is between binding Lua to UE and binding JavaScript to UE. Puerts and UnrealJS take the JavaScript route, which changes the language your gameplay programmers write and the toolchain around it. Slua is the closer comparison, since it is also a Lua binding for UE; the difference to check is the binding strategy and what each project exposes without custom export code, because UnLua's stated position is direct access to UCLASS, UPROPERTY, UFUNCTION, USTRUCT and UENUM with no glue, plus static export for anything beyond that.

Luadec and Unluac appear in the same search list but are not alternatives. They are Lua decompilers, tools that read compiled Lua bytecode back into source. Their presence in the search results is a naming collision, not a feature comparison. If you arrived looking for a decompiler, UnLua is not that.

The README also points at Lyra with UnLua, a separate repository based on Epic's Lyra starter game, described as under construction. That is the reference to check if you want to see the plugin applied to a full project rather than to the tutorial scripts, though the README gives no completion date for it.

## Conclusion

Adopt UnLua if your team ships an Unreal Engine project and wants gameplay logic in Lua while keeping the engine's class and Blueprint model intact; the plugin targets UE 4.17.x through 5.x on Windows, Android, iOS, Linux and OSX. Do not adopt it as a standalone Lua interpreter or for a non-UE host, and do not expect the README to cover install steps beyond copying Plugins. Before committing, verify the 4.17.x and 4.18.x Build.cs changes the README flags, confirm your engine version against the supported range, and read Docs/CN/How_To_Implement_Overriding.md to understand which of the two overriding mechanisms your Blueprint bindings will use.

## FAQ

### Which Unreal Engine versions does UnLua support?

The README states support for Unreal Engine 4.17.x through Unreal Engine 5.x, running on Windows, Android, iOS, Linux and OSX. It adds that 4.17.x and 4.18.x require modifications to Build.cs, without specifying which ones.

### How do I install UnLua in my UE project?

Copy the Plugins directory into the root of your Unreal Engine project and restart the project, per the README's install section. There is no package manager step in the documented instructions.

### How do I connect a Blueprint to a Lua file in UnLua?

Open the Blueprint, choose Bind from the UnLua toolbar, then fill the GetModule function with the Lua file path, for example GameModes.BP_MyGameMode. The toolbar's Create Lua template file option generates the matching file under Content/Script.

### Does UnLua require glue code to access engine types?

The README states that UCLASS, UPROPERTY, UFUNCTION, USTRUCT and UENUM are accessible directly without glue code, and that custom static export is available for classes, member variables, member functions, global functions and enums beyond that.

### Is UnLua the same as Unluac or Luadec?

No. UnLua is a Lua scripting plugin for Unreal Engine from Tencent. Unluac and Luadec are Lua decompilers, which are unrelated tools that share part of the name.

## Sources

- [Issues](https://github.com/Tencent/UnLua/issues)
- [README](https://github.com/Tencent/UnLua/blob/master/README.md)
- [Releases](https://github.com/Tencent/UnLua/releases)
- [Tencent/UnLua on GitHub](https://github.com/Tencent/UnLua)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tencent-unlua