跳到主要内容

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 配置（不可改源码时）​

与 [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(...)

与全签名键 / register_method 的关系​

方式时机适用
全签名键 Run(System.Int32)Bind 期自动（同名多候选）精确点名，无需改 C#、无需 API
[LuaAlias] / XML类型 EnsureBinding 时编译期固定短名、热路径首选
zlua.register_methodLua 运行时把 direct（常来自全签名键）挂成自定义短名，便于 obj:alias(...)

[LuaAlias] / XML 是 methodTable 上的 换名（替换默认键）；全签名键解决「点名哪一个重载」；register_method 在运行时挂 额外 空位短名。

Mono / Il2Cpp 支持​

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

相关文档​