lua 函数 默认值_Unity 热更新解决方案 学习笔记(19) XLua API

笔者只是一位刚大三的学生本文章仅为学习笔记，非专业教程，仅供参考和学习交流！！！ 如有错误或更好的方案欢迎指出和探讨！！！

参考链接：

C# API

LuaEnv类

object[] DoString(string chunk, string chunkName = "chuck", LuaTable env = null)

描述：

执行一个代码块。

参数：

chunk: Lua代码的字符串；

chunkName： 发生error时的debug显示信息中使用，指明某某代码块的某行错误；

env ：这个代码块的环境变量；

返回值：

代码块里return语句的返回值;

比如：return 1, “hello”，DoString返回将包含两个object的数组， 一个是double类型的1， 一个是string类型的“hello”

例如：

LuaEnv luaenv = new LuaEnv();

object[] ret = luaenv.DoString("print(‘hello’)\r\nreturn 1")

UnityEngine.Debug.Log("ret="+ret[0]);

luaenv.Dispose()

T LoadString(string chunk, string chunkName = "chunk", LuaTable env = null)

描述：

加载一个代码块，但不执行，只返回类型可以指定为一个delegate或者一个LuaFunction

参数：

chunk: Lua代码的字符串；

chunkName： 发生error时的debug显示信息中使用，指明某某代码块的某行错误；

env ：这个代码块的环境变量；

返回值：

代表该代码块的delegate或者LuaFunction类；

LuaTable Global

描述：

代表lua全局环境的LuaTable

void Tick()

描述：

清除Lua的未手动释放的LuaBase对象(比如：LuaTable， LuaFunction)，以及其它一些事情。

需要定期调用，比如在MonoBehaviour的Update中调用。

void AddLoader(CustomLoader loader)

描述：

增加一个自定义loader

参数：

loader：一个包括了加载函数的委托，其类型为delegate byte[] CustomLoader(ref string filepath)，当一个文件被require时，这个loader会被回调，其参数是调用require所使用的参数，如果该loader找到文件，可以将其读进内存，返回一个byte数组。如果需要支持调试的话，而filepath要设置成IDE能找到的路径(相对或者绝对都可以)

void Dispose()

描述：

Dispose该LuaEnv。LuaEnv的使用建议：全局就一个实例，并在Update中调用GC方法，完全不需要时调用Dispose

LuaTable类

T Get(string key)

描述：

获取在key下，类型为T的value，如果不存在或者类型不匹配，返回null；

T GetInPath(string path)

描述：

和Get的区别是，这个函数会识别path里头的“.”，比如var i = tbl.GetInPath(“a.b.c”)相当于在lua里头执行i = tbl.a.b.c，避免仅为了获取中间变量而多次调用Get，执行效率更高。

void SetInPath(string path, T val)

描述：

和GetInPaht对应的setter；

void Get(TKey key, out TValue value)

描述：

上面的API的Key都只能是string，而这个API无此限制；

void Set(TKey key, TValue value)

描述：

对应Get的setter；

T Cast()

描述：

把该table转成一个T指明的类型，可以是一个加了CSharpCallLua声明的interface，一个有默认构造函数的class或者struct，一个Dictionary，List等等。

void SetMetaTable(LuaTable metaTable)

描述：

设置metaTable为table的metatable

LuaFunction类注意：用该类访问Lua函数会有boxing，unboxing的开销，为了性能考虑，需要频繁调用的地方不要用该类。建议通过table.Get获取一个delegate再调用(假设ABCDelegate是C#的一个delegate)。在使用使用table.Get之前，请先把ABCDelegate加到代码生成列表。

object[] Call(params object[] args)

描述：

以可变参数调用Lua函数，并返回该调用的返回值。

object[] Call(object[] args, Type[] returnTypes)

描述：

调用Lua函数，并指明返回参数的类型，系统会自动按指定类型进行转换。

void SetEnv(LuaTable env)

描述：

相当于lua的setfenv函数。

Lua API

CS对象

CS.namespace.class(...)

描述：

调用一个C#类型的构造函数,并返回类型实例

例如：

local v1=CS.UnityEngine.Vector3(1,1,1)

CS.namespace.class.field

描述：

访问一个C#静态成员

例如：

Print(CS.UnityEngine.Vector3.one)

CS.namespace.enum.field

描述：

访问一个枚举值

typeof函数

描述：

类似C#里头的typeof关键字，返回一个Type对象，比如GameObject.AddComponent其中一个重载需要一个Type参数

例如：

newGameObj:AddComponent(typeof(CS.UnityEngine.ParticleSystem))

无符号64位支持

uint64.tostring

描述：

无符号数转字符串。

uint64.divide

描述：

无符号数除法。

uint64.compare

描述：

无符号比较，相对返回0，大于返回正数，小于返回负数。

uint64.remainder

描述：

无符号数取模。

uint64.parse

描述： 字符串转无符号数。

xlua.structclone

描述：

克隆一个c#结构体

xlua.private_accessible(class)

描述：

让一个类的私有字段，属性，方法等可用

例子：

xlua.private_accessible(CS.UnityEngine.GameObject)

xlua.get_generic_method

描述：

获取一个泛型方法

例子：

local foo_generic = xlua.get_generic_method(CS.GetGenericMethodTest, 'Foo')local bar_generic = xlua.get_generic_method(CS.GetGenericMethodTest, 'Bar')local foo = foo_generic(CS.System.Int32, CS.System.Double)local bar = bar_generic(CS.System.Double, CS.UnityEngine.GameObject)-- call instance methodlocal o = CS.GetGenericMethodTest()local ret = foo(o, 1, 2)print(ret)-- call static methodbar(2, nil)

cast函数

描述：

指明以特定的接口访问对象，这在实现类无法访问的时候(比如internal修饰)很有用，这时可以这么来(假设下面的calc对象实现了C#的PerformentTest.ICalc接口)

例子：

cast(calc, typeof(CS.PerformentTest.ICalc))

然后就木有其它API了 访问csharp对象和访问一个table一样，调用函数跟调用lua函数一样，也可以通过操作符访问c#的操作符，下面是一个例如：

local v1=CS.UnityEngine.Vector3(1,1,1)

local v2=CS.UnityEngine.Vector3(1,1,1)

v1.x = 100

v2.y = 100

print(v1, v2)

local v3 = v1 + v2

print(v1.x, v2.x)

print(CS.UnityEngine.Vector3.one)

print(CS.UnityEngine.Vector3.Distance(v1, v2))

类型映射

基本数据类型

C#类型Lua类型sbyte，byte，short，ushort，int，uint，double，char，floatnumberdecimaluserdatalong，ulonguserdata/lua_Integer(lua53)bytes[]stringboolbooleanstringstring

复杂数据类型

C#类型Lua类型LuaTabletableLuaFunctionfunctionclass或者 struct的实例userdata，tablemethod，delegatefunction

LuaTable：

C#侧指明从Lua侧输入(包括C#方法的输入参数或者Lua方法的返回值)LuaTable类型，则要求Lua侧为table。或者Lua侧的table，在C#侧未指明类型的情况下转换成LuaTable。

LuaFunction：

C#侧指明从Lua侧输入(包括C#方法的输入参数或者Lua方法的返回值)LuaFunction类型，则要求Lua侧为function。或者Lua侧的function，在C#侧未指明类型的情况下转换成LuaFunction。

LuaUserData：

对应非C# Managered对象的lua userdata。

class或者 struct的实例:

从C#传一个class或者struct的实例，将映射到Lua的userdata，并通过__index访问该userdata的成员 C#侧指明从Lua侧输入指定类型对象，Lua侧为该类型实例的userdata可以直接使用；如果该指明类型有默认构造函数，Lua侧是table则会自动转换，转换规则是：调用构造函数构造实例，并用table对应字段转换到c#对应值后赋值各成员。

method， delegate：

成员方法以及delegate都是对应lua侧的函数。 C#侧的普通参数以及引用参数，对应lua侧函数参数；C#侧的返回值对应于Lua的第一个返回值；引用参数和out参数则按序对应于Lua的第2到第N个参数。

宏

HOTFIX_ENABLE

打开hotfix功能。

NOT_GEN_WARNING

反射时打印warning。

GEN_CODE_MINIMIZE

以偏向减少代码段的方式生成代码。

xLua的配置

xLua所有的配置都支持三种方式：打标签；静态列表；动态列表。

配置有两必须两建议：列表方式均必须是static的字段/属性

列表方式均必须放到一个static类

建议不用标签方式

建议列表方式配置放Editor目录(如果是Hotfix配置，而且类位于Assembly-CSharp.dll之外的其它dll，必须放Editor目录)

打标签

xLua用白名单来指明生成哪些代码，而白名单通过attribute来配置，比如你想从lua调用c#的某个类，希望生成适配代码，你可以为这个类型打一个LuaCallCSharp标签：

[LuaCallCSharp]publicclassA{

}

该方式方便，但在il2cpp下会增加不少的代码量，不建议使用。

有时我们无法直接给一个类型打标签，比如系统api，没源码的库，或者实例化的泛化类型，这时你可以在一个静态类里声明一个静态字段，该字段的类型除BlackList和AdditionalProperties之外只要实现了IEnumerable就可以了(这两个例外后面具体会说)，然后为这字段加上标签：

[LuaCallCSharp]public static List mymodule_lua_call_cs_list = new List()

{    typeof(GameObject),    typeof(Dictionary),

};

这个字段需要放到一个 静态类 里头，建议放到 Editor目录 。

动态列表

声明一个静态属性，打上相应的标签即可。

[Hotfix]public static List by_property{    get

{        return (from type in Assembly.Load("Assembly-CSharp").GetTypes()                where type.Namespace == "XXXX"

select type).ToList();

}

}

Getter是代码，你可以实现很多效果，比如按名字空间配置，按程序集配置等等。

这个属性需要放到一个 静态类 里头，建议放到 Editor目录 。

XLua.LuaCallCSharp

一个C#类型加了这个配置，xLua会生成这个类型的适配代码(包括构造该类型实例，访问其成员属性、方法，静态属性、方法)，否则将会尝试用性能较低的反射方式来访问。

一个类型的扩展方法(Extension Methods)加了这配置，也会生成适配代码并追加到被扩展类型的成员方法上。

xLua只会生成加了该配置的类型，不会自动生成其父类的适配代码，当访问子类对象的父类方法，如果该父类加了LuaCallCSharp配置，则执行父类的适配代码，否则会尝试用反射来访问。

反射访问除了性能不佳之外，在il2cpp下还有可能因为代码剪裁而导致无法访问，后者可以通过下面介绍的ReflectionUse标签来避免。

XLua.ReflectionUse

一个C#类型类型加了这个配置，xLua会生成link.xml阻止il2cpp的代码剪裁。

对于扩展方法，必须加上LuaCallCSharp或者ReflectionUse才可以被访问到。

建议所有要在Lua访问的类型，要么加LuaCallCSharp，要么加上ReflectionUse，这才能够保证在各平台都能正常运行。

XLua.DoNotGen

指明一个类里头的部分函数、字段、属性不生成代码，通过反射访问。

只能标准Dictionary的field或者property。key指明的是生效的类，value是一个列表，配置的是不生成代码的函数、字段、属性的名字。

和ReflectionUse的区别是：1、ReflectionUse指明的是整个类；2、当第一次访问一个函数(字段、属性)时，ReflectionUse会把整个类都wrap，而DoNotGen只wrap该函数(字段、属性)，换句话DoNotGen更lazy一些；

和BlackList的区别是：1、BlackList配了就不能用；2、BlackList能指明某重载函数，DoNotGen不能；

XLua.CSharpCallLua

如果希望把一个lua函数适配到一个C# delegate(一类是C#侧各种回调：UI事件，delegate参数，比如List:ForEach；另外一类场景是通过LuaTable的Get函数指明一个lua函数绑定到一个delegate)。或者把一个lua table适配到一个C# interface，该delegate或者interface需要加上该配置。

XLua.GCOptimize

一个C#纯值类型(注：指的是一个只包含值类型的struct，可以嵌套其它只包含值类型的struct)或者C#枚举值加上了这个配置。xLua会为该类型生成GC优化代码，效果是该值类型在lua和c#间传递不产生(C#)GC alloc，该类型的数组访问也不产生GC。各种无GC的场景，可以参考05_NoGC例子。

除枚举之外，包含无参构造函数的复杂类型，都会生成lua table到该类型，以及改类型的一维数组的转换代码，这将会优化这个转换的性能，包括更少的GC alloc。

XLua.AdditionalProperties

这个是GCOptimize的扩展配置，有的时候，一些struct喜欢把field做成是私有的，通过property来访问field，这时就需要用到该配置(默认情况下GCOptimize只对public的field打解包)。

标签方式比较简单，配置方式复杂一点，要求是Dictionary>类型，Dictionary的Key是要生效的类型，Value是属性名列表。可以参考XLua对几个UnityEngine下值类型的配置，SysGCOptimize类。

XLua.BlackList

如果你不要生成一个类型的一些成员的适配代码，你可以通过这个配置来实现。

标签方式比较简单，对应的成员上加就可以了。

由于考虑到有可能需要把重载函数的其中一个重载列入黑名单，配置方式比较复杂，类型是List>，对于每个成员，在第一层List有一个条目，第二层List是个string的列表，第一个string是类型的全路径名，第二个string是成员名，如果成员是一个方法，还需要从第三个string开始，把其参数的类型全路径全列出来。

例如下面是对GameObject的一个属性以及FileInfo的一个方法列入黑名单：

[BlackList]public static List> BlackList = new List>()  {    new List(){"UnityEngine.GameObject", "networkView"},    //new List(){ typeof(UnityEngine.GameObject).FullName, "networkView"},

new List(){"System.IO.FileInfo", "GetAccessControl", "System.Security.AccessControl.AccessControlSections"},    //new List(){ typeof(System.IO.FileInfo).FullName, "GetAccessControl",typeof(System.Security.AccessControl.AccessControlSections).FullName },};

下面是生成期配置，必须放到Editor目录下

CSObjectWrapEditor.GenPath

配置生成代码的放置路径，类型是string。默认放在"Assets/XLua/Gen/"下。

CSObjectWrapEditor.GenCodeMenu

该配置用于生成引擎的二次开发，一个无参数函数加了这个标签，在执行"XLua/Generate Code"菜单时会触发这个函数的调用。

Lua文件加载执行字符串

最基本是直接用LuaEnv.DoString执行一个字符串，当然，字符串得符合Lua语法 比如：

luaenv.DoString("print('hello world')")

完整代码见XLua\Tutorial\LoadLuaScript\ByString目录但这种方式并不建议，更建议下面介绍这种方法。

加载Lua文件

用lua的require函数即可 比如：

DoString("require 'byfile'")

完整代码见XLua\Tutorial\LoadLuaScript\ByFile目录

require实际上是调一个个的loader去加载，有一个成功就不再往下尝试，全失败则报文件找不到。 目前xLua除了原生的loader外，还添加了从Resource加载的loader，需要注意的是因为Resource只支持有限的后缀，放Resources下的lua文件得加上txt后缀(见附带的例子)。

建议的加载Lua脚本方式是：整个程序就一个DoString("require 'main'")，然后在main.lua加载其它脚本(类似lua脚本的命令行执行：lua main.lua)。

有童鞋会问：要是我的Lua文件是下载回来的，或者某个自定义的文件格式里头解压出来，或者需要解密等等，怎么办？问得好，xLua的自定义Loader可以满足这些需求。

自定义Loader

在xLua加自定义loader是很简单的，只涉及到一个接口：

public delegate byte[] CustomLoader(ref string filepath);

public void LuaEnv.AddLoader(CustomLoader loader)

通过AddLoader可以注册个回调，该回调参数是字符串，lua代码里头调用require时，参数将会透传给回调，回调中就可以根据这个参数去加载指定文件，如果需要支持调试，需要把filepath修改为真实路径传出。该回调返回值是一个byte数组，如果为空表示该loader找不到，否则则为lua文件的内容。 有了这个就简单了，用IIPS的IFS？没问题。写个loader调用IIPS的接口读文件内容即可。文件已经加密？没问题，自己写loader读取文件解密后返回即可。。。 完整示例见XLua\Tutorial\LoadLuaScript\Loader

C#访问Lua

这里指的是C#主动发起对Lua数据结构的访问。 本章涉及到的例子都可以在XLua\Tutorial\CSharpCallLua下找到。获取一个全局基本数据类型 访问LuaEnv.Global就可以了，上面有个模版Get方法，可指定返回的类型。

luaenv.Global.Get("a")

luaenv.Global.Get("b")

luaenv.Global.Get("c")

访问一个全局的table

也是用上面的Get方法，那类型要指定成啥呢？映射到普通class或struct

定义一个class，有对应于table的字段的public属性，而且有无参数构造函数即可，比如对于{f1 = 100, f2 = 100}可以定义一个包含public int f1;public int f2;的class。 这种方式下xLua会帮你new一个实例，并把对应的字段赋值过去。

table的属性可以多于或者少于class的属性。可以嵌套其它复杂类型。 要注意的是，这个过程是值拷贝，如果class比较复杂代价会比较大。而且修改class的字段值不会同步到table，反过来也不会。

这个功能可以通过把类型加到GCOptimize生成降低开销，详细可参见配置介绍文档。 那有没有引用方式的映射呢？有，下面这个就是：

映射到一个interface

这种方式依赖于生成代码(如果没生成代码会抛InvalidCastException异常)，代码生成器会生成这个interface的实例，如果get一个属性，生成代码会get对应的table字段，如果set属性也会设置对应的字段。甚至可以通过interface的方法访问lua的函数。

更轻量级的by value方式：映射到Dictionary<>，List<>

不想定义class或者interface的话，可以考虑用这个，前提table下key和value的类型都是一致的。

另外一种by ref方式：映射到LuaTable类

这种方式好处是不需要生成代码，但也有一些问题，比如慢，比方式2要慢一个数量级，比如没有类型检查。

访问一个全局的function

仍然是用Get方法，不同的是类型映射。映射到delegate

这种是建议的方式，性能好很多，而且类型安全。缺点是要生成代码(如果没生成代码会抛InvalidCastException异常)。

delegate要怎样声明呢？ 对于function的每个参数就声明一个输入类型的参数。 多返回值要怎么处理？从左往右映射到c#的输出参数，输出参数包括返回值，out参数，ref参数。

参数、返回值类型支持哪些呢？都支持，各种复杂类型，out，ref修饰的，甚至可以返回另外一个delegate。

delegate的使用就更简单了，直接像个函数那样用就可以了。

映射到LuaFunction

这种方式的优缺点刚好和第一种相反。 使用也简单，LuaFunction上有个变参的Call函数，可以传任意类型，任意个数的参数，返回值是object的数组，对应于lua的多返回值。

使用建议访问lua全局数据，特别是table以及function，代价比较大，建议尽量少做，比如在初始化时把要调用的lua function获取一次(映射到delegate)后，保存下来，后续直接调用该delegate即可。table也类似。

如果lua侧的实现的部分都以delegate和interface的方式提供，使用方可以完全和xLua解耦：由一个专门的模块负责xlua的初始化以及delegate、interface的映射，然后把这些delegate和interface设置到要用到它们的地方。

Lua调用C#本章节涉及到的实例均在XLua\Tutorial\LuaCallCSharp下

new C#对象

你在C#这样new一个对象：

var newGameObj = new UnityEngine.GameObject();

对应到Lua是这样：

local newGameObj = CS.UnityEngine.GameObject()

基本类似，除了：

1. lua里头没有new关键字；

2. 所有C#相关的都放到CS下，包括构造函数，静态成员属性、方法；

如果有多个构造函数呢？放心，xlua支持重载，比如你要调用GameObject的带一个string参数的构造函数，这么写：

local newGameObj2 = CS.UnityEngine.GameObject('helloworld')

访问C#静态属性，方法

读静态属性

CS.UnityEngine.Time.deltaTime

写静态属性

CS.UnityEngine.Time.timeScale = 0.5

调用静态方法

CS.UnityEngine.GameObject.Find('helloworld')

小技巧：如果需要经常访问的类，可以先用局部变量引用后访问，除了减少敲代码的时间，还能提高性能：

local GameObject = CS.UnityEngine.GameObject

GameObject.Find('helloworld')

访问C#成员属性，方法

读成员属性

testobj.DMF

写成员属性

testobj.DMF = 1024

调用成员方法

注意：调用成员方法，第一个参数需要传该对象，建议用冒号语法糖，如下

testobj:DMFunc()

父类属性，方法

xlua支持(通过派生类)访问基类的静态属性，静态方法，(通过派生类实例)访问基类的成员属性，成员方法

参数的输入输出属性(out，ref)

Lua调用侧的参数处理规则：C#的普通参数算一个输入形参，ref修饰的算一个输入形参，out不算，然后从左往右对应lua 调用侧的实参列表；

Lua调用侧的返回值处理规则：C#函数的返回值(如果有的话)算一个返回值，out算一个返回值，ref算一个返回值，然后从左往右对应lua的多返回值。

重载方法

直接通过不同的参数类型进行重载函数的访问，例如：

testobj:TestFunc(100)

testobj:TestFunc('hello')

将分别访问整数参数的TestFunc和字符串参数的TestFunc。

注意：xlua只一定程度上支持重载函数的调用，因为lua的类型远远不如C#丰富，存在一对多的情况，比如C#的int，float，double都对应于lua的number，上面的例子中TestFunc如果有这些重载参数，第一行将无法区分开来，只能调用到其中一个(生成代码中排前面的那个)

操作符

支持的操作符有：+，-，*，/，==，一元-，

参数带默认值的方法

和C#调用有默认值参数的函数一样，如果所给的实参少于形参，则会用默认值补上。

可变参数方法

对于C#的如下方法：

void VariableParamsFunc(int a, params string[] strs)

可以在lua里头这样调用：

testobj:VariableParamsFunc(5, 'hello', 'john')

使用Extension methods

在C#里定义了，lua里就能直接使用。

泛化(模版)方法

不直接支持，可以通过Extension methods功能进行封装后调用。

枚举类型

枚举值就像枚举类型下的静态属性一样。

testobj:EnumTestFunc(CS.Tutorial.TestEnum.E1)

上面的EnumTestFunc函数参数是Tutorial.TestEnum类型的。

枚举类支持__CastFrom方法，可以实现从一个整数或者字符串到枚举值的转换，例如：

CS.Tutorial.TestEnum.__CastFrom(1)

CS.Tutorial.TestEnum.__CastFrom('E1')

delegate使用(调用，+，-)

C#的delegate调用：和调用普通lua函数一样

+操作符：对应C#的+操作符，把两个调用串成一个调用链，右操作数可以是同类型的C# delegate或者是lua函数。

-操作符：和+相反，把一个delegate从调用链中移除。Ps：delegate属性可以用一个luafunction来赋值。

event

比如testobj里头有个事件定义是这样：public event Action TestEvent;

增加事件回调

testobj:TestEvent('+', lua_event_callback)

移除事件回调

testobj:TestEvent('-', lua_event_callback)

64位整数支持

Lua53版本64位整数(long，ulong)映射到原生的64位整数，而luajit版本，相当于lua5.1的标准，本身不支持64位，xlua做了个64位支持的扩展库，C#的long和ulong都将映射到userdata：

支持在lua里头进行64位的运算，比较，打印

支持和lua number的运算，比较

要注意的是，在64扩展库中，实际上只有int64，ulong也会先强转成long再传递到lua，而对ulong的一些运算，比较，我们采取和java一样的支持方式，提供一组API，详情请看API文档。

C#复杂类型和table的自动转换

对于一个有无参构造函数的C#复杂类型，在lua侧可以直接用一个table来代替，该table对应复杂类型的public字段有相应字段即可，支持函数参数传递，属性赋值等，例如： C#下B结构体(class也支持)定义如下：

public struct A

{

public int a;

}

public struct B

{

public A b;

public double c;

}

某个类有成员函数如下：

void Foo(B b)

在lua可以这么调用

obj:Foo({b = {a = 100}, c = 200})

获取类型(相当于C#的typeof)

比如要获取UnityEngine.ParticleSystem类的Type信息，可以这样

typeof(CS.UnityEngine.ParticleSystem)

“强”转

lua没类型，所以不会有强类型语言的“强转”，但有个有点像的东西：告诉xlua要用指定的生成代码去调用一个对象，这在什么情况下能用到呢？有的时候第三方库对外暴露的是一个interface或者抽象类，实现类是隐藏的，这样我们无法对实现类进行代码生成。该实现类将会被xlua识别为未生成代码而用反射来访问，如果这个调用是很频繁的话还是很影响性能的，这时我们就可以把这个interface或者抽象类加到生成代码，然后指定用该生成代码来访问：

cast(calc, typeof(CS.Tutorial.Calc))

上面就是指定用CS.Tutorial.Calc的生成代码来访问calc对象。