Commit Graph
6 Commits
Author SHA1 Message Date
Brues bb6df3556c feat(settings): retail Settings window, with Interface Options on top
Ports retail's Blizzard_Settings_Shared (Settings, categories, canvas and
vertical layouts, the setting controls, key binding rows, SettingsPanel,
SettingsInbound) as the one options window. Addons of both eras land in
it: newer addons register through the Settings API, and the 3.3.5
InterfaceOptions_AddCategory API (Ace3's AddToBlizOptions) now registers
a canvas category. Its panel protocol maps onto the window's: okay on
commit (Close, Apply, Escape), default and refresh where the window
calls OnDefault / OnRefresh, cancel only when the window closes without
a commit. A panel's name is its category ID, as Ace3 and newer addons
set it. The old InterfaceOptionsFrame* names alias the window's frames
so addons that restyle or overlay them keep working.

ClassicAPI's own pages are vertical layouts of Settings controls (cvar
and proxy settings, key binding rows, a ClassicAPI number box for
settings that take any number), so the window's search finds them. They
are the window's game categories, at the root of its first tab, which
reads ClassicAPI; addons go on the AddOns tab.

C_SettingsUtil.OpenSettingsPanel and NotifySettingsLoaded fire
SETTINGS_PANEL_OPEN and SETTINGS_LOADED through the engine's event
dispatcher (Event::Custom::FireValues), passing the category ID as
given. Also: slider:SetEnabled, Enum.BindingSet, C_CVar.GetCVar /
GetCVarDefault / RegisterCVar, C_KeyBindings.GetBindingIndex and its
two context answers, and retail's CvarUtil, BindingUtil, MinimalSlider,
DropdownWithSteppers and ColorPickerFrame:SetupColorPickerAndShow.

Engine changes the window needs:
- CVAR_UPDATE(cvarName, value) for every change of a cvar Lua can see,
  from a hook on CVar::Set (0x0063DF50). 1.12 fires CVAR_UPDATE only
  from Script_SetCVar with a caller's token. The change is queued and
  fired at the head of the next UI frame, never inside the setter: the
  engine sets cvars mid-way through its own work while a script runs
  further up the stack.
- Script SetParent (0x007A1550) shows a frame that is shown under a
  visible parent, as 3.3.5's CSimpleFrame::SetParent does; 1.12's
  (0x0076AB10) re-shows only a frame that was visible before. The key
  binding rows move their buttons onto an input blocker and back after
  the blocker is hidden.
- The child walks of the frame show (0x0076AE10) and hide (0x0076AD50)
  run on a copy of the child list and skip a child that has left. Each
  child runs its OnShow / OnHide inside the walk, and 1.12 (and 3.3.5,
  and 4.3.4) read the next node only afterwards, from a node a
  reparenting script may have freed. Auctionator's options page opens
  another page from its OnShow, and the window takes the first out of
  its canvas with SetParent(nil) while the canvas is being shown.

1.12 specifics in the port:
- ToggleGameMenu() without an argument is the Escape handler and can
  SpellStopCasting or ClearTarget, so closing returns to the game menu
  through ShowUIPanel(GameMenuFrame).
- StaticPopup_EscapePressed runs OnCancel(data, "clicked"), so button2
  is always the dialogs' no-op choice. Only Turtle's StaticPopup has
  button3 / OnAlt; stock 1.12 shows two buttons.
- The layout-cache reader (0x4905e0) replaces a movable or resizable
  frame's anchors and size from a saved record, so the window is
  neither: it has no drag or size handle.
- A $parent name under an unnamed frame takes the nearest named
  ancestor's name, so pooled rows avoid templates that anchor slices by
  name (UIPanelButtonTemplate2, InputBoxTemplate).
- GetChecked returns 1 or nil, GetBinding has no category, and
  GetBindingText is FrameXML Lua that needs the "KEY_" prefix.
- The slider rounds every value to its step in single-precision floats,
  and the rounding does not settle, so a value set from a setting does
  not report back as a change.
- Retail's Options and control atlases do not exist; the controls use
  1.12's checkbox, slider, dropdown and spellbook page arrows, the
  frames the tooltip backdrop.

Retail's strings are added in all eight locales. Not ported yet: the
Keybindings category.
2026-11-15 02:55:21 -06:00
Brues 05fa5845b7 feat(baselib): debuglocals, and the error window shows locals
debuglocals([level [, skipFunctionsAndUserdata]]) returns the locals and
then the upvalues of a call level as text, one name=value line each.

It runs only while an error handler runs, as in 4.3.4. 1.12.1's error
function sets no flag for that, but while a handler runs that function
(FUN_FRAMESCRIPT_CALL_ERROR_HANDLER) is a C closure level on the stack;
ErrorCallstack's search for it moves into a header so both modules use
it. level counts as lua_getstack and debugstack do.

Each local comes from lua_getlocal (0x6FBB20, fastcall L/ar + n), then
each upvalue of the level's function (lua_getinfo "f") from
lua_getupvalue (0x6F4660, fastcall L/funcindex + n). Values are
formatted as 4.3.4's FrameScript_PackVariable does, with retail's
spacing (probed: n=7, s="hi", t=<table>{ / k=1 / }): a frame table shows
its name, read from t[0] as FrameScript_GetObject does; a table's fields
show one space in at the top level only; a function shows where it is
defined (lua_getinfo ">nS"). The text stops at 4095 bytes. The second
argument, which retail's error handler passes as true, leaves out
function and userdata values.

Where 4.3.4 would fail inside the handler, this does not: a number key
outside int range is formatted from a copy, not converted in place
(which breaks lua_next), and a key that is not a number or string prints
as its type.

Retail also lists (*temporary) lines, 5.1's names for a level's stack
slots past its locals, including a C level's arguments. 1.12.1's
lua_getlocal is 5.0's and names declared locals only; those slots are
compiler registers that 5.0 and 5.1 allocate differently, so they are
not imitated.

The error window takes the locals as retail's GetErrorData does,
debuglocals(level, true) at the stack's level, and shows them under
Locals ("<none>" when there are none).

LuaCAPI.md had lua_pushupvalues, lua_getupvalue and aux_upvalue one row
off; corrected.
2026-11-03 15:04:55 -06:00
Brues bd1bd9f5d8 feat(aura): slot-batching API and lazy caster match
C_UnitAuras.GetAuraSlots / GetAuraDataBySlot / UnitAuraBySlot: enumerate a
unit's auras once into opaque slot ids and fetch each by id, so a full scan
walks the aura array once instead of once per index (the by-index getters
re-walk from slot 0 on every call). Slot ids cover live descriptor slots,
the stealth / range cache fallback, and the out-of-range group array, so
the slot path keeps every source the by-index path had.

GetAuraSlots also takes a table as a 5th argument (ClassicAPI extension)
and fills it in place, returning `continuationToken, n`. Lua 5.0 allocates
an `arg` table for EVERY vararg call (luaD_precall 0x006F6050 ->
adjust_varargs 0x006F6200 -> luaH_new, verified in Ghidra), so a Lua helper
receiving the retail multi-return costs one table per batch. The fill form
keeps per-frame scans allocation-free; AuraUtil.ForEachAura / FindAura use
it with a per-nesting-depth buffer pool instead of retail's vararg helpers.

The descriptor walkers (FindNthSlot, FindSlotBySpellID/Name, GetUnitAuras)
now evaluate IsPlayerCast only when the filter restricts on caster. It
scans the Aura::Source cache (~1000 entries in a raid) and was paid for
every populated slot on every call, PLAYER token or not.

Cache-fallback eligibility is centralized (EligibleFallbacks /
EligibleGroupFallbacks) so the by-index, bulk, and by-slot paths share one
ordering, which is the ordinal an opaque cache slot id encodes.
2026-09-02 16:19:31 -05:00
Brues 5f66e381d2 Restore Lua 5.0 coroutine.* library
Re-registers the standard five entries (create / resume / yield /
status / wrap) on the global `coroutine` table. The C-level
machinery (lua_resume, lua_yield, lua_newthread, threads as tag 8)
was always linked into the engine; only the script-side library
was stripped from the registration tables at build time.

Two WoW-specific quirks discovered along the way and worked
around:

- `lua_resume` returns 1 for BOTH yield and caught runtime error.
  Disambiguated by checking `co->ci > co->base_ci` — a yielded
  coroutine still has its body frame on the call stack; an
  errored one has been unwound to base_ci.

- The byte at L+0x31 is `allowhook` (saved/restored around
  protected calls), not `L->status` as it initially looked.
  Status reading is replaced by the ci comparison above.
2026-06-04 16:23:55 -05:00
Brues bef40ab877 hooksecurefunc 2026-05-10 14:24:46 -05:00
Brues 8216df4193 Lua C API doc 2026-05-07 16:28:32 -05:00