WeirdUtils/src/minimapicons/RESEARCH.md

MinimapIcons Research

SavedVariables -- Addon Registration System

Problem

DLL-embedded addons are served via loadFileDetour (hook on LoadFileWithTextureResourceFallback at 0x648620). The game reads our embedded .toc and .lua files successfully, but SavedVariablesPerCharacter never persists to disk. The addon's toggle state resets every session.

Root Cause

The game discovers addons by scanning Interface\AddOns\ on the filesystem via EnumerateDirectoryWithCallback. Since our addon has no real directory on disk, ProcessAddonFilePath is never called, LoadAddonTOC never runs, and the addon is never registered in the internal addon hash table. Without registration, the save system has no record of which variables to persist.

The addon's .lua code still runs (served via loadFileDetour), but it's loaded through a different path -- loadFileListWithIncludes reads the TOC file list and loads each .lua/.xml, all of which go through our hook. The disconnect is that LoadAddonTOC (which parses ## SavedVariablesPerCharacter and registers the variable names) only runs during the directory-scan phase.

Addon Loading Sequence

HandleLogin (0x0046afb0)
  -> SetupAddonProcessing (0x0051c740) -- __fastcall(ECX=mgr_ptr), RET
    -> ShutdownAddonSystem (0x0051fa40) -- clears old state
    -> ProcessAddonDirectory (0x0051c760) -- filesystem scan
      -> EnumerateDirectoryWithCallback("Interface\\AddOns\\", ...)
        -> ProcessAddonFilePath (0x0051c910) -- per .toc file found
          -> LoadAddonTOC (0x0051c9b0) -- parses TOC, registers addon in hash table
                                        -- reads TOC via LoadFileWithTextureResourceFallback (hookable!)
  -> [our hook: callLoadAddonTOC per non-hidden embedded addon]

InitializeGameInterface (0x0048fbf0)
  -> LoadAddonSavedVariables (0x0051ebe0) -- loads WTF/.../AddOns.txt (enabled/disabled state per addon)
  -> LoadAddonsRecursively (0x0051f600) -- iterates registered addon list
    -> LoadAddonRecursive (0x0051f242) -- per addon:
      1. loadFileListWithIncludes() -- loads TOC file list (.lua/.xml)
      2. Loads Bindings.xml via preloadFileWithFlags (does NOT go through our file hook)
      3. Loads WTF/Account/<acct>/SavedVariables/<name>.lua (account-wide)
      4. Loads WTF/Account/<acct>/<realm>/<char>/SavedVariables/<name>.lua (per-character)
      5. FireLuaEvent(0x1ad) -- ADDON_LOADED event
  -> [our hook: for hidden addons, callLoadFileListWithIncludes + callLoadUIBindingsFromFile]
  -> [our hook: for all addons with Bindings.xml, callLoadUIBindingsFromFile]
  -> SaveAddonVariables (0x0051f650) -- called from World_HandlePlayerLogin (0x00490bd0) on logout

Key Functions

Address	Name	Convention	Notes
0x0051c740	SetupAddonProcessing	__fastcall(ECX=mgr_ptr), RET	Calls ShutdownAddonSystem + ProcessAddonDirectory
0x0051c760	ProcessAddonDirectory	cdecl/void	Scans filesystem, builds addon list
0x0051c910	ProcessAddonFilePath	__fastcall(ECX=path)	Per-.toc callback, strips prefix, calls LoadAddonTOC
0x0051c9b0	LoadAddonTOC	__fastcall(ECX=addonName), RET	Parses TOC, registers addon in hash table
0x0051d410	ProcessAddonInterface	__fastcall(ECX=addonData)	Reads .pub file for secure addons
0x0051d4c0	ProcessAddonURL	__fastcall(ECX=addonData)	Reads .url file
0x0051ebe0	LoadAddonSavedVariables	__fastcall(ECX=addonName or NULL for all)	Loads AddOns.txt state
0x0051f242	LoadAddonRecursive	__fastcall(ECX=addonName, EDX=loadFlag, stack=callback)	Loads one addon + saved vars
0x0051f600	LoadAddonsRecursively	__fastcall(ECX=callback)	Iterates all registered addons
0x0051f650	SaveAddonVariables	cdecl/void	Writes all dirty addons' saved vars to WTF/
0x0051fa40	ShutdownAddonSystem	?	Cleanup
0x0064b3f0	String_ComputeHash	__stdcall(string), RET 0x4	NOT fastcall! Reads from [EBP+8]. Returns hash in EAX
0x0051def0	GetAddonCount	cdecl	Returns PTR_00be1b90
0x0051df00	GetAddonByIndex	__fastcall(ECX=index)	Returns PTR_00be1b94[index]
0x0051e3e0	IsAddonSecure	__fastcall(ECX=name)	Returns addon[0x30] byte (from .pub parsing)
0x0051e470	ValidateCommandAccess	__fastcall(ECX=name, EDX=acctName, stack=flag)	Checks addon enabled state
0x0051e780	EnableAddonWithDependencies	__fastcall(ECX=name, ...)	Validates + enables addon
0x0051e980	GetAddonSecurityString	__fastcall(ECX=state)	Returns PTR_s_SECURE_0085367c[state]
0x0051e990	GetAddonState	__fastcall(ECX=name)	Returns addon[9] (+0x24) from hash table

Addon Data Structure (hash table entry)

+0x00: u32  hash of addon name
+0x04: ...  (hash table linkage)
+0x14: *u8  addon name string (entry[5])
+0x18: u8   dirty flag (needs variable save)
+0x19: u8   loaded flag (entry[6] byte 1)
+0x1c: u32  interface version (## Interface)
+0x20: u32  revision (## Revision)
+0x24: u32  security state (0=SECURE, 1=INSECURE, 2=BANNED)
+0x26-0x2f: hash table for Title/Notes/Author/Version metadata
+0x28: u8   secure TOC flag (## Secure) -- triggers .pub validation
+0x2b: u8   default state enabled/disabled (## DefaultState)
+0x2c: u8   load on demand flag (## LoadOnDemand)
+0x34: u32  line count in TOC

Dynamic arrays (each: capacity/count/data_ptr/growth at 3 dword intervals):
+0x38/3c/40/44: OptionalDeps (## OptionalDep)
+0x48/4c/50/54: RequiredDeps (## RequiredDep / ## Dep)
+0x58/5c/60/64: LoadWith/Dependencies (## LoadWith)
+0x68/6c/70/74: SavedVariables (## SavedVariables) -- account-wide
+0x78/7c/80/84: SavedVariablesPerCharacter (## SavedVariablesPerCharacter)
+0x8c-0x98:     dependents array

+0xC1: u8   .pub type byte (from ParseAddonInterfaceData)
+0xC2: [256]u8  .pub key data (256 bytes)
+0x1C2: [16]u8  MD5 hash for signature validation

Key Globals

Address	Name	Purpose
0x00be1b60	PTR_00be1b60	Hash table control structure
0x00be1b64	PTR_00be1b64	Linked list base for traversal (node+4 offset)
0x00be1b6c	PTR_00be1b6c	Addon linked list head
0x00be1b7c	PTR_00be1b7c	Hash table buckets array
0x00be1b84	PTR_00be1b84	Hash table mask (0xffffffff = uninitialized)
0x00be1b90	PTR_00be1b90	Flat addon count (for GetAddonCount)
0x00be1b94	PTR_00be1b94	Flat addon array (for GetAddonByIndex)
0x00be1bd8	PTR_00be1bd8	Saved variables state list head

Hash Table Structure

• Buckets at PTR_00be1b7c, mask at PTR_00be1b84
• Each bucket is 12 bytes: [+0] next_offset, [+4] ?, [+8] list_head_ptr
• Node traversal: next = *(node + bucket.next_offset + 4)
• Lookup: compute hash via String_ComputeHash, bucket = mask & hash, walk chain comparing hash then name

Addon Security System

Security States (+0x24)

• 0 = SECURE -- Blizzard addon, hidden from addon list, always loaded
• 1 = INSECURE -- Normal third-party addon, shown in list
• 2 = BANNED -- Failed signature validation, shown as "Banned"

String table at PTR_s_SECURE_0085367c indexed by state value.

Signature Validation Flow

When ## Secure: 1 is in the TOC:

1. LoadAddonTOC sets +0x28 secure flag, then calls ProcessAddonInterface + ProcessAddonURL
2. ProcessAddonInterface (0x0051d410) reads Interface\AddOns\<name>\<name>.pub via LoadFileWithTextureResourceFallback
3. .pub file must be exactly 257 bytes: 1 byte type + 256 bytes public key
4. Stored at addon struct +0xC1 (type) and +0xC2 (key data)
5. Later in LoadAddonRecursive, MD5 hash of addon files is compared against signature
6. If no valid .pub or signature mismatch: security state set to 2 (BANNED)

Hiding Addons -- Approaches Tried

Approach 1: ## Secure: 1 in TOC -- FAILED Sets secure flag but without a valid .pub file, ProcessAddonInterface runs and the addon ends up as BANNED (state 2). Cannot forge a valid .pub without Blizzard's private key.

Approach 2: Patch +0x24 after LoadAddonTOC -- NOT VERIFIED After calling LoadAddonTOC, look up addon in hash table and write 0 to +0x24. Issue: String_ComputeHash is __stdcall NOT __fastcall -- initial crash was caused by calling it via hook.fastcall which passed the string pointer in ECX instead of on the stack. Fixed to use direct function pointer cast with callconv(sc). The write logic itself was not verified to work at runtime before being removed.

Approach 3: Skip LoadAddonTOC for hidden addons -- CURRENT Hidden addons (hidden = true in EmbedModule) are NOT registered via LoadAddonTOC at all. They don't appear in the addon hash table, so the game doesn't know about them. Their files are loaded directly via callLoadFileListWithIncludes in loadAddonsDetour, same as the original pre-SavedVariables approach. This means they are invisible in the addon list but also cannot have SavedVariables.

Current Implementation

Two-tier addon loading controlled by EmbedModule.hidden:

Visible addons (hidden = false):

• Registered via LoadAddonTOC in setupAddonsDetour (hook on SetupAddonProcessing)
• Appear in charselect addon list as INSECURE (normal)
• Game handles file loading, SavedVariables, ADDON_LOADED events
• Bindings.xml loaded explicitly (preloadFileWithFlags bypass)

Hidden addons (hidden = true):

• NOT registered via LoadAddonTOC -- invisible in addon list
• Files loaded directly via callLoadFileListWithIncludes in loadAddonsDetour
• Bindings.xml loaded explicitly
• No SavedVariables support (no addon hash table entry)

Addon	Hidden
WeirdUtils_Screenshot	yes
WeirdUtils_Interact	no
WeirdUtils_Outline	no
WeirdUtils_WorldMarkers	yes
WeirdUtils_LogSessions	no
WeirdUtils_MinimapIcons	no

Future: Proper Addon Hiding

To revisit Approach 2 (patching +0x24 to SECURE after registration), need to:

1. Verify markAddonSecure hash table traversal with debug logging
2. Confirm hook.writeMem actually writes to the addon struct
3. Check if GetAddonState is the only thing the UI reads, or if there are other security-related fields that also need patching
4. Investigate whether generating a valid .pub + MD5 signature is feasible (likely needs Blizzard's private key, but the validation algorithm is in-binary)

Login Screen Addon List

Architecture

Two separate Lua C function tables exist for addon management:

• Glue (login/charselect) table at 0x008374a0 -- functions in 0x0046dxxx range
• In-game table at 0x0083e488 -- functions in 0x0048exxx range

Both read from the same underlying addon data.

Glue Lua Functions (charselect screen)

Address	Function
0x0046d420	GetNumAddOns
0x0046d460	GetAddOnInfo -- returns: name, title, notes, url, loadable, reason, security, isNew
0x0046d5e0	LaunchAddOnURL
0x0046d650	GetAddOnDependencies
0x0046d6f0	GetAddOnEnableState
0x0046d7b0	EnableAddOn
0x0046d850	EnableAllAddOns
0x0046d8a0	DisableAddOn
0x0046d940	DisableAllAddOns
0x0046d990	SaveAddOns
0x0046d9a0	ResetAddOns

Data Path

• GetAddonCount (0x0051def0): returns PTR_00be1b90 (simple count)
• GetAddonByIndex (0x0051df00): returns PTR_00be1b94[index] (flat array of addon ptrs)

These are a flat indexed view, separate from the hash table (PTR_00be1b7c) and linked list (PTR_00be1b6c). Registered addons appear in the list after SetupAddonProcessing.

Open Questions

1. When is PTR_00be1b90/PTR_00be1b94 populated? Need to find xrefs to determine who writes to it and when relative to our hook.

2. Enable/Disable persistence: EnableAddOn/DisableAddOn write to AddOns.txt via SaveAddOns. The DLL could check this file or the addon struct's enabled field at startup to decide whether to install hooks for a given module.