From 1caf9fde18d861718e59413d03ce39e6a5551d0d Mon Sep 17 00:00:00 2001 From: Brues <5278969+brues-code@users.noreply.github.com> Date: Sun, 18 Oct 2026 03:46:26 -0500 Subject: [PATCH] feat(luasyntax): give strings 4.3.4's shared metatable 4.3.4 ships stock Lua 5.1, whose createmetatable gives every string one metatable { __index = string } in G(L)->mt[LUA_TSTRING]. 1.12 differs in one line of each reader: lua_getmetatable returns 0 for a non-table, and luaT_gettmbyobj returns nil. Co-hook both so a string reads a per-state metatable instead, and drop the index-continuation hook that answered with the string table directly. getmetatable("") now returns the metatable, so libraries that extend it (StatLogic: getmetatable("").__index.trim = trim) work, and a replaced or function __index resolves through the engine's own code. A method lookup costs what 4.3.4's does: luaH_getstr for "__index", then the lookup in string. Verified in-game: getmetatable("").__index == string, methods, nil on a missing key, extending __index, a function __index, the write / call / arithmetic errors, tostring, and the kill switch. --- docs/API.md | 14 +- src/Offsets.h | 37 ++++- src/luasyntax/StringMethods.cpp | 249 +++++++++++++++++++------------- 3 files changed, 195 insertions(+), 105 deletions(-) diff --git a/docs/API.md b/docs/API.md index 7bbfedaa..8004815d 100644 --- a/docs/API.md +++ b/docs/API.md @@ -11268,11 +11268,21 @@ link:sub(1, 5) `nil`, and `("x"):nope()` fails with `attempt to call`, not `attempt to index`. - Writing to a string (`("x").y = 1`) still fails, the same as Lua 5.1. +- `getmetatable("")` returns the shared string metatable, the same table + for every string. Its `__index` is the `string` table. You can change the + metatable, but `setmetatable` cannot replace it: + + ```lua + getmetatable("").__index == string -- true + getmetatable("").__index.shout = function(s) return s:upper() .. "!" end + ("hi"):shout() -- "HI!" + ``` + - Works everywhere strings do: in the world, on the login screen, and inside coroutines. - To turn method resolution off for diagnosis, call - `_classicapi_SetStringMethods(false)`. Strings then error on index, the - stock 1.12 behavior. Use it only to answer "is this backport breaking + `_classicapi_SetStringMethods(false)`. Strings then have no metatable + and error on index, the stock 1.12 behavior. Use it only to answer "is this backport breaking this addon?". ### `getfenv` / `setfenv` environment protection diff --git a/src/Offsets.h b/src/Offsets.h index f04e48e3..b5e260eb 100644 --- a/src/Offsets.h +++ b/src/Offsets.h @@ -6283,6 +6283,14 @@ enum Offsets { // objindex and returns 1, or pushes nothing and returns 0 when it has none. // Verified in docs/LuaCAPI.md and by the getfenv/getmetatable base-lib // functions that call it. Used by the `__environment` env-protection hook. + // __fastcall(L, idx) -> int. Body: index2adr; table/userdata → mt at + // `value+0x08`, rejected when it is the default sentinel `*(L+0x10)+ + // 0x48`; pushes `{tt=5, ctx=[VAR_FRAMESCRIPT_EXEC_CONTEXT], mt}` at + // L->top (`L+0x08`) and adds 0x10. Every other type returns 0. Engine + // callers: luaL_checkudata 0x006F4A90, luaL_getmetafield 0x006F4D00 + // (→ luaL_callmeta 0x006F4D60 → `tostring` 0x00702F40 for __tostring), + // luaB_getmetatable 0x007029F0. Co-hooked by LuaSyntax::StringMethods + // to return strings' 5.1 shared metatable. LUA_GET_METATABLE = 0x6F3CF0, // `lua_setmetatable(L, objindex)` — pops the table at the top of the // stack and installs it as the metatable of the value at objindex; @@ -6408,12 +6416,31 @@ enum Offsets { // FUN_006F8720) — so it fires ONLY when code indexes a non-table, // which in stock 5.0 is always about to raise "attempt to index" // (table `__index` dispatch goes through FUN_006F7D60's fasttm and - // never lands here). A cold, uncontested hook site. Prologue is - // plain PUSH/MOV — MinHook-relocatable. Co-hooked by - // LuaSyntax::StringMethods to backport Lua 5.1 string methods - // (`("x"):upper()`): strings get the `string` library table as their - // __index, exactly 5.1's shared-string-metatable mechanism. + // never lands here). Not hooked: string methods ride + // FUN_LUAT_GETTMBYOBJ below, which this continuation calls. FUN_LUA_INDEX_NONTABLE = 0x006F7EE0, + // `luaT_gettmbyobj(L, o, event)` — the tag-method lookup for a value + // that has no fasttm path. __fastcall(L /*ecx*/, const TValue *o + // /*edx*/, int event /*stack*/), RET 4, returns const TValue* (eax; + // &nilobject 0x00811BC0 on a miss). Reads the event name from + // `G(L)->tmname` at `*(L+0x10) + 0x80 + event*4`, then for a table or + // userdata calls FUN_LUAH_GETSTR on its metatable (`hvalue+0x08`, no + // null check — 5.0's default-metatable sentinel is never NULL). Every + // other type hardcodes &nilobject: this is the ONE line where 5.1 + // reads the per-type slot `G(L)->mt[ttype(o)]` instead. Callers (7): + // luaD_tryfuncTM 0x006F6370, index/newindex non-table continuations + // 0x006F7EE0 / 0x006F7F40, call_binTM 0x006F8670 (x2), call_orderTM + // 0x006F8210 (x2) — all fallbacks for values with no native + // operation, so cold. Prologue PUSH EBP / MOV EBP,ESP / MOV ECX,[ECX+ + // 0x10] — MinHook-relocatable. Co-hooked by LuaSyntax::StringMethods + // to give strings 5.1's shared metatable. + FUN_LUAT_GETTMBYOBJ = 0x006F7BD0, + // `luaH_getstr(Table *t, TString *key)` — raw hash lookup of an + // interned string key. __fastcall(t /*ecx*/, key /*edx*/), returns + // const TValue* (eax; &nilobject on a miss). Node stride 0x28, key tt + // at +0, key ptr at +8, value at +0x10, next at +0x20. Called by + // FUN_LUAT_GETTMBYOBJ. + FUN_LUAH_GETSTR = 0x006FA760, // `luaL_loadbuffer(L, buff, size, chunkname)` — compiles a source // buffer into a Lua function on the stack (does NOT run it). Returns // an int status (0 = ok) in eax; Ghidra types it void because the diff --git a/src/luasyntax/StringMethods.cpp b/src/luasyntax/StringMethods.cpp index 626e6594..ccb2d2fb 100644 --- a/src/luasyntax/StringMethods.cpp +++ b/src/luasyntax/StringMethods.cpp @@ -15,56 +15,64 @@ // // Lua 5.0 has no string methods AT ALL — the shared string metatable with // `__index = string` is a 5.1 addition (`createmetatable` in 5.1's -// lstrlib.c). Nothing was stripped from this build: both halves of the -// would-be mechanism match stock 5.0 source exactly — -// * `lua_setmetatable` (0x006F4020) accepts only tables/userdata, so no -// API call can attach a metatable to the string TYPE; and -// * `luaT_gettmbyobj` (0x006F7BD0) hardcodes `&nilobject` for anything -// that isn't a table or userdata, so the VM would never read one. +// lstrlib.c, which 4.3.4 ships unmodified). Nothing was stripped from this +// build: both places 5.1 changed match stock 5.0 source exactly — +// * `lua_getmetatable` (0x006F3CF0) returns 0 for anything but a table or +// userdata, where 5.1 reads the per-type slot `G(L)->mt[ttype(o)]`; and +// * `luaT_gettmbyobj` (0x006F7BD0) hardcodes `&nilobject` for those same +// types, where 5.1 does `luaH_getstr(G(L)->mt[ttype(o)], tmname[event])`. // So this is the runtime half of the 5.1 backport (the syntax half is -// Transpile.cpp): we transplant 5.1's mechanism at the read side. +// Transpile.cpp): one metatable `{ __index = string }` per Lua state, and a +// co-hook on each of those two functions that answers for strings exactly as +// 5.1's line does. Everything downstream is the engine's own unmodified code: +// the index continuation (0x006F7EE0) gets `__index` back from gettmbyobj +// and resolves it (table -> luaV_gettable, function -> callTM), so +// `("x").nonexistent` is nil, `("x").k = v` still errors (no __newindex), +// and a script that edits the metatable — `getmetatable("").__index.trim = +// f` (StatLogic) or a replacement `__index` — behaves as on 4.3.4. // -// Mechanism: co-hook FUN_LUA_INDEX_NONTABLE (0x006F7EE0) — luaV_gettable's -// non-table continuation, the ONE choke every string index reaches (3 call -// sites: luaV_gettable's else-branch + luaV_execute's OP_GETTABLE/OP_SELF -// fallbacks; see Offsets.h). When the indexed object is a string, answer -// with `luaV_gettable(L, , key, loop)` — byte-for-byte -// what the original's own TM-table branch would do had gettmbyobj returned -// that table (it passes `loop` through unchanged too, 0x006F7F23). The -// engine's unmodified lookup then does everything, including exact 5.1 miss -// semantics: `("x").nonexistent` → plain table miss → nil, not an error -// (verified: FUN_006F7D60 returns &nilobject when the table has no -// metatable). Non-strings fall through to the original — userdata __index, -// and the stock "attempt to index" error for everything else. `settable` -// on a string is a different continuation (FUN_006F7F40), untouched: still -// an error, which is also 5.1's behavior. +// Cost per string method lookup is 4.3.4's: one luaH_getstr for "__index" +// in the metatable, then the lookup in the table it names. The only other +// work 5.1 also does is `tostring(s)` probing the metatable for `__tostring` +// (luaL_callmeta). // -// Hotness: cold. Table `__index` dispatch (all frame/OO method traffic) -// reads the table's OWN metatable via FUN_006F7D60/fasttm and never lands -// here; today's only callers are about-to-error non-table indexes. No other -// Octo DLL hooks the Lua VM internals. +// Hotness: cold. gettmbyobj is reached only from fallbacks for values with +// no native operation (index/newindex/call on non-tables, arithmetic/order +// on non-numbers); table `__index` dispatch reads the table's OWN metatable +// via FUN_006F7D60's fasttm and never lands there. lua_getmetatable's +// callers are getmetatable, luaL_getmetafield (tostring) and +// luaL_checkudata. Both hooks hand every non-string to the original, so +// tables and userdata get the engine's exact result. No other Octo DLL +// hooks the Lua VM internals. +// +// What stays 5.0: only `__index` matters. A pair of strings has native +// concat, compare and coercing arithmetic, so the VM never asks for +// `__concat`/`__lt`/etc.; a mixed operand that does reach call_binTM now +// finds the metatable, which has no such field, and errors as before. +// `setmetatable` still rejects a string (it requires a table in 5.1 too), so +// the metatable can be edited but not replaced. // // State/GC lifecycle: one slot per Lua state (in-game + glue), keyed by the // state's global_State (`*(L+0x10)`) so coroutine threads — which share G -// with their parent — resolve too. Each capture anchors the string table in -// that state's registry, so the hook can never serve a GC-collected table: -// even if an addon nils/replaces `_G.string`, resolution keeps the snapshot -// (5.1 parity — its metatable pins the open-time table the same way). -// Captures re-run per /reload (ModuleAutoRegister) and per glue boot -// (GlueModuleAutoRegister), overwriting the anchor so the previous table is -// released. Slots are cleared BEFORE their state can die, so a capture can -// never outlive the table it points at: PrepareForReload (called from -// FrameScript_Initialize_h, which fires on /reload AND /logout before the -// world Lua state is reset) clears the game slot, and the in-game -// registration clears the glue slot (once world scripts are loading, the -// glue state is gone; the next glue boot re-captures before any glue Lua -// runs). A cleared slot fails closed — strings error on index exactly as -// stock 1.12 until the re-capture. +// with their parent — resolve too. Each capture builds a fresh metatable and +// anchors it in that state's registry, so the hooks can never serve a +// GC-collected table; the metatable holds the `string` table, so even if an +// addon nils/replaces `_G.string`, methods keep the open-time table (5.1 +// parity). Captures re-run per /reload (ModuleAutoRegister) and per glue +// boot (GlueModuleAutoRegister), overwriting the anchor so the previous +// metatable is released. Slots are cleared BEFORE their state can die, so a +// capture can never outlive the table it points at: PrepareForReload +// (called from FrameScript_Initialize_h, which fires on /reload AND /logout +// before the world Lua state is reset) clears the game slot, and the +// in-game registration clears the glue slot (once world scripts are +// loading, the glue state is gone; the next glue boot re-captures before +// any glue Lua runs). A cleared slot fails closed — strings have no +// metatable, exactly as stock 1.12, until the re-capture. // // Kill switch: `_classicapi_SetStringMethods(false)` (registered on both -// states) makes the hook forward everything to the original resolver — -// exact stock behavior — for "is this backport breaking this addon?" -// diagnosis, mirroring `_classicapi_SetTranspileOption`. +// states) makes both hooks forward everything to the originals — exact +// stock behavior — for "is this backport breaking this addon?" diagnosis, +// mirroring `_classicapi_SetTranspileOption`. #include "StringMethods.h" @@ -84,89 +92,134 @@ namespace { // local per the Offsets.h rule. constexpr uintptr_t OFF_L_GLOBALSTATE = 0x10; -// This build's TValue is 16 bytes with `tt` FIRST: {tt @ +0, value @ +8} — -// NOT stock 5.0's {value, tt} order. Verified from lua_setmetatable -// (tag = `*tv`, GC pointer = `tv[2]`, Table->metatable at hvalue+0x08 / -// fast-TM flags byte at hvalue+0x06) and the push helpers' 0x10 stride. +// `L->top` slot in lua_State — lua_getmetatable writes the pushed TValue +// there and adds 0x10 (0x006F3CF0). Single-consumer, local. +constexpr uintptr_t OFF_L_TOP = 0x08; +// `G(L)->tmname[]` — the interned event-name strings luaT_gettmbyobj indexes +// by event (0x006F7BDB). Single-consumer, local. +constexpr uintptr_t OFF_G_TMNAME = 0x80; + +// This build's TValue is 16 bytes with `tt` FIRST: {tt @ +0, ctx @ +4, +// value @ +8} — NOT stock 5.0's {value, tt} order. Verified from +// lua_getmetatable's push (tt=5, ctx=[VAR_FRAMESCRIPT_EXEC_CONTEXT], +// value=Table*) and the push helpers' 0x10 stride. struct TValueMirror { - int tt = 0; - int pad0 = 0; - const void *value = nullptr; // Table* when tt == TYPE_TABLE - int pad1 = 0; + int tt; + int ctx; + const void *value; + int pad; }; static_assert(sizeof(TValueMirror) == 16, "TValue is 16 bytes in this build"); -// Captured `string` library table for one Lua state. `G` doubles as the -// valid flag — nullptr means "no capture, pass everything through". +// The string metatable for one Lua state — 5.1's `G(L)->mt[LUA_TSTRING]`. +// `G` doubles as the valid flag — nullptr means "no capture, pass +// everything through". struct StateSlot { const void *G = nullptr; - TValueMirror tv{}; + const void *mt = nullptr; // Table* }; StateSlot g_gameSlot; StateSlot g_glueSlot; // Runtime kill switch — `_classicapi_SetStringMethods(false)` reverts to -// exact stock behavior (the hook forwards everything). Process-wide; both +// exact stock behavior (both hooks forward everything). Process-wide; both // states share it. bool g_enabled = true; -// Registry key anchoring the captured table against GC (rawset — the +// Registry key anchoring the captured metatable against GC (rawset — the // registry has no metatable). One key per state's registry; re-capture -// overwrites it, releasing the previously anchored table. -constexpr const char *kAnchorKey = "__classicapi_string_lib"; +// overwrites it, releasing the previous metatable. +constexpr const char *kAnchorKey = "__classicapi_string_mt"; -// FUN_LUA_INDEX_NONTABLE / FUN_LUA_V_GETTABLE shared convention: -// __fastcall(L /*ecx*/, tv /*edx*/, key /*stack*/, loop /*stack*/), RET 8, -// result TValue* in eax (see Offsets.h for the disassembly evidence). -using IndexResolve_t = void *(__fastcall *)(void *L, const void *tv, void *key, int loop); -IndexResolve_t g_indexNonTableOriginal = nullptr; - -void *__fastcall IndexNonTable_h(void *L, const void *obj, void *key, int loop) { - // 5.1 backport: a string's `__index` is the `string` library table. - if (g_enabled && obj != nullptr && - *static_cast(obj) == Game::Lua::TYPE_STRING) { - const void *G = Game::Read(L, OFF_L_GLOBALSTATE); - const StateSlot *slot = nullptr; - if (g_gameSlot.G == G) - slot = &g_gameSlot; - else if (g_glueSlot.G == G) - slot = &g_glueSlot; - if (slot != nullptr && slot->tv.value != nullptr) - return reinterpret_cast(Offsets::FUN_LUA_V_GETTABLE)( - L, &slot->tv, key, loop); - } - return g_indexNonTableOriginal(L, obj, key, loop); +// The string metatable for L's state, or nullptr when there is none. +const void *StringMetatable(void *L) { + if (!g_enabled) + return nullptr; + const void *G = Game::Read(L, OFF_L_GLOBALSTATE); + if (g_gameSlot.G == G) + return g_gameSlot.mt; + if (g_glueSlot.G == G) + return g_glueSlot.mt; + return nullptr; } -const Game::HookAutoRegister _hook{Offsets::FUN_LUA_INDEX_NONTABLE, - reinterpret_cast(&IndexNonTable_h), - reinterpret_cast(&g_indexNonTableOriginal)}; +using GetTMByObj_t = const void *(__fastcall *)(void *L, const void *o, int event); +using LuaHGetStr_t = const void *(__fastcall *)(const void *t, const void *key); +GetTMByObj_t g_getTMByObjOriginal = nullptr; -// Captures `_G.string` for the CURRENT state (whatever VAR_LUA_STATE points -// at — the registration callbacks below run inside the right window for -// each) into `slot`, anchoring it in that state's registry. +// 5.1's `default: mt = G(L)->mt[ttype(o)]` for strings, then the same +// luaH_getstr(mt, tmname[event]) the original does for tables. +const void *__fastcall GetTMByObj_h(void *L, const void *o, int event) { + if (*static_cast(o) == Game::Lua::TYPE_STRING) { + if (const void *mt = StringMetatable(L)) { + const void *G = Game::Read(L, OFF_L_GLOBALSTATE); + const void *name = Game::Read(G, OFF_G_TMNAME + event * 4); + return reinterpret_cast(Offsets::FUN_LUAH_GETSTR)(mt, name); + } + } + return g_getTMByObjOriginal(L, o, event); +} + +const Game::HookAutoRegister _tmHook{Offsets::FUN_LUAT_GETTMBYOBJ, + reinterpret_cast(&GetTMByObj_h), + reinterpret_cast(&g_getTMByObjOriginal)}; + +using GetMetatable_t = int(__fastcall *)(void *L, int idx); +GetMetatable_t g_getMetatableOriginal = nullptr; + +// 5.1's lua_getmetatable for strings: push the per-type metatable with the +// same TValue write the original uses for a table's (`sethvalue` + +// incr_top), so the caller's stack contract is unchanged. +int __fastcall GetMetatable_h(void *L, int idx) { + if (g_getMetatableOriginal(L, idx)) + return 1; + if (Game::Lua::Type(L, idx) != Game::Lua::TYPE_STRING) + return 0; + const void *mt = StringMetatable(L); + if (mt == nullptr) + return 0; + auto &top = Game::Ref(L, OFF_L_TOP); + top->tt = Game::Lua::TYPE_TABLE; + top->ctx = Game::Read(Offsets::VAR_FRAMESCRIPT_EXEC_CONTEXT); + top->value = mt; + ++top; + return 1; +} + +const Game::HookAutoRegister _mtHook{Offsets::LUA_GET_METATABLE, + reinterpret_cast(&GetMetatable_h), + reinterpret_cast(&g_getMetatableOriginal)}; + +// Builds `{ __index = _G.string }` for the CURRENT state (whatever +// VAR_LUA_STATE points at — the registration callbacks below run inside the +// right window for each) into `slot`, anchoring it in that state's registry. +// 5.1's createmetatable, run at the same point relative to scripts (before +// any addon or FrameXML Lua). void CaptureFor(StateSlot &slot) { slot.G = nullptr; - slot.tv.value = nullptr; + slot.mt = nullptr; void *L = Game::Lua::State(); if (L == nullptr) return; + const int top = Game::Lua::GetTop(L); Game::Lua::PushString(L, "string"); - Game::Lua::GetTable(L, Game::Lua::GLOBALS_INDEX); // [stringlib?] + Game::Lua::GetTable(L, Game::Lua::GLOBALS_INDEX); // [lib?] if (Game::Lua::Type(L, -1) == Game::Lua::TYPE_TABLE) { - Game::Lua::PushString(L, kAnchorKey); // [tbl, key] - Game::Lua::PushValue(L, -2); // [tbl, key, tbl] - Game::Lua::RawSet(L, Game::Lua::REGISTRY_INDEX); // registry[key]=tbl. [tbl] - slot.tv.tt = Game::Lua::TYPE_TABLE; - slot.tv.value = Game::Lua::ToPointer(L, -1); // hvalue (Table*) + Game::Lua::NewTable(L); // [lib, mt] + Game::Lua::PushString(L, "__index"); + Game::Lua::PushValue(L, -3); + Game::Lua::RawSet(L, -3); // mt.__index = lib + Game::Lua::PushString(L, kAnchorKey); // [lib, mt, key] + Game::Lua::PushValue(L, -2); // [lib, mt, key, mt] + Game::Lua::RawSet(L, Game::Lua::REGISTRY_INDEX); // registry[key] = mt + slot.mt = Game::Lua::ToPointer(L, -1); // hvalue (Table*) slot.G = Game::Read(L, OFF_L_GLOBALSTATE); } - Game::Lua::SetTop(L, -2); // pop + Game::Lua::SetTop(L, top); } // `_classicapi_SetStringMethods(enabled)` — diagnostic kill switch. While -// false, string index falls through to the original resolver and errors as -// stock 1.12. Use only to answer "is this backport breaking this addon?". +// false, strings have no metatable and index errors as stock 1.12. Use only to answer "is this backport breaking this addon?". int __fastcall Script_SetStringMethods(void *L) { g_enabled = Game::Lua::ToBoolean(L, 1) != 0; return 0; @@ -177,7 +230,7 @@ void RegisterLuaFunctions() { // glue→world handoff). Clear its slot so a future glue global_State // that lands at the same address can never match this stale capture. g_glueSlot.G = nullptr; - g_glueSlot.tv.value = nullptr; + g_glueSlot.mt = nullptr; CaptureFor(g_gameSlot); Game::Lua::RegisterGlobalFunction("_classicapi_SetStringMethods", &Script_SetStringMethods); @@ -195,11 +248,11 @@ const Game::GlueModuleAutoRegister _glueAutoreg{&RegisterGlueFunctions}; void PrepareForReload() { // The world Lua state is about to be reset (/reload) or destroyed - // (/logout); its string table may not survive. Fail closed until the + // (/logout); its string metatable may not survive. Fail closed until the // next LoadScriptFunctions re-capture — a cleared slot means strings - // error on index exactly as stock, and nothing can read a freed table. + // have no metatable exactly as stock, and nothing can read a freed table. g_gameSlot.G = nullptr; - g_gameSlot.tv.value = nullptr; + g_gameSlot.mt = nullptr; } static const Game::ReloadAutoRegister _reloadReg{&PrepareForReload};