跳到主要内容

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。见 值类型。

相关文档​