ref / in / out
权威:BYREF、OPAQUE。特性级强制形态见 LuaMarshalAs;0GC 套路见 0GC Marshal。
双路径摘要
| 方向 | 行为 |
|---|---|
C# → Lua(GetFunction / delegate 桥) | ref / out / in 默认 Push OpaqueValue |
Lua → C# · ref / in | 仍占实参;能否写回看实参形态(见下表) |
Lua → C# · out | 不占实参;Invoke 后以 多返回值 吐出(return, out1, …) |
ref / in 写回规则(直觉)
| Lua 实参形态 | 写回 C# byref |
|---|---|
OpaqueValue(get/set_opaquevalue) | ✅ |
| 同型 ByValUserData(如 struct userdata) | ✅(真 ref 语义) |
| 裸 number / string / 多数 ByObj | ❌ |
local x = 5
Demo.Increment(x) -- 若形参为 ref int:裸 number 不写回,x 仍为 5
local p = Point2D(1, 2)
Demo.Offset(p) -- ref Point2D:字段可写回 p
out:多返回值
-- void GetPosition(out float x, out float y, out float z)
local x, y, z = Demo.GetPosition()
-- bool TryGet(out float x, out float y)
local ok, x, y = Demo.TryGet()
需要写回同一 Lua 可观察槽时用 ref,不要用 number 占位 out。
Opaque 读写
C#→Lua 拿到的 byref 槽位通常是 Opaque:
-- 在同一次同步调用链内
local v = zlua.get_opaquevalue(slot)
zlua.set_opaquevalue(slot, newValue)
对 ref Point2D 等值类型形参,传入同型 ByValUserData(如 Point2D(1, 2))即可写回;无需额外 API。详见 值类型、常用 zlua 库。
注意
Opaque 不可跨 pcall / 跨帧持久化当长期句柄用。需要 userdata 门面时用 zlua.to_user_data(见规范)。
与值类型章的关系
by-val struct 是 拷贝;要「改字段并反映到 C#」须对 ref 形参传入同型 userdata,或走 Opaque。见 值类型。