Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
- `UnitFrames/Integration/EditMode.lua`: layout-specific positions and snapping through LibEditMode.
- `UnitFrames_Workbench/`: load-on-demand settings and previews, opened with `/uf wb`. `Entries/Units.lua` edits the real saved unit style; `Data.lua` defines preview sources. Keep static, animated and live previews consistent with runtime behaviour.
- `UnitFrames_Media/`: independently registered LibSharedMedia fonts and their licences.
- `UnitFrames_Onboarding/`: load-on-demand Getting started guide (`/uf welcome`). `Integration/Onboarding.lua` in the core opens it once on a fresh install (`global.onboarding.done`). Presets are style-string data applied through `Profiles:Prepare("style", …)`; previews render unsaved styles inside `Config:WithTheme`, which gives the preview theme a revision of its own. Never write saved config before Apply.
- `UnitFrames_ClickGrid/`: optional healing panel companion (`/ufcg`): party/raid groups, member targets, native aura slots, status indicators and click-spell bindings, built from the same `UnitFrame` component through the public `UnitFrames` handle.
- Match nearby code: tabs, local helpers, existing component methods. New runtime files must be added to the appropriate `.toc` in dependency order; the tests load those TOCs too.
- Embedded libraries under either addon's `Libs/` are pinned dependencies, not normal edit targets. The folders are gitignored: `scripts/fetch-libs.sh` replaces local copies and records `UnitFrames/Libs/VERSIONS.md`, and `scripts/setup-test-libs.sh` holds the commits tests and releases build from. Run them only for an intentional dependency update and keep both pins in step.
Expand Down Expand Up @@ -87,7 +88,7 @@ luajit tests/run.lua --tag shields
luajit tests/run.lua workbench -t "preview"
```

- Specs live in `tests/spec/<area>/` (`core`, `contract`, `components`, `auras`, `units`, `workbench`, `editmode`, `clickgrid`, `tracking`). Put new specs in the area of the code they exercise; a feature spec keeps its live and Workbench preview tests together. When behaviour also has tests in other areas, tag them in the `describe`/`it` name (`#shields`) and keep existing tags.
- Specs live in `tests/spec/<area>/` (`core`, `contract`, `components`, `auras`, `units`, `workbench`, `editmode`, `clickgrid`, `tracking`, `onboarding`). Put new specs in the area of the code they exercise; a feature spec keeps its live and Workbench preview tests together. When behaviour also has tests in other areas, tag them in the `describe`/`it` name (`#shields`) and keep existing tags.
- Path filters match **spec paths** (`units/` is exactly that folder, `name_spec.lua` exactly that file); `-t` matches test names and `--tag` matches tags. `-j [N]` runs spec files in parallel; `--times` (runner or `scripts/run-tests.sh`) reports per-spec durations; `luajit -jp=F tests/run.lua ...` profiles. The runner includes addon Lua syntax checks. No external busted installation is needed.
- `tests/helpers.lua` loads TOCs into a fresh mocked client; `tests/mock/wow.lua` includes fake secrets and `tests/mock/ouf.lua` supplies the usual oUF stand-in. Some specs exercise embedded oUF paths explicitly.
- The mock is held to the client API through `tests/fixtures/api_snapshot.lua`, generated from Blizzard's API documentation and Lua source by `luajit scripts/api-snapshot.lua` (regenerate after adding API usage or updating the source checkout, and review the diff). The checkout must match the commit pinned in the workflows, or CI regenerates a different snapshot. `tests/mock/api.lua` enforces it on every mock call: undocumented widget methods, rejected arguments, secrets passed where addon (tainted) code may not pass them, and protected calls in combat raise errors. `tests/spec/contract/api_contract_spec.lua` checks the mock's functions, methods, enums, restricted secret returns and our event names, and that the snapshot is current when the source checkout exists.
Expand All @@ -99,7 +100,7 @@ luajit tests/run.lua workbench -t "preview"
## Local installation

- Default client AddOns directory: `/mnt/data02/Games/Faugus/battlenet/drive_c/Program Files (x86)/World of Warcraft/_forever_/Interface/AddOns/`. `scripts/install.sh` supports `WOW_DIR` overrides; validate the actual target before deploying.
- For authorized deployments, use `scripts/install.sh` by default, passing the changed addon names when appropriate (for example, `scripts/install.sh UnitFrames_Workbench`). Do not substitute manual `rsync` deployments unless specifically requested.
- For authorized deployments, use `scripts/install.sh` by default, passing the changed addon names when appropriate (for example, `scripts/install.sh UnitFrames_Workbench`). When the client runs on another machine than the checkout, add `--host <ssh destination>` (for example `--host arch`). Do not substitute manual `rsync` deployments unless specifically requested.
- The install script replaces the targeted addon directories before copying/linking; this replacement is expected and authorized as part of a requested installation. SavedVariables under `WTF/` are retained. `--uninstall` is a separate removal operation and requires an explicit uninstall request.
- Request the required filesystem approval when installing outside the workspace. Never edit SavedVariables or unrelated installed addons as part of routine deployment.
- `/reload` normally picks up changed Lua. Restart the client for new TOC-listed files or new media/font assets. State clearly whether changes were installed or only edited/tested in the repository.
7 changes: 7 additions & 0 deletions DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,6 +184,7 @@ in source is needed before tagging.
| `UnitFrames/Integration/` | Edit Mode and launcher integration |
| `UnitFrames_Workbench/` | Load-on-demand settings, component gallery and static/animated/live previews |
| `UnitFrames_ClickGrid/` | Party/raid panel, member targets, indicators, auras and click-spell bindings |
| `UnitFrames_Onboarding/` | Load-on-demand Getting started guide: preset looks, tweaks, extras and Workbench hand-off |
| `UnitFrames_Media/` | Additional fonts and their licences |
| `tests/` | Mocked client, API snapshot and regression specs |
| `scripts/` | Library fetching, installation and API snapshot generation |
Expand Down Expand Up @@ -385,6 +386,12 @@ supports `WOW_DIR`, named addon arguments, `--link` and `--uninstall`.
`--uninstall` removes it too.** SavedVariables under `WTF/` remain intact,
but other files in those addon folders are replaced.

`--host <ssh destination>` does the same on another machine, for a client
that runs elsewhere than the checkout: `scripts/install.sh --host arch
UnitFrames_Onboarding`. It needs key-based SSH login and rsync on both ends;
`WOW_DIR` then names the path on that machine (same default). `--link` is
local only.

Use `/reload` for changed Lua in existing files. Restart the client for new
TOC-listed files or new media/font assets. Keep repository edits and game
installation distinct when reporting changes.
Expand Down
3 changes: 2 additions & 1 deletion NOTICE.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@ Required Notice: Copyright (c) 2026 Martin Konstantin Herrmann.

Original UnitFrames code and documentation are licensed under the PolyForm
Noncommercial License 1.0.0; see LICENSE. This covers original work in
UnitFrames, UnitFrames_Workbench, UnitFrames_Media and UnitFrames_ClickGrid.
UnitFrames, UnitFrames_Workbench, UnitFrames_Media, UnitFrames_ClickGrid and
UnitFrames_Onboarding.
Third-party libraries, fonts, reference projects and Blizzard materials are
excluded and retain their own terms.

Expand Down
21 changes: 15 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,12 @@ Use **Global Settings** to adjust inherited defaults. Development builds also
include a **Developer tools** component gallery for testing; those demonstrations do
not change your unit settings.

New to the addon? **Getting started** (`/uf welcome`, or the button at the
top of the Workbench) lets you pick one of four preset looks with live
previews, adjust font, textures, border, colours, portraits and size, and
switch on castbars and timers. It saves the result as a new profile, so your
previous look stays one switch away.

To move frames, open the game's **Edit Mode**. If you want matching frames,
start with your player and use **Copy player style** under **Layout & border** on the others.
You can still customise each one afterward.
Expand Down Expand Up @@ -110,12 +116,15 @@ those separately. If no release is listed yet, the first bundle has not
been published.

Extract the ZIP into your Forever client's `Interface/AddOns` folder. It
contains four addon folders: `UnitFrames`, `UnitFrames_Workbench`,
`UnitFrames_Media` and `UnitFrames_ClickGrid`. Keep the first two for frames
and settings. The extra fonts and ClickGrid healing panel are optional.

Restart the game, enable the addons on the character selection screen,
then type `/uf wb` to get started.
contains five addon folders: `UnitFrames`, `UnitFrames_Workbench`,
`UnitFrames_Media`, `UnitFrames_ClickGrid` and `UnitFrames_Onboarding`. Keep
the first two for frames and settings. The extra fonts, ClickGrid healing
panel and the Getting started guide are optional.

Restart the game and enable the addons on the character selection screen.
On your first login, **Getting started** walks you through picking a preset
look, the options that matter most and the extras you want. Afterwards,
`/uf wb` opens all settings and `/uf welcome` reopens the guide.

Use the attached **UnitFrames-….zip**, rather than GitHub's **Source code**
archives or **Download ZIP** button, which contain source without dependencies.
Expand Down
26 changes: 26 additions & 0 deletions USER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,32 @@ A detailed reference for the settings available in game. For a quick
introduction, see the [main README](README.md). For setup and implementation,
see the [developer guide](DEVELOPMENT.md).

## Getting started

On a first install, the **Getting started** guide opens shortly after you log
in (never during combat). Reopen it any time with `/uf welcome`, the
**Getting started** button at the top of the Workbench or the minimap icon's
right-click menu. It is its own optional addon, **UnitFrames Getting
started**: turn it off in the AddOns list and nothing of it loads.

1. **Pick a look**: Default, Minimal, Classic or Healer, each with a live
preview of your player and target frames.
2. **Make it yours**: font, bar texture, border, health colour, portraits and
size, shown on the preview as you click.
3. **Add the extras**: castbars on your player, target and focus frames,
experience, combo points, and the standalone timer bars with global
cooldown and swing timer. **Save as a new profile** (on by default) puts
the look into a new profile named after it and switches to it; your
previous profile is left untouched. Turn it off to replace the style of
the current profile instead. Frame positions always stay.
4. **Ready**: open Edit Mode to place your frames, or jump straight to the
Workbench pages for buffs and debuffs, texts, timers, ClickGrid or
importing a shared string.

Nothing is saved before **Apply and finish**. Skip, Escape or the close
button end the guide without changes. Combat hides it with your choices kept;
it returns when combat ends.

## Open settings

In game: `/uf wb` opens the Workbench.
Expand Down
30 changes: 27 additions & 3 deletions UnitFrames/Core/Commands.lua
Original file line number Diff line number Diff line change
Expand Up @@ -3,26 +3,45 @@ local _, ns = ...
local HELP = {
"/uf help - show this list of commands",
"/uf wb - open settings and previews",
"/uf welcome - walk through presets and the first setup again",
"/uf minimap - show or hide the minimap icon",
"/uf logs [clear] - show or clear saved diagnostic entries",
"/uf dots [reset] - toggle DoT tracking with its trace in chat, or forget learned tick sizes",
"/uf perf help - show developer performance commands",
}

-- Loads the Workbench on demand and shows it, optionally at an entry.
function ns:OpenWorkbench(entryId)
-- Loads the Workbench on demand and shows it, optionally at an entry and the
-- settings page holding `path` (e.g. "auras").
function ns:OpenWorkbench(entryId, path)
local loaded, reason = C_AddOns.LoadAddOn("UnitFrames_Workbench")
if not loaded then
self:Print("could not load UnitFrames_Workbench:", reason or "unknown reason")
return
end
if entryId then
self.Workbench:Open(entryId)
self.Workbench:Open(entryId, path)
else
self.Workbench:Toggle()
end
end

-- Loads Getting started on demand and shows it. Players who turned the addon
-- off in the AddOns list only get a hint, and none when `quiet` (first login).
function ns:OpenOnboarding(quiet)
local loaded, reason = C_AddOns.LoadAddOn("UnitFrames_Onboarding")
if not loaded then
if quiet then return false end
if reason == "DISABLED" then
self:Print("Getting started is turned off. Enable UnitFrames Getting started in the AddOns list to use it.")
else
self:Print("could not load UnitFrames_Onboarding:", reason or "unknown reason")
end
return false
end
self.Onboarding:Open()
return true
end

local commands = {}

function commands.help()
Expand All @@ -37,6 +56,11 @@ function commands.wb()
end
commands.workbench = commands.wb

function commands.welcome()
ns:OpenOnboarding()
end
commands.onboarding = commands.welcome

function commands.minimap()
ns.Launcher:ToggleMinimap()
ns:Print(ns.Launcher:IsMinimapShown() and "minimap icon shown" or "minimap icon hidden")
Expand Down
20 changes: 20 additions & 0 deletions UnitFrames/Core/Config.lua
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ local function BuildDefaults()
},
global = {
minimap = { hide = false },
-- Getting started (UnitFrames_Onboarding): finished or skipped once.
onboarding = { done = false },
},
}
end
Expand All @@ -47,6 +49,8 @@ local function OwnProfile(db)
end

function Config:Initialize()
-- No saved variables yet: a first install, offered the Getting started guide.
self.freshInstall = UnitFramesDB == nil
self.db = LibStub("AceDB-3.0"):New("UnitFramesDB", BuildDefaults(), true)
OwnProfile(self.db)
local function OnProfile()
Expand All @@ -65,14 +69,30 @@ function Config:ProfileChanged()
end

-- Before ADDON_LOADED (and in offline tests) the static defaults are used.
-- Inside WithTheme a preview's own theme is returned instead.
function Config:GetTheme()
if self.previewTheme then return self.previewTheme end
if self.db then
return self.db.profile.theme
end
self.defaultTheme = self.defaultTheme or Schema.Defaults(ns.Theme.schema)
return self.defaultTheme
end

-- Runs fn with `theme` as the effective theme, for previews of a style that
-- isn't saved (Getting started presets). Theme-derived caches see a revision
-- of their own, so neither the preview nor the live frames reuse the other's.
-- The previous theme is restored even when fn raises; the error still raises.
local previewRevision = 0
function Config:WithTheme(theme, fn, ...)
local previous, revision = self.previewTheme, self.themeRevision
previewRevision = previewRevision - 1
self.previewTheme, self.themeRevision = theme, previewRevision
local ok, err = pcall(fn, ...)
self.previewTheme, self.themeRevision = previous, revision
if not ok then error(err, 0) end
end

function Config:GetThemeDefaults()
self.themeDefaults = self.themeDefaults or Schema.Defaults(ns.Theme.schema)
return self.themeDefaults
Expand Down
19 changes: 19 additions & 0 deletions UnitFrames/Core/Profiles.lua
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,16 @@ local function CheckName(name)
return name
end

-- `base`, or "base 2", "base 3"... when that name is taken.
function Profiles:UniqueName(base)
local name, index = base, 1
while self:Exists(name) do
index = index + 1
name = base .. " " .. index
end
return name
end

function Profiles:Switch(name)
if not self:Exists(name) then return false, "There is no profile named " .. tostring(name) .. "." end
DB():SetProfile(name)
Expand Down Expand Up @@ -159,6 +169,15 @@ function Profiles:Decode(text)
return payload
end

-- Validates decoded data of one kind (as a string would carry it) without
-- writing anything: an apply function and the skipped paths, or nil and a
-- reason. Built-in presets use it to apply style tables.
function Profiles:Prepare(kindKey, data)
local kind = self.kinds[kindKey]
assert(kind, "Profiles: unknown kind " .. tostring(kindKey))
return kind.prepare(data)
end

--[[
Imports a string. With `profileName` (different from the active profile) the
data goes into a new profile, created and made active; otherwise it replaces
Expand Down
1 change: 1 addition & 0 deletions UnitFrames/Integration/Launcher.lua
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ end
local function BuildMenu(_, root)
root:CreateTitle("UnitFrames")
root:CreateButton("Toggle Workbench", function() ns:OpenWorkbench() end)
root:CreateButton("Getting started", function() ns:OpenOnboarding() end)
root:CreateCheckbox("Show minimap icon",
function() return Launcher:IsMinimapShown() end,
function() Launcher:ToggleMinimap() end)
Expand Down
55 changes: 55 additions & 0 deletions UnitFrames/Integration/Onboarding.lua
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
local _, ns = ...

--[[
Offers Getting started (UnitFrames_Onboarding, load on demand) once. A first
install opens it shortly after the first login, waiting for combat to end;
an existing install is marked done and gets a one-line hint instead. The
guide marks itself done when it is skipped, closed or applied.
]]
local FirstRun = {}
ns.FirstRun = FirstRun

FirstRun.DELAY = 2

local frame = CreateFrame("Frame")

local function Settings()
return ns.Config.db.global.onboarding
end

function FirstRun:IsDone()
return Settings().done == true
end

function FirstRun:MarkDone()
Settings().done = true
end

local function OpenWhenReady()
if FirstRun:IsDone() then return end
if InCombatLockdown() then
frame:RegisterEvent("PLAYER_REGEN_ENABLED")
return
end
frame:UnregisterEvent("PLAYER_REGEN_ENABLED")
ns:OpenOnboarding(true)
end

frame:SetScript("OnEvent", function(self, event, isInitialLogin)
if event == "PLAYER_ENTERING_WORLD" then
self:UnregisterEvent(event)
if isInitialLogin then C_Timer.After(FirstRun.DELAY, OpenWhenReady) end
return
end
OpenWhenReady()
end)

ns.Events.RegisterCallback(FirstRun, "Initialized", function()
if FirstRun:IsDone() then return end
if not ns.Config.freshInstall then
FirstRun:MarkDone()
ns:Print("New: /uf welcome walks you through preset looks and the most important options.")
return
end
frame:RegisterEvent("PLAYER_ENTERING_WORLD")
end)
3 changes: 2 additions & 1 deletion UnitFrames/NOTICE.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@ Required Notice: Copyright (c) 2026 Martin Konstantin Herrmann.

Original UnitFrames code and documentation are licensed under the PolyForm
Noncommercial License 1.0.0; see LICENSE. This covers original work in
UnitFrames, UnitFrames_Workbench, UnitFrames_Media and UnitFrames_ClickGrid.
UnitFrames, UnitFrames_Workbench, UnitFrames_Media, UnitFrames_ClickGrid and
UnitFrames_Onboarding.
Third-party libraries, fonts, reference projects and Blizzard materials are
excluded and retain their own terms.

Expand Down
1 change: 1 addition & 0 deletions UnitFrames/UnitFrames.toc
Original file line number Diff line number Diff line change
Expand Up @@ -112,3 +112,4 @@ Timers\Runtime.lua

Core\Commands.lua
Integration\Launcher.lua
Integration\Onboarding.lua
3 changes: 2 additions & 1 deletion UnitFrames_ClickGrid/NOTICE.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@ Required Notice: Copyright (c) 2026 Martin Konstantin Herrmann.

Original UnitFrames code and documentation are licensed under the PolyForm
Noncommercial License 1.0.0; see LICENSE. This covers original work in
UnitFrames, UnitFrames_Workbench, UnitFrames_Media and UnitFrames_ClickGrid.
UnitFrames, UnitFrames_Workbench, UnitFrames_Media, UnitFrames_ClickGrid and
UnitFrames_Onboarding.
Third-party libraries, fonts, reference projects and Blizzard materials are
excluded and retain their own terms.

Expand Down
3 changes: 2 additions & 1 deletion UnitFrames_Media/NOTICE.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@ Required Notice: Copyright (c) 2026 Martin Konstantin Herrmann.

Original UnitFrames code and documentation are licensed under the PolyForm
Noncommercial License 1.0.0; see LICENSE. This covers original work in
UnitFrames, UnitFrames_Workbench, UnitFrames_Media and UnitFrames_ClickGrid.
UnitFrames, UnitFrames_Workbench, UnitFrames_Media, UnitFrames_ClickGrid and
UnitFrames_Onboarding.
Third-party libraries, fonts, reference projects and Blizzard materials are
excluded and retain their own terms.

Expand Down
Loading
Loading