Marshal 模型概览
:::tip 谁该读本文
需要理解参数如何在 C# 与 Lua 间转换、何时用 [LuaMarshalAs] / Opaque 的开发者。 查表用 Marshal 速查表；ref/out 实操见 指南。
:::
ZLua 在 Mono 与 Il2Cpp 上 Lua 可见 Marshal 语义一致；Il2Cpp 侧重零 GC 与生成代码快速路径。
双向调用路径
默认规则摘要
| 类别 | C# → Lua | Lua → C# |
|---|---|---|
| 基元 / enum | integer / number / boolean | 同左 |
| string | string | string |
| class | ClassUserData | userdata / nil |
| struct | ByValUserData 或 OpaqueValue | StructUserData / Type(...)（默认不接受 table） |
| delegate | DelegateUserData | function 或 userdata |
| array | ArrayUserData | ArrayUserData |
完整表格：Marshal 速查表。
ref / out / in（Lua → C#）
Lua 侧 不区分 ref/out/in，统一按 ref 语义处理：
| Lua 实参 | 行为 |
|---|---|
同型 ByValUserData（如 Point2D(...)）/ 兼容 Opaque | 真 ref，C# 修改写回 |
| 裸 number / string / table | 拷贝到临时槽，不写回 local |
GetFunction 取得的 delegate 调用与 delegate bridge 上 ref/out/in 默认 Push OpaqueValue（见 OPAQUE）；params 仍不支持。
[LuaMarshalAs] 覆盖
| LuaMarshalType | 典型用途 |
|---|---|
| UserData | 强制 boxed userdata（基元、enum、string） |
| Bytes | byte[] ↔ Lua string |
| OpaqueLightUserData | C#→Lua 栈上 struct 临时句柄 → zlua.to_user_data |
合法组合见 LuaMarshalAs 参考。
分册索引（何时读哪本）
| 类型 | 规范 |
|---|---|
| 总览与默认表 | Marshal 规范 |
| byref / Opaque | BYREF、OPAQUE |
| struct | STRUCT |
| class / 引用 | CLASS |
| Delegate / 回调 | FUNCTION |
| 日常查表 | Marshal 速查表 |