mirror of
https://github.com/brues-code/ClassicAPI.git
synced 2026-11-16 08:00:42 +00:00
Adds the three call stack heights an error handler uses to start its
stack at the code that failed:
debugstack(GetCallstackHeight() - (GetErrorCallstackHeight() - 1))
A height counts levels as lua_getstack (0x006FBAA0) does, and so as
debugstack does: C functions and lost tail calls count, and level 1 is
the caller.
1.12.1 records no error height, but every error report runs one C
function, FrameScriptCallErrorHandler (0x00703B40, __fastcall(L)). It
pushes the seterrorhandler function (registry ref 0x008722CC), moves it
under the message and lua_calls it. Nothing calls it directly: state
open pushes it as a C closure and refs it (0x008722C8). Every script
pcall passes that closure as the errfunc, so Lua calls it at the point
of the error before the stack unwinds; a chunk that fails to compile is
reported by a pcall of it (0x00704AE0). ClassicAPI's securecall,
hooksecurefunc and script runners pass the same ref.
So while any handler runs, that closure's level sits directly above the
code that failed. GetErrorCallstackHeight walks the levels with
lua_getstack and lua_getinfo "f", finds the innermost one whose function
is 0x00703B40 (lua_tocfunction, 0x006F3720) and answers the height below
it, or nil when no error is being reported. There is no hook, and
nothing is recorded, so a handler that fails part way leaves nothing
behind.
SetErrorCallstackHeight sets the height for a handler called with no
error raised. It applies only while no 0x00703B40 level is on the stack,
so a value left set by a failed handler cannot move a later error's
stack. A new Lua state starts with no value set.
Users:
- The Lua error window takes its stack this way, so it starts at the
failing code even when another addon wraps the handler.
- CallErrorHandler and assertsafe set the height around their direct
handler call, so they report from their caller.
- Game::Lua gains GetStack, GetInfo and ToCFunction; SourceLocation uses
them in place of its own copies.
Docs: the xpcall and coroutine notes said error() returns without
raising. Stock error (0x00702970) ends in lua_error (0x006F4440) and
raises. pfUI replaces the global error with one that prints and
returns, which is what those notes described.
Tested in game: with seterrorhandler wrapping the old handler, a nil
index in a local function f showed a stack that starts at f.
781 lines
38 KiB
C++
781 lines
38 KiB
C++
// 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 <https://www.gnu.org/licenses/>.
|
|
|
|
#pragma once
|
|
|
|
#include <cstddef>
|
|
#include <cstdint>
|
|
|
|
namespace Game {
|
|
|
|
// --- Typed engine-memory access ---------------------------------------------
|
|
//
|
|
// The canonical way to read/write an engine object field or a fixed-VA global,
|
|
// replacing the `*reinterpret_cast<const T *>(base + Offsets::OFF_X)` idiom
|
|
// (and its double-cast variant when `base` isn't a byte pointer). Offsets stay
|
|
// in Offsets.h per the single-source-of-truth rule — these only centralize the
|
|
// cast noise, they add no checking.
|
|
//
|
|
// Game::Read<int>(obj, Offsets::OFF_FIELD) field read
|
|
// Game::Ref<uint32_t>(obj, Offsets::OFF_FIELD) writable field lvalue
|
|
// Game::Ptr<float>(obj, Offsets::OFF_FIELD) pointer TO a field (arrays,
|
|
// out-params for engine calls)
|
|
// Game::Read<float>(Offsets::VAR_GLOBAL) fixed-VA global read
|
|
// Game::Ref<int>(Offsets::VAR_GLOBAL) fixed-VA global lvalue
|
|
|
|
template <typename T>
|
|
inline const T *Ptr(const void *base, uintptr_t offset) {
|
|
return reinterpret_cast<const T *>(reinterpret_cast<const uint8_t *>(base) + offset);
|
|
}
|
|
template <typename T>
|
|
inline T *Ptr(void *base, uintptr_t offset) {
|
|
return reinterpret_cast<T *>(reinterpret_cast<uint8_t *>(base) + offset);
|
|
}
|
|
template <typename T>
|
|
inline T Read(const void *base, uintptr_t offset) {
|
|
return *Ptr<T>(base, offset);
|
|
}
|
|
template <typename T>
|
|
inline T &Ref(void *base, uintptr_t offset) {
|
|
return *Ptr<T>(base, offset);
|
|
}
|
|
template <typename T>
|
|
inline T Read(uintptr_t address) {
|
|
return *reinterpret_cast<const T *>(address);
|
|
}
|
|
template <typename T>
|
|
inline T &Ref(uintptr_t address) {
|
|
return *reinterpret_cast<T *>(address);
|
|
}
|
|
|
|
// Calls `fn(object)` for each object of one of a frame's intrusive lists,
|
|
// OFF_FRAME_REGION_LIST or OFF_FRAME_CHILD_LIST: node+4 next, node+8 object,
|
|
// a NULL or low-bit-1 link ends it - the walk the engine's own frame code
|
|
// does (the alpha setter, the bounds walk 0x00786F80).
|
|
template <typename Fn>
|
|
void ForEachFrameListObject(void *frame, uintptr_t listOffset, Fn fn) {
|
|
uintptr_t link = Read<uintptr_t>(frame, listOffset);
|
|
while (link != 0 && (link & 1) == 0) {
|
|
void *obj = *reinterpret_cast<void *const *>(link + 8);
|
|
const uintptr_t next = *reinterpret_cast<const uintptr_t *>(link + 4);
|
|
if (obj != nullptr)
|
|
fn(obj);
|
|
link = next;
|
|
}
|
|
}
|
|
|
|
// --- Engine primitives ------------------------------------------------------
|
|
|
|
// Resolve a unit token (`"player"`, `"target"`, `"party3"`, `"nameplate1"`,
|
|
// …) to its live `CGUnit_C *`, through the engine's own resolver
|
|
// (`FUN_RESOLVE_UNIT_TOKEN`). Returns null for a valid token that currently
|
|
// has no unit (e.g. `"target"` with nothing targeted). NOTE: the engine
|
|
// RAISES a Lua error for a string that isn't a valid token form (an arbitrary
|
|
// name like `"Bob"`), so only pass real unit tokens — the same contract every
|
|
// stock `Unit*` global carries. Centralizes the
|
|
// `reinterpret_cast<…>(FUN_RESOLVE_UNIT_TOKEN)` idiom that was copy-pasted
|
|
// across a dozen modules.
|
|
void *ResolveUnitToken(const char *token);
|
|
|
|
// UI pixels <-> internal layout (anchor) units. Script_SetPoint converts its
|
|
// pixel offsets with `px * [VAR_COORD_DDC_WIDTH_SCALE] / ([VAR_COORD_ASPECT_COMPENSATION]
|
|
// * UI_COORD_SCALE_UNIT)`; Script_GetLeft and Script_GetStringWidth push the
|
|
// inverse. A region's LOCAL pixels must be multiplied by its effective scale
|
|
// (OFF_REGION_EFFECTIVE_SCALE) first. Both return 0 while the scale globals
|
|
// are unset, so an early caller gets a zero offset rather than a wild one.
|
|
float PixelToInternal(float px);
|
|
double InternalToPixel(float internal);
|
|
|
|
using FrameScript_Initialize_t = bool(__fastcall *)();
|
|
using LoadScriptFunctions_t = void(__fastcall *)();
|
|
|
|
// Master glue Lua-state init function. `__stdcall` (no args, no return).
|
|
// Hooked to inject our own glue-side globals after the engine finishes
|
|
// registering its 109 glue functions. See FUN_LOAD_GLUE_SCRIPT_FUNCTIONS.
|
|
using LoadGlueScriptFunctions_t = void(__stdcall *)();
|
|
|
|
// The engine's text-to-flag reader (FUN_XML_ATTR_TO_BOOL, 4.3.4's
|
|
// `StringToBOOL(const char *)`), which XML boolean attributes go through:
|
|
// true for text starting 1-9/T/Y/t/y or equal to "on"/"enabled" (any case),
|
|
// false for anything else, including null.
|
|
bool StringToFlag(const char *text);
|
|
|
|
// Storm's case-insensitive compare, SStrCmpI (FUN_SSTR_CMP_I) — the one the
|
|
// engine uses for names, tokens and tags: at most `n` characters, ASCII case
|
|
// folded, <0 / 0 / >0 like strcmp. The default `n` is Storm's "whole string".
|
|
// Always call it through here: the engine function is `__stdcall` (RET 0xC),
|
|
// and a `__cdecl` declaration drifts ESP by 12 per call.
|
|
int StrCmpI(const char *a, const char *b, int n = 0x7FFFFFFF);
|
|
|
|
// --- API documentation descriptors -----------------------------------------
|
|
//
|
|
// Every Lua registration (see the `Register*` functions in `Game::Lua`) can
|
|
// carry a descriptor: the signature the function presents to Lua — typed
|
|
// arguments and returns, nilability, defaults — plus a one-sentence summary.
|
|
// The descriptors are the single source of truth for the API's SHAPE.
|
|
// `src/api/Documentation.cpp` records each registration on the first pass of
|
|
// each Lua state and exports the result on demand as Blizzard
|
|
// `APIDocumentation` tables (`C_APIDocumentation.GetSystems` / `GetSystem`),
|
|
// which the embedded addon's `/api` browser renders. Prose beyond one
|
|
// sentence stays in the docs; a descriptor is shape, not manual.
|
|
//
|
|
// Rules:
|
|
// - One descriptor per REGISTERED NAME, not per C function. The same
|
|
// `Script_*` bound twice with different return conventions
|
|
// (`IsUsableSpell` → 1/nil pairs, `C_Spell.IsSpellUsable` → booleans)
|
|
// gets two descriptors; a pair with the same shape may share one.
|
|
// - `type` uses Blizzard's spellings — "number", "string", "bool",
|
|
// "table", "luaIndex", "UnitToken", "SpellIdentifier", … — or the Name
|
|
// of a `Structure` / enumeration declared elsewhere, which the browser
|
|
// renders as a link.
|
|
// - `Function::system` names the System a GLOBAL belongs to; convention
|
|
// `<Area>Globals` ("SpellGlobals", "ItemGlobals"). Table functions
|
|
// derive theirs from the table ("C_Spell" → System "Spell", Namespace
|
|
// "C_Spell"); frame methods from the registry. A global's system must
|
|
// not reuse a namespaced System's Name — the browser would prefix it.
|
|
// - Descriptors are `const` objects with constant initializers (string
|
|
// literals + file-scope arrays): no heap, no dynamic init.
|
|
// - Summaries are user-facing text: one sentence, plain words, present
|
|
// tense, no patch versions.
|
|
namespace Doc {
|
|
|
|
struct Field {
|
|
const char *name;
|
|
const char *type;
|
|
bool nilable;
|
|
const char *defaultValue; // Lua literal ("false", "0", "\"player\""), or nullptr
|
|
const char *doc; // one sentence, or nullptr
|
|
};
|
|
|
|
// Required argument / always-present return.
|
|
constexpr Field Req(const char *name, const char *type, const char *doc = nullptr) {
|
|
return {name, type, false, nullptr, doc};
|
|
}
|
|
// Optional: nilable when no default is given, otherwise non-nil with that
|
|
// default (Blizzard marks defaulted arguments `Nilable = false` + `Default`).
|
|
constexpr Field Opt(const char *name, const char *type, const char *dflt = nullptr,
|
|
const char *doc = nullptr) {
|
|
return {name, type, dflt == nullptr, dflt, doc};
|
|
}
|
|
// Variable arguments / returns.
|
|
constexpr Field Vararg(const char *type, const char *doc = nullptr) {
|
|
return {"...", type, true, nullptr, doc};
|
|
}
|
|
|
|
// A view over a file-scope `const Field[]`; `{}` means none.
|
|
struct FieldList {
|
|
const Field *data = nullptr;
|
|
int count = 0;
|
|
constexpr FieldList() = default;
|
|
template <size_t N>
|
|
constexpr FieldList(const Field (&a)[N]) : data(a), count(static_cast<int>(N)) {}
|
|
};
|
|
|
|
// A registered function. Positional init: `{summary, args, rets}` for a
|
|
// table function, `{summary, args, rets, "XGlobals"}` for a global, and
|
|
// `{summary, args, rets, nullptr, true}` for a namespaced ClassicAPI
|
|
// extension.
|
|
struct Function {
|
|
const char *summary;
|
|
FieldList args;
|
|
FieldList rets;
|
|
const char *system; // globals / glue / aliases only; see the rules above
|
|
bool extension; // a ClassicAPI-original API, not a Blizzard one
|
|
};
|
|
|
|
// Pairs a frame method with its descriptor BY NAME (the engine's method
|
|
// tables are name-keyed; `SetShown` exists on four registries with four
|
|
// function pointers). Order is free; unmatched names are reported.
|
|
struct Method {
|
|
const char *name;
|
|
const Function *doc;
|
|
};
|
|
|
|
// A table shape a function returns or accepts → `Tables{Type="Structure"}`
|
|
// in `system`. Self-registering: nothing binds a structure to Lua, so it
|
|
// chains onto a static list at construction. Declare it next to the
|
|
// function that returns it.
|
|
struct Structure {
|
|
Structure(const char *name, const char *system, FieldList fields,
|
|
const char *summary = nullptr);
|
|
const char *name;
|
|
const char *system;
|
|
FieldList fields;
|
|
const char *summary;
|
|
const Structure *next;
|
|
};
|
|
|
|
// A custom event's payload, attached to its `Event::Custom::AutoReserve`.
|
|
struct Event {
|
|
const char *system;
|
|
const char *summary;
|
|
FieldList payload;
|
|
};
|
|
|
|
} // namespace Doc
|
|
|
|
namespace Lua {
|
|
using CFunction = int(__fastcall *)(void *L);
|
|
|
|
// Lua 5.0 pseudo-index used to read/write entries on the globals table.
|
|
constexpr int GLOBALS_INDEX = -10001;
|
|
// Lua 5.0 pseudo-index for the registry table — a Lua-state-local
|
|
// table protected from script code, used by C modules to anchor
|
|
// values across calls (e.g. timer callbacks pinned against GC).
|
|
constexpr int REGISTRY_INDEX = -10000;
|
|
// LUA_UPVALUEINDEX(i) — pseudo-index for accessing the i-th upvalue
|
|
// of a C closure. Lua 5.0 layout: `LUA_GLOBALSINDEX - i`.
|
|
constexpr int UpvalueIndex(int i) { return GLOBALS_INDEX - i; }
|
|
|
|
// `lua_call` / `lua_pcall` nresults sentinel meaning "all".
|
|
constexpr int MULTRET = -1;
|
|
|
|
// Type tag values returned by `Type()` (lua_type).
|
|
constexpr int TYPE_NIL = 0;
|
|
constexpr int TYPE_BOOLEAN = 1;
|
|
constexpr int TYPE_LIGHTUSERDATA = 2;
|
|
constexpr int TYPE_NUMBER = 3;
|
|
constexpr int TYPE_STRING = 4;
|
|
constexpr int TYPE_TABLE = 5;
|
|
constexpr int TYPE_FUNCTION = 6;
|
|
constexpr int TYPE_USERDATA = 7;
|
|
constexpr int TYPE_THREAD = 8;
|
|
|
|
using lua_isnumber_t = bool(__fastcall *)(void *L, int index);
|
|
using lua_isstring_t = bool(__fastcall *)(void *L, int index);
|
|
using lua_tonumber_t = double(__fastcall *)(void *L, int index);
|
|
using lua_toboolean_t = int(__fastcall *)(void *L, int index);
|
|
using lua_tostring_t = const char *(__fastcall *)(void *L, int index);
|
|
using lua_strlen_t = unsigned int(__fastcall *)(void *L, int index);
|
|
using lua_pushnumber_t = void(__fastcall *)(void *L, double n);
|
|
using lua_pushnil_t = void(__fastcall *)(void *L);
|
|
using lua_pushboolean_t = void(__fastcall *)(void *L, int b);
|
|
using lua_pushstring_t = void(__fastcall *)(void *L, const char *s);
|
|
using lua_pushlstring_t = void(__fastcall *)(void *L, const char *s, unsigned int len);
|
|
using lua_pushvalue_t = void(__fastcall *)(void *L, int idx);
|
|
using lua_pushcclosure_t = void(__fastcall *)(void *L, CFunction fn, int upvals);
|
|
using lua_newtable_t = void(__fastcall *)(void *L);
|
|
using lua_gettable_t = void(__fastcall *)(void *L, int idx);
|
|
using lua_rawget_t = void(__fastcall *)(void *L, int idx);
|
|
// Pushes t[n] for the table at idx, raw (no metamethods). With idx =
|
|
// REGISTRY_INDEX it pushes a value stored under an integer ref.
|
|
using lua_rawgeti_t = void(__fastcall *)(void *L, int idx, int n);
|
|
using lua_settable_t = void(__fastcall *)(void *L, int idx);
|
|
using lua_rawset_t = void(__fastcall *)(void *L, int idx);
|
|
// Pushes the metatable of the value at idx and returns 1, or pushes
|
|
// nothing and returns 0 when it has none.
|
|
using lua_getmetatable_t = int(__fastcall *)(void *L, int idx);
|
|
// Pops the table at the top and installs it as the metatable of the value
|
|
// at idx; returns 1.
|
|
using lua_setmetatable_t = int(__fastcall *)(void *L, int idx);
|
|
using lua_insert_t = void(__fastcall *)(void *L, int idx);
|
|
using lua_remove_t = void(__fastcall *)(void *L, int idx);
|
|
using lua_gettop_t = int(__fastcall *)(void *L);
|
|
using lua_settop_t = void(__fastcall *)(void *L, int idx);
|
|
using lua_call_t = void(__fastcall *)(void *L, int nargs, int nresults);
|
|
using lua_pcall_t = int(__fastcall *)(void *L, int nargs, int nresults, int errfunc);
|
|
using lua_next_t = int(__fastcall *)(void *L, int idx);
|
|
using lua_type_t = int(__fastcall *)(void *L, int index);
|
|
using lua_typename_t = const char *(__fastcall *)(void *L, int type);
|
|
// The 1.12 `lua_error` wrapper at `0x6F4940` is actually variadic —
|
|
// it does `lua_pushvfstring(L, fmt, args)` then prepends `luaL_where`
|
|
// and throws. Existing callers pass a single literal (no `%`), which
|
|
// is fine because cdecl tolerates extra-arg-less calls. New callers
|
|
// forwarding user-supplied error strings should use `Error(L, "%s",
|
|
// userMsg)` to avoid format-string interpretation of `%` in the
|
|
// message body.
|
|
using lua_error_t = void(__cdecl *)(void *L, const char *fmt, ...);
|
|
using lua_topointer_t = const void *(__fastcall *)(void *L, int idx);
|
|
using lua_tothread_t = void *(__fastcall *)(void *L, int idx);
|
|
using lua_iscfunction_t = int(__fastcall *)(void *L, int idx);
|
|
using lua_tocfunction_t = CFunction(__fastcall *)(void *L, int idx);
|
|
// Fill a lua_Debug (Offsets::SIZEOF_LUA_DEBUG bytes) for a call level /
|
|
// with the fields `what` names. Level 0 is the running C function.
|
|
using lua_getstack_t = int(__fastcall *)(void *L, int level, void *ar);
|
|
using lua_getinfo_t = int(__fastcall *)(void *L, const char *what, void *ar);
|
|
using lua_xmove_t = void(__fastcall *)(void *from, void *to, int n);
|
|
// `lua_newthread` returns the new `lua_State *` in eax, but Ghidra
|
|
// infers `void` because the inner call's value just flows through.
|
|
// We declare the return type honestly here; callers that don't want
|
|
// to rely on the calling convention preserving eax can read the
|
|
// thread back from L's top via `ToPointer(L, -1)`.
|
|
using lua_newthread_t = void *(__fastcall *)(void *L);
|
|
using lua_resume_t = int(__fastcall *)(void *L, int nargs);
|
|
using lua_yield_t = int(__fastcall *)(void *L, int nresults);
|
|
using luaL_argerror_t = void(__fastcall *)(void *L, int narg, const char *msg);
|
|
using luaL_setn_t = void(__fastcall *)(void *L, int t, int n);
|
|
// Pops the top value into the table at `t` under a fresh integer key and
|
|
// returns the key (LUA_REFNIL, -1, for a nil). With REGISTRY_INDEX it anchors
|
|
// a value across calls; read it back with RawGetI(L, REGISTRY_INDEX, ref).
|
|
using luaL_ref_t = int(__fastcall *)(void *L, int t);
|
|
// Releases a key returned by luaL_ref; ignores LUA_REFNIL / LUA_NOREF.
|
|
using luaL_unref_t = void(__fastcall *)(void *L, int t, int ref);
|
|
using lua_checkstack_t = int(__fastcall *)(void *L, int size);
|
|
// Pops the top `n` values and pushes their `..` concatenation; n == 0 pushes
|
|
// "" and n == 1 leaves the value untouched.
|
|
using lua_concat_t = void(__fastcall *)(void *L, int n);
|
|
// Pushes a new full userdata of `size` bytes and returns its block.
|
|
using lua_newuserdata_t = void *(__fastcall *)(void *L, unsigned int size);
|
|
// The block of the full userdata at idx, the pointer of a light one, else null.
|
|
using lua_touserdata_t = void *(__fastcall *)(void *L, int idx);
|
|
|
|
extern const lua_isnumber_t IsNumber;
|
|
extern const lua_isstring_t IsString;
|
|
extern const lua_tonumber_t ToNumber;
|
|
extern const lua_toboolean_t ToBoolean;
|
|
extern const lua_tostring_t ToString;
|
|
extern const lua_strlen_t StrLen;
|
|
extern const lua_pushnumber_t PushNumber;
|
|
extern const lua_pushnil_t PushNil;
|
|
extern const lua_pushboolean_t PushBoolean;
|
|
// Convenience overload — takes a real `bool` so callers don't have to
|
|
// `static_cast<int>(...)` or `condition ? 1 : 0` at every site. The
|
|
// engine's `lua_pushboolean` ABI wants `int` (any non-zero = true), so
|
|
// this just funnels through the raw binding with a single conversion.
|
|
inline void PushBool(void *L, bool b) { PushBoolean(L, static_cast<int>(b)); }
|
|
// The engine's script-flag argument reader (FUN_LUA_TO_BOOLEAN_LOOSE, 4.3.4's
|
|
// `StringToBOOL(L, index, default)`), which every engine method taking an
|
|
// optional flag uses: nil is false, a boolean is itself, a number is its
|
|
// truncated int (so 0.5 is false), a string reads as StringToFlag except that
|
|
// text it does not recognize is `defaultValue`, and any other type is
|
|
// `defaultValue`.
|
|
bool ToFlag(void *L, int index, bool defaultValue = false);
|
|
extern const lua_pushstring_t PushString;
|
|
extern const lua_pushlstring_t PushLString;
|
|
extern const lua_pushvalue_t PushValue;
|
|
extern const lua_pushcclosure_t PushCClosure;
|
|
extern const lua_newtable_t NewTable;
|
|
extern const lua_gettable_t GetTable;
|
|
extern const lua_rawget_t RawGet;
|
|
extern const lua_rawgeti_t RawGetI;
|
|
extern const lua_settable_t SetTable;
|
|
extern const lua_rawset_t RawSet;
|
|
extern const lua_getmetatable_t GetMetatable;
|
|
extern const lua_setmetatable_t SetMetatable;
|
|
extern const lua_insert_t Insert;
|
|
extern const lua_remove_t Remove;
|
|
extern const lua_gettop_t GetTop;
|
|
extern const lua_settop_t SetTop;
|
|
extern const lua_call_t Call;
|
|
extern const lua_pcall_t PCall;
|
|
extern const lua_next_t Next;
|
|
extern const lua_type_t Type;
|
|
extern const lua_typename_t TypeName;
|
|
extern const lua_error_t Error;
|
|
extern const lua_topointer_t ToPointer;
|
|
extern const lua_tothread_t ToThread;
|
|
extern const lua_iscfunction_t IsCFunction;
|
|
extern const lua_tocfunction_t ToCFunction;
|
|
extern const lua_getstack_t GetStack;
|
|
extern const lua_getinfo_t GetInfo;
|
|
extern const lua_xmove_t XMove;
|
|
extern const lua_newthread_t NewThread;
|
|
extern const lua_resume_t Resume;
|
|
extern const lua_yield_t Yield;
|
|
extern const luaL_argerror_t ArgError;
|
|
extern const luaL_setn_t SetN;
|
|
extern const luaL_ref_t Ref;
|
|
extern const luaL_unref_t Unref;
|
|
extern const lua_checkstack_t CheckStack;
|
|
extern const lua_concat_t Concat;
|
|
extern const lua_newuserdata_t NewUserdata;
|
|
extern const lua_touserdata_t ToUserdata;
|
|
|
|
// Returns the global `lua_State *` (read on demand from the engine's global).
|
|
// Callable outside a Lua callback, e.g. during LoadScriptFunctions setup.
|
|
void *State();
|
|
|
|
// Resolves a Lua-side frame/object table at stack index `idx` to its
|
|
// underlying `CFrameScriptObject *`. Mirrors the standard prologue
|
|
// of the engine's own `Set*` frame methods — pushes the object via
|
|
// `FrameScript_PushObject`, reads it back as a pointer via
|
|
// `FrameScript_GetObject`, then balances the stack. Returns nullptr
|
|
// if the slot isn't a CObject (table, light-userdata, or userdata
|
|
// types are accepted by the engine resolver). Callers pass `1` for
|
|
// the `self` slot of any `frame:method(...)` invocation.
|
|
void *ResolveObject(void *L, int idx);
|
|
|
|
// The inverse: the object's Lua-registry ref, created on first use exactly as
|
|
// the engine does it (GetMouseFocus and the script runners register an
|
|
// object with FUN_FRAMESCRIPT_OBJECT_SCRIPT_REGISTER when its refcount is 0).
|
|
int ObjectLuaRef(void *object);
|
|
// Pushes the object's Lua table (registry[ObjectLuaRef(object)]).
|
|
void PushObject(void *L, void *object);
|
|
|
|
// The object's global name (VTBL_SCRIPTOBJECT_GET_NAME), or nullptr when it
|
|
// has none.
|
|
const char *ObjectName(void *object);
|
|
|
|
// How the engine names an object in its frame-script usage errors:
|
|
// `GetName() ?: "<unnamed>"`.
|
|
const char *ObjectDisplayName(void *object);
|
|
|
|
// Same resolve, then the type gate every engine frame method applies to its
|
|
// `self` before touching it: `lua_type == table`, resolve to the object, then
|
|
// the `IsA(typeId)` vmethod at vtable+0x10. `ResolveObject` alone is not
|
|
// enough for a method that casts the result — it hands back a
|
|
// `CFrameScriptObject *` for ANY frame, so `GameTooltip.SetSpellByID(button)`
|
|
// would reach the tooltip builder with a Button. Frame methods are ordinary
|
|
// first-class Lua values (the per-type dispatcher is an `__index` handler
|
|
// that returns the method closure), so that call is reachable from plain Lua
|
|
// and the gate is not optional.
|
|
//
|
|
// `typeIdVar` is the class's `VAR_*_LUA_TYPE_ID`, which must match the
|
|
// registry the method was registered on. The id is assigned lazily by
|
|
// whichever method of the class runs first, so these mirror that assignment
|
|
// and work even before any stock method of the type has been called.
|
|
//
|
|
// Raises the engine's own three errors and returns null. Pass
|
|
// `raiseError = false` for an optional object ARGUMENT, where the caller
|
|
// wants a silent null rather than a "this" error naming the wrong slot.
|
|
// Returns null either way, so callers always check.
|
|
void *ResolveTypedObject(void *L, int idx, uintptr_t typeIdVar,
|
|
bool raiseError = true);
|
|
|
|
// For a method registered on SEVERAL registries, where any of those types is
|
|
// a legitimate `self`. Accepts the object if `IsA` passes for any of the
|
|
// listed ids — which is exactly what being in all of those registries means,
|
|
// and avoids having to pin down the shared base class.
|
|
void *ResolveTypedObjectAny(void *L, int idx, const uintptr_t *typeIdVars,
|
|
int count, bool raiseError = true);
|
|
|
|
// The class's live type id, assigning it if the engine has not yet. Needed
|
|
// directly only when calling a type-specific vtable slot.
|
|
int FrameScriptTypeId(uintptr_t typeIdVar);
|
|
|
|
// The object's `IsA(typeId)` vmethod for a class's `VAR_*_LUA_TYPE_ID`.
|
|
bool IsA(void *object, uintptr_t typeIdVar);
|
|
|
|
// Per-type sugar over `ResolveTypedObject`, so a call site cannot pair a
|
|
// method with the wrong class's id. `idx` defaults to the `self` slot.
|
|
void *ResolveTooltip(void *L, int idx = 1, bool raiseError = true);
|
|
void *ResolveFrame(void *L, int idx = 1, bool raiseError = true);
|
|
void *ResolveRegion(void *L, int idx = 1, bool raiseError = true);
|
|
void *ResolveTexture(void *L, int idx = 1, bool raiseError = true);
|
|
void *ResolveFontString(void *L, int idx = 1, bool raiseError = true);
|
|
void *ResolveEditBox(void *L, int idx = 1, bool raiseError = true);
|
|
void *ResolveModel(void *L, int idx = 1, bool raiseError = true);
|
|
|
|
// Every name these registrars bind is ALSO bound under `_G.ClassicAPI` —
|
|
// `ClassicAPI.GetSpellInfo`, `ClassicAPI.C_Item.IsBound` — as an escape
|
|
// hatch for names something else replaces later, and by value so
|
|
// `ClassicAPI.X == X` until that happens. Automatic; a new module needs no
|
|
// extra call. See `MirrorRegistration` in Game.cpp for why it lives here
|
|
// and what it does not cover.
|
|
//
|
|
// Every registrar also RECORDS the registration for the API documentation
|
|
// (`src/api/Documentation.cpp`): kind, table, name, registry, and which Lua
|
|
// state's pass it ran in (in-game / glue / both). Only the FIRST pass of
|
|
// each state records — later passes (every `/reload`) are no-ops — and a
|
|
// registration made outside a `Run*Registrations` pass is not recorded at
|
|
// all. The trailing `doc` argument is the descriptor (see `Game::Doc`
|
|
// above); pass `nullptr` for a not-yet-documented registration and
|
|
// `_classicapi_UndocumentedAPI()` lists it. The defaults exist only until
|
|
// the sweep finishes; then they go and a missing descriptor stops compiling.
|
|
|
|
// Registers a single global Lua function (e.g. `GetSpellInfo`). The function
|
|
// must use the WoW Lua C function ABI: `int __fastcall(void *L)`.
|
|
void RegisterGlobalFunction(const char *name, CFunction func,
|
|
const Doc::Function *doc = nullptr);
|
|
|
|
// Glue-state equivalent of `RegisterGlobalFunction`. Identical wire
|
|
// (calls `FrameScript_RegisterFunction`); the engine routes the
|
|
// registration to whichever Lua state `VAR_LUA_STATE` currently
|
|
// references. Only safe to call from inside a `GlueModuleAutoRegister`
|
|
// callback — at that point the engine has just finished registering
|
|
// its own 109 glue functions, and `VAR_LUA_STATE` still points at the
|
|
// glue state. Calling outside that window would silently target the
|
|
// wrong state.
|
|
void RegisterGlueFunction(const char *name, CFunction func,
|
|
const Doc::Function *doc = nullptr);
|
|
|
|
// Frame-method registration entry: { name, func } pairs walked by the engine's
|
|
// per-frame-type method-table iterator. Layout matches what the engine expects
|
|
// natively — name first, then function pointer.
|
|
struct FrameMethodEntry {
|
|
const char *name;
|
|
CFunction func;
|
|
};
|
|
|
|
// Registers a batch of methods on a per-frame-type registry (e.g.
|
|
// GameTooltipMethodRegistry for `tooltip:Foo()` calls). `context` is the
|
|
// registry address — see Offsets::VAR_*_METHOD_REGISTRY. `docs` pairs
|
|
// descriptors to the entries by NAME (any order, any subset).
|
|
void RegisterFrameMethods(void *context, const FrameMethodEntry *table, int count,
|
|
const Doc::Method *docs = nullptr, int docCount = 0);
|
|
|
|
// Registers `func` at `_G[tableName][methodName]`, creating the namespace
|
|
// table if it doesn't already exist. This is how modern WoW C_*-style APIs
|
|
// are bound — the engine has no built-in support for table-bound Lua
|
|
// functions, so we manipulate the globals table directly via the Lua C API.
|
|
void RegisterTableFunction(const char *tableName, const char *methodName,
|
|
CFunction func, const Doc::Function *doc = nullptr);
|
|
|
|
// Binds `_G[alias]` to the SAME closure as `_G[tableName][methodName]`, by
|
|
// value — the way the engine's own Lua-init snippet binds its short aliases
|
|
// (`tinsert = table.insert`, `strlen = string.len`, …). Use it after
|
|
// registering over a library function whose alias the snippet has already
|
|
// captured, so the alias follows the replacement and `alias == table.method`
|
|
// stays true. Mirrored under `_G.ClassicAPI` like every other registration.
|
|
void RegisterGlobalAlias(const char *alias, const char *tableName, const char *methodName,
|
|
const Doc::Function *doc = nullptr);
|
|
|
|
// Key/value pair for `RegisterIntegerEnum` and `RegisterConstants`. `key`
|
|
// becomes a field name (PascalCase for Blizzard's `Enum.*`, UPPER_CASE for
|
|
// its `Constants.*`) and `value` is the integer the field maps to.
|
|
struct EnumIntegerEntry {
|
|
const char *key;
|
|
int value;
|
|
};
|
|
|
|
// Registers `_G[parent][sub] = { entries }` as an integer-valued enum
|
|
// table, creating `_G[parent]` if needed. Used for Blizzard-style
|
|
// `Enum.AddOnSecurityStatus = { Secure=0, Insecure=1, ... }` shapes.
|
|
// `docSystem` is the documentation System the enumeration belongs to
|
|
// ("SpellBook", "Item", …); the entries themselves are the documentation.
|
|
void RegisterIntegerEnum(const char *parent, const char *sub,
|
|
const EnumIntegerEntry *entries, int count,
|
|
const char *docSystem = nullptr);
|
|
|
|
// Registers `Constants[sub] = { entries }`, Blizzard's engine constant
|
|
// tables (`Constants.MoneyFormattingConstants`). Documented as a "Constants"
|
|
// table of `docSystem`.
|
|
void RegisterConstants(const char *sub, const EnumIntegerEntry *entries, int count,
|
|
const char *docSystem);
|
|
|
|
// Set `t[key] = value` on the table currently at stack[-1] (the most
|
|
// common shape used when populating a struct-style table mid-build).
|
|
// Pushes the key + value, calls `SetTable(L, -3)`, which pops both and
|
|
// leaves the table on the stack — so it's safe to chain. NULL string
|
|
// values are coerced to `""` so callers don't have to gate each push.
|
|
void SetFieldNumber(void *L, const char *key, double value);
|
|
void SetFieldString(void *L, const char *key, const char *value);
|
|
void SetFieldBool(void *L, const char *key, bool value);
|
|
// `t[key] = nil` — clears a field a reused (caller-supplied) table may still
|
|
// hold from an earlier fill. Not for fresh tables: Lua 5.0 inserts a node for
|
|
// a missing key even when the value is nil.
|
|
void SetFieldNil(void *L, const char *key);
|
|
|
|
// Sets `_G[name] = value` via `lua_rawset` on the globals
|
|
// pseudo-index. `RawSet` over `SetTable` because the globals table has
|
|
// no `__newindex` in vanilla 1.12 — explicit intent and skips a dead
|
|
// metatable check. Used for flat constant globals like
|
|
// `CLASSIC_API_VERSION` and the `LE_ITEM_QUALITY_*` family.
|
|
void SetGlobalNumber(void *L, const char *name, double value);
|
|
|
|
// Pushes `_G[globalName]` onto the stack if it resolves to a string
|
|
// (Blizzard's FrameXML globals like `ITEMS_EQUIPPED`, addon-defined
|
|
// localization tables, etc.); otherwise pushes `fallback`. Either way
|
|
// leaves exactly one string at the top of the stack. The canonical
|
|
// pattern is "look up a localized format string with an English
|
|
// fallback for stripped servers / pre-init states":
|
|
//
|
|
// Game::Lua::PushLocalizedString(L, "ITEMS_EQUIPPED", "%d equipped");
|
|
// Game::Lua::PushNumber(L, count);
|
|
// // … then string.format / sprintf-style consume
|
|
void PushLocalizedString(void *L, const char *globalName, const char *fallback);
|
|
|
|
// Pushes `string.format(_G[globalName] or fallback, n)` — the result
|
|
// of formatting a single integer into a localized string. Leaves the
|
|
// formatted string on top of the stack. Common shape: most
|
|
// FrameXML count-style strings (`ITEMS_EQUIPPED = "%d equipped"`,
|
|
// `ITEM_SLOTS_IGNORED = "%d slot(s) ignored"`, etc.). Callers that
|
|
// need string or float args, or multiple args, can build their own
|
|
// using `PushLocalizedString` + manual `string.format` invocation.
|
|
// A `|4singular:plural;` in the string stays; the engine's grammar pass
|
|
// (Text::Grammar) expands it when the text is set.
|
|
void PushLocalizedFormatInt(void *L, const char *globalName,
|
|
const char *fallback, int n);
|
|
|
|
// Pushes `_G[name]` and returns true only if it resolved to a function
|
|
// (leaving it on the stack, ready to be called); otherwise pops it and
|
|
// returns false. The building block for the CallGlobal* helpers below and for
|
|
// any C module that dispatches to a Lua/FrameXML global by name (a pattern
|
|
// several modules otherwise open-code).
|
|
bool PushGlobalFunction(void *L, const char *name);
|
|
|
|
// `_G[name]()` — no args, no results; a no-op if the global isn't a function.
|
|
// Stack-neutral.
|
|
void CallGlobal(void *L, const char *name);
|
|
|
|
// `_G[name](arg)` — one string arg (NULL → nil), no results. Returns true iff
|
|
// the global was a function and got called, so callers can fall back to a
|
|
// native path when the FrameXML/addon global is absent. Stack-neutral.
|
|
bool CallGlobalString(void *L, const char *name, const char *arg);
|
|
} // namespace Lua
|
|
|
|
// Developer-console command system — the `~` console available when the
|
|
// client is launched with `-console`. Vanilla maintains a
|
|
// `TSExplicitList<CONSOLECOMMAND>`; these wrap the engine's registrar
|
|
// and output paths. See the "Console commands & Interface file export"
|
|
// section in CLAUDE.md for the underlying offsets and ABI.
|
|
namespace Console {
|
|
|
|
// Console-command handler ABI — 4.3.4's `COMMANDHANDLER(command,
|
|
// arguments)`. `command` is the name the command was invoked by, which
|
|
// is how one handler serves several names: every CVar is registered with
|
|
// the shared FUN_CONSOLE_CVAR_COMMAND_HANDLER, which looks the CVar up by
|
|
// `command`. `args` is the text after the name (empty string when
|
|
// invoked bare). The engine ignores the return value; return 1.
|
|
using CommandHandler = int(__fastcall *)(const char *command, const char *args);
|
|
|
|
// Help-grouping categories — 4.3.4's `CATEGORY` enum, which matches the
|
|
// nine-entry table the 1.12 `help` command lists (VAR_CONSOLE_CATEGORY_TABLE).
|
|
// Cosmetic: only `help` grouping reads it; the registrar doesn't validate it.
|
|
enum Category {
|
|
CATEGORY_DEBUG = 0,
|
|
CATEGORY_GRAPHICS = 1,
|
|
CATEGORY_CONSOLE = 2,
|
|
CATEGORY_COMBAT = 3,
|
|
CATEGORY_GAME = 4,
|
|
CATEGORY_DEFAULT = 5,
|
|
CATEGORY_NET = 6,
|
|
CATEGORY_SOUND = 7,
|
|
CATEGORY_GM = 8,
|
|
};
|
|
|
|
// Registers a console command. `name` and `description` are stored BY
|
|
// POINTER (the engine doesn't copy them), so pass string literals or
|
|
// otherwise process-lifetime storage. Dedup-safe: re-registering the
|
|
// same name is a harmless no-op, so it's fine to call from a hook that
|
|
// fires more than once. Safe any time after engine boot — the command
|
|
// table self-initializes on first use. `description` may be nullptr.
|
|
void RegisterCommand(const char *name, CommandHandler handler, int category,
|
|
const char *description);
|
|
|
|
// Line colour types — 4.3.4's `COLOR_T`, indexing the nine-entry
|
|
// VAR_CONSOLE_COLORS table. The engine's `help` writes WARNING (yellow),
|
|
// its failures ERROR (red), and its plain output DEFAULT.
|
|
enum Color {
|
|
COLOR_DEFAULT = 0,
|
|
COLOR_INPUT = 1,
|
|
COLOR_ECHO = 2,
|
|
COLOR_ERROR = 3,
|
|
COLOR_WARNING = 4,
|
|
COLOR_GLOBAL = 5,
|
|
COLOR_ADMIN = 6,
|
|
COLOR_HIGHLIGHT = 7,
|
|
COLOR_BACKGROUND = 8,
|
|
};
|
|
|
|
// Writes a line to the console output buffer. No-ops cleanly when the
|
|
// console isn't active, so it's always safe to call.
|
|
void Write(const char *line, Color color = COLOR_DEFAULT);
|
|
|
|
// The engine's own `ConsolePrintf` (FUN_CONSOLE_PRINTF): formats with
|
|
// Storm's printf into a 1024-byte buffer, then writes it in
|
|
// COLOR_DEFAULT. Exposed as the engine's entry itself rather than a
|
|
// wrapper, because a cdecl varargs call cannot be forwarded.
|
|
extern void(__cdecl *const Printf)(const char *format, ...);
|
|
|
|
} // namespace Console
|
|
|
|
// Self-registration for API modules. Each module .cpp declares a file-scope
|
|
// `static const Game::ModuleAutoRegister _r{&RegisterLuaFunctions};`, which
|
|
// chains itself onto a global list at DLL-load time. `RunModuleRegistrations`
|
|
// is called once from the LoadScriptFunctions post-hook to fire them all,
|
|
// so DllMain.cpp doesn't need to know the modules exist.
|
|
//
|
|
// Order is unspecified (LIFO of static-init order across TUs). Modules must
|
|
// not depend on each other's registration side effects.
|
|
struct ModuleAutoRegister {
|
|
using Fn = void (*)();
|
|
explicit ModuleAutoRegister(Fn fn);
|
|
Fn fn;
|
|
ModuleAutoRegister *next;
|
|
};
|
|
|
|
void RunModuleRegistrations();
|
|
|
|
// Glue-state mirror of `ModuleAutoRegister`. Modules wanting login-
|
|
// screen exposure declare a file-scope
|
|
// `static const Game::GlueModuleAutoRegister _g{&RegisterGlueFunctions};`
|
|
// alongside (or instead of) the in-game `ModuleAutoRegister`. Glue
|
|
// callbacks run from the `FUN_LOAD_GLUE_SCRIPT_FUNCTIONS` post-hook,
|
|
// once per glue boot (game launch + every world→glue return). Use
|
|
// `Game::Lua::RegisterGlueFunction` from inside the callback.
|
|
struct GlueModuleAutoRegister {
|
|
using Fn = void (*)();
|
|
explicit GlueModuleAutoRegister(Fn fn);
|
|
Fn fn;
|
|
GlueModuleAutoRegister *next;
|
|
};
|
|
|
|
void RunGlueModuleRegistrations();
|
|
|
|
// Declarative MinHook registration. Each feature module declares a
|
|
// file-scope `static const Game::HookAutoRegister _hookreg{target,
|
|
// &hook_fn, reinterpret_cast<void**>(&original_fn)};` and the installer
|
|
// (`InstallHooks` in DllMain.cpp) walks the list once after
|
|
// `MH_Initialize`, creating each hook and QUEUE-enabling it; a single
|
|
// `MH_ApplyQueued` then activates them all in one thread-freeze.
|
|
//
|
|
// The install runs OFF the loader lock (via the `Load` export or the
|
|
// fallback worker thread — see DllMain.cpp), never inside DllMain, so
|
|
// the thread-freeze can't deadlock or stall the loader.
|
|
//
|
|
// Same lifetime rules as ModuleAutoRegister: constructors chain onto
|
|
// a static-init list before DllMain runs, the linker keeps the OBJ
|
|
// because the constructor has side effects, and order across TUs is
|
|
// undefined but doesn't matter here (hooks are independent).
|
|
//
|
|
// Use only for feature hooks. The four core engine-init hooks in
|
|
// DllMain (FrameScript_Initialize / LoadScriptFunctions /
|
|
// LoadGlueScriptFunctions / Frame::RegisterEvent) have inline logic that
|
|
// interleaves with the hook chain and stays with the installer.
|
|
struct HookAutoRegister {
|
|
HookAutoRegister(uintptr_t target, void *hook, void **original);
|
|
uintptr_t target;
|
|
void *hook;
|
|
void **original;
|
|
HookAutoRegister *next;
|
|
};
|
|
|
|
// Creates and QUEUE-enables every registered hook (no `MH_ApplyQueued`
|
|
// here — the caller applies the whole batch at once). Returns `false`
|
|
// and stops on first failure.
|
|
bool RunHookRegistrations();
|
|
|
|
// Self-registration for per-/reload state cleanup. A module that keeps
|
|
// file-static state which goes STALE across a game /reload declares a
|
|
// file-scope `static const Game::ReloadAutoRegister _reload{&PrepareForReload};`
|
|
// right after its `void PrepareForReload()`. `RunReloadCleanups()` — called
|
|
// from the FrameScript_Initialize hook, BEFORE the engine tears down the Lua
|
|
// state — fires them all, so DllMain no longer hand-maintains the list and a
|
|
// new module can't forget to wire itself in.
|
|
//
|
|
// State is "reload-fragile" when it survives in C++ but its meaning does not:
|
|
// - Lua registry refs / handler cells (the Lua reset invalidates them);
|
|
// - maps/sets keyed by a frame/object POINTER (the allocator recycles
|
|
// addresses, so an old entry aliases an unrelated new object);
|
|
// - cached event-slot indices (the engine rebuilds the event table).
|
|
// Firing a stale entry is the recurring bug this prevents (Tooltip::SetEvents
|
|
// issue #33, Frame::Attributes). A pure-C++ cache keyed by spellID/itemID is
|
|
// NOT fragile and must not register.
|
|
//
|
|
// Same lifetime + ordering rules as ModuleAutoRegister: static-init chaining,
|
|
// undefined cross-TU order — fine, because each callback only clears its OWN
|
|
// state. This is the "clear stale state" category only; a save-before-teardown
|
|
// like Player::NameCache::Flush stays an explicit DllMain call (it persists
|
|
// rather than clears, and also runs on the glue-return path).
|
|
struct ReloadAutoRegister {
|
|
using Fn = void (*)();
|
|
explicit ReloadAutoRegister(Fn fn);
|
|
Fn fn;
|
|
ReloadAutoRegister *next;
|
|
};
|
|
|
|
void RunReloadCleanups();
|
|
|
|
} // namespace Game
|