Records the engine trail found while evaluating it: the per-frame
dispatcher FUN_0076B2C0 (vtable +0x38, __thiscall(frame, float elapsed),
fires the OnUpdate slot at +0x128) and the walk FUN_00765650, which
iterates nine strata buckets of the frame+0x310 intrusive list with NO
visibility check in either place. Visibility is list membership, and that
list is the render list -- which is what splits the enum: Disabled /
RunWhenVisible / RunWhenVisibleOnce need only a co-hook on the
dispatcher, while RunOnce / RunAlways have to be driven from the
already-owned WorldTick because a hidden frame is not in the list at all
and forcing it in would try to draw it.
Also notes the open question (which elapsed the self-driven modes pass,
and whether WorldTick runs before or after the UI pass), that no loaded
DLL references either function, and that RunAlways is the only genuinely
new capability -- the rest is parity with existing idioms.
docs/API.md is 18.7k lines and its anchors are signature slugs, so editing a
signature breaks the 281 internal and 88 README links into it. Blizzard
solved the same problem by shipping the API as data plus a browser addon,
and warcraft.wiki.gg renders those same tables. One set of descriptors can
feed all three.
Each registration now carries one next to it: typed arguments and returns,
nilability, defaults, and a sentence. Events, enumerations and returned table
shapes are described the same way. No Script_* body changed.
Game.h gains namespace Game::Doc (Field with Req/Opt/Vararg, FieldList,
Function, Method, Structure, Event) and a trailing descriptor argument on all
six Game::Lua::Register* plus Event::Custom::AutoReserve.
api/Documentation.cpp records every registration on the first pass of each
Lua state and seals it, so /reload re-registers but records nothing and the
environment comes from which pass saw the name. Export is lazy: nothing is
materialized until C_APIDocumentation.GetSystem asks for one system, because
eager export would build thousands of tables per reload for a slash command.
_classicapi_UndocumentedAPI lists what still has no descriptor.
AddOns/!!!ClassicAPI/APIDocumentation/ ports Blizzard_APIDocumentation's eight
files. Named /classicapi, not /api: the browser holds only what ClassicAPI
adds, so /api would have implied the whole 1.12 surface. Two deliberate
differences from the retail source, both noted in the file headers: a system
search also matches its namespace, since that is the name people type; and an
undocumented function says so, because an empty signature otherwise reads as
a real one.
LinkUtil gains the SetItemRef to LinkUtil.ProcessLink dispatch. That handler
registry was dead code; a new link type now registers a handler instead of
stacking another SetItemRef override. Also defines assertsafe there, which
was undefined and only mattered once the function went live.
Documented: the C_Spell and C_SpellBook surface, the spell globals, both
spellbook enumerations, the 13 UNIT_SPELLCAST_* events, GameTooltip as the
widget-method example and C_Glue as the glue and mixed-environment example.
66 of 692 function registrations. tools/New-ApiDocSkeletons.ps1 emits
paste-ready skeletons to make the rest of the sweep tractable.
Verified in game: the browser lists, searches, and prints detail; links
render and click through; right-click copies and shift-click dumps.
IsUsableSpell hand-rolled five checks (known, alive, off cooldown,
power, reagents) and diverged from IsUsableAction exactly where the
engine does more or less: it never tested stance, so Whirlwind in
Battle Stance reported usable, and it tested cooldown first, so a
0-rage Whirlwind on cooldown reported (nil, nil) instead of (nil, 1).
IsUsableAction reads a per-slot cache that FUN_004E5050 fills by
calling FUN_SPELL_IS_USABLE (0x006E3D60) on a player spell's record,
or by comparing the pet's power against the spell cost for a pet
spell. Run those same two paths live, plus the knowledge gate the
helper lacks. Cooldown is not part of usability: the helper has no
cooldown branch and FrameXML greys and swipes as separate states.
Item::Usable had been calling the helper all along.
A pet-book spell given by ID now takes the pet path instead of
always reporting not usable.
Offsets.h: add VAR_PET_GUID and FUN_PET_ACTIONS_USABLE (verified via
Script_HasPetUI, Script_GetPetActionsUsable and the recompute's pet
branch); replace the FUN_SPELL_IS_USABLE comment with the decompiled
check list.
Fixes#51
`kUnhookableNames` is patch 11.0.0's own refusal list, verbatim — the 23
taint-relevant names, not "the Lua base library". Nothing said so, and
with the base-library luaL_reg table (0x00811E28, 36 entries) freshly
catalogued the two looked like they should be one thing. They must not
be: 11.0 leaves tostring / error / loadstring / assert / collectgarbage
hookable and includes secure-family names that are no base function, so
deriving the list from the engine table would move it away from the
client. No earlier client on this machine (3.3.5, 4.3.4, 5.4.8) has the
restriction at all.
Say so in the source comment and the TODO section, and list the names in
the API reference, which documented every other hooksecurefunc error but
this one. Comment-only in the source; no behavior change.
* feat(lua): backport 5.1 `#` and `%` operators via source transpile
Vanilla's Lua is 5.0, which lacks the `#` (length) and `%` (modulo)
operators, so modern addon ports that use them fail to COMPILE. Rather than
patch the 5.0 parser/VM (no OP_LEN/OP_MOD, no free opcode), rewrite the
SOURCE before it reaches the parser.
src/luasyntax/Transpile.cpp co-hooks luaL_loadbuffer (0x006F5690) — the one
function every compile funnels through (file scripts, loadstring, XML
handlers) — tokenizes each chunk with a small Lua-aware lexer, and runs a
precedence-climbing parser that rewrites, in one pass:
#operand -> __len(operand)
a % b -> __mod(a, b)
`#` is prefix but `%` is binary infix, so its operands are delimited by
PRECEDENCE: a*b%c -> __mod(a*b,c), a+b%c -> a+__mod(b,c), a%b%c chains
left-assoc as __mod(__mod(a,b),c), a%b^c -> __mod(a,b^c). The two operators
compose in the same pass (#t%2 -> __mod(__len(t),2)). No newlines are
inserted, so error line numbers are preserved.
Runtime helpers (registered on both the in-game and glue states):
- __len: string length, or a table border via bisection (5.1 `#`
semantics — ignores any table.setn count).
- __mod: a - floor(a/b)*b. NOT the engine's math.mod, which is C fmod
(truncated toward zero) and disagrees with `%` for negatives
(-1 % 3 == 2, but fmod(-1,3) == -1).
Safety: the rewrite runs only when a chunk contains `#`/`%`, and either as an
operator already fails to compile on 5.0 — so it cannot regress working code
except by misreading one inside a string/comment ("%d", "%a+", --[[ # ]]).
The lexer's string/comment skipping is the one safety-critical part and is
exact. Gated behind default-on toggles (_classicapi_SetLengthOperator /
SetModuloOperator); diagnostic _classicapi_TranspileLength returns the
rewrite. `...` is a separate, larger phase.
Adds FUN_LUAL_LOADBUFFER to Offsets.h with its derivation.
* feat(lua): honor the 5.1 `__environment` metatable field in getfenv/setfenv
Lua 5.1 lets a sandbox hide an environment: put `__environment` in the env
table's metatable and `getfenv` returns that value instead of the real env,
while `setfenv` refuses to change it. 1.12's engine already has this
protection but reads a RAW `__fenv` field on the env table itself — the older
5.0 form. Modern addons ported from 5.1 use the metatable `__environment`
spelling, which 1.12 silently ignored, so their sandboxes leaked.
getfenv (0x00702AC0) and setfenv (0x00702BF8) share one predicate
(0x00702BA0) that reads the marker and, when present, substitutes it / errors
"cannot change a protected environment". src/luaenv/Fenv.cpp co-hooks and
fully replaces that predicate to read `rawget(getmetatable(env),
"__environment")` first, falling back to the raw `env.__fenv` field. One hook
updates both consumers. The reimplementation preserves the predicate's exact
stack contract (push env, push marker, net +2, boolean return) that getfenv
(settop -2) and setfenv (settop -3) depend on; both metatable and env lookups
are RAW, so an `__index` metatable on the env is not disturbed.
The 5.1 mechanism was verified against 3.3.5's `FUN_0084F2F0` (raw
`__environment` off the metatable; no `"__fenv"` string exists there — Blizzard
renamed it and moved it to the metatable at the 5.0->5.1 jump). The change is
additive and inert: nothing on disk sets either marker, so every existing
getfenv/setfenv caller keeps getting the real env — it only activates when
code deliberately marks an environment.
Adds LUA_GET_METATABLE, LUA_GET_FENV, and FUN_LUA_ENV_PROTECT_PREDICATE to
Offsets.h.
* Use Lua length operator for class count
* feat(lua): backport the 5.1 `...` vararg expression via source transpile
This build is pure Lua 5.0 varargs: `function(...)` parses and populates the
`arg` table (with `arg.n`), but `...` used as an EXPRESSION is a parse error
("unexpected symbol near '...'") — verified in-game. So modern 5.1 addon code
using `...` (`{...}`, `local a,b = ...`, `f(...)`, `return ...`,
`select('#', ...)`) fails to compile.
Add a vararg pass to the transpiler (RewriteChunk runs it before the # / %
precedence parser) that rewrites the `...` EXPRESSION to `unpack(arg)`. This is
a faithful, position-independent substitution: `unpack(arg)` is itself a
multi-value expression, so it spreads in tail position and truncates to one
value elsewhere exactly as `...` does, and this build's `unpack(arg)` preserves
embedded nils via `arg.n` (verified: `f(1,nil,3)` -> `1 nil 3`). No precedence
analysis needed — unlike `%`, it's a token substitution once one case is
excluded: the `...` in a function's PARAMETER LIST (the vararg declaration that
creates `arg`) is left intact, found by scanning each `function` keyword and
skipping its param parens. Nested vararg functions work for free — each
`function(...)` makes its own `arg` and `unpack(arg)` binds to the nearest one
(verified: inner arg count 2, outer 3).
Safety mirrors # / %: only chunks containing `...` are touched, and `...` as an
expression already fails to compile on 5.0, so it can't regress working code;
`...` inside strings/comments is skipped by the lexer, and `.` (field) / `..`
(concat) are distinguished by run length. Gated behind the default-on
`_classicapi_SetVarargExpansion` toggle; `_classicapi_TranspileLength` now shows
the full rewrite (vararg + # + %).
File-scope `...` (the `local name, addon = ...` idiom) transpiles fine but only
yields values if the client passes varargs to addon chunks — a loader question,
separate from this syntax rewrite.
* feat(lua): provide addon-args so file-scope `local name, ns = ...` works
Modern addons open files with `local name, ns = ...` — the addon name plus a
per-addon shared namespace table, passed by the loader as the chunk's varargs.
Vanilla 1.12 never passed those (its main chunk has no `arg`), so with the
`...` backport in place the idiom resolved to `unpack(nil)` and errored. This
supplies the args ourselves.
In the luaL_loadbuffer hook, for an addon-file chunk (chunkname
`@Interface\AddOns\<Name>\...`, parsed case-insensitively) that uses a real
`...`, prepend a chunk-local `arg = {"<Name>", __addonns("<Name>"), n=2}`. The
existing `... -> unpack(arg)` pass then makes `local name, ns = ...` yield the
name and the namespace table. The preamble is newline-free (line numbers
preserved), placed after any UTF-8 BOM, and only injected for AddOns\ chunks
(FrameXML and loadstring are untouched); the addon name is rejected if it
contains characters that would break the string literal.
`__addonns(name)` returns the per-addon table — created once and returned
identically for every file of the addon (backed by a name->table map in the
Lua registry), matching modern WoW's shared second vararg. Registered in-game.
Verified in-game: an addon file's `local name, ns = ...` yields
`("<AddonName>", <table>)` with `ns == __addonns(name)` (shared across the
addon's files). File-scope `...` was the last piece; the in-function case was
already handled by the `...` pass.
* feat(lua): add C_AddOns.GetAddOnLocalTable(name)
Public alias of the addon-args namespace: returns the same per-addon table the
`local name, ns = ...` idiom yields — create-once and shared across every file
of the addon, backed by the same registry map as the internal `__addonns`
(both call Script_AddonNS). Lets code fetch an addon's namespace by name.
Registered via RegisterTableFunction on C_AddOns (non-destructive; coexists
with the existing C_AddOns.* functions regardless of module init order).
Currently ungated — it returns a table for any name, create-on-demand. TODO #99
records the follow-up to match retail: return nil unless the addon is loaded
AND its TOC declares `## AllowAddOnTableAccess: 1`, gating only this public
entry point while leaving the internal preamble path ungated.
* feat(lua): gate C_AddOns.GetAddOnLocalTable behind loaded + TOC opt-in
GetAddOnLocalTable was a raw alias of the addon-args namespace accessor:
it returned any addon's private table by name, loaded or not, with no
access control. Retail (11.0) gates this -- one addon reads another's
local table only when the target opts in via the `## AllowAddOnTableAccess`
TOC directive. Mirror that.
The public accessor now lives in addons/LocalTable.cpp and returns the
table only when the named addon is loaded (FUN_ADDON_IS_LOADED, by-name)
AND its .toc declares `## AllowAddOnTableAccess: <nonzero>` (scanned via
FUN_FILE_READ, read as a TOC boolean flag). Either check failing returns
nil. Directive spelling and function name both verified present in the
1.15.8 Classic Era binary.
The internal preamble path (an addon receiving its OWN table via the
injected `local _, ns = ...`) stays ungated -- an addon never needs
permission for its own namespace. Both paths now resolve to the same
per-addon table through LuaSyntax::PushAddonNamespace (AddonNamespace.h),
the single owner of the registry-backed name->table map.
Also close the bypass in the `__addonns` global itself. The map lives in
the Lua registry (unreachable from Lua -- this build ships no
debug.getregistry / debug introspection), so `__addonns` was the sole
Lua-visible door, and it was ungated. It is now context-gated: it answers
only while an addon's own chunk is mid-load, for its own name, one-shot.
At runtime it denies every name. Verified safe against the loader: the
addon file loader is strictly per-file load-then-run
(FUN_006edb90 -> FUN_006ede10 -> FUN_00704bc0 -> FUN_00704ae0, where
luaL_loadbuffer is immediately followed by lua_pcall), so nothing runs
between the grant being set and the preamble consuming it.
Net result: the only runtime path to another addon's local table is the
TOC-gated GetAddOnLocalTable.
* fix(lua): close the __addonns loadstring-forgery vector
The addon-args grant (`g_loadingAddon`) that lets a chunk's injected
preamble fetch its own namespace via the `__addonns` global was armed
whenever luaL_loadbuffer saw an `Interface\AddOns\...` chunkname with a
`...`. That chunkname is forgeable: `loadstring(s, chunkname)` takes a
caller-controlled chunkname (arg 2) and compiles WITHOUT running, so
loadstring("return ...", "@Interface\AddOns\Victim\x")
__addonns("Victim") -- returned Victim's private table
armed the grant and leaked another addon's local table, with no
`## AllowAddOnTableAccess` opt-in.
Fix: arm the grant only when the loadbuffer call comes from the engine's
immediate-run file funnel FUN_00704AE0 (it pcalls the chunk right after
compiling, so the preamble consumes the grant before anything else runs).
The hook checks `_ReturnAddress()` against RET_LUA_FILE_COMPILE
(0x00704B11, the instruction after that funnel's `call luaL_loadbuffer`).
`loadstring` (FUN_00703280) and `RunScript` (FUN_00704C70) call from
different return addresses, so neither can arm — even a loadstring nested
inside a RunScript body that itself runs through the file funnel. The two
callers that DO reach 0x00704B11 (FUN_00704bc0 DoFile, FUN_00704cd0
inline-XML-script) both supply engine-built chunknames, not caller data.
Verified in-game: forged loadstring compiles but yields nil.
Also fix two lexer/scan bugs found in review:
- SkipNumber treated e/E as an exponent marker in hex literals, so
`0xE-1 % 2` lexed `0xE-1` as one token and rewrote to __mod(0xE-1,2)
(=1) instead of 0xE-(1%2) (=13). Hex literals now use p/P only.
- The addon-path marker matched a backslash separator only while its
own terminator scan accepted both; it now matches `addons\` or
`addons/`, consistent with addons/Embedded.cpp.
* refactor(addons,lua): dedup CI helpers, share TOC scan, table-driven toggles
Review cleanups, behavior-preserving:
- Drop the hand-rolled LowerAscii/EqualsCI copies in luasyntax/Transpile.cpp
and addons/LocalTable.cpp for `_stricmp`/`_strnicmp` (the codebase norm).
- Add addons/Toc.h `FindValue(buf, size, directive, ...)` — the `## Key:`
line-start scan in one place. Embedded.cpp (Version) and LocalTable.cpp
(AllowAddOnTableAccess) both consume it; the file-read stays per-caller
since Embedded's is entangled with its disk-vs-embedded decision.
- Collapse the six per-switch transpile toggle functions to a {name, bool*}
table plus one `_classicapi_SetTranspileOption(name, bool)` /
`_classicapi_GetTranspileOption(name)` pair (name = Length / Modulo /
VarargExpansion). Nothing outside Transpile.cpp referenced the old names.
* feat(addons): load multi-flavor addons via _Vanilla/_Classic TOC selection
Modern addons target several game flavors from one folder by shipping
`<Name>_Vanilla.toc` / `_Mainline.toc` / `_Cata.toc` / … and frequently no
plain `<Name>.toc`. Vanilla 1.12 only ever opens `<Name>\<Name>.toc`, so such
an addon never registers -- it is invisible, not merely mis-loaded.
Backport the retail client's flavor-file selection at the file-read layer.
The scan's TOC parser FUN_0051C9B0 reads Interface\AddOns\<Name>\<Name>.toc
via FUN_FILE_READ (0x00648620) and registers the addon only if that read
succeeds; the load pass and GetAddOnMetadata read the same path. We already
co-hook FUN_FILE_READ for the embedded addon, so FileRead_h now calls
AddOns::FlavorToc::TryHandle in its non-!!!ClassicAPI branch: for a base-TOC
read it probes <Name>_Vanilla.toc then <Name>_Classic.toc via the original
reader and serves the first that exists in place of the base (the parser
passes outSize=NULL, so it just forwards args with a different path).
Precedence mirrors retail: flavor wins over an existing base, and _Vanilla
beats _Classic. Does NOT fall back to _Mainline/_Cata/etc -- an addon shipping
only those doesn't support vanilla and stays unlisted. Folder enumeration
already lists flavor-only folders, so only the TOC read needed redirecting.
Verified in-game: a folder with only FlavorTest_Vanilla.toc registers and
loads; GetAddOnInfo returns the _Vanilla title/notes.
* feat(addons): prefer _Turtle.toc flavor on Turtle-lineage clients
Extend multi-flavor TOC selection with a _Turtle.toc suffix, a ClassicAPI
extension (not a retail flavor) for addons targeting Turtle's server content.
Probe order becomes _Turtle -> _Vanilla -> _Classic, with _Turtle offered
first and only when Turtle::Detected() is true, so stock 1.12 never prefers
Turtle-only code.
The redirect fires at both the registration scan (glue/char-select) and the
in-world load pass, which must select the same flavor -- so detection has to
read consistently at glue-scan time and in-world. The in-world signal
(TURTLE_WOW_VERSION, engine-set) is absent on the glue state, so Turtle::Detect
now also recognizes Turtle's glue-time TURTLE_* GlueXML string globals
(AUTH_TURTLE_WEBSITE / TURTLE_ARMORY / TURTLE_KNOWLEDGE_DATABASE, set in
GlueStrings.lua at glue boot, before the scan). Clones keep those names and
only rebrand the URL values, so name presence is clone-robust where realmList
is not. Detected() now latches on either signal and works in both states;
Version() still fills from TURTLE_WOW_VERSION once in-world.
Verified in-game: a folder shipping only FlavorTest2_Turtle.toc registers and
loads on Turtle (GetAddOnInfo returns the _Turtle title), while the earlier
_Vanilla-only test still works.
* feat(addons): narrow flavor TOC selection to _Turtle + _ClassicAPI
Drop `_Vanilla`/`_Classic` from the flavor probe list. Those are the 1.15
Classic Era client's suffixes -- a modern engine with the full modern API and
modern FrameXML templates. Adopting them told a multi-flavor addon "I'm 1.15",
so its `_Vanilla` build would assume APIs/templates this 1.12 + partial-backport
client doesn't fully have, load, and then break. A clean non-load is better.
Select only the two flavors that describe THIS environment, most specific first:
_Turtle -- Turtle client/content, only when Turtle::Detected();
_ClassicAPI -- 1.12 + ClassicAPI, always (ClassicAPI is present by
definition -- it is the code doing the redirect).
Both are ClassicAPI conventions the addon author opts into, not an attempt to
impersonate a retail flavor. If neither exists, TryHandle returns false and the
caller does the normal base read, which chains through any other FUN_FILE_READ
hooker before reaching the engine.
Verified in-game: a folder with only `<Name>_ClassicAPI.toc` registers/loads; a
`_Turtle`-only folder registers on Turtle; a `_Vanilla`-only folder no longer
registers (correctly, now that `_Vanilla` is not a selected flavor).
* feat(addons): backport per-line TOC directives (conditions + variables)
Single-TOC multi-flavor addons gate individual file-reference lines and
expand path variables:
[Family]\Init.lua -> Classic\Init.lua
Vanilla.lua [AllowLoadGameType vanilla] kept
Mainline.lua [AllowLoadGameType mainline] dropped
Localization\[TextLocale].lua -> Localization\enUS.lua
Vanilla 1.12's TOC readers understand none of it: the scan parser
FUN_0051C9B0 only parses `##` metadata, and the load pass FUN_006edb90
hands each file line to FUN_006ede10 verbatim, where a trailing ` [...]`
breaks the extension check so the file silently never loads.
New module AddOns::TocRewrite rewrites the TOC buffer at the FUN_FILE_READ
chokepoint (alongside FlavorToc/Embedded), so the engine's own load loop
sees clean paths and both parsers are covered by one edit.
On this client the tokens resolve to: [AllowLoadGameType] keeps iff the
list has `vanilla`; [AllowLoadTextLocale] keeps iff it has the client
locale; [AllowLoad] keeps `game` and drops `glue`; [Family]->Classic,
[Game]->Vanilla, [TextLocale]->the client locale code. Locale comes from
VAR_LOCALE_NAME_TABLE (0x008558A4), the exact source Script_GetLocale
reads, so it matches GetLocale() byte-for-byte.
Gated to ...\AddOns\...\*.toc reads (a .lua `t[1]` would otherwise be
mangled); bracket-free TOCs stay zero-copy via a memchr bail; a rewritten
TOC goes into a fresh Storm buffer the engine frees like its own. Unknown
conditions fail safe (drop the line); gated-out lines become `#` comments.
Verified in-game on Turtle: 8 keep-cases loaded, 4 drop-cases (bare
mainline, glue, deDE, unknown keyword) did not.
* docs: document the branch's Lua 5.1 and TOC compatibility features
User-facing docs for the feat/lua-syntax-transpile branch.
docs/API.md:
- New "Lua 5.1 syntax: length, modulo, and vararg" section: the source
rewrite for `#`, `%`, and `...`-as-expression; what each form becomes
(`#` = border, ignores table.setn; `%` = 5.1 sign-of-b, contrasted with
math.mod); the `local name, tbl = ...` addon-args idiom; limits
(string/comment safety, first-close long-bracket matching, preserved
line numbers) and the diagnostic kill-switch.
- New "getfenv / setfenv environment protection" section: the 5.1
`__environment` metatable field, with the `__fenv` fallback noted.
- New "Conditional and multi-flavor TOC loading" section under AddOns:
`_ClassicAPI` / `_Turtle` flavor file selection and per-line
`[AllowLoadGameType]` / `[AllowLoadTextLocale]` / `[AllowLoad]`
conditions and `[Family]` / `[Game]` / `[TextLocale]` path variables,
with the token resolution table and limits.
- Table-of-contents entries for all three.
README.md:
- Add C_AddOns.GetAddOnLocalTable to the AddOns calls row (was missing).
- Add three rows to the Behaviors table (Lua 5.1 syntax, Lua 5.1
environment protection, multi-flavor & conditional TOC loading), each
linking to its API.md section.
* feat(addons): accept multi-flavor `## Interface:` version lists
A retail TOC can list several interface versions on one line
(`## Interface: 120100, 50504, 38002, 20506, 11200`). Vanilla's parse is a
plain atoi (FUN_0064ade0) that reads only the first number into entry+0x1C,
and the loadability resolver FUN_0051e780 compares that to the client
version FUN_0051d7d0() (0x2BC0 = 11200): a mismatch is the OUT_OF_DATE
reason that blocks loading while checkAddonVersion is on. So a list whose
first entry isn't 11200 never loads even when 11200 appears later in it.
TocRewrite now special-cases the `## Interface:` line: parse the whole
list, and if the client version (read live via
FUN_ADDON_CLIENT_INTERFACE_VERSION, not hardcoded) is present but not
first, rewrite the value to that single number so the engine stores 11200
and marks the addon compatible. A list without 11200 (or already leading
with it) is left verbatim, so it stays out of date exactly as before. The
fast-path gate widened to `[` or `,`; the content-compare bail keeps
comma-bearing TOCs (e.g. `## Dependencies: A, B`) zero-copy.
Docs (API.md, README.md) describe the behavior and the 11200-only
compatibility rule.
Verified in-game on Turtle: GetAddOnInfo on an addon listing
120100,50504,38002,20506,11200 returned no reason (loaded); the ...,11509
control returned INTERFACE_VERSION (out of date).
* feat(addons): honor ## LoadSavedVariablesFirst
Modern addons use `## LoadSavedVariablesFirst: 1` so their SavedVariables
are restored before their Lua runs, letting file-scope code read config.
Vanilla always runs an addon's files first, then loads SavedVariables,
then fires ADDON_LOADED (verified in FUN_0051f240), and never parses the
directive — so file-scope SV is always nil.
New module AddOns::SavedVarsFirst co-hooks the per-addon file loader
FUN_ADDON_LOAD_FILES (FUN_006edb90). For an addon whose TOC declares the
directive, it loads the SavedVariables first, mirroring the engine's own
path construction two steps later:
account : WTF\Account\<account>\SavedVariables\<Name>.lua
per-char: WTF\Account\<account>\<realm>\<character>\SavedVariables\<Name>.lua
(falling back to the realm-less path)
account = *VAR_ACCOUNT_NAME_PTR, realm = FUN_GET_REALM_NAME, character =
FUN_GET_LOGIN_ACCOUNT_NAME (whose offset label is a misnomer — it is the
character name). Then it calls the original so the files run with SV
present. FUN_FILE_EXISTS picks the same per-char variant the engine would;
FUN_LUA_LOAD_FILE no-ops on a missing file.
v1 caveat (documented): the engine still runs its own SV load right after
the files, so a file-scope READ works but a file-scope WRITE is overwritten
before ADDON_LOADED. Writes belong in an ADDON_LOADED handler, as usual.
Docs: API.md "SavedVariables loaded first" + a README behaviors row.
Verified in-game on Turtle (login -> /reload): flagged SVFirst saw its DB
at file scope (sawAtFileScope=true), control SVNormal did not (false).
* feat(addons): suppress the redundant SavedVariables re-load (LoadSavedVariablesFirst v2)
v1 loaded a flagged addon's SavedVariables before its files, but the engine
still ran its OWN SV load right after the files — overwriting any value the
addon wrote to its SavedVariable at file scope before ADDON_LOADED.
v2 co-hooks FUN_LUA_LOAD_FILE and skips that one redundant re-load per
pre-loaded path: RunLuaFile loads each SV via the trampoline (bypassing the
hook) and records its full path; LuaLoad_h matches the engine's imminent
FUN_00704bc0(svPath, 0, 0) (case-insensitive, one-shot erase) and returns 0
without loading. The SV-load call sites ignore the return and the SV file
feeds nothing into the TOC checksum, so the skip is side-effect-free.
FUN_00704bc0 loads files only (RunScript runs strings through a different
path), so the extra hook is a cold addon-load-time path.
Now file-scope reads AND writes both survive — matching true
LoadSavedVariablesFirst. Docs (API.md) drop the write-clobber caveat.
Verified in-game on Turtle (fresh SavedVariables, repeated /reload): flagged
SVFirst's file-scope write persists (runs counter climbs 2, 3, 4), control
SVNormal stays 1.
* feat(addons): flavor-specific addon Bindings (Bindings_Turtle/_ClassicAPI.xml)
The Bindings.xml analog of FlavorToc. A modern addon may ship a
flavor-specific keybinding file instead of / alongside a plain
Bindings.xml. Vanilla only ever builds Interface\AddOns\<Name>\Bindings.xml,
gates it on an exists-check (FUN_00648a30), and — only then — loads it via
FUN_004b6f70, which reads through FUN_FILE_READ. So flavor selection needs
two pieces (a FileRead redirect alone can't help a flavor-only addon,
because the exists-check is on the base name):
- AddOns::FlavorBindings::TryHandle, called from the FUN_FILE_READ hook
after FlavorToc: for a …\AddOns\<Name>\Bindings.xml read, serve a flavor
variant if present (flavor wins over a plain Bindings.xml). Probe order
Bindings_Turtle.xml (Turtle only) -> Bindings_ClassicAPI.xml.
- A co-hook on FUN_FILE_EXISTS: report Bindings.xml as existing when the
base is absent but a flavor variant is present, so the loader runs for a
flavor-only addon. Non-Bindings paths pass straight through.
Suffixes are _Turtle / _ClassicAPI, never _Vanilla / _Classic (a _Vanilla
bindings file pairs with the 1.15 build we don't load, so its handlers
wouldn't exist). Docs: API.md flavor section + README behaviors row.
Verified in-game: on Turtle all three cases load (flavor-only ClassicAPI,
flavor-only Turtle, flavor-over-base with the flavor winning); on stock the
Turtle-only one correctly drops while the ClassicAPI ones still load.
* feat(lua): backport 5.1 hexadecimal number literals via source transpile
Lua 5.0's lexer reads only decimal digits + one '.' + 'e' exponent, so a
`0x...` literal is a compile error (hence addons resort to
`tonumber("0x...", 16)`). Lua 5.1 added hex literals. As with `#` / `%` /
`...`, we rewrite the SOURCE at the luaL_loadbuffer chokepoint: each hex
INTEGER token becomes the exact decimal it denotes (unsigned), which 5.0's
lexer accepts and reads as the same double 5.1 would.
RewriteHex runs first in the transpile pipeline, gated on a "0x"/"0X"
presence scan; it reuses the tokenizer (so strings/comments are never
touched) and inserts no newlines (line numbers preserved). Hex floats
(0x1.8p3) and > 64-bit literals are left as-is — vanishingly rare, and they
fail exactly as today (no regression). Also fixed SkipNumber to stop a
number at a `..` so `0xFF.."x"` (hex then concat) tokenizes cleanly.
Toggle: _classicapi_SetTranspileOption("HexLiterals", false).
Docs: API.md "Lua 5.1 syntax" section + README behaviors row.
Verified in-game (19/19 harness asserts) and cross-checked against retail:
0xFF->255, 0xFFFFFFFF->4294967295, bit.band(0xF0,0x0F)->0, "0xFF" untouched
all match modern WoW exactly.
* feat(frame): enable modern positional script args by default
Modern handler signatures — `function(self, delta)` / OnEvent
`(self, event, ...)` — are core Lua 5.1 behavior, so flip Frame::ScriptArgs
on by default instead of opt-in. Ports that use them now work with no
`SetModernScriptArgs(true)` call.
It's purely additive (the `this`/`arg1`/`event` globals are still set, so
vanilla-style handlers keep working). `SetModernScriptArgs(false)` remains
the escape valve — it reimplements the tail of the engine's hottest Lua
path (fires for every OnUpdate frame), and disabling it makes both runners
a straight passthrough to exact vanilla dispatch.
Docs + code comments updated from "default OFF (opt-in)" to "default ON".
* docs: surface modern script-handler arguments as a behavior
Add a README Behaviors-table row for the now-default modern positional
script arguments (function(self, delta), OnEvent (self, event, ...)),
alongside the Lua 5.1 syntax row. The SetModernScriptArgs / GetModernScriptArgs
functions stay in the Frame calls table as the off-switch.
* fix(lua): correct transpiler lexer edge cases and operator env-independence
Review findings against the Lua 5.1 syntax transpiler:
- Tokenize `.`/`..`/`...` as multi-char tokens like Lua's own lexer, so a
`...` vararg adjacent to a `..` concat (e.g. `x .. ...`) is recognized
instead of forming an unsplittable five-dot run that left `...`
un-rewritten and failed to compile. Guard the `#`/`%` field-access check
to a single-char `.` so `a..b` isn't misread as `a.b`.
- Nest level-0 `[[ ]]` long brackets in SkipLongBracket to match the engine's
own long-string reader (FUN_00700010 keeps a nesting counter). First-close
matching mis-identified nested-string boundaries and could rewrite `#`/`%`
bytes the parser treats as string content.
- Capture `__len`/`__mod`/`unpack` as chunk-locals in the load-time preamble
so the lowered `#`/`%`/`...` operators resolve under a setfenv sandbox with
no _G fall-through, mirroring real 5.1's environment-independent operators.
- Skip precompiled bytecode (0x1B chunk signature) instead of tokenizing it
as source and corrupting the chunk.
- Cap parse recursion at 200 (Lua's LUAI_MAXCCALLS) so a pathologically
nested chunk fails to compile cleanly instead of overflowing the C stack
inside the hook.
- Case-fold the addon-namespace map key in PushAddonNamespace so a
case-mismatched C_AddOns.GetAddOnLocalTable request lands on the addon's
real table instead of minting a fresh empty one.
The `.. ...` vararg and nested-long-bracket fixes verified in-game via
_classicapi_TranspileLength.
* fix(addons): gate LoadSavedVariablesFirst pre-load on the declared scope
LoadSavedVarsEarly chose which SavedVariables files to pre-load from file
existence alone, but the engine loads the account file only when the addon
declares `## SavedVariables` and the per-char file only when it declares
`## SavedVariablesPerCharacter`. So a stale file for a scope the addon no
longer declares got executed early (Lua the engine never runs) and queued in
g_pendingSuppress, which the engine then never drained — a leak of one entry
per stale file per /reload.
Mirror the engine: read the TOC once (ReadSvFlags, replacing
TocWantsSavedVarsFirst) for the reorder flag plus whether each SV scope is
declared, and load each file only when its directive is declared and the file
exists. Every suppress entry we queue is now a file the engine re-loads and
drains.
* fix(turtle): only trust glue markers on the glue Lua state
Probe() checked the `TURTLE_*` glue markers whenever detection wasn't yet
latched, on whatever Lua state was current — including in-world. Those names
are set by Turtle's GlueXML and are only trustworthy on the glue state; in
world any loaded addon can define a global by one of them (a Turtle-UI port
shipping the strings, say), which permanently mis-latched Turtle detection on
a stock client and skewed flavor TOC/Bindings selection for the session.
Gate the marker probe on a `g_onGlue` phase flag driven by the engine's own
per-state script-registration hooks: the in-world ModuleAutoRegister (fires
before the addon load pass) clears it, each glue boot's GlueModuleAutoRegister
sets it. Neither reads a forgeable Lua global. Turtle still detects via the
markers at the glue scan and via TURTLE_WOW_VERSION in-world; a stock client
can no longer be latched by an in-world global.
Also make Version() return nullptr (not "") in the glue-detected-but-no-version
window, matching the header contract.
* revert MAX_CLASSES
* fix(frame): only pass positional script args to handlers that declare them
Default-ON modern script args changed behavior for every handler on the
engine's hottest Lua path, and the docs' "purely additive" claim was wrong:
a handler that DECLARES a parameter received a real value where vanilla always
passed nil.
Gate the reimplemented positional path on the handler's arity: a Lua closure
that declares a parameter or is vararg (function(self, delta) / function(self,
...)) takes it; a param-less handler (the vast majority of vanilla handlers,
which read this/arg1 globals) and a C-closure handler tail-call the original
engine runner unchanged. So param-less handlers are provably identical to
vanilla AND off the hot path (also the efficiency win: OnUpdate handlers that
gain nothing no longer pay the modern tail every frame). Only param-declaring
handlers observe the (self, [event,] arg1..N) shape.
Arity is read from the handler's Proto; offsets verified against the engine's
own luaD_precall (numparams @ +0x45, is_vararg @ +0x46), lua_dump, and
lua_iscfunction/lua_tocfunction (closure @ TValue+8, isC @ +6, Proto @ +0xC).
The param-declaring-vanilla-handler case (a function reused as both a direct
call and a handler) is inherently ambiguous and still gets the value; documented
honestly in ScriptArgs.cpp, docs/API.md, and README with SetModernScriptArgs
(false) as the opt-out. Verified in-game across both runners, both paths, the
toggle, and the caveat.
* refactor(addons): centralize engine-IO typedefs and CI string helpers
The `__stdcall` FUN_FILE_READ / FUN_FILE_EXISTS / Storm-allocator function
types were copied into ~8 places across the addon files, and Lower/EqCI into
three. These are ABI-critical: a copy declared __cdecl by mistake drifts ESP
per call and kills the process with no crash log. Hoist them to one home:
- new addons/EngineIO.h — FileReadFn / FileExistsFn / SMemAllocFn / SMemFreeFn,
used by Embedded, FlavorToc.h, FlavorBindings.h/.cpp, SavedVarsFirst,
LocalTable, TocRewrite.
- addons/Toc.h gains Lower / EqCI, used by FlavorBindings, SavedVarsFirst,
TocRewrite.
Also drop EvalCondition's dead `known` out-parameter in TocRewrite (nothing
read it — an unknown keyword already returns false). Pure refactor, no behavior
change.
* perf(lua): tokenize each chunk once and gate the #/% parse on an operator token
The transpiler ran on every compiled chunk at login/reload, and:
- RewriteHex / RewriteVararg / RewriteAll each re-tokenized the whole chunk, so
a file that trips more than one pre-check was lexed two or three times;
- RewriteAll's fast-bail was a raw memchr for '%', which is present in nearly
every chunk via format strings ("%d"), so almost every chunk paid a full
recursive parse only to discard an empty edit list.
New RunPasses tokenizes once and shares the stream across the passes, re-lexing
only after a pass actually rewrites the buffer (rare). RewriteAll now gates the
parse on an actual '#'/'%' OPERATOR token — a '%' inside a string is a TK_STRING
token, not a punct, so the format-string case skips the parse entirely.
RunPasses also unifies the previously duplicated RewriteChunk / LoadBuffer_h
pipelines. Output is identical (verified in-game via _classicapi_TranspileLength:
vararg-next-to-concat, nested long brackets, and a format-string vs operator '%'
all rewrite exactly as before).
* feat(lua): backport 5.1 leveled long brackets; fix top-level vararg fallback
Adversarial testing of the transpiler surfaced two gaps beyond PR 28:
- Leveled long brackets ([=[ ]=], [==[ ]==]) are the one 5.1 syntax
construct still missing. The 5.0 engine lexer has no =-level handling
(verified in FUN_006ff610), so they fail to compile. A new source-walking
pre-pass rewrites a leveled long string to [[body]] when the body is safe
(byte-exact, keeps the leading-newline strip) or to a quoted literal with
\-newline continuations otherwise, and blanks leveled long comments to
spaces. Line numbers preserved. Gated by the new LongBrackets toggle.
- Top-level ... outside the addon file funnel (RunScript, XML <OnLoad>,
loadstring) expanded to unpack(arg) and threw on nil arg, where 5.1
yields nothing. Non-addon vararg chunks now get a local arg={n=0}
fallback.
Adds a /capitranspile self-test suite (19 cases, all passing in-game) and
updates docs/API.md (also fixing a stale limits note that described plain
long strings as non-nesting: they nest by depth, matching the engine) and
README.
Fires (no payload) when any equipped item's durability changes -
combat damage, death, repairs - via a co-hook on the engine's
inventory-alerts recompute (FUN_004C7EE0, the routine behind vanilla's
UPDATE_INVENTORY_ALERTS). The engine calls it whenever an owned item's
fields change (the item post-update handler FUN_005D9A90 routes every
item values-update through it) plus equip/enter-world paths, so it is
the engine's own durability-may-have-changed signal. Post-original we
diff a per-slot {itemGuid, durability} snapshot and fire once per
recompute with a real change - a death dinging all armor produces one
event, not nineteen.
The snapshot seeds silently on the first recompute of the process and
is deliberately NOT re-seeded per enter-world: death/release/graveyard
teleports re-run the setup, and a per-setup reset swallowed the
death's own durability loss (verified in-game; repairs fired, deaths
didn't until this was fixed).
Dead end, kept documented at OFF_DESC_ITEM_DURABILITY: bank-1 (ITEM
field) descriptor observers register without error but are never
invoked - item values-updates demonstrably arrive and player-bank
observers fire in the same session; registration arithmetic fully
verified (bank base FUN_00465690(1)=0x18, bank walk item 0->1->2).
Prime suspect is the registrar's internal wrapper lookup
(FUN_00464890, the observer registry, distinct from the object
manager) silently no-op'ing for item objects.
Also in Player::Equipment: resolve the player via the non-throwing
GUID resolver (FUN_00468460, what the engine's own bag observer uses)
instead of FUN_RESOLVE_UNIT_TOKEN, which raises a Lua error when the
token doesn't resolve - unsafe inside SMSG_UPDATE_OBJECT processing
where the player can be mid-create.
The earlier investigation tried to hook a firer of
UNIT_INVENTORY_CHANGED; none of the three known 0xBA fire sites
trigger on equip because equipment descriptor writes are silent — the
engine registers descriptor-field observers (the __AUCMirrorHandler__
system: registrar 0x00467E70, dispatcher 0x00465570 with per-node
mirror + memcmp change detection) for the bag/backpack/bank/keyring
GUID ranges but never for equipment 0x4A8..0x538.
So register our own: co-hook the engine's inventory observer setup
(FUN_004F8CC0, once per enter-world) and, post-original, register one
observer per equipment GUID field through the engine's registrar —
same bank/size/GUID shape as the engine's bag observers, engine-
managed lifetime, no polling, no hot-function hook. The dispatcher
invokes us only on a real change.
Callback ABI verified from the dispatcher call site at 0x004655DC and
the engine callback FUN_004F8DB0's RET 0x10:
__fastcall(fieldOffset /*ecx*/, size /*edx*/, guidLo, guidHi,
oldValue*, userArg) -> ret 0x10
equipmentSlot is the 1-based Lua inventory slot (1 head .. 19 tabard);
hasCurrent (1/nil) is read from the player invMgr GUID array — the
same post-change truth the engine's bag observer reads.
Vanilla GameTooltip:AddLine silently drops any line past the 30
TextLeftN/TextRightN FontStrings the FrameXML template declares, so
stat-heavy tooltips (pfUI eqcompare, AtlasLoot) lose their tail.
Tooltip::LinePool co-hooks the tooltip's XML-OnLoad region scan
(FUN_00529650, CGameTooltip vtable slot 9) via HookAutoRegister. After
the engine sets up the template's 30 lines it creates TextLeft/Right
31..60 in C++ (alloc from the CSimpleFontString pool -> ctor(parent) ->
name -> font copied from the previous line -> anchor) and appends each
pair to the tooltip's three line arrays, bumping numLinesAllocated. Runs
once per GameTooltip-family frame at creation and per /reload, so it
auto-covers GameTooltip, ShoppingTooltip1/2, ItemRefTooltip, AtlasLoot,
WorldMapTooltip, etc. No addon Lua and no per-line AddLine hook.
SetPoint stores offsets in internal coordinates, not pixels, so the
anchor offsets are scaled the way Script_SetPoint does
(pixel * [0x00832A44] / ([0x00832A4C] * 1024)) — without that a -2px gap
rendered ~3950px off.
Adds the tooltip line-pool, FontString-creation, and UI-scale offsets to
Offsets.h; documents the behavior in the README and marks TODO #97 done.
Cast/channel info for the local player with full timing, plus channel
spellID/name/texture for any unit. Vanilla stores no cast times anywhere
readable (confirmed via the cross-binary technique: 3.3.5 reads them from
per-unit CGUnit fields that don't exist in 1.12), so the player's
cast/channel start/end are self-tracked on WorldTick:
- cast: VAR_CURRENT_CAST_SPELL 0->nonzero transition stamps startMs = now
(FUN_OS_TICKCOUNT_MS) and endMs = now + effective cast time. The cast
time comes from the engine's own helper FUN_006e3340 (base + level
scaling + cast-time SpellMod op 10 + the caster's haste/cast-speed
multiplier), the same one the engine cast-start uses -- so end time
matches the cast bar, e.g. a talented Frostbolt reads 2.5s not 3.0s.
Instant casts (cast time 0) and channels are filtered out.
- channel: player's broadcast UNIT_FIELD_CHANNEL_SPELL (+0x228),
endMs = now + SpellDuration base ms.
FUN_OS_TICKCOUNT_MS shares GetTime()'s epoch (x0.001), so startMs/endMs
feed addon progress math directly. Other units: channel info from the
broadcast +0x228 field (no times, since per-unit start isn't tracked);
regular casts return nil (no vanilla data -- remote casts are transient
spell-visual objects, not a queryable record).
isTradeskill is real: the spell's SPELL_ATTR_TRADESPELL flag (Attributes
bit 0x20). Remaining placeholders: castID/castBarID nil, notInterruptible
false, delayTimeMs 0.
Verified in-game: Blizzard channel 8s, Conjure Food cast 3s, talented
Frostbolt 2.5s, correct icons/spellIDs, GetTime()*1000 between start/end;
isTradeskill true for Rough Blasting Powder (Engineering).
Docs: API.md sections + README Spell row; TODO #68 marked done.
GetSpellRadius now returns (baseRadius, modifiedRadius). modifiedRadius
applies the local player's talent/item radius modifiers; equal to base
when no modifier matches.
The modifier logic is extracted into a reusable Spell::Mod helper
(src/spell/Mod.{h,cpp}) since the same engine SpellMod mechanism drives
cast time, mana cost, duration, range, cooldown, etc. — only the op
differs. Spell::Mod::Apply(spellRecord, op, base) replicates
FUN_006e6b30/FUN_006e6bf0: gate on the spell's SpellFamilyName matching
the player's class family (ChrClasses.dbc[class]+0x3c), sum the player's
flat/percent tables (0x00CEAD60 / 0x00CECB30, stride 0x74) over the
spell's 64-bit SpellFamilyFlags, then (base + flat) * (100 + pct) * 0.01.
Inherently local-player-only — the client tracks spell mods for the
player alone.
Offsets: VAR_SPELLMOD_FLAT/PCT_TABLE, SPELLMOD_SLOT_STRIDE/COUNT,
SPELLMOD_OP_RADIUS, OFF_SPELL_RECORD_FAMILY_NAME/FLAGS/ATTRIBUTES_EX2,
SPELL_ATTR_EX2_NO_SPELL_MODS, OFF_CHRCLASSES_SPELL_FAMILY.
Verified in-game: Frost Nova (10230) -> (10, 10) without Arctic Reach,
(10, 12) with rank 2 (+20%). op 6 = radius confirmed via FUN_006e6350;
percent constant 0.01 confirmed from .rdata.
C_Spell.GetSpellRadius(spellID) plus the vanilla-positional
GetSpellRadius(slot, bookType). Returns the spell's AOE radius in yards,
or nil for a non-AOE spell.
Radius is per-effect: Spell.dbc EffectRadiusIndex[3] at record +0x160
(verified via FUN_006e6350, which reads spellRec[+0x160]/[+0x164] for
effects 0/1), each resolving into SpellRadius.dbc (records 0x00C0D7B0,
count 0x00C0D7B4; base radius f32 at record +0x04). Returns the largest
base radius across the three effects. Base radius only — no caster-level
scaling, matching modern GetSpellRadius.
Dual signature mirrors SpellHasRange/GetSpellInfo: namespaced form takes
a spell identifier, the bare global takes a (slot, bookType) spellbook
position (bookType "pet" -> pet book, else player book).
Docs: API.md section + README Spell row; TODO #38 marked done.
True if the spell is currently being cast, queued mid-GCD, or
channeled by the player. Reads three engine slots and returns true
on any match:
VAR_CURRENT_CAST_SPELL (0x00CECA88) — cast bar; written by the
cast-start helper at FUN_006E4AD0, read by FUN_006E3D30's
is-currently-casting check (which Script_SpellStopCasting
consults before sending CMSG_CANCEL_CAST).
VAR_QUEUED_CAST_SPELL (0x00CECAA8) — the spell pushed aside when
a new cast superseded it mid-GCD; restored to current when the
new cast ends. Covers the "queued to cast next" half of
modern's documented semantics.
UNIT_FIELD_CHANNEL_SPELL (player descriptor +0x228) — channels
(Fishing, Drain Soul, Ritual of Summoning, etc.).
Accepts the full spellIdentifier shape via Spell::Arg::ResolveSpellID
(number / |Hspell:N|h link / known-spellbook name). Closes TODO #32.
Modern table-shape cooldown query. Accepts spellID (number),
spell name (with optional (Rank N) suffix), or |Hspell:N|h
hyperlink. Returns a SpellCooldownInfo table:
{ startTime, duration, isEnabled, modRate }
or nil for spellIDs without a Spell.dbc row. modRate is hard-coded
to 1.0 (vanilla has no haste-on-cooldown mechanic); the
post-vanilla fields (activeCategory, timeUntilEndOfStartRecovery,
isOnGCD) are left unset.
Reads the engine's per-spell cooldown manager via
FUN_SPELL_QUERY_COOLDOWN (0x006E2EA0). Fixed the
(*outDuration, *outStart) argument order while doing this — the
typedef in Spell::Usable had it as (*outStart, *outDuration), which
worked accidentally because both fields are 0 when no cooldown is
active, but produced swapped values when a cooldown was running.
Round-tripped against Blink (1953) to verify the corrected order.
Sibling to UnitClassBase. Reads byte 0 of UNIT_FIELD_BYTES_0
(descriptor +0x78) and looks up ChrRaces.dbc::Filename for the
locale-independent token. Returns (raceFile, raceID): "Human"/1,
"Orc"/2, "Dwarf"/3, "NightElf"/4, "Scourge"/5, "Tauren"/6,
"Gnome"/7, "Troll"/8.
Obviated by C_UnitAuras. The slot system was a Shadowlands-era
continuation-token pattern for huge aura sets — irrelevant on
vanilla's 48-slot cap, where GetUnitAuras returns all of them in
one call. The Util/Aura.lua and Util/AuraUtil.lua files the original
TODO referenced are also gone from the repo.
The single addon driving the C_CharacterList.* bindings moved off
them; keeping the engine-hook surface live for a feature nobody
calls is dead weight. Snapshot record layout, hook target, and the
"why memory-only" rationale all land in TODO #95 so another DLL
can pick it up without re-deriving any of it.
Replaces the planning writeup with a short summary of what landed:
final API, storage location, the three infrastructure pieces (glue hook,
GlueModuleAutoRegister, Settings::Account), and the misnamed-offset
note for future callers.
Six functions matching the retail namespace:
- GetItemInfo(slot) reads the 28-byte merchant entry directly.
- GetBuybackItemID(slot) walks buyback storage → player invMgr →
CGItem instance block. No GetBuybackItemLink roundtrip.
- GetNumJunkItems / SellAllJunkItems iterate bags via the existing
ResolveBag helper and read quality from the ItemStats cache.
- IsMerchantItemRefundable / IsSellAllJunkEnabled stub to false /
true to match retail's API contract in a version that has no
refund mechanic or sell-junk-disabled setting.
SellAllJunkItems calls the engine's internal MerchantSellItem
dispatcher (CMSG_SELL_ITEM) directly rather than going through
Script_UseContainerItem. The dispatcher uses an irregular fastcall
(count in ECX, four stack args, EDX ignored); a dummy EDX in the
typedef forces MSVC to lay the args out the callee expects.
Sells are deferred one per frame via the shared WorldTick
subscriber. Burst-sending 10 CMSG_SELL_ITEM packets in one frame
consistently dropped the 2nd-to-last sell (verified empirically).
Spreading them across frames matches the cadence of click-by-
click selling.
GetNumJunkItems also returns 0 away from a merchant frame to
match retail's contract — the count is meant as a "what would the
sell button do right now" signal, not a passive inventory query.
Includes a small refactor: factored GUID→CGItem resolution out of
EquipmentSet::Locations into Item::Location::ResolveByGUID so it's
shared cleanly between modules, and renamed VAR_MERCHANT_FLAG_A/B
to VAR_MERCHANT_NPC_GUID_LO/HI now that the semantic is decoded.
Cursor-clearing-when-holding-junk left as TODO #93.
C_Item.EquipItemByName (explicit slot) and C_EquipmentSet.UseEquipmentSet
now call the engine's own swap primitive directly. No cursor touch,
2-cycles resolve atomically in one server packet.