AGENTS.md

EverQuest client config and a minimal classic UI skin (UISkin=isuldor) maintained as unified diffs against uifiles/default/.

Docs

Install paths and INI layout: docs/steam-linux-paths.md
2026 theme refresh (what broke, what we changed): docs/ui-theme-2026-refresh.md

Patch-set model (advice)

We patch six EQUI_*.xml files plus two dark_tile_*.tga textures — not a full skin fork. That is intentional.

Do	Avoid
Keep the patch set small (persistent on-screen windows only)	Copying all of `uifiles/default/` into git
Patch `uifiles/default/` → install to `uifiles/isuldor/`	Patching `uiresources/` / `AtlasSkin` (HTML/Cohtml panels)
Run `bash ui/verify.sh` before every commit and after every game patch	Relying on `patch --fuzz 3` without a dry-run
Regenerate diffs with `bash ui/install.sh --update` (CRLF-aware)	Hand-editing diffs or `diff -u` from LF-only XML
Budget manual re-merge for `EQUI_PlayerWindow` after major client updates	Expecting every patch to apply for years unchanged

Highest-churn files: EQUI_PlayerWindow.xml (roles, aggro, meters), then EQUI_HotButtonWnd.xml (many slot animations). Everything else has been stable across years.

Pin the client you verified against: ui/.verified-build (eqgame mtime, patch list). Refresh with bash ui/verify.sh --record after a successful in-game check.

Non-obvious details

Two UI trees: UISkin → uifiles/<name>/ (XML we patch). AtlasSkin → uiresources/<name>/ (modern panels; out of scope — stay stock Default).
Stock XML is CRLF. uifiles/default/*.xml use Windows line endings. LF-only merged files produce giant whole-file diffs; install.sh --update normalizes to CRLF when the default file is CRLF.
patch --fuzz 3 helps when line numbers drift (e.g. EQUI_Animations) but can apply the wrong hunk if context is ambiguous. Verify always uses dry-run; treat any future FAILED on PlayerWindow as a hand-merge, not a fuzz tweak.
Textures: Register new .tga only in EQUI_Animations.diff; reference by filename elsewhere. install.sh copies ui/*.tga into uifiles/isuldor/.
Theme vs layout: XML = chrome/templates. Window positions and fade % live in UI_<Char>_<Server>_<Class>.ini (UISkin, fades). Chat colors in eqclient.ini [TextColors]. Client updates can stomp INIs — keep canonical copies in this repo.
EQType on labels: The player-window theme uses shadow labels and specific EQTypes (e.g. HP 17, mana 124) so text overlays gauges; stock uses different types — do not “fix” to match default without checking in-game.
Required stub labels: HPPerLabel / ManPercLabel / FatiguePercLabel must exist as minimal <Label> pieces (ScreenID only) or the client breaks.
Install script: Use bash ui/install.sh (shebang can fail on some mounts). EQ_GAME_PATH overrides auto-detect (Steam Linux path is tried first).
Game path detection: Looks for eqgame.exe in install root (including Proton/Steam Linux .exe name).

Lint / verify (run before commit)

From repo root:

# 1. Patches apply cleanly against live uifiles/default/
bash ui/verify.sh

# 2. Optional: fail if eqgame.exe changed since ui/.verified-build
bash ui/verify.sh --strict

# 3. After game patch + in-game smoke test — update pin file
bash ui/verify.sh --record

Install + verify together:

bash ui/install.sh && bash ui/verify.sh

After editing uifiles/isuldor/ in-game or by hand:

bash ui/install.sh --update   # regenerate *.diff (CRLF-safe)
bash ui/verify.sh --record

Manual checks (no automated linter for EQ UI XML):

No duplicate <Pieces> entries in EQUI_PlayerWindow (easy to introduce when merging).
grep -c Player_HPLabelShadow in built XML — should appear twice (element + one Pieces line), not three.
Diff size sanity: EQUI_PlayerWindow.diff should be hundreds of lines, not 1500+ (signals CRLF/LF mismatch).

In-game smoke test (after client update): player window (HP/mana/XP/AA, group roles, aggro), hotbars, chat, spell window; inventory/AA should still look like Default.

Workflow summary

game patch → bash ui/install.sh → bash ui/verify.sh
          → fix failed hunks (usually EQUI_PlayerWindow) → install.sh --update → verify.sh --record
          → set UISkin=isuldor in UI INI → login smoke test

4.5 KiB Raw Blame History