# 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.

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

`MyDragonUIMinimap.toc`:

```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`:

```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)

```lua
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:

```text
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.