xLua热更新（一）xLua基本使用

╰半橙微兮° 2023-09-26 09:23 26阅读 0赞

## 一、什么是xLua ##

> xLua为Unity、 .Net、 Mono等C\#环境增加Lua脚本编程的能力，借助xLua，这些Lua代码可以方便的和C\#相互调用。

xLua是用来实现Lua代码与C\#代码相互调用的插件。我们可以借助这个插件来实现热更新方案。

那么为什么要选择Lua实现热更新呢？

这是因为Lua具有轻量、灵活的特点，可以在几乎任何平台上编译、运行。Unity一般使用C\#代码编写游戏逻辑。在打包时，C\#会先编译成IL（中间语言），存储到dll（动态链接库）中。在游戏运行时，需要通过JIT（即时编译）将IL解释为机器码。在这期间，会开辟一块内存空间，且要求这块空间可读、可写、可执行。但IOS平台是不允许获取具有可执行权限的内存空间的。因此只能进行全量更新。但Lua是使用C写的脚本语言，在运行时读入Lua代码，在解释时直接使用C代码进行解释，不需要开辟特殊的内存空间，执行解释的是C语言编写的虚拟机。（参考自[这篇文章][Link 1]）

## 二、如何使用 ##

### 2.1 Hello World ###

首先在[xLua的GitHub主页][xLua_GitHub]下载源码，并引入到Unity中。

创建一个C\#脚本，并编写如下代码。`DoString()`方法可以执行传入的Lua代码。

public class HelloWorld : MonoBehaviour
    {
        
    	private LuaEnv _lua;
    
    	private void Start()
    	{
        
    		_lua = new LuaEnv();
    		_lua.DoString("print('Hello World')");
    	}
    
    	private void OnDestroy()
    	{
        
    		_lua.Dispose();
    		_lua = null;
    	}
    }

将脚本挂载到一个游戏物体上，运行游戏。可以在控制台看到输出结果，且输出的字符串带有“Lua:”前缀。  
![940ce855c34d50355955e889599f5db2.png][]

**需要注意的是，一个LuaEnv的实例对应着一个Lua虚拟机，建议全局唯一。**

### 2.2 加载Lua文件 ###

在`DoString()`方法中直接写大量的Lua代码是不现实的，我们需要载入外部的Lua文件，并将文件内容传入这个方法中执行。

首先编写一个简单的Lua脚本，并将脚本放在「Resources」目录下

a = 2  
    b = 3  
    print("a+b="..a+b)

然后在C\#脚本中通过`Resources`进行载入

public class LoadLuaFile : MonoBehaviour
    {
        
    	private void Start()
    	{
        
    		var lua = Resources.Load<TextAsset>("AddLua");
    		Debug.Log(lua);
    		if (lua != null)
    		{
        
    			LuaEnv luaEnv = new();
    			luaEnv.DoString(lua.text);
    			luaEnv.Dispose();
    		}
    	}
    }

此时运行游戏我们会发现，控制台输出的是「Null」。这是因为`Resources.Load<TextAsset>()`会默认给文件名后面增加「.txt」后缀。也就是说这个方法只会读取到后缀为「.txt」的文件。  
![fb852e8e727a47bd15c02b2199fa9eca.png][]

为了能读取到Lua文件，我们需要将Lua文件的后缀改为「.lua.txt」。在加载时，文件名传入「XXX.lua」，这样就能顺利读取到Lua脚本的内容了。  
![3f94ac3cc1af2fb34bc5a6b670d08e76.png][]

我们也可以使用xLua内置的loader进行加载。方法是在`luaEnv.DoString()`方法中直接传入`require`语句。`require`会调一个个的Loader去加载，直到遇到不返回空的Loader。如果全部返回空则会报文件找不到的异常。

LuaEnv luaEnv = new();  
    luaEnv.DoString("require 'AddLua'");  
    luaEnv.Dispose();

如果lua脚本没有问题，但运行时“unexpected symbol”之类的错误，可以用记事本打开lua脚本，重新保存为UTF-8编码格式。

### 2.3 自定义Loader ###

某些情况下系统内置的Loader并不能满足我们的需求。比如需要对Lua文件解密，或者Lua文件不在「Resources」目录下等。这时就需要我们自定义Loader。

要实现自定义Loader也很简单，只需要调用`LuaEnv.AddLoader()`方法，添加一个自定义Loader即可。该方法需要传入一个委托，委托的参数是加载文件的路径，返回值是文件内容的字节数组。

public class CustomLoader : MonoBehaviour
    {
        
    	private void Start()
    	{
        
    		LuaEnv luaEnv = new();
    		luaEnv.AddLoader(MyLoader);
    		luaEnv.DoString("require '不存在的文件'");
    		luaEnv.Dispose();
    	}
    
    	private byte[] MyLoader(ref string filePath)
    	{
        
    		string content = "print('Hello World')";
    		return System.Text.Encoding.UTF8.GetBytes(content);
    	}
    }

上面的代码运行结果如下  
![8c4e93cb73723a5caae248f3f55c1a9a.png][]

要实现加载指定目录的Lua文件，只需要在自定义Loader中通过文件流读取文件即可

string path = "[指定路径]";  
    return System.Text.Encoding.UTF8.GetBytes(File.ReadAllText(path));

### 2.4 C\#访问Lua ###

#### 2.4.1 访问全局变量 ####

Lua脚本

str="Hello World"  
    num=12  
    isTrue=true

C\#脚本

LuaEnv luaEnv = new();  
    luaEnv.DoString("require 'CSharpCallLua'");  
    var str = luaEnv.Global.Get<string>("str");  
    var num = luaEnv.Global.Get<int>("num");  
    var isTrue = luaEnv.Global.Get<bool>("isTrue");  
    Debug.Log($"str:{
          str} num:{
          num} isTrue:{
          isTrue}");  
    luaEnv.Dispose();

运行结果  
![d534aa23c0f0ae7198f5ec43015a42e7.png][]

#### 2.4.2 访问全局table ####

##### 映射到class或struct #####

Lua脚本

person = {
          
        Name="宇智波佐助",  
        Age=12  
    }

C\#脚本

class Person  
    {
          
        public string Name;  
        public int Age;  
    }  
      
    private void CallTableToClass()  
    {
          
        LuaEnv luaEnv = new();  
        luaEnv.DoString("require 'CSharpCallLua'");  
        var person = luaEnv.Global.Get<Person>("person");  
        Debug.Log($"name:{
          person.Name} age:{
          person.Age}");  
        luaEnv.Dispose();  
    }

运行结果  
![4ffe380abfd64507017240f24d8f8f09.png][]

**需要注意的是，这个映射过程是值拷贝，如果class比较复杂，代价会比较大。且因为是值拷贝，无论去修改任何一边的字段值，另一边也不会同步修改。**

##### 映射到interface #####

Lua脚本

person = {
          
        Name="宇智波佐助",  
        Age=12,  
        Do=function(self,a,b) -- 需要额外定义一个参数self,相当于this  
            print(a+b)  
        end  
    }

C\#脚本

[CSharpCallLua]
    public interface IPerson // 接口必须声明为public
    {
          
        string Name {
         get; set; }  
        int Age {
         get; set; }  
        void Do(int a,int b);  
    }
    
    private void CallTableToInterface()  
    {
          
        LuaEnv luaEnv = new();  
        luaEnv.DoString("require 'CSharpCallLua'");  
        var person = luaEnv.Global.Get<IPerson>("person");  
        Debug.Log($"name:{
          person.Name} age:{
          person.Age}");  
        person.Do(12,3);  
        luaEnv.Dispose();  
    }

运行结果  
![db4fd579e20c0cab84b0dcc710de868c.png][]

这是引用方式的映射，也就是说在C\#中更改字段值，对应的Lua表中的值也会跟着修改。另外，如果映射的方法具有参数，则在Lua代码中，需要在最前面额外定义一个接收参数，用来充当this。或者通过如下方式定义方法

function person:Do(a,b)  
        print(a+b)  
    end

另外在运行时可能会碰到如下问题：  
![1e03e8db21578d65572242906f725b61.png][]

首先检查映射的接口上有没有加`[CSharpCallLua]`特性。如果已经添加该特性，且Unity版本是2018以上，那就将「File->Build Settings->Player Settings->Player->Other Settings->Configuration->Api Compatibility Level」中的选项改为「.NET Framework」。具体原因可以查看xLua官方文档中的「faq」文档  
![e859e85531c3cfa1d781d730d9f49498.png][]

##### 映射到集合 #####

Lua脚本

person = {
          
        Name="宇智波佐助",  
        Age=12,  
        Do=function(self,a,b)  
            print(a+b)  
        end,  
        1,2,3,  
        "Hello",  
        true  
    }

C\#脚本

private void CallTableToCollection()
    {
        
    	LuaEnv luaEnv = new();
    	luaEnv.DoString("require 'CSharpCallLua'");
    	var person1 = luaEnv.Global.Get<Dictionary<string,object>>("person");
    	foreach (var e in person1)
    	{
        
    		Debug.Log($"Key:{
          e.Key} Value:{
          e.Value}");
    	}
    	Debug.Log("------------------------------------------------");
    	var person2 = luaEnv.Global.Get<List<object>>("person");
    	foreach (var e in person2)
    	{
        
    		Debug.Log(e);
    	}
    	luaEnv.Dispose();
    }

运行结果  
![0d52b0a367954f84df9d978600497760.png][]

可以看到，在table中显式定义了键值的字段都可以正常映射到字典中，而没有定义键值的则会丢失；线性表则与之相反，只会映射没有定义键值的字段。

##### 映射到LuaTable #####

Lua脚本

C\#脚本

private void CallTableToLuaTable()  
    {
          
        LuaEnv luaEnv = new();  
        luaEnv.DoString("require 'CSharpCallLua'");  
        var person = luaEnv.Global.Get<LuaTable>("person");  
        Debug.Log($"{
          person.Get<int,int>(1)}");  
        Debug.Log($"{
          person.Get<int,int>(2)}");  
        Debug.Log($"{
          person.Get<int,int>(3)}");  
        Debug.Log($"{
          person.Get<int,string>(4)}");  
        Debug.Log($"{
          person.Get<int,bool>(5)}");  
        Debug.Log($"{
          person.Get<string,string>("Name")}");  
        Debug.Log($"{
          person.Get<string,int>("Age")}");  
        Debug.Log($"{
          person.Get<string,object>("Do")}");  
        luaEnv.Dispose();  
    }

运行结果  
![86eba760cfd42a8a5115972b8f42ac43.png][]

LuaTable类是xLua提供的类，它可以把定义了键值和未定义键值的字段全部映射过来。但是性能上要慢很多，且没有类型检查。因而一般很少会使用这种方法。

#### 2.4.3 访问全局函数 ####

##### 映射到委托 #####

对于Lua中无参数和返回值的函数，可以使用C\#中的`Action`接收  
Lua脚本

function Add1()  
        print("调用了Add")  
    end

C\#脚本

private void CallFunctionToDelegate()  
    {
          
        LuaEnv luaEnv = new();  
        luaEnv.DoString("require 'CSharpCallLua'");  
        Action act = luaEnv.Global.Get<Action>("Add1");  
        act();  
        // 延时调用确保引用被释放  
        StartCoroutine(DisposeLuaEnv(luaEnv));  
    }  
      
    IEnumerator DisposeLuaEnv(LuaEnv luaEnv)  
    {
          
        yield return new WaitForSeconds(0.1f);  
        luaEnv.Dispose();  
    }

运行结果  
![37f3b639e7ec247bfe695e41267c90fd.png][]

如果是有返回值和参数的函数，可以自定义一个委托来接收。对于有多个返回值的函数，可以使用out参数接收。  
Lua脚本

function Add2(a,b)  
        print("调用了Add 结果："..a+b)  
        return a+b,"Hello",true  
    end

C\#脚本

[CSharpCallLua]  
    private delegate int Add(int a, int b, out string res2, out bool res3);
    
    private void CallFunctionToDelegate()  
    {
          
        LuaEnv luaEnv = new();  
        luaEnv.DoString("require 'CSharpCallLua'");  
        int res1 = add(12,3,out string res2,out bool res3);  
        Debug.Log($"res1:{
          res1} res2:{
          res2} res3:{
          res3}");  
        // 延时调用确保引用被释放
        StartCoroutine(DisposeLuaEnv(luaEnv));
    }
    
    IEnumerator DisposeLuaEnv(LuaEnv luaEnv)  
    {
          
        yield return new WaitForSeconds(0.1f);  
        luaEnv.Dispose();  
    }

运行结果  
![6bc03f59e167400c9b1b2fe817d60b0b.png][]

##### 映射到LuaFunction #####

这种方式是将函数映射到xLua提供的`LuaFunction`类中，写起来比较简单，但是性能要比委托的方式差。  
Lua脚本

function Add2(a,b)  
        print("调用了Add 结果："..a+b)  
        return a+b,"Hello",true  
    end

C\#脚本

private void CallFunctionToLuaFunction()
    {
        
    	LuaEnv luaEnv = new();
    	luaEnv.DoString("require 'CSharpCallLua'");
    	var add = luaEnv.Global.Get<LuaFunction>("Add2");
    	var res = add.Call(12, 3);
    	foreach (var e in res)
    	{
        
    		Debug.Log(e);
    	}
    	
    	luaEnv.Dispose();
    }

运行结果  
![944913a686f1319d69d8030182398026.png][]

### 2.5 Lua访问C\# ###

在Lua中访问C\#脚本的成员比较简单，只需要在所有C\#相关的代码都加上`CS`前缀即可  
C\#脚本

private void Start()  
    {
          
        LuaEnv luaEnv = new();  
        luaEnv.DoString("require 'LuaCallCSharp'");  
        luaEnv.Dispose();  
    }

Lua脚本

-- 实例化对象  
    local go = CS.UnityEngine.GameObject("LuaGameObject")  
      
    -- 访问静态属性、方法  
    local deltaTime = CS.UnityEngine.Time.deltaTime  
    local GameObject = CS.UnityEngine.GameObject  
    local camera = GameObject.Find("Main Camera")  
      
    -- 访问成员属性、方法  
    camera.name = "LuaCamera"  
    camera:GetComponent("Camera").clearFlags = CS.UnityEngine.CameraClearFlags.SolidColor

再次强调在Lua中调用成员方法时，要么使用`:`的方式访问，要么使用`.`调用并在参数中额外传入对象本身的方式访问。

[Link 1]: https://www.jianshu.com/p/71fffc9a9cac
[xLua_GitHub]: https://github.com/Tencent/xLua
[940ce855c34d50355955e889599f5db2.png]: https://img-blog.csdnimg.cn/img_convert/940ce855c34d50355955e889599f5db2.png
[fb852e8e727a47bd15c02b2199fa9eca.png]: https://img-blog.csdnimg.cn/img_convert/fb852e8e727a47bd15c02b2199fa9eca.png
[3f94ac3cc1af2fb34bc5a6b670d08e76.png]: https://img-blog.csdnimg.cn/img_convert/3f94ac3cc1af2fb34bc5a6b670d08e76.png
[8c4e93cb73723a5caae248f3f55c1a9a.png]: https://img-blog.csdnimg.cn/img_convert/8c4e93cb73723a5caae248f3f55c1a9a.png
[d534aa23c0f0ae7198f5ec43015a42e7.png]: https://img-blog.csdnimg.cn/img_convert/d534aa23c0f0ae7198f5ec43015a42e7.png
[4ffe380abfd64507017240f24d8f8f09.png]: https://img-blog.csdnimg.cn/img_convert/4ffe380abfd64507017240f24d8f8f09.png
[db4fd579e20c0cab84b0dcc710de868c.png]: https://img-blog.csdnimg.cn/img_convert/db4fd579e20c0cab84b0dcc710de868c.png
[1e03e8db21578d65572242906f725b61.png]: https://img-blog.csdnimg.cn/img_convert/1e03e8db21578d65572242906f725b61.png
[e859e85531c3cfa1d781d730d9f49498.png]: https://img-blog.csdnimg.cn/img_convert/e859e85531c3cfa1d781d730d9f49498.png
[0d52b0a367954f84df9d978600497760.png]: https://img-blog.csdnimg.cn/img_convert/0d52b0a367954f84df9d978600497760.png
[86eba760cfd42a8a5115972b8f42ac43.png]: https://img-blog.csdnimg.cn/img_convert/86eba760cfd42a8a5115972b8f42ac43.png
[37f3b639e7ec247bfe695e41267c90fd.png]: https://img-blog.csdnimg.cn/img_convert/37f3b639e7ec247bfe695e41267c90fd.png
[6bc03f59e167400c9b1b2fe817d60b0b.png]: https://img-blog.csdnimg.cn/img_convert/6bc03f59e167400c9b1b2fe817d60b0b.png
[944913a686f1319d69d8030182398026.png]: https://img-blog.csdnimg.cn/img_convert/944913a686f1319d69d8030182398026.png