LibMonetColor-1.0 is a small, dependency-free LibStub library that gives an addon a colour theme derived from where the player actually is. It samples the ambient colour of the current zone and derives four coordinated, Impressionist-style colours — Edge Glow, Ambient Tint, Highlight Wash and a Monet Neutral — so borders, backgrounds and highlights follow the world instead of one fixed palette.
This is a library, not a standalone UI. Nothing is drawn on screen until an addon consumes the colours. It is built for addon authors.
Why it is different
- Not a lookup table of fixed themes: colours are computed from the zone's environment colour through a Monet-style rule engine (complementary hue, S-curve lightness clamp, hue domains, achromatic fallback).
- Zone data for 25 areas is included, generated from in-game screenshots and travel photography. Resolution order: runtime override → zone data → parent map chain → neutral fallback. Extend any zone at runtime with
RegisterMapEnv; no fork needed. - A strict 5+3 model: functional colours (primary, health, resource, danger, neutral) stay with the addon and are never stylised. The library only supplies the neutral plus three signature colours. Readability wins over art.
- Debounced events:
OnThemeColorsChangedfires only when Delta E > 5.0;OnThemeRefreshedfires on every recompute.
Optional state layer — LibMonetColor-Anim-1.0
An optional companion layer translates player state (combat, out of combat, resting, low health, PvP, vehicle, death) into colour modifiers. Consumers register a colour sink and just paint the RGBA they receive — no event registration, no health math, no OnUpdate. All pulsing runs on one shared ticker with a 64-point waveform lookup, 15 fps, and it hides itself when idle. Do not load this file if you only need environment colours.
Colour tools
ContrastRatio() (WCAG 2.x) and AtLightness() (CIE L* relocation, preserving hue and saturation) are pure functions for building readable lightness ladders. Compute them on theme refresh and cache the result — never call them per frame.
For addon authors
local LMC = LibStub("LibMonetColor-1.0", true)
if LMC then
local r, g, b, a = LMC:GetCurrentEdgeColor()
MyFrame:SetBackdropBorderColor(r, g, b, a)
else
MyFrame:SetBackdropBorderColor(0.5, 0.5, 0.5, 0.8) -- graceful fallback
end
LMC:RegisterCallback("OnThemeColorsChanged", function(_, entry)
MyFrame:ApplyTheme(entry) -- edge, ambient, highlight, neutral
end)
Installation
| Mode | How |
|---|---|
| Standalone | Install as Interface/AddOns/LibMonetColor-1.0. It is LoadOnDemand; consumers use ## OptionalDeps: LibMonetColor-1.0 or LoadAddOn. LibStub is embedded. |
| Vendored | Copy the four Lua files plus Libs/LibStub/LibStub.lua into your addon's Libs/ and list them in TOC order. |
Use one mode or the other, never both on the same client: two copies register the same LibStub major version and the second one exits.
Contracts
- Never throws — on error, public APIs return neutral grey
(0.5, 0.5, 0.5)with a 30-second warning cooldown. - Every returned component is clamped to
[0, 1]. - Consumer isolation — one broken callback cannot break the others.
- Secret-value safe — when health is restricted, only the low-health effect is disabled.
- Zero idle cost — without sinks or callbacks the state layer registers no events and runs no ticker.
- Public API is backwards compatible throughout 1.x.
Compatibility & dependencies
Interface 16001, Lua 5.1, no hard dependencies. Embedded LibStub is public domain; CallbackHandler-1.0 is optional (a built-in registry is used when absent). The library creates no frames and registers no game events — the optional state layer's ticker is the only exception. 155 unit tests pass outside the game client.
Documentation & source
Credits & license
MIT © 2026 EastHillGu. Embedded LibStub is public domain. Monet painting samples used to derive the colour rules come from Wikimedia Commons (public domain); the images are not distributed. No Blizzard in-game assets are shipped.