README EN

Lua programming solution for C#

xLua adds Lua scripting capability to Unity, .Net, Mono, and other C# environments. With xLua, Lua code and C# code can easily call each other.

xLua's superior features

xLua has many breakthroughs in function, performance, and ease of use. The most significant features are:

• You can use C# implementations (methods, operators, properties, events, etc...) in Lua.
• Outstanding GC optimization, customized struct, no C# gc alloc when passing the enumerated objects between C# and Lua;
• Lightweight development with no needs to generate code in editor mode;

Installation

Unpack the ZIP package and you will see an Assets directory, which corresponds to the Unity project's Assets directory. Keep the directory structure in your Unity project.

If you want to install it to another directory, please see the FAQs.

Documents

• FAQs: Frequently asked questions are summarized here. You can find answers to questions for beginners.
• (Must-read) XLua Tutorial: This is a tutorial. The supporting code can be found here.
• (Must-read) XLua Configuration: Descriptions on how to configure xLua.
• Hotfix Operation Guide: Description on how to use the hotfix feature.
• Add/remove third-party Lua Libraries on xLua: Descriptions on how to add or remove third-party Lua extension libraries.
• xLua APIs: API documentation
• Secondary Development of the Build Engine: Descriptions on how to do secondary development of the build engine.

Quick Start

A complete example requires only 3 lines of code:

Install xLua, create a MonoBehaviour drag scenario, add the following code to Start:

XLua.LuaEnv luaenv = new XLua.LuaEnv();
luaenv.DoString("CS.UnityEngine.Debug.Log('hello world')");
luaenv.Dispose();

1. The DoString parameter is a string, and you can enter any allowable Lua code. In this example, Lua calls C#’s UnityEngine.Debug.Log to print a log.

2. A LuaEnv instance corresponds to a Lua virtual machine. Due to overhead, it is recommended that the Lua virtual machine be globally unique.

It is simple that C# actively calls Lua. For example, the recommended method to call Lua's system function is:

• Declare

[XLua.CSharpCallLua]
public delegate double LuaMax(double a, double b);

• Bind

var max = luaenv.Global.GetInPath<LuaMax>("math.max");

• Call

Debug.Log("max:" + max(32, 12));

It is recommended that you bind once and reuse it. If code is generated, no gc alloc is generated when calling max.

Hotfix

• This has lower intrusiveness, and it can be used without any modification of the original code of the old project.
• This has little impact on the runtime, which is almost the same as the original program which hotfix is not used.
• If you have problems, you can also use Lua to patch. Then the Lua code logic is involved.

Here is the usage guide:

More Examples

• 01_Helloworld: Quick Start Examples
• 02_U3DScripting: This example shows how to use Mono to write MonoBehaviour.
• 03_UIEvent: This example shows how to use Lua to write UI logic.
• 04_LuaObjectOrented: This example shows the cooperation between Lua's object-oriented programming and C#.
• 05_NoGc: This example shows how to avoid the value type GC.
• 06_Coroutine: This example shows how Lua coroutines work with Unity coroutines.
• 07_AsyncTest: This example shows how to use Lua coroutines to synchronize asynchronous logic.
• 08_Hotfix: These are Hotfix examples (Please enable hotfix feature. See the Guide for details).
• 09_GenericMethod: This is a generic function support demo.
• 10_SignatureLoader: This example shows how to read the Lua script with a digital signature. See the Digital Signature document for details.
• 11_RawObject: This example shows how to specify transferring a Lua number in the int after boxing when the C# parameter is an object.
• 12_ReImplementInLua: This shows how to change complex value types to Lua implementations.
• 14_HotfixAsyncAwait: This shows how to change asynchronous functions and await keyword to Lua implementation.

Technical support

QQ Group 1: 612705778 (may be full)

QQ Group 2: 703073338

QQ Group 3: 811246782

Check answers: If you encounter a problem, please read the FAQs first.