LuaMember AllowNil support

[ashtonmeuser]

Allows LuaMembers that hold LuaObjects to accept nil assignment from Lua via [LuaMember("my_prop", AllowNil = true)]. This aligns with the C# concept of said LuaObjects being reference types, and thus, accepting null

[LuaObject]
public partial class AllowNilReferencedObject
{
    [LuaMember("label")]
    public string Label { get; set; } = "";
}

[LuaObject]
public partial class AllowNilMemberContainer
{
    [LuaMember("optionalObject", AllowNil = true)]
    public AllowNilReferencedObject OptionalObject { get; set; } = null!;

    [LuaMember("requiredObject")]
    public AllowNilReferencedObject RequiredObject { get; set; } = null!;
}

state.Environment["target"] = new AllowNilMemberContainer();
state.Environment["reference"] = new AllowNilReferencedObject();

target.optionalObject = reference -- Works
target.optionalObject = nil -- Works
target.requiredObject = reference -- Works
target.requiredObject = nil -- Fails

In C#, state.Environment["target"]. OptionalObject is null.

[ashtonmeuser]

Thoughts, @nuskey8 @akeit0?

[akeit0]

I am wondering if it should be applied automatically with nullable in nullable enable context.

[ashtonmeuser]

I am wondering if it should be applied automatically with nullable in nullable enable context.

I considered this and originally used nullable annotations to determine whether or not nil was accepted. However, nullable context support in Unity — where I’d assume a fair share of Lua-CSharp usage is — is spotty, and it typically isn’t used. If you want to go down that route, I think it's a great addition to this PR but doesn't necessarily preclude merging this one.

[akeit0]

I am also uncertain about consistency.
If we provide AllowNil for properties, I think it would be insufficient if we do not also have AllowNil for function parameters.

[ashtonmeuser]

Good point. Although, with a large usage share not having nullable context, there's really only so much you can do. Wholesale accepting nil for reference types would be a large breaking change.

[ashtonmeuser]

@akeit0 Any chance we can get this merged?

I know you raised the issue of nil function params, but that's 1) a huge lift, 2) will surely be a breaking change, and 3) won't be usable in a Unity context. Further, nil can be accepted as function params, albeit a little awkwardly, using LuaValue and then TryRead<mytype>.

This PR provides a minimal change that is opt in only. I'd love to see this merged.

[Copilot]

Copilot review overview

🟢 Approval recommended

No unresolved review issues were identified.

Review effort: Lite
Findings: None

What changed in this PR

Adds AllowNil support for LuaObject reference-type members, allowing Lua nil assignments to map to C# null while preserving required-member validation.

Changes:

• Adds AllowNil attribute and metadata support.
• Generates nullable assignment handling.
• Adds diagnostics and tests for allowed and rejected nil assignments.

File	Description
tests/​Lua.Tests/​LuaObjectTests.cs	Tests optional and required LuaObject members.
src/​Lua.SourceGenerator/​PropertyMetadata.cs	Reads AllowNil metadata.
src/​Lua.SourceGenerator/​LuaObjectGenerator.Emit.cs	Emits nullable assignment handling.
src/​Lua.SourceGenerator/​DiagnosticDescriptors.cs	Adds invalid-use diagnostics.
src/​Lua.Annotations/​Attributes.cs	Adds the AllowNil attribute property.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[akeit0]

Thanks!
Nuskey and I discussed this and decided to merge this PR for now.
We plan to handle nullables, including value types, later.

[akeit0]

@ashtonmeuser
I created a pr which replaces AllowNil to standard AllowNull.

#341

Any thoughts on this?

[ashtonmeuser]

We plan to handle nullables, including value types, later.

That's great to hear! That will be a very welcome feature.

I created a pr which replaces AllowNil to standard AllowNull.

That's fine by me if that's your preference. It's a bit of a judgement call as it's "nil" in Lua and "null" in C#.