跳到主要内容

LuaAlias

为 C# 方法重载提供 Lua 侧换名键,O(1) 绑定到单一重载,绕过运行时分派(dispatch)。有别名时 不再注册 C# 默认方法名。

using ZLua;

public class Demo
{
[LuaAlias("run_i32")]
public void Run(int value) { x = value; }

public void Run(string value) { x = value?.Length ?? 0; }
}
local demo = CSharp.AC.Demo()
demo:run_i32(10) -- 直接命中 Run(int)
demo:Run("hi") -- 仍走 Run 的 dispatch

属性定义​

[AttributeUsage(AttributeTargets.Method, AllowMultiple = false, Inherited = false)]
public sealed class LuaAliasAttribute : Attribute
{
public string Alias { get; }
public LuaAliasAttribute(string alias);
}
项说明
目标仅 Method
多重每个方法最多一个别名
继承不继承到子类重写

键空间规则​

[LuaAlias] 在 Bind 期 替换该方法的默认 Lua 键;并 允许与其它方法的默认名或其它别名重复(重复则并入同一 overload 组,走 dispatch)。若别名下 仅一个 候选,则为 direct,热路径首选。

完整规则见 重载规范 §5。同名多候选时还会自动挂全签名键(§3.7)。

[LuaAlias("run_i32")] // 通常单候选 → direct
public void Run(int value) { }

public void Run(string value) { } // 默认名仍进 "Run" 组

XML 配置(不可改源码时)​

Settings XML 用于构建期已知的预编译 / AOT 程序集。热更程序集可用 Attribute,或在 Il2Cpp Player 加载程序集后、首次类型绑定前调用对应的 InteropMetadata.Register*Xml;Editor Mono 的注册方法为空实现。

与 [LuaMarshalAs] 分开配置:Settings 使用独立字段 luaAliasXmlPaths,根元素 ZLuaAlias。

<?xml version="1.0" encoding="utf-8"?>
<ZLuaAlias version="1">
<Assembly name="Assembly-CSharp">
<Type fullName="Demo">
<Method name="Run" signature="(System.Int32)" alias="run_i32"/>
</Type>
</Assembly>
</ZLuaAlias>
字段说明
Assembly/@name程序集短名
Type/@fullName类型全名
Method/@nameC# 方法名
Method/@signature仅参数部分,如 (System.Int32)
Method/@aliasLua 侧最终键名(必填;替换默认名)

优先级:Attribute > XML。有别名则 不再挂 MethodInfo.Name。权威全文:重载规范 §5.4。

静态 / 实例​

方法种类别名写入位置Lua 调用
实例方法实例 methodTableobj:alias(...)
静态方法类型表 methodTableTypeTable.alias(...)

与全签名键的关系​

方式时机适用
全签名键 Run(System.Int32)__index miss 懒解析并缓存精确点名,无需改 C#、无需运行时 API
[LuaAlias] / XML类型 EnsureBinding 时Bind 期固定短名、热路径首选冒号
本地缓存 direct脚本自行保存 closure热路径复用;无运行时挂短名 API

[LuaAlias] / XML 是 methodTable 上的 换名(替换默认键);全签名键解决「点名哪一个重载」。

Mono / Il2Cpp 支持​

运行时支持
Mono (Editor)✅
Il2Cpp (Player)✅

相关文档​