From 12a81f7f89fcec90ea405d0d1c305d792b5d4085 Mon Sep 17 00:00:00 2001
From: Brues <5278969+brues-code@users.noreply.github.com>
Date: Tue, 3 Nov 2026 15:33:30 -0600
Subject: [PATCH] feat(baselib): debugstack takes a coroutine
debugstack([thread,] [start [, count1 [, count2]]]) returns the stack
of a coroutine when one is passed first, with start defaulting to 0
(the coroutine's innermost level), as 4.3.4's Script_debugstack does.
1.12.1's debugstack (0x703760) has no thread argument. A thread fails
its lua_isnumber and lua_isstring checks, so it returns the thread
itself, and msg .. debugstack(co) raises "attempt to concatenate a
thread value" in the coroutine error paths of WeakAuras, Questie's
ThreadLib, MRT and Zygor.
The engine function still builds the text, so its line format and its
12/10-level head and tail windows are unchanged, which keeps addons
that parse debugstack() for their folder working. It reads levels
through six calls on the state it runs on: lua_getstack (0x6FBAA0) at
0x70383F, 0x70386E, 0x703896, 0x7038AD and 0x703998, and
lua_getinfo (0x6FBC70) at 0x7038CD. Those calls are redirected to
read from the state the new global names for the call: the thread, or
the calling state. The engine function has no callers of its own, so
the global is its only way in and sets that state for every call; an
error part way cannot leave a thread behind for the next call.
The global removes the thread argument, inserts 0 as start when none
is given, and calls the engine function directly in its own frame, so
levels without a thread count exactly as before.
---
docs/API.md | 13 +++++
src/Offsets.h | 12 +++++
src/baselib/DebugStack.cpp | 102 +++++++++++++++++++++++++++++++++++++
3 files changed, 127 insertions(+)
create mode 100644 src/baselib/DebugStack.cpp
diff --git a/docs/API.md b/docs/API.md
index b703d204..425d0c61 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -678,6 +678,7 @@ build instructions.
- [`difftime(time2 [, time1])`](#difftimetime2--time1)
- [`xpcall(f, msgh [, arg1, ...])`](#xpcallf-msgh--arg1-)
- [`GetCallstackHeight()` / `GetErrorCallstackHeight()` / `SetErrorCallstackHeight([height])`](#getcallstackheight--geterrorcallstackheight--seterrorcallstackheightheight)
+ - [`debugstack(thread [, start [, count1 [, count2]]])`](#debugstackthread--start--count1--count2)
- [`debuglocals([level [, skipFunctionsAndUserdata]])`](#debuglocalslevel--skipfunctionsanduserdata)
- [`collectgarbage(opt [, arg])`](#collectgarbageopt--arg)
- [`table.wipe(t)` / `wipe(t)`](#tablewipet--wipet)
@@ -16137,6 +16138,18 @@ end
Works in the world and on the login screen.
+### `debugstack(thread [, start [, count1 [, count2]]])`
+
+With a coroutine as the first argument, `debugstack` returns the call stack
+of that coroutine. `start` is 0 by default, which is the innermost level of
+the coroutine. Without a coroutine, `debugstack` works as before.
+
+```lua
+local co = coroutine.create(function() coroutine.yield() end)
+coroutine.resume(co)
+print(debugstack(co))
+```
+
### `debuglocals([level [, skipFunctionsAndUserdata]])`
Returns the local variables and the upvalues of a call level as one string.
diff --git a/src/Offsets.h b/src/Offsets.h
index 706e39f1..18215ee7 100644
--- a/src/Offsets.h
+++ b/src/Offsets.h
@@ -8809,6 +8809,18 @@ enum Offsets {
// name ("" for a C closure), or null for no such upvalue or a value that
// is not a function. (0x006F45B0 is lua_pushupvalues.)
LUA_GET_UPVALUE = 0x006F4660,
+ // `debugstack([start [, count1 [, count2]]])` — the engine's C function
+ // (base-function table 0x811E28); no engine callers. It reads the stack
+ // of the state it is called on through five lua_getstack calls and one
+ // lua_getinfo("Snl"), and pushes its text onto that same state.
+ // BaseLib::DebugStack points those six calls at a thread's state.
+ FUN_SCRIPT_DEBUGSTACK = 0x00703760,
+ CALL_DEBUGSTACK_GETSTACK_FIRST = 0x0070383F,
+ CALL_DEBUGSTACK_GETSTACK_TAIL_PROBE = 0x0070386E,
+ CALL_DEBUGSTACK_GETSTACK_TAIL_START = 0x00703896,
+ CALL_DEBUGSTACK_GETSTACK_TAIL_SKIP = 0x007038AD,
+ CALL_DEBUGSTACK_GETSTACK_NEXT = 0x00703998,
+ CALL_DEBUGSTACK_GETINFO = 0x007038CD,
// `luaO_chunkid(out, source, bufflen)` — `void __fastcall(char *out /*ecx*/,
// const char *source /*edx*/, int bufflen /*stack*/)`, RET 4: the name a
// chunk has in error messages. `=name` is copied as is, `@file` is the
diff --git a/src/baselib/DebugStack.cpp b/src/baselib/DebugStack.cpp
new file mode 100644
index 00000000..06db84e9
--- /dev/null
+++ b/src/baselib/DebugStack.cpp
@@ -0,0 +1,102 @@
+// 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 .
+
+// `debugstack([thread,] [start [, count1 [, count2]]])` — the stack of a
+// coroutine, as 4.3.4's Script_debugstack takes it: with a thread first,
+// the levels are that thread's and `start` defaults to 0 (the thread's
+// innermost level) instead of 1.
+//
+// 1.12's debugstack (FUN_SCRIPT_DEBUGSTACK) has no thread argument, and a
+// thread falls through its argument checks so that it returns the thread
+// itself: `msg .. debugstack(co)` raises "attempt to concatenate a thread
+// value" in the coroutine error paths of WeakAuras, Questie's ThreadLib,
+// MRT and Zygor.
+//
+// The engine's function still does the work, so its text and its head and
+// tail windows stay exactly as they are. It reads levels through six calls
+// (five lua_getstack, one lua_getinfo), and those calls are redirected to
+// read from the state Script_debugstack names for the call: the thread, or
+// the calling state when there is none. Script_debugstack replaces the
+// global and is the engine function's only way in, so the state is set for
+// every call; an error part way cannot leave a thread behind for the next.
+//
+// Registered on both Lua states, like the base-library helpers.
+
+#include "Common.h"
+#include "Game.h"
+#include "Offsets.h"
+
+#include
+#include
+
+namespace BaseLib::DebugStack {
+
+namespace {
+
+namespace Lua = Game::Lua;
+
+// The state whose levels the engine's debugstack reads, or null for its own.
+void *g_levelsOf = nullptr;
+
+int __fastcall GetStack(void *L, int level, void *ar) {
+ return Lua::GetStack(g_levelsOf ? g_levelsOf : L, level, ar);
+}
+
+int __fastcall GetInfo(void *L, const char *what, void *ar) {
+ return Lua::GetInfo(g_levelsOf ? g_levelsOf : L, what, ar);
+}
+
+int __fastcall Script_debugstack(void *L) {
+ const auto engineDebugStack =
+ reinterpret_cast(Offsets::FUN_SCRIPT_DEBUGSTACK);
+ g_levelsOf = nullptr;
+ if (Lua::Type(L, 1) == Lua::TYPE_THREAD) {
+ g_levelsOf = Lua::ToThread(L, 1);
+ Lua::Remove(L, 1);
+ if (!Lua::IsNumber(L, 1)) { // start defaults to 0 for a thread
+ Lua::PushNumber(L, 0);
+ Lua::Insert(L, 1);
+ }
+ }
+ const int results = engineDebugStack(L);
+ g_levelsOf = nullptr;
+ return results;
+}
+
+void Apply() {
+ const auto getStack = reinterpret_cast(&GetStack);
+ for (const uintptr_t site :
+ {Offsets::CALL_DEBUGSTACK_GETSTACK_FIRST, Offsets::CALL_DEBUGSTACK_GETSTACK_TAIL_PROBE,
+ Offsets::CALL_DEBUGSTACK_GETSTACK_TAIL_START, Offsets::CALL_DEBUGSTACK_GETSTACK_TAIL_SKIP,
+ Offsets::CALL_DEBUGSTACK_GETSTACK_NEXT})
+ Common::RedirectCall(site, Offsets::LUA_GET_STACK, getStack);
+ Common::RedirectCall(Offsets::CALL_DEBUGSTACK_GETINFO, Offsets::LUA_GET_INFO,
+ reinterpret_cast(&GetInfo));
+}
+
+void RegisterInGame() {
+ Apply();
+ Lua::RegisterGlobalFunction("debugstack", &Script_debugstack);
+}
+
+void RegisterGlue() {
+ Apply();
+ Lua::RegisterGlueFunction("debugstack", &Script_debugstack);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterInGame};
+const Game::GlueModuleAutoRegister _autoregGlue{&RegisterGlue};
+
+} // namespace
+
+} // namespace BaseLib::DebugStack