diff --git a/docs/API.md b/docs/API.md
index 54e7283b..42796fc0 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -344,6 +344,7 @@ build instructions.
- [Lua](#lua)
- [Lua 5.1 syntax](#lua-51-syntax)
+ - [String methods (`s:upper()`, `s:format(...)`)](#string-methods-supper-sformat)
- [`getfenv` / `setfenv` environment protection](#getfenv--setfenv-environment-protection)
- [`select(index, ...)`](#selectindex-)
- [`table.wipe(t)`](#tablewipet)
@@ -8571,6 +8572,34 @@ needs that addon's opt-in.
reverts affected chunks to the state that fails to compile, so use it
only to answer "is the rewrite breaking this addon?".
+### String methods (`s:upper()`, `s:format(...)`)
+
+In Lua 5.1, every string value accepts method calls: `s:method(...)`
+resolves through the `string` table. Lua 5.0 has no string methods — on
+stock 1.12, any `s:upper()` fails with `attempt to index a string value`.
+ClassicAPI restores the 5.1 behavior:
+
+```lua
+("asd"):upper() -- "ASD"
+("%d gold"):format(price) -- method call on a literal
+msg:match("^!(%w+)") -- method call on a variable
+link:sub(1, 5)
+```
+
+- Both call forms work and give the same result: `s:upper()` and
+ `string.upper(s)`.
+- Every function in the `string` table is reachable as a method. That
+ includes the ClassicAPI additions ([`match` /
+ `gmatch`](#stringmatch--stringgmatch),
+ [`reverse`](#stringreverses--strrevs)) and any function an addon adds to
+ `string`.
+- Reading an unknown key gives `nil`, the Lua 5.1 result: `("x").nope` is
+ `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.
+- Works everywhere strings do: in the world, on the login screen, and
+ inside coroutines.
+
### `getfenv` / `setfenv` environment protection
A sandbox can protect the environment table it gives to restricted code.
@@ -8715,13 +8744,8 @@ string.match("no digits", "%d+") -- nil
for word in string.gmatch("a,bb,ccc", "[^,]+") do print(word) end -- a / bb / ccc
```
-> **Only the `string.foo(s, ...)` call form works — not the `("x"):foo(...)`
-> method sugar.** WoW's Lua VM strips type-metatables for every value except
-> tables and userdata (both `lua_setmetatable` and the VM's own
-> `luaT_gettmbyobj` hard-return "no metamethod" for strings), so string values
-> have no `__index` and there's no client-side way to add one short of hooking
-> a hot VM-core function. This is the long-standing vanilla 1.12 constraint —
-> always write `string.match(s, p)`, never `s:match(p)`.
+Both call forms work: `string.match(s, p)` and `s:match(p)`. See
+[String methods](#string-methods-supper-sformat).
### `strsplit(sep, str [, pieces])`
diff --git a/src/Offsets.h b/src/Offsets.h
index 263718be..b951eca8 100644
--- a/src/Offsets.h
+++ b/src/Offsets.h
@@ -4820,6 +4820,37 @@ enum Offsets {
// `rawset(nil)` clear leaves it stale and subsequent `table.insert`
// appends past the wiped slots.
LUAL_SETN = 0x6F4EA0,
+ // `luaV_gettable(L, t, key, loop)` — the VM's generic index resolver.
+ // __fastcall(L /*ecx*/, t /*edx*/, key /*stack*/, loop /*stack*/),
+ // RET 8. Returns the result TValue* in eax (Ghidra types it void; the
+ // table-hit path demonstrably reaches the epilogue with eax =
+ // luaH_get's return — `CALL 0x006fa7a0; CMP [EAX],0; JNZ epilogue` at
+ // 0x006F7D1D..25). Table case: luaH_get (0x006FA7A0); nil result →
+ // the metatable continuation FUN_006F7D60, which reads the TABLE'S
+ // OWN metatable (hvalue+0x08, fast-TM flag byte hvalue+0x06 — 5.0
+ // fasttm) and returns &nilobject (0x00811BC0) when there is none
+ // (miss = nil, never an error). Non-table case → the continuation
+ // below, loop+1. Depth-guarded at 100 ("loop in gettable").
+ FUN_LUA_V_GETTABLE = 0x006F7CF0,
+ // The non-table branch of luaV_gettable — stock Lua 5.0's "index a
+ // non-table value" continuation. Same convention/return as
+ // FUN_LUA_V_GETTABLE (result TValue* in eax, RET 8). Body: __index
+ // tag method via luaT_gettmbyobj (0x006F7BD0 — which HARDCODES
+ // &nilobject for anything but table/userdata; stock 5.0, nothing
+ // stripped); nil → luaG_typeerror "attempt to index" (0x006FC620);
+ // function TM → call it; table TM → recurse FUN_LUA_V_GETTABLE with
+ // `loop` passed through UNCHANGED (0x006F7F23). Exactly 3 call
+ // sites: luaV_gettable's else-branch + luaV_execute's OP_GETTABLE /
+ // OP_SELF non-table fallbacks (0x006F8A14 / 0x006F8C17 in
+ // 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.
+ FUN_LUA_INDEX_NONTABLE = 0x006F7EE0,
// `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
new file mode 100644
index 00000000..35c800fb
--- /dev/null
+++ b/src/luasyntax/StringMethods.cpp
@@ -0,0 +1,158 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see .
+
+// Lua 5.1 string methods (`("asd"):upper()`, `s:format(...)`) on the 5.0 VM.
+//
+// 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.
+// 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.
+//
+// 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.
+//
+// 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.
+//
+// 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. Between a state teardown and its re-capture a slot can be
+// stale, but no Lua executes in those windows (engine C init only — and on
+// this 5.0 engine no pre-existing code indexes strings anyway, since doing
+// so always errored).
+
+#include "Game.h"
+#include "Offsets.h"
+
+#include
+
+namespace LuaSyntax::StringMethods {
+
+namespace {
+
+// `global_State *` slot in lua_State — the per-universe object shared by
+// every coroutine thread of a state. Verified: luaT_gettmbyobj reads the
+// tmname array at `*(L+0x10) + 0x80`, lua_setmetatable resolves the
+// REGISTRY pseudo-index via `*(L+0x10) + 0x30`. Single-consumer offset,
+// 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.
+struct TValueMirror {
+ int tt = 0;
+ int pad0 = 0;
+ const void *value = nullptr; // Table* when tt == TYPE_TABLE
+ int pad1 = 0;
+};
+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".
+struct StateSlot {
+ const void *G = nullptr;
+ TValueMirror tv{};
+};
+StateSlot g_gameSlot;
+StateSlot g_glueSlot;
+
+// Registry key anchoring the captured table 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";
+
+// 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 (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);
+}
+
+const Game::HookAutoRegister _hook{Offsets::FUN_LUA_INDEX_NONTABLE,
+ reinterpret_cast(&IndexNonTable_h),
+ reinterpret_cast(&g_indexNonTableOriginal)};
+
+// 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.
+void CaptureFor(StateSlot &slot) {
+ slot.G = nullptr;
+ slot.tv.value = nullptr;
+ void *L = Game::Lua::State();
+ if (L == nullptr)
+ return;
+ Game::Lua::PushString(L, "string");
+ Game::Lua::GetTable(L, Game::Lua::GLOBALS_INDEX); // [stringlib?]
+ 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*)
+ slot.G = Game::Read(L, OFF_L_GLOBALSTATE);
+ }
+ Game::Lua::SetTop(L, -2); // pop
+}
+
+void RegisterLuaFunctions() { CaptureFor(g_gameSlot); }
+void RegisterGlueFunctions() { CaptureFor(g_glueSlot); }
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+const Game::GlueModuleAutoRegister _glueAutoreg{&RegisterGlueFunctions};
+
+} // namespace
+
+} // namespace LuaSyntax::StringMethods