跳到主要内容

LuaMarshalAs

覆盖 C# ↔ Lua 双向调用时的 默认编组规则。标注于参数、返回值、方法或字段。

using ZLua;

public void SendRaw([LuaMarshalAs(LuaMarshalType.Bytes)] byte[] data) { }

[return: LuaMarshalAs(LuaMarshalType.OpaqueLightUserData)]
public Point2D GetPointOnStack() { ... }

类型定义​

public enum LuaMarshalType
{
    Default,
    UserData,
    Bytes,
    OpaqueLightUserData,
}

[Flags]
public enum LuaMarshalFlags
{
    None = 0,
    OptionalField = 1,  // struct table 组装时缺键不报错
}

[AttributeUsage(AttributeTargets.Parameter | AttributeTargets.ReturnValue
    | AttributeTargets.Method | AttributeTargets.Field)]
public sealed class LuaMarshalAsAttribute : Attribute
{
    public LuaMarshalType LuaMarshalType { get; }
    public LuaMarshalFlags Flags { get; set; }
    public LuaMarshalAsAttribute(LuaMarshalType luaMarshalType = LuaMarshalType.Default);
}

LuaMarshalType 说明​

值方向效果
Default双向使用 编组速查表 默认规则
UserData双向强制 full userdata（替代默认 boolean/number/string 等）
Bytes双向byte[] ↔ Lua string（原始 octet，非 UTF-8 文本语义）
OpaqueLightUserData仅 C# → LuaPush lightuserdata 临时令牌（StructStackScope handle）；须同步链内使用或 zlua.to_user_data 升级

合法组合（摘要）​

Default 对所有类型均合法。下表为 Default 之外 可显式标注的值：

C# 类型合法 LuaMarshalType
基元（bool、char、整型、float/double）UserData
IntPtr / UIntPtr / nint / nuintUserData
stringUserData、Bytes
byte[]Bytes、UserData
T[] / 多维数组UserData
enumUserData
structUserData、OpaqueLightUserData（后者仅 C#→Lua）
class / interface / Delegate / objectUserData
Nullable<T>同 T 的合法集合
非托管指针、函数指针、TypedReference、decimal、ref struct仅 Default（或类型本身不支持）

方向过滤： OpaqueLightUserData 标注于纯 Lua→C# 形参 时视为非法，Editor 回退 Default 并打错误日志。

完整规则见 编组规范 §6.2。

非法标注行为​

行为说明
编组静默回退 Default，不中断调用
Editor 日志输出 [ZLua] Invalid LuaMarshalAs: ... falling back to Default
Player不打印日志，仍回退 Default

示例​

byte[] 作为 Lua string​

public void Upload([LuaMarshalAs(LuaMarshalType.Bytes)] byte[] payload) { }
Upload("\001\002\003")  -- Lua string 作为字节序列

强制 enum userdata​

public void SetColor([LuaMarshalAs(LuaMarshalType.UserData)] Color c) { }
local c = CSharp.AC['MyGame.Color'](CSharp.AC['MyGame.Color'].Red)
SetColor(c)

C#→Lua 栈上 struct 临时句柄​

[return: LuaMarshalAs(LuaMarshalType.OpaqueLightUserData)]
public Point2D GetPointHandle() { ... }
local opaque = GetPointHandle()      -- lightuserdata，同步链内有效
local ud = zlua.to_user_data(opaque) -- 升级为 StructUserData

解析优先级​

对单个形参 / 返回值：

  1. 参数 / 返回值上的 [LuaMarshalAs]
  2. 方法级 [LuaMarshalAs]（覆盖整方法，除非被更细粒度标注覆盖）
  3. Default

Mono / Il2Cpp 支持​

运行时支持
Mono (Editor)✅
Il2Cpp (Player)❌（MVP 未实现）

相关文档​