Skip to main content

Method overloads

Lua has no static types, so same-name multiple signatures cannot be chosen at compile time. ZLua provides: default dispatch, full-signature keys (lazy resolution on __index miss, then cached), Bind-time [LuaAlias] / XML short names, and local caching of direct closures in scripts. See: Demo.Run, app.lua.

Short intro: Method calls. Day-to-day demo:Run(10) is enough in Lua calling C#; read this page for ambiguity or hot paths. Authoritative details: Overload Spec.

Open generic methods (GetComponent<T>, etc.) are not an overload problem — see Generics.

How to choose​

ApproachSyntaxWhen
Default dispatchdemo:Run(10)Arguments uniquely match
Full-signature key (lazy)demo['Run(System.Int32)'](demo, 5)Pick one overload exactly; first access resolves on miss and caches as direct
[LuaAlias] / XMLdemo:run_i32(5)You can edit C# or XML; hot path needs colon + short name
Local direct cachelocal run = demo['Run(System.Int32)']; run(demo, 5)Same fixed overload in a tight loop

After Bind, there is no runtime API to attach new short names; colon + short name is Bind-time alias only.

Default dispatch​

demo:Run(10) -- Run(int)
demo:Run("hello") -- Run(string)

With a single public overload, the short name is direct (zero dispatch); with multiple, you get dispatch matched by arguments.

Default parameters​

C# trailing optional formals (HasDefault) are supported. Lua arg count may fall in [minArity, maxArity]; omitted trailing formals are filled with C# defaults at invoke (cached at Bind; hot path does not parse metadata blobs).

public static int Foo(int x, int y = 5) => x + y;
public static string Bar(string s, int a = 1, int b = 2) => $"{s}:{a},{b}";
public static int G(int x) => x;
public static int G(int x, int y = 5) => x + y;
Demo.Foo(1) -- y=5
Demo.Foo(1, 9)
Demo.Bar("hi") -- a=1, b=2
Demo.Bar("hi", 7) -- b=2
Demo.G(1) -- pick G(int), not the “expand defaults” G(int,int)
Demo.G(1, 4) -- G(int, int)
RuleNotes
Trailing contiguous defaults onlySame as C#: cannot “skip” a required formal in the middle
Too few argsCannot cover the first non-default formal → argument mismatch / no matching overload
Multi-overload tie-breakWhen conversion scores tie, the candidate that uses fewer defaults wins
ConstructorsType(...) / SMT.__call support the same rules

Authoritative details: Overload Spec §3.3.

Full-signature keys (lazy resolution)​

Bind does not pre-hang MethodName(Type.FullName,…) keys for every method. On metatable access, if the method table misses and the key is a string containing (, ZLua looks up by signature on the type and base-class chain, builds a direct closure, caches it, and returns it.

ItemNotes
Key formatMethodName(parameter Type.FullName,…), no return type; name is CLR MethodInfo.Name (not a [LuaAlias] short name)
ScopeAny public instance/static method (including single-candidate; aliased methods still use CLR name in the key)
ExcludedInstance constructors and static .cctor — construction stays on type-table __call
vs short nameDoes not change existing Run direct/dispatch; adds signature-key entries only

With multiple overloads, short Run stays dispatch; full-signature keys bypass dispatch:

KeyMeaning
RunRuntime dispatch (when multiple candidates)
Run(System.Int32)Fixed Run(int) (cached after first bracket-key access)
Run(System.String)Fixed Run(string)
demo['Run(System.Int32)'](demo, 5)
demo['Run(System.String)'](demo, "hi")
-- Single candidate works too: demo['GetValue()'](demo)

-- Hot path: after first miss the key is cached; keep a local
local run_i32 = demo['Run(System.Int32)']
run_i32(demo, 20)

Keys contain parentheses, so you cannot write demo:Run(System.Int32)(...); use bracket keys + dot + explicit self. For colon + short name, configure [LuaAlias] in C# or XML (next section).

Use zlua.signature(...) to build the parameter parenthesis part; see Overload Spec §4.1.

[LuaAlias]​

[LuaAlias("run_i32")]
public void Run(int value) { }

public void Run(string value) { }
demo:run_i32(10) -- short name + colon, direct; Run(int) renamed, default "Run" not registered for it
demo:Run("hi") -- Run(string) not renamed → dispatch

An alias is a rename (replaces the default Lua key), not an append. XML (luaAliasXmlPaths / ZLuaAlias) and more examples: LuaAlias. C# extensions on the instance table: Extension methods.

Common mistakes​

SymptomFix
Wrong overload / ambiguousFull-signature key, [LuaAlias], or cache a direct closure locally; watch default-parameter tie-break
argument mismatch (with defaults)Required formals not supplied; cannot skip middle parameters
Want demo['(System.Int32)']Forbidden; must include the method name: Run(System.Int32)
Full-signature key member not foundCheck CLR method name and Type.FullName against metadata; constructors are not full-signature keys
Want runtime short-name registrationNot supported; use Bind-time [LuaAlias] / XML, or bracket keys + local cache