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: 2 additions & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@ jobs:
persist-credentials: false
- name: Verify the generated spell catalogue against pinned exports
run: python3 -B scripts/spell_catalog.py --fetch --check
- name: Verify the generated proof atlas table against pinned exports
run: python3 -B scripts/atlas_catalog.py --fetch --check
- name: Run all tests and addon syntax checks
run: bash scripts/run-tests.sh --times -j
- name: Cache Blizzard interface art for UI proof
Expand Down
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@

- `UnitFrames/Core/`: namespace/bootstrap, schema, AceDB configuration, theme, media, colours and text formats. Core Lua files receive `local _, ns = ...`; the public `UnitFrames` handle exposes that namespace to companion addons.
- `UnitFrames/Tracking/`: data-only DoT damage estimates (tracking ported from DoesItDie, MIT). `DotSpells` reads generated numeric metadata, never descriptions. `ns.DotTracker` runs only while `Acquire`d on the exact catalogue client build, checks player-known spell IDs, keys active DoTs by generated family and learns ticks per rank. It matches `UNIT_COMBAT` on target/focus, fires `DotsChanged(key)` and fills reused lists through `Breakdown`. In combat `UNIT_COMBAT` amounts are secret: those hits match on school and rhythm alone (never drop them, or every DoT looks resisted) and are tallied per spell; on `PLAYER_REGEN_ENABLED` the `C_DamageMeter` per-spell totals, minus the generated `directPoints` upfront hit, become weighted average ticks. Fights with unseen ticks, several combo-point sizes or a dominant upfront hit are not learned. Learned tick sizes and weights live in AceDB `global`.
- `tests/proof/atlases.lua` is generated by `python3 -B scripts/atlas_catalog.py` from Wago atlas exports for the same pinned Forever build (manifest in `data/forever-atlases/`). Regenerate it after adding a `SetAtlas` call, so UI proof draws the atlas.
- `Tracking/DotCatalog.lua` is generated by `python3 -B scripts/spell_catalog.py` from checksum-verified Wago exports cached under ignored `examples/forever-spells/<build>/`. Only the manifest (`data/forever-spells/manifest.json`), generated Lua and small native-record fixtures are tracked. It must match the exact Forever UI-source build/commit in both workflows and the TOC interface. `scripts/update-blizzard-source.sh` refreshes both sources; `--fetch --check` populates a fresh cache and validates regeneration in CI. Ordinary tests use `--check-pin` and the small fixtures offline. The ignored `catalog.json` audits periodic candidates and exclusions; CI uploads it as an artifact. Channels are excluded. Runtime only accepts player-known spells. Combo builders, finishers, rank families and projectile flags are generated. Agony's uneven shape remains an explicit family-ID exception in `DotSpells`; baseline damage is unmodified client data until ticks are learned.
- Pending DoT damage: `Components/PendingDamage.lua` is owned by Bar (`spec.pendingDamage`, health rows) like Overheal; the `pendingDamage` frame driver binds `UF_PendingDamage` (Elements.lua), and the health `PostUpdate` (`ufHealthHooks`) gives it the secret scale and current health.
- `UnitFrames/Components/`: reusable visual building blocks. Keep them independent of oUF bindings; their configuration and data APIs also serve previews. `UnitFrame` exposes rows and optional parts through `GetRow(key)`/`GetPart(key)` and the `Rows()`/`Parts()` iterators; add a part to `UnitFrame.PARTS` rather than adding per-part getters. Ready-check state lives in the `ReadyCheck` presenter (`GetReadyCheck()`), which also owns its settings schema.
Expand Down Expand Up @@ -102,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 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, an atlas the generated table lacks or a portrait model, not a bug; 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
21 changes: 20 additions & 1 deletion DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -264,9 +264,28 @@ commit that art. `UF_PROOF_ART` picks another cache folder, and
`UF_PROOF_ART_FETCH=0` stays offline. Set `GH_TOKEN` or `GITHUB_TOKEN` if
GitHub's API rate limit bites.

Atlases (`SetAtlas`) come from `tests/proof/atlases.lua`, which
`scripts/atlas_catalog.py` generates from Wago's `UiTextureAtlas`,
`UiTextureAtlasMember` and `UiTextureAtlasElement` exports for the pinned
Forever build. It keeps only the atlases the addon and oUF elements name: dashed
string literals in files that mention atlases, plus `"prefix-" .. value`
concatenations. Where an atlas has several members, it takes the 1x one and
prefers Forever's `-c60` variant. The sheets are downloaded by file ID from
Wago for the same build into `.proof-art/casc-<build>/`. Don't edit the
generated table:

```sh
python3 -B scripts/atlas_catalog.py --update # fetch exports for the pinned build and regenerate
python3 -B scripts/atlas_catalog.py # regenerate from the cached exports
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.

Still drawn as dashed placeholders:
- art the mirror lacks, listed in `.proof-art/missing-<commit>.txt`
- atlases (`SetAtlas`), which need Blizzard's atlas table
- atlases the generated table lacks
- portrait models

### Pull request checks
Expand Down
4 changes: 2 additions & 2 deletions UnitFrames/Units/Definitions.lua
Original file line number Diff line number Diff line change
Expand Up @@ -345,14 +345,14 @@ Units.SAMPLE = {
{ icon = [[Interface\Icons\Spell_Nature_Rejuvenation]], duration = 12, remaining = 5, sourceUnit = "party1", isRaidInCombat = true },
{ icon = [[Interface\Icons\Spell_Nature_ResistNature]], duration = 20, remaining = 14, sourceUnit = "party1" },
{ icon = [[Interface\Icons\Spell_Holy_PowerWordShield]], duration = 30, remaining = 21, sourceUnit = "player" },
{ icon = [[Interface\Icons\Spell_Nature_LifeBloom]], duration = 15, remaining = 9, applications = 3, sourceUnit = "player", isRaidInCombat = true },
{ icon = [[Interface\Icons\INV_Misc_Herb_Felblossom]], duration = 15, remaining = 9, applications = 3, sourceUnit = "player", isRaidInCombat = true },
{ icon = [[Interface\Icons\Spell_Nature_Regeneration]], duration = 0, sourceUnit = "player", isRaid = true },
{ icon = [[Interface\Icons\Spell_Holy_DivineIntervention]], duration = 8, remaining = 5, sourceUnit = "player", isBigDefensive = true, isImportant = true },
{ icon = [[Interface\Icons\Spell_Holy_SealOfProtection]], duration = 10, remaining = 4, sourceUnit = "party1", isExternalDefensive = true },
},
debuffs = {
{ icon = [[Interface\Icons\Spell_Frost_FrostBolt02]], duration = 15, remaining = 7, dispelName = "Magic", sourceUnit = "player", isRaid = true },
{ icon = [[Interface\Icons\Spell_Shadow_CurseOfTongues]], duration = 24, remaining = 18, dispelName = "Curse", sourceUnit = "party1", isRaid = true },
{ icon = [[Interface\Icons\Spell_Shadow_CurseOfTounges]], duration = 24, remaining = 18, dispelName = "Curse", sourceUnit = "party1", isRaid = true },
{ icon = [[Interface\Icons\Spell_Shadow_AbominationExplosion]], duration = 20, remaining = 13, dispelName = "Disease", applications = 2, sourceUnit = "party1", isRaid = true },
{ icon = [[Interface\Icons\Spell_Nature_CorrosiveBreath]], duration = 12, remaining = 6, dispelName = "Poison", applications = 4, sourceUnit = "player", isRaid = true },
{ icon = [[Interface\Icons\Ability_Gouge]], duration = 15, remaining = 11, sourceUnit = "party1", isCrowdControl = true },
Expand Down
24 changes: 24 additions & 0 deletions data/forever-atlases/manifest.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
{
"build": "1.60.1.70862",
"format": 1,
"tables": {
"UiTextureAtlas": {
"filename": "UiTextureAtlas.1.60.1.70862.csv",
"rows": 2826,
"sha256": "a53e784e29c3a42d4a991e843fa1908d15f1fc381c66ac4ecfc508c3b7d19041",
"url": "https://wago.tools/db2/UiTextureAtlas/csv?build=1.60.1.70862&locale=enUS"
},
"UiTextureAtlasElement": {
"filename": "UiTextureAtlasElement.1.60.1.70862.csv",
"rows": 20817,
"sha256": "d5b5244ceefcde365bbdcf925104ddf848ce35554bc182b7d9e06071abc7d262",
"url": "https://wago.tools/db2/UiTextureAtlasElement/csv?build=1.60.1.70862&locale=enUS"
},
"UiTextureAtlasMember": {
"filename": "UiTextureAtlasMember.1.60.1.70862.csv",
"rows": 20685,
"sha256": "000fe3517bb7600aeee97b4465e9c721accd6914dde6ba079ebe00a6e2562d6b",
"url": "https://wago.tools/db2/UiTextureAtlasMember/csv?build=1.60.1.70862&locale=enUS"
}
}
}
221 changes: 221 additions & 0 deletions scripts/atlas_catalog.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,221 @@
import argparse
import csv
import gzip
import io
import json
from pathlib import Path
import re
import subprocess
import sys
import tempfile
from collections import defaultdict

from spell_catalog import canonical, digest, pinned_source, validate_download


ROOT = Path(__file__).resolve().parents[1]
DATA = ROOT / "data/forever-atlases"
CACHE = ROOT / "examples/forever-atlases"
OUTPUT = ROOT / "tests/proof/atlases.lua"
SOURCE_GLOBS = ("UnitFrames*/**/*.lua", "UnitFrames/Libs/oUF/elements/*.lua")
TABLES = {
"UiTextureAtlas": {"ID", "FileDataID", "AtlasWidth", "AtlasHeight"},
"UiTextureAtlasMember": {"ID", "CommittedName", "UiTextureAtlasID", "Width", "Height", "CommittedLeft", "CommittedRight", "CommittedTop", "CommittedBottom", "UiTextureAtlasElementID", "CommittedFlags"},
"UiTextureAtlasElement": {"ID", "Name"},
}
TILES_VERTICALLY, TILES_HORIZONTALLY = 2, 4
LITERAL = re.compile(r"""(["'])([^"'\s\\]*-[^"'\s\\]*)\1""")
CONCATENATION = re.compile(r"""(["'])([^"'\s\\]+-)\1\s*\.\.\s*[\w.:\[\]()]+(?:\s*\.\.\s*(["'])([^"'\s\\]*)\3)?""")


def table_url(name, build):
return f"https://wago.tools/db2/{name}/csv?build={build}&locale=enUS"


def parse_table(name, raw):
reader = csv.DictReader(io.StringIO(raw.decode("utf-8-sig")))
missing = TABLES[name] - set(reader.fieldnames or [])
if missing:
raise ValueError(f"{name}: missing columns {sorted(missing)}")
rows = list(reader)
ids = [int(row["ID"]) for row in rows]
if not rows or len(ids) != len(set(ids)):
raise ValueError(f"{name}: empty table or duplicate IDs")
return rows


def download(pin):
tables, records, compressed = {}, {}, {}
for name in TABLES:
url = table_url(name, pin["build"])
with tempfile.TemporaryDirectory() as directory:
headers = Path(directory) / "headers"
raw = subprocess.check_output(["curl", "--fail", "--silent", "--show-error", "--location", "--max-time", "90", "--dump-header", str(headers), url])
validate_download(name, pin["build"], headers.read_text())
tables[name] = parse_table(name, raw)
compressed[name] = gzip.compress(raw, mtime=0)
records[name] = {"url": url, "filename": f"{name}.{pin['build']}.csv", "sha256": digest(raw), "rows": len(tables[name])}
print(f"Fetched {name}: {len(tables[name])} records", file=sys.stderr)
return tables, {"build": pin["build"], "format": 1, "tables": records}, compressed


def read_manifest(pin):
manifest = json.loads((DATA / "manifest.json").read_text())
if manifest.get("format") != 1 or manifest.get("build") != pin["build"]:
raise ValueError("atlas snapshot does not match the pinned Forever build; run --update")
if set(manifest["tables"]) != set(TABLES):
raise ValueError("atlas snapshot table set changed; run --update")
for name in TABLES:
record = manifest["tables"][name]
if record["url"] != table_url(name, pin["build"]) or record.get("filename") != f"{name}.{pin['build']}.csv":
raise ValueError(f"{name}: source does not match the pinned build")
if not re.fullmatch(r"[0-9a-f]{64}", record["sha256"]) or record["rows"] <= 0:
raise ValueError(f"{name}: invalid checksum or row count")
return manifest


def read_snapshot(pin):
manifest = read_manifest(pin)
tables = {}
for name in TABLES:
record = manifest["tables"][name]
raw = gzip.decompress((CACHE / pin["build"] / f"{name}.csv.gz").read_bytes())
if digest(raw) != record["sha256"]:
raise ValueError(f"{name}: checksum mismatch")
tables[name] = parse_table(name, raw)
if len(tables[name]) != record["rows"]:
raise ValueError(f"{name}: row count mismatch")
return tables, manifest


def write_cache(pin, compressed):
directory = CACHE / pin["build"]
directory.mkdir(parents=True, exist_ok=True)
for name, content in compressed.items():
(directory / f"{name}.csv.gz").write_bytes(content)


def source_files(root=ROOT):
if not (root / "UnitFrames/Libs/oUF/elements").is_dir():
raise ValueError("oUF is missing; run scripts/setup-test-libs.sh first")
files = set()
for pattern in SOURCE_GLOBS:
for path in root.glob(pattern):
relative = path.relative_to(root).as_posix()
if "/Libs/" not in relative or relative.startswith("UnitFrames/Libs/oUF/elements/"):
files.add(path)
return sorted(files)


def atlas_uses(root=ROOT):
literals, patterns = set(), set()
for path in source_files(root):
text = path.read_text(encoding="utf-8")
if not re.search("atlas", text, re.I):
continue
literals.update(match[2].lower() for match in LITERAL.finditer(text))
for match in CONCATENATION.finditer(text):
patterns.add(re.escape(match[2].lower()) + r"[a-z]+" + re.escape((match[4] or "").lower()))
return literals, re.compile("|".join(sorted(patterns))) if patterns else None


def preferred_member(members):
def rank(member):
name = member["CommittedName"].lower()
return (name.endswith("-2x"), not name.endswith("-c60"), int(member["ID"]))
return min(members, key=rank)


def compile_atlases(tables, root=ROOT):
atlases = {row["ID"]: row for row in tables["UiTextureAtlas"]}
members = defaultdict(list)
for row in tables["UiTextureAtlasMember"]:
members[row["UiTextureAtlasElementID"]].append(row)
literals, pattern = atlas_uses(root)
selected = {}
for element in tables["UiTextureAtlasElement"]:
name = element["Name"]
lower = name.lower()
if not members[element["ID"]] or (lower not in literals and not (pattern and pattern.fullmatch(lower))):
continue
member = preferred_member(members[element["ID"]])
atlas = atlases[member["UiTextureAtlasID"]]
width, height = int(atlas["AtlasWidth"]), int(atlas["AtlasHeight"])
flags = int(member["CommittedFlags"])
selected[name] = {
"file": int(atlas["FileDataID"]),
"width": int(member["Width"]),
"height": int(member["Height"]),
"left": int(member["CommittedLeft"]) / width,
"right": int(member["CommittedRight"]) / width,
"top": int(member["CommittedTop"]) / height,
"bottom": int(member["CommittedBottom"]) / height,
"tilesH": bool(flags & TILES_HORIZONTALLY),
"tilesV": bool(flags & TILES_VERTICALLY),
}
if not selected:
raise ValueError("no atlas used by the addon was found in the client tables")
return selected


def lua_atlases(atlases, build):
lines = ["return {", f'\tbuild = "{build}",', "\tatlases = {"]
for name in sorted(atlases, key=str.lower):
info = atlases[name]
fields = [f'file = {info["file"]}', f'width = {info["width"]}', f'height = {info["height"]}']
fields += [f"{key} = {info[key]:.12g}" for key in ("left", "right", "top", "bottom")]
fields += [f'{key} = {"true" if info[key] else "false"}' for key in ("tilesH", "tilesV")]
lines.append(f'\t\t["{name}"] = {{ ' + ", ".join(fields) + " },")
return "\n".join(lines + ["\t},", "}", ""])


def main():
global CACHE
parser = argparse.ArgumentParser()
parser.add_argument("--update", action="store_true")
parser.add_argument("--check", action="store_true")
parser.add_argument("--fetch", action="store_true")
parser.add_argument("--check-pin", action="store_true")
parser.add_argument("--cache", type=Path, default=CACHE)
args = parser.parse_args()
CACHE = args.cache.resolve()
if args.update and (args.check or args.fetch or args.check_pin):
parser.error("--update cannot be combined with validation or --fetch")
if args.check_pin and (args.check or args.fetch):
parser.error("--check-pin cannot be combined with --check or --fetch")
pin = pinned_source()
if args.update:
tables, manifest, compressed = download(pin)
else:
manifest = read_manifest(pin)
if args.check_pin:
if f'build = "{pin["build"]}"' not in OUTPUT.read_text():
raise ValueError("generated atlas table build does not match the source pin")
print(f'Forever {pin["build"]}: atlas table pin verified')
return
if args.fetch:
tables, fetched, compressed = download(pin)
if fetched != manifest:
raise ValueError("downloaded tables do not match the committed checksums; review with --update")
write_cache(pin, compressed)
else:
tables, manifest = read_snapshot(pin)
atlases = compile_atlases(tables)
output = lua_atlases(atlases, pin["build"])
if args.check:
if not OUTPUT.exists() or OUTPUT.read_text() != output:
raise ValueError(f"stale generated artifact: {OUTPUT.relative_to(ROOT)}")
else:
if args.update:
DATA.mkdir(parents=True, exist_ok=True)
write_cache(pin, compressed)
(DATA / "manifest.json").write_text(canonical(manifest))
OUTPUT.write_text(output)
print(f'Forever {pin["build"]}: {len(atlases)} atlases')


if __name__ == "__main__":
try:
main()
except (ValueError, OSError, subprocess.CalledProcessError) as error:
sys.exit(str(error))
1 change: 1 addition & 0 deletions scripts/update-blizzard-source.sh
Original file line number Diff line number Diff line change
Expand Up @@ -34,4 +34,5 @@ for workflow in tests release; do
done
(cd "$repo_dir" && luajit scripts/api-snapshot.lua "$source_dir")
python3 -B "$repo_dir/scripts/spell_catalog.py" --update --source "$source_dir"
python3 -B "$repo_dir/scripts/atlas_catalog.py" --update
echo "Pinned wow-ui-source $commit (Forever $version)"
Loading
Loading