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
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ luajit tests/run.lua workbench -t "preview"
Every change that can affect what a frame, preview or Workbench panel looks like ships with UI proof rendered by `wowproof`: in the pull request and, when working in Beluga, in the chat and on the task.

1. Pick the scenarios in `tests/proof/units.lua` and `tests/proof/workbench.lua` that show the change. When none does (a new setting, state or layout), add one: a name plus a `build` that configures through `Config:SetUnitValue` and feeds sample values. Prefer one scenario per state the change touches (like `player-idle` beside `player`) over one busy frame.
2. Render and look at them with `bash scripts/proof.sh <filters>` before claiming the change works. Dashed placeholders mean missing art, an atlas the generated table lacks or a portrait model, not a bug; mention them if they hide the change.
2. Render and look at them with `bash scripts/proof.sh <filters>` before claiming the change works. Dashed placeholders mean missing art or an atlas the generated table lacks, not a bug. 3D portraits show a static race portrait as a stand-in; mention them if they hide the change.
3. When opening or updating the pull request, run `bash scripts/proof-publish.sh --out .beluga/scratch/proof <filters>`. It renders the scenarios, commits the PNGs to the orphan `ui-proof` branch under `<branch>/` (it never touches the working tree or the current branch) and prints a `### UI proof` Markdown section with images pinned to that commit. Paste that section into the PR body (`gh pr create --body-file` or `gh pr edit --body-file`). Re-run it after visual changes in review; old links keep showing the earlier images. `--dry-run` skips the push.
4. In Beluga, show the same PNGs in the answer as Markdown images with their absolute paths under `.beluga/scratch/proof/`, and attach each one to the worktree's task with `task_attach_proof` (kind `image`).
5. Proof shows mocked rendering only. Still list what needs in-game verification (see Verification above): combat, secret values, taint, Edit Mode and live unit changes.
Expand Down
19 changes: 18 additions & 1 deletion DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -283,10 +283,27 @@ python3 -B scripts/atlas_catalog.py --fetch --check # what CI runs
Regenerate after adding a `SetAtlas` call. A name the table lacks draws as a
placeholder.

3D portraits (`PlayerModel`) can't be rendered headlessly, so `Setup.Model`
stands in a picture for the unit the model shows, keeping the model's alpha,
model alpha and dead/ghost desaturation. Proof renders Forever's **Classic**
experience preset (original "SD" character models) by default;
`UF_PROOF_PRESET=enhanced` renders the HD one. For each preset it first looks
for an in-game capture of the default portrait,
`<preset>/<Sex>-<Race>.png` (`Pet`/`Monster` for non-players), in the private
folder `UF_PROOF_PORTRAITS` (default `nas:/volume1/Game/unit-frames/proof-portraits`,
fetched over `ssh` into `.proof-art/portraits/`; also a local folder or an
HTTPS URL; skipped when `CI` is set or `UF_PROOF_ART_FETCH=0`). Captures are
Blizzard art: keep them in that folder, never in the repo. Without a capture
it falls back to Blizzard's static HD portrait
(`Interface\CharacterFrame\TemporaryPortrait-Male-<race>`) from the mirror.
Previews always show the player's own model (the portrait driver's sample is
`"player"`), so every sample portrait is the mocked Human. `player-dead`,
`focus-portrait` and `pet-portrait` cover the portraits that are off by
default.

Still drawn as dashed placeholders:
- art the mirror lacks, listed in `.proof-art/missing-<commit>.txt`
- atlases the generated table lacks
- portrait models

### Pull request checks

Expand Down
36 changes: 36 additions & 0 deletions tests/proof/setup.lua
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ local Raster = require("wowproof.raster")
local BlizzardArt = require("wowproof.sources.wow_ui_textures")
local ClientFiles = require("wowproof.sources.wago_casc")
local AtlasTable = require("wowproof.sources.atlas_table")
local RemoteDir = require("wowproof.sources.remote_dir")

local Mock = Helpers.Mock

Expand All @@ -19,6 +20,13 @@ local ART_REF = "d23deaf8f44a7d280dc974a5c9d5321c013db59b"
local ATLASES = dofile("tests/proof/atlases.lua")
local ART_DIR = os.getenv("UF_PROOF_ART") or ".proof-art"
local ART_FETCH = os.getenv("UF_PROOF_ART_FETCH") ~= "0"
local PRESETS = { classic = true, enhanced = true }
local PRESET = os.getenv("UF_PROOF_PRESET") or "classic"
local PORTRAIT_REMOTE = os.getenv("UF_PROOF_PORTRAITS") or "nas:/volume1/Game/unit-frames/proof-portraits"
local PORTRAIT_ART = "Interface\\CharacterFrame\\TemporaryPortrait-"
local PORTRAIT_SEX = "Male"
local PORTRAIT_CROP = { 0.14, 0.86, 0.14, 0.86 }
local CREATURE_PORTRAITS = { Beast = "Pet", Mechanical = "Vehicle-Mechanical" }

local Setup = {}

Expand All @@ -29,6 +37,13 @@ local blizzardArt = BlizzardArt({
token = os.getenv("GITHUB_TOKEN") or os.getenv("GH_TOKEN"),
})
local clientFiles = ClientFiles({ build = ATLASES.build, dir = ART_DIR, fetch = ART_FETCH })
local portraitCaptures = RemoteDir({
remote = PORTRAIT_REMOTE,
dir = ART_DIR .. "/portraits",
fetch = ART_FETCH and os.getenv("CI") == nil,
})

if not PRESETS[PRESET] then error("UF_PROOF_PRESET must be classic or enhanced, not " .. PRESET) end

local function AddonFile(path)
if type(path) ~= "string" or path:lower():sub(1, #ADDON_PREFIX) ~= ADDON_PREFIX then return nil end
Expand All @@ -49,6 +64,26 @@ function Setup.Texture(path)
return Setup.AddonTexture(path) or blizzardArt(path) or clientFiles(path)
end

local function Plain(value)
if Mock.IsSecret(value) then return value.secretValue end
return value
end

function Setup.Model(info)
local unit = info.unit
if not unit then return nil end
local art
if Plain(UnitIsPlayer(unit)) then
local _, race = UnitRace(unit)
art = PORTRAIT_SEX .. "-" .. Plain(race)
else
art = CREATURE_PORTRAITS[Plain(UnitCreatureType(unit))] or "Monster"
end
local capture = portraitCaptures(PRESET .. "/" .. art .. ".png")
if capture then return { path = capture } end
return { file = PORTRAIT_ART .. art, texCoords = PORTRAIT_CROP }
end

function Setup.Font(path)
local file = AddonFile(path)
local style = file and file:match("^" .. FONT_DIR .. "/RobotoCondensed%-(%a+)%.ttf$")
Expand Down Expand Up @@ -97,6 +132,7 @@ function Setup.Proof(options)
assets = {
textures = Setup.Texture,
atlases = AtlasTable(ATLASES.atlases),
models = Setup.Model,
fonts = { dirs = { FONT_DIR }, family = Setup.Font, default = FONT_FAMILY, defaultWeight = 500 },
},
})
Expand Down
9 changes: 9 additions & 0 deletions tests/proof/units.lua
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,12 @@ local function NoBorder(ns)
ns.Config:SetUnitValue("player", "border.enabled", false)
end

local function Enable(unit, keys)
return function(ns)
for _, key in ipairs(keys) do ns.Config:SetUnitValue(unit, key .. ".enabled", true) end
end
end

local function ThickAuraBorder(ns)
ns.Config:SetUnitValue("target", "auras.border", { enabled = true, border = "Blizzard Tooltip", size = 10, padding = 2 })
end
Expand All @@ -45,13 +51,16 @@ return {
{ name = "player-idle", build = UnitFrame("player", { showCast = false }) },
{ name = "player-tooltip-border", build = UnitFrame("player", { showCast = false }, TooltipBorder) },
{ name = "player-no-border", build = UnitFrame("player", { showCast = false }, NoBorder) },
{ name = "player-dead", build = UnitFrame("player", { status = "dead", showCast = false }) },
{ name = "player-overheal", build = UnitFrame("player", { health = 22000, heal = 7000, showCast = false }, EnableOverheal) },
{ name = "target", build = UnitFrame("target") },
{ name = "target-35pct", build = UnitFrame("target", { health = 8400, showCast = false }) },
{ name = "target-aura-border", build = UnitFrame("target", { showCast = false }, ThickAuraBorder) },
{ name = "target-aura-wide", build = UnitFrame("target", { showCast = false }, WideAuras) },
{ name = "targettarget", build = UnitFrame("targettarget") },
{ name = "focus", build = UnitFrame("focus") },
{ name = "focus-portrait", build = UnitFrame("focus", { showCast = false }, Enable("focus", { "portrait" })) },
{ name = "focustarget", build = UnitFrame("focustarget") },
{ name = "pet", build = UnitFrame("pet") },
{ name = "pet-portrait", build = UnitFrame("pet", nil, Enable("pet", { "health", "power", "portrait" })) },
}
23 changes: 23 additions & 0 deletions wowproof/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ the adapter's job.
| `Text(r)` | nil, or for font strings `{ text, font, size, flags, color, justifyH, justifyV }` |
| `FillOf(r)` *(optional)* | the status bar whose fill texture `r` is; the fill then gets its rect from the bar value |
| `ClipsChildren(r)` *(optional)* | whether the frame clips its children |
| `Model(r)` *(optional)* | nil, or for model frames (`Scene.MODEL_TYPES`) `{ unit, file, displayId, creatureId, zoom, modelAlpha, desaturation }`; all sources nil once cleared |

`wowproof.scene` validates adapters and lists the strata and draw-layer order.
`wowproof.adapters.mock_state` covers mocks that keep widget state in
Expand All @@ -80,6 +81,11 @@ the adapter's job.
texture coordinates (crops, mirrors, rotations and tiling beyond 0–1, such as backdrop edges)
- atlases, cropped to their sub-rectangle; later texture coordinates map into it
- anything else as a dashed placeholder titled with its path or atlas name
- **Models:** `PlayerModel` and the other model frames through `assets.models(info)`, which gets
the adapter's `Model(r)` and returns a texture path (resolved through `assets.textures`),
`{ file, texCoords }`, or `{ path, texCoords }` for a local image used as is. The image covers the frame (centre-cropped to its aspect) at the frame's
alpha times the model alpha, desaturated by the model's desaturation. Without art it's a dashed
placeholder titled `model: <unit>`; a cleared model draws nothing.
- **Status bars and text:** status bar fills by value, and font strings with justification, outline and `|c` colour codes.

Rendering is deterministic: the same scene gives the same SVG.
Expand Down Expand Up @@ -126,6 +132,23 @@ assets.atlases = require("wowproof.sources.atlas_table")(pinnedAtlases)

Tiling atlases draw once, not repeated, and flipbooks show their whole sheet.

Models can't be rendered without the client, so a host maps them to stand-in
art. `wowproof.sources.remote_dir` copies named files once from a private
folder (`host:/dir` over `ssh`, an `https://` URL, or a local folder) into a
cache, for example in-game captures that must not live in the repository:

```lua
local captures = require("wowproof.sources.remote_dir")({ remote = "nas:/srv/captures", dir = ".proof-art/captures" })
```

A race portrait for player units, from the mirror:

```lua
assets.models = function(info)
if info.unit then return { file = "Interface\\CharacterFrame\\TemporaryPortrait-Male-Human", texCoords = { 0.14, 0.86, 0.14, 0.86 } } end
end
```

## Tests

`spec/` holds busted-style specs (`describe`/`it`/`assert.*`) that need
Expand Down
24 changes: 24 additions & 0 deletions wowproof/adapters/mock_state.lua
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
local Scene = require("wowproof.scene")

return function(options)
options = options or {}
local isSecret = options.isSecret or function() return false end
Expand Down Expand Up @@ -174,6 +176,28 @@ return function(options)
}
end

local MODEL_SOURCES = { SetUnit = "unit", SetModel = "file", SetDisplayInfo = "displayId", SetCreature = "creatureId" }

function adapter.Model(region)
if not Scene.IsModel(adapter, region) then return nil end
local state = State(region)
local info = { zoom = 0, desaturation = 0 }
for _, call in ipairs(rawget(region, "__calls") or {}) do
local name = call[1]
if name == "ClearModel" or MODEL_SOURCES[name] then
info.unit, info.file, info.displayId, info.creatureId = nil, nil, nil, nil
if MODEL_SOURCES[name] then info[MODEL_SOURCES[name]] = Plain(call[2]) end
elseif name == "SetPortraitZoom" then
info.zoom = Plain(call[2])
elseif name == "SetDesaturation" then
info.desaturation = Plain(call[2])
end
end
local modelAlpha = Plain(state.modelAlpha)
info.modelAlpha = modelAlpha == nil and 1 or modelAlpha
return info
end

local function FontObject(value)
if type(value) == "string" then value = globals[value] end
if type(value) == "table" and rawget(value, "__state") then return value end
Expand Down
22 changes: 17 additions & 5 deletions wowproof/init.lua
Original file line number Diff line number Diff line change
Expand Up @@ -28,24 +28,34 @@ function Proof.New(options)
}, Proof)
end

function Proof:Image(file)
local cached = self.images[file]
local function LoadImage(self, key, locate)
local cached = self.images[key]
if cached == nil then
local resolve = self.assets.textures
local localFile = resolve and resolve(file)
local localFile = locate()
local png = localFile and Raster.ToPng(localFile, self.cacheDir)
local uri = png and Raster.DataUri(png)
cached = false
if uri then
local width, height = Raster.PngSize(png)
cached = { uri = uri, width = width, height = height }
end
self.images[file] = cached
self.images[key] = cached
end
if not cached then return nil end
return cached.uri, cached.width, cached.height
end

function Proof:Image(file)
return LoadImage(self, file, function()
local resolve = self.assets.textures
return resolve and resolve(file)
end)
end

function Proof:File(path)
return LoadImage(self, "path:" .. path, function() return path end)
end

local function Pixel(value, size)
return math.floor(value * size + 0.5)
end
Expand Down Expand Up @@ -104,8 +114,10 @@ function Proof:Render(region, options)
debug = options.debug,
background = options.background,
image = function(file) return self:Image(file) end,
file = function(path) return self:File(path) end,
atlas = function(name) return self:Atlas(name) end,
font = function(file) return self:Font(file) end,
model = function(info) return self.assets.models and self.assets.models(info) end,
})
end

Expand Down
65 changes: 61 additions & 4 deletions wowproof/paint.lua
Original file line number Diff line number Diff line change
Expand Up @@ -354,11 +354,64 @@ function Context:DrawTexture(region, rect, alpha)
self:Emit(string.format('<rect %s %s%s/>', RectAttributes(rect), Fill(texture.vertexColor, alpha), blend))
return
end
if texture.file or texture.atlas then
self:Emit(string.format('<rect %s %s stroke="%s" stroke-opacity="0.5" stroke-dasharray="2 2"><title>%s</title></rect>',
RectAttributes(rect), Fill(PLACEHOLDER_COLOR, alpha), Rgb(PLACEHOLDER_COLOR),
Escape(texture.file or texture.atlas)))
if texture.file or texture.atlas then self:DrawPlaceholder(rect, alpha, texture.file or texture.atlas) end
end

function Context:DrawPlaceholder(rect, alpha, title)
self:Emit(string.format('<rect %s %s stroke="%s" stroke-opacity="0.5" stroke-dasharray="2 2"><title>%s</title></rect>',
RectAttributes(rect), Fill(PLACEHOLDER_COLOR, alpha), Rgb(PLACEHOLDER_COLOR), Escape(title)))
end

local function CoverRect(source, target)
if source.width <= 0 or source.height <= 0 or target.width <= 0 or target.height <= 0 then return source end
local aspect = target.width / target.height
if source.width / source.height > aspect then
local width = source.height * aspect
return { left = source.left + (source.width - width) / 2, top = source.top, width = width, height = source.height }
end
local height = source.width / aspect
return { left = source.left, top = source.top + (source.height - height) / 2, width = source.width, height = height }
end
Paint.CoverRect = CoverRect

local function ModelSubject(info)
return info.unit or info.file or (info.displayId and "display " .. info.displayId)
or (info.creatureId and "creature " .. info.creatureId)
end
Paint.ModelSubject = ModelSubject

function Context:DrawModel(region, rect, alpha)
local info = self.adapter.Model and self.adapter.Model(region)
if not info then
self:DrawPlaceholder(rect, alpha, "model: " .. self.adapter.Type(region))
return
end
local subject = ModelSubject(info)
alpha = alpha * Clamp(info.modelAlpha or 1)
if not subject or alpha <= 0 then return end
local art = self.model(info)
if type(art) == "string" then art = { file = art } end
local image
if art and art.path then
image = self:ImageDef("path:" .. art.path, function() return self.file(art.path) end)
elseif art and art.file then
image = self:ImageDef(art.file, function() return self.image(art.file) end)
end
if not image or not image.width then
self:DrawPlaceholder(rect, alpha, "model: " .. subject)
return
end
local filter = ""
local desaturation = Clamp(info.desaturation or 0)
if desaturation > 0 then
local id = self:Define(string.format(
'<filter id="{id}" color-interpolation-filters="sRGB"><feColorMatrix type="saturate" values="%s"/></filter>',
Number(1 - desaturation)))
filter = string.format(' filter="url(#%s)"', id)
end
self:Emit(string.format('<g opacity="%s"%s>', Number(alpha), filter))
self:DrawImagePiece(image, rect, CoverRect(SourceRect(art.texCoords, image.width, image.height), rect))
self:Emit("</g>")
end

function Context:DrawBar(region, alpha)
Expand Down Expand Up @@ -438,6 +491,8 @@ function Paint.Render(options)
image = options.image or function() return nil end,
atlas = options.atlas or function() return nil end,
font = options.font or function() return nil end,
model = options.model or function() return nil end,
file = options.file or function() return nil end,
defs = {},
body = {},
images = {},
Expand Down Expand Up @@ -472,6 +527,8 @@ function Paint.Render(options)
context:DrawTexture(entry.region, entry.rect, entry.alpha)
elseif kind == "FontString" then
context:DrawText(entry.region, entry.rect, entry.alpha)
elseif Scene.IsModel(adapter, entry.region) then
context:DrawModel(entry.region, entry.rect, entry.alpha)
elseif not adapter.FillOf and not Scene.IsRegion(adapter, entry.region) then
context:DrawBar(entry.region, entry.alpha)
end
Expand Down
1 change: 1 addition & 0 deletions wowproof/raster.lua
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,7 @@ local function NonEmpty(file)
handle:close()
return size > 0
end
Raster.NonEmpty = NonEmpty

function Raster.Download(url, target, headers)
Raster.MakeDir(target:match("^(.*)/[^/]+$") or ".")
Expand Down
8 changes: 7 additions & 1 deletion wowproof/scene.lua
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Scene.REQUIRED = {
"Texture", "Bar", "Text",
}

Scene.OPTIONAL = { "FillOf", "ClipsChildren" }
Scene.OPTIONAL = { "FillOf", "ClipsChildren", "Model" }

Scene.SOLID_FILES = {
["interface\\buttons\\white8x8"] = true,
Expand All @@ -21,6 +21,12 @@ end

Scene.REGION_TYPES ={ Texture = true, FontString = true, Line = true, MaskTexture = true }

Scene.MODEL_TYPES = { Model = true, PlayerModel = true, DressUpModel = true, CinematicModel = true, TabardModel = true }

function Scene.IsModel(adapter, region)
return Scene.MODEL_TYPES[adapter.Type(region)] == true
end

Scene.STRATA = {
"WORLD", "BACKGROUND", "LOW", "MEDIUM", "HIGH", "DIALOG", "FULLSCREEN", "FULLSCREEN_DIALOG", "TOOLTIP",
}
Expand Down
Loading
Loading