WoWTools Architecture Expert

This skill provides comprehensive guidance for developing the WoWTools World of Warcraft addon - a modular Lua-based enhancement suite covering UI improvements, gameplay features, and utility tools.

What This Skill Does

Assists developers working on WoWTools by providing:

Project Context

WoWTools is a comprehensive World of Warcraft addon with four major modules:

The addon is Chinese-first localized and supports multiple WoW versions (Retail, Classic, Cataclysm).

Architecture Guidelines

Load Order (CRITICAL)

The file load order is **absolutely critical** and defined in `WoWTools.toc`:

1. **Source/Libs/** - External libraries (LibStub, CallbackHandler, LibDataBroker)

2. **0_Data/** - Core data structures and mixins (MUST load first)

- `1_DataMixin.lua` - Global WoWTools_DataMixin table

- `2_DataMixin_WoW.lua` - WoW API data structures

- `3_DataMixn_Func.lua` - Utility functions (Hook, Call, Load)

- Files with `z_` prefix load last within this directory

3. **1_Mixin/** - Reusable UI/Framework mixins

4. **Plus_*** modules - Optional feature modules

5. **ChatButton*** modules - Chat integration

6. **Tools_*** modules - Tool implementations

7. **Z_Other/** - Miscellaneous features

**File naming conventions for load order:**

Data Persistence Pattern

Use three main SavedVariables (defined in .toc):

```lua

-- Primary settings (keyed by module name)

WoWToolsSave['ChatButton'] = {...}

WoWToolsSave['Other_VoiceTalking'] = {...}

-- Character-specific data (indexed by GUID)

WoWTools_WoWDate[characterGUID] = {...}

-- Player-specific state

WoWTools_PlayerDate = {...}

```

**Module pattern:** Define a `Save()` function returning the module's settings table:

```lua

local function Save()

return WoWToolsSave['ModuleName'] or {}

end

```

Mixin System Architecture

**Global Mixins** (loaded in 1_Mixin/):

**Module-specific Mixins:** Extend base mixins for specialized functionality

Button/UI Creation Pattern

Use declarative tables with `Cbtn()`:

```lua

local btn = Cbtn(parent, {

name = 'MyButtonName',

size = 24,

template = 'ItemButton',

tooltip = 'Button tooltip text',

texture = 'Interface\\Icons\\...',

OnClick = function(self)

-- Handle click

end,

})

```

Position menus with `AnchorMenuTab` (TOPLEFT, BOTTOMLEFT, etc.) and corresponding `AnchorTooltip` settings.

Event Handling & Hooks

Use `WoWTools_DataMixin:Hook()` for secure function hooking:

```lua

WoWTools_DataMixin:Hook(btnObj, 'OnMenuOpened', function(self)

self:SetButtonState('PUSHED')

end)

```

This wrapper:

Loading Game Data Asynchronously

Use `WoWTools_DataMixin:Load(id, loadType)`:

```lua

-- Load quest data

WoWTools_DataMixin:Load(questID, 'quest') -- Uses C_QuestLog.RequestLoadQuestByID

-- Load spell data

WoWTools_DataMixin:Load(spellID, 'spell') -- Uses C_Spell.RequestLoadSpellData

-- Load item data

WoWTools_DataMixin:Load(itemID, 'item') -- Uses C_Item.RequestLoadItemDataByID

-- Load M+ data

WoWTools_DataMixin:Load(mapID, 'challengeMap') -- Uses C_ChallengeMode.RequestLeaders

```

Development Workflows

Adding a New Module

1. Create directory: `Plus_NewFeature/` or `Tools_NewFeature/`

2. Create `1_Init.lua` with initialization logic

3. Add to `WoWTools.toc` in correct load order (after 0_Data/1_Mixin)

4. Implement `Save()` function pattern

5. Register settings options in module initialization

Working with Protected Code

Always check protection status before modifying frames in combat:

```lua

local isProtected, isExplicit = frame:IsProtected()

local disabled = isProtected and InCombatLockdown()

if disabled then

return -- Cannot modify protected frames in combat

end

```

Use `WoWTools_DataMixin:Hook()` instead of direct `hooksecurefunc` for automatic protection handling.

Cross-Module Communication

Code Conventions

Naming Conventions

Localization

```lua

-- Detect Chinese locale

LOCALE_zhCN = GetLocale() == 'zhCN'

-- Set locale flag

onlyChinese = LOCALE_zhCN and true or false

-- Use ternary for locale-specific logic

local text = LOCALE_zhCN and "中文文本" or "English text"

```

UI Styling

**Masks:**

**Button templates:**

**Colors:**

```lua

local r, g, b, hex = GetClassColor(baseClass)

```

WoW Version Branching

```lua

-- Check for Retail vs Classic

if WOW_PROJECT_ID == WOW_PROJECT_MAINLINE then

-- Retail-specific code

else

-- Classic-specific code

end

```

Key Integration Points

LibStub Libraries

C_* Namespaced APIs

Use modern WoW API namespaces:

Quick Reference: Key Files

Instructions for AI Assistant

When helping with WoWTools development:

1. **Always respect load order** - Check `WoWTools.toc` before suggesting file placement

2. **Use established patterns** - Follow mixin system, `Save()` functions, and hook patterns

3. **Handle protected code** - Use `WoWTools_DataMixin:Hook()` and check combat lockdown

4. **Maintain independence** - Modules should not directly depend on each other

5. **Consider localization** - Support both Chinese and English text

6. **Check WoW version** - Branch code for Retail vs Classic when APIs differ

7. **Follow naming conventions** - Use proper prefixes and casing

8. **Preserve file structure** - Keep numbered prefixes for load order control

When suggesting new features:

When debugging: