moonwell-client/DRAGONUI_OVERRIDES.md

DragonUI: replacement addons

MoonWell ships DragonUI as the default interface. Players can replace an individual DragonUI module without copying or editing the bundled addon.

Replacement addon structure

The replacement must use its own folder and addon name. Do not create another folder named DragonUI; files inside an MPQ and loose files with the same virtual path do not form a supported update mechanism.

MyDragonUIMinimap/
|-- MyDragonUIMinimap.toc
`-- MyDragonUIMinimap.lua

MyDragonUIMinimap.toc:

## Interface: 30300
## Title: My DragonUI Minimap
## Dependencies: DragonUI
## X-DragonUI-Overrides: minimap
## X-DragonUI-Override-Priority: 100

MyDragonUIMinimap.lua

The X-DragonUI-Overrides declaration is required. DragonUI reads it before dependent addons execute and does not apply the bundled implementation. A list may contain several comma-separated module identifiers.

MyDragonUIMinimap.lua:

local provider = {}

function provider:Activate(dragonUI, moduleName)
    -- Create or show the replacement here.
end

function provider:Deactivate(dragonUI, moduleName)
    -- Hide frames and unregister events created by this provider.
end

local ok, reason = DragonUI:RegisterModuleOverride(
    "minimap",
    "MyDragonUIMinimap",
    provider,
    { priority = 100 }
)

if not ok then
    DEFAULT_CHAT_FRAME:AddMessage("MyDragonUIMinimap: " .. tostring(reason))
end

The owner passed to RegisterModuleOverride must match the addon folder/TOC name. Supported provider activation names are Activate, Apply, Enable, or OnEnable; cleanup names are Deactivate, Restore, Disable, or OnDisable.

Public API (version 1)

DragonUI.PUBLIC_API_VERSION
DragonUI:RegisterModuleOverride(moduleName, owner, provider[, options])
DragonUI:UnregisterModuleOverride(moduleName, owner)
DragonUI:IsModuleOverridden(moduleName)
DragonUI:GetModuleOverride(moduleName) -- owner, provider

DragonUI also sends the Ace message DRAGONUI_OVERRIDE_CHANGED with moduleName, owner. owner is nil after the final provider is removed.

Registering a replacement at runtime without TOC metadata is supported only for a module that can be restored safely. For a load-once module the call returns true, "RELOAD_REQUIRED"; add the metadata and reload the UI.

Bundled module identifiers

The registry currently exposes these identifiers:

bagsort, boss, buffs, buttons, castbar, chatmods, combuctor, cooldowns,
darkmode, itemquality, keybinding, mainbars, micromenu, minimap, multicast,
noop, petbar, player, questtracker, rage_indicator, stance, tooltip,
unitframe_layers, vehicle

Target/focus/party frames still contain legacy startup code and will be added to the public registry before they are advertised as independently replaceable.

Conflict resolution

When multiple enabled addons claim the same module, the highest numeric X-DragonUI-Override-Priority wins. Equal priorities are resolved by addon name to make the result deterministic. A declaration that never registers a provider is rejected at PLAYER_LOGIN, and DragonUI restores its bundled module so the player is not left without that UI element.

Module suppression is session-only. DragonUI restores the player's saved enabled/disabled choice during PLAYER_LOGOUT, so removing a replacement addon automatically brings back the previous DragonUI configuration.