From 991baa2610c8954acfc0f523cc87a2a5dbd7adce Mon Sep 17 00:00:00 2001
From: Brues <5278969+brues-code@users.noreply.github.com>
Date: Sun, 6 Sep 2026 14:16:39 -0500
Subject: [PATCH] feat(lua): cap upvalues at Lua 5.1's 60 rather than the byte
The limit shipped at 255, the structural ceiling -- f->nups and
LClosure.nupvalues are lu_byte, so that is the most a closure can hold.
But the point of the change is that a function valid on a 5.1 client
should load here, and 5.1's own MAXUPVALUES is 60. Anything past that is
not a compatibility gap, it is an invitation to write something no other
client would accept, which is not a thing to be first at.
One constant. Nothing in either hook depends on which number it is: the
spill path, the stale-clear and the emission loop are unchanged, and the
refusal still comes from the engine's own luaY_checklimit, so its message
carries whichever limit is in force.
Verified in-game: 60 upvalues load and sum correctly, 61 fails with
"too many upvalues (limit=60)".
---
README.md | 2 +-
docs/API.md | 12 ++++++------
src/Offsets.h | 3 ++-
src/luasyntax/Upvalues.cpp | 18 ++++++++++++------
4 files changed, 21 insertions(+), 14 deletions(-)
diff --git a/README.md b/README.md
index a16851f6..69c51c97 100644
--- a/README.md
+++ b/README.md
@@ -22,7 +22,7 @@ The flagship feature: run modern Lua 5.1 addon code on 1.12's Lua 5.0 VM.
| Feature | Effect |
|---------|--------|
| [Syntax](docs/API.md#lua-51-syntax) | Compiles the Lua 5.1 length (`#`), modulo (`%`), `...`-expression, `0x` hex-literal, and leveled long bracket (`[=[ ]=]`) syntax that vanilla's Lua 5.0 rejects, by rewriting addon source before it compiles. Each addon file also receives its `(name, table)` through `...` (`local name, tbl = ...`). |
-| [Upvalue limit](docs/API.md#upvalue-limit) | A function can use up to 255 upvalues, the outer locals it refers to. Lua 5.0 stops at 32 and rejects the whole file. Lua 5.1 allows 60, so a large handler that reads many file-level locals can be valid 5.1 and still fail to load here. Nothing changes for a function within 32. |
+| [Upvalue limit](docs/API.md#upvalue-limit) | A function can use up to 60 upvalues, the outer locals it refers to, matching Lua 5.1. Lua 5.0 stops at 32 and rejects the whole file, so a large handler that reads many file-level locals can be valid 5.1 and still fail to load here. Nothing changes for a function within 32. |
| [String methods](docs/API.md#string-methods-supper-sformat) | Every string value accepts method calls — `("asd"):upper()`, `("%d gold"):format(n)`, `msg:match("^!(%w+)")` — resolving through the `string` table, the way Lua 5.1 works. Works on literals and variables, in-world and on the login screen, and inside coroutines. |
| [Script-handler arguments](docs/API.md#setmodernscriptargsenable--getmodernscriptargs) | Frame-script handlers receive their values as positional arguments — `OnMouseWheel(self, delta)`, `OnClick(self, button)`, `OnEvent(self, event, ...)`, etc. — so modern addon ports work unmodified. The `this` / `arg1` globals stay set. A handler that declares no parameters is unaffected. A handler that declared a parameter and expected nil now receives its real value. On by default. `SetModernScriptArgs(false)` restores exact vanilla dispatch. |
diff --git a/docs/API.md b/docs/API.md
index 5053758b..8cb63af2 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -9285,15 +9285,15 @@ needs that addon's opt-in.
### Upvalue limit
-A function can use up to 255 upvalues — the outer locals it refers to.
+A function can use up to 60 upvalues — the outer locals it refers to.
Lua 5.0 stops at 32 and rejects the whole file with `too many upvalues
-(limit=32)`. Lua 5.1 allows 60. A large handler that reads many file-level
-locals can be valid Lua 5.1 and still fail to load here for that reason
-alone. ClassicAPI raises the limit to 255, the most a closure can hold.
+(limit=32)`. A large handler that reads many file-level locals can be
+valid Lua 5.1, which allows 60, and still fail to load here for that
+reason alone. ClassicAPI raises the limit to the same 60.
-Nothing changes for a function within the old limit. Past 255 the error is
-the same message with the new number: `too many upvalues (limit=255)`.
+Nothing changes for a function within the old limit. Past 60 the error is
+the same message with the new number: `too many upvalues (limit=60)`.
### String methods (`s:upper()`, `s:format(...)`)
diff --git a/src/Offsets.h b/src/Offsets.h
index c621a766..874b0a05 100644
--- a/src/Offsets.h
+++ b/src/Offsets.h
@@ -5168,7 +5168,8 @@ enum Offsets {
// parser is dynamic (nups and LClosure.nupvalues are bytes, OP_GETUPVAL's B
// field is 9 bits, closures are sized per instance, the debug-name array
// grows with luaM_growaux). LuaSyntax::Upvalues co-hooks the two readers and
- // spills entries 33+ into side storage, raising the ceiling to the byte.
+ // spills entries 33+ into side storage, raising the limit to Lua 5.1's 60.
+ // The structural ceiling is the byte, 255, if it is ever wanted.
//
// indexupvalue(fs, name, v) -> index. `__fastcall(ecx = FuncState*, edx =
// TString *name, [stack] expdesc *v)`, RET 4. Scans fs->upvalues for
diff --git a/src/luasyntax/Upvalues.cpp b/src/luasyntax/Upvalues.cpp
index 89bd8bdc..54e55e24 100644
--- a/src/luasyntax/Upvalues.cpp
+++ b/src/luasyntax/Upvalues.cpp
@@ -11,7 +11,7 @@
// You should have received a copy of the GNU General Public License along with
// ClassicAPI. If not, see .
-// Lifts the parser's limit of 32 upvalues per function to 255.
+// Lifts the parser's limit of 32 upvalues per function to Lua 5.1's 60.
//
// Lua 5.0 refuses the 33rd upvalue with "too many upvalues (limit=32)". Lua 5.1
// allows 60, so a function written against a modern client can be perfectly
@@ -33,8 +33,8 @@
// complete to emit one OP_MOVE / OP_GETUPVAL per entry after OP_CLOSURE.
// Everything downstream is sized dynamically -- f->nups and LClosure.nupvalues
// are bytes, OP_GETUPVAL's B field is 9 bits, closures are allocated per
-// instance, the debug-name array grows on demand -- so the byte is the real
-// ceiling and the array is the only obstacle.
+// instance, the debug-name array grows on demand -- so the structural ceiling
+// is the byte, 255, and the array is the only obstacle in the way of it.
//
// THE APPROACH. Co-hook both readers and keep entries 33 and up in side storage
// keyed by the FuncState's address. A function that stays within 32 upvalues
@@ -84,7 +84,13 @@ static_assert(sizeof(Expdesc) == Offsets::SIZEOF_LUA_EXPDESC,
"expdesc must match the parser's 20-byte stride");
constexpr int kNativeSlots = Offsets::LUA_PARSER_NATIVE_UPVALUE_SLOTS;
-constexpr int kLimit = 255; // f->nups and LClosure.nupvalues are lu_byte
+
+// Lua 5.1's own MAXUPVALUES. Addons are written against that, so it is the
+// number that makes a 5.1-valid function load, rather than an invitation to
+// write something no other client would accept. The structural ceiling is 255
+// (f->nups and LClosure.nupvalues are lu_byte) and nothing below depends on
+// which of the two this is: raising it is this constant and nothing else.
+constexpr int kLimit = 60;
constexpr int32_t VLOCAL = 5;
constexpr int32_t VRELOCABLE = 10;
@@ -142,8 +148,8 @@ int __fastcall IndexUpvalue_h(void *fs, void *name, Expdesc *v) {
if (SameUpvalue(spill[i], *v))
return kNativeSlots + static_cast(i);
- // The engine's own limit check with the byte's ceiling: over it, this raises
- // "too many upvalues (limit=255)" exactly as the original raises at 32, and
+ // The engine's own limit check with the raised ceiling: over it, this raises
+ // "too many upvalues (limit=60)" exactly as the original raises at 32, and
// does not return.
void *ls = *At(fs, Offsets::OFF_LUA_FUNCSTATE_LS);
reinterpret_cast(Offsets::FUN_LUA_PARSER_CHECKLIMIT)(ls, nups + 1, kLimit,