linux-wallpaperengine-kde/tools/wecompare

wecompare - library inventory and comparison against the real Wallpaper Engine

Tools to scan a workshop library for features, render every wallpaper with this engine and with the real Wallpaper Engine (2.8.x, Windows build under Wine + DXVK on an isolated display), and compare the two.

Data locations (all overridable):

what	default	env
workshop items	/workspace/SteamLibrary/steamapps/workshop/content/431960	LWE_WORKSHOP_DIR
WE assets	/workspace/SteamLibrary/steamapps/common/wallpaper_engine/assets	LWE_ASSETS_DIR
feature database, results	~/.local/share/lwe-library	LWE_LIBRARY_DIR
Wine prefix + WE install copy	~/.local/share/we_live	WE_LIVE_DIR
WE reference frames	~/.local/share/we_live/refs/<id>/f*.png	REFS

Scripts

• scan.py [ids] - feature scan (reads scene.pkg in memory, well under a second for 100+ items). Writes features.json and FEATURES.md (feature -> item ids, rarest first) and prints new/removed items.
• render_we.py [ids | scene paths] - real WE reference frames, ~12s per item (~30s for 100+ object scenes): a fresh WE per item that is captured as soon as the first frame is rendered instead of after fixed sleeps. Skips items that already have frames unless FORCE=1. Scene dirs/files (test variants) go to $REFS/<dir name>. FRAMES, INTERVAL, SETTLE, SWITCH_TIMEOUT (per attempt), RETRIES (new instances while the window stays flat, video-texture scenes need that sometimes) tune the capture. Reusing one instance via -control openWallpaper doesn't work under Wine (the command only re-shows the UI window).
• render_ours.sh <outdir> [ids] - headless GPU render of this engine at the WE window size (1920x1058), frame 600 at 30 fps. LWE=<dir> picks another build (the dir needs its own copy of the lib .so).
• compare.py <ours dir> <review dir> [ids] - scores against the closest WE frame (they animate), writes <id>.png (WE | ours, diff heat below), 4-item sheet_*.png for skimming and scores.json (mean diff, area with big differences, WE frame-to-frame motion, global shift by phase correlation).
• frames.py <id> <ours.png> <out.png> - all WE frames plus ours in one grid, to tell animation from real differences.
• crop.py <id> <ours.png> <out.png> x y w h [zoom] - same region of both side by side.

wine/ has the lower level real-WE helpers:

• we_display.sh - starts the isolated display :98 (headless weston + Xwayland in a private runtime dir).
• we_full.sh <scene> <outdir> [count] [interval] - single cold run with full-screen grabs.
• we_cursor.sh <scene> <outdir> "x,y x,y" [settle] - warps the pointer before each grab (parallax, cursor).
• we_capture.sh <scene> [secs] - RenderDoc capture of one WE frame (inspect with tools/rdc_dump.py on :98, rdscripts/ has the replay scripts).
• repack_pkg.py in.pkg out.pkg name=file ... - replaces files inside a scene.pkg (test variants of scenes whose texture names Wine can't open in folder mode).

Regression pass after engine changes

./render_ours.sh /tmp/ours [ids] && ./compare.py /tmp/ours /tmp/review [ids]

WE refs only need re-rendering when the item was updated on the workshop (mtime in features.json). Pick targets by feature from FEATURES.md.

Setting up the WE side (once per WE_LIVE_DIR)

mkdir -p $WE_LIVE_DIR/we28 && cd $WE_LIVE_DIR/we28
cp <wallpaper_engine>/distribution/wallpaper64.exe <wallpaper_engine>/distribution/version.json .
ln -s <wallpaper_engine>/distribution/bin bin; ln -s <wallpaper_engine>/assets assets
ln -s <wallpaper_engine>/distribution/plugins plugins
bash wine/we_display.sh
WINEPREFIX=$WE_LIVE_DIR/wineprefix DISPLAY=:98 wine64 wineboot --init
WINEPREFIX=$WE_LIVE_DIR/wineprefix dxvk-setup install -s -y

For RenderDoc: mkdir -p $WE_LIVE_DIR/vklayer; cp wine/renderdoc_capture.json $WE_LIVE_DIR/vklayer/; cp wine/rd_trigger.py $WE_LIVE_DIR/, and cp wine/qrenderdoc_analytics.json ~/.local/share/qrenderdoc/analytics.json (the first-run analytics dialog blocks the trigger script otherwise). Set "postprocessing": "enabled" in we28/config.json (WE's default; disabled turns bloom off and shows up as false differences).

Pitfalls

• Audio: if the desktop's audio server socket is reachable (e.g. a shared /run/user/<uid>/pulse), Wine and this engine both connect to it. WE then plays wallpaper sounds on real speakers and both sides pick up real system audio, so audio-reactive layers differ between runs. All scripts point PULSE_SERVER / PIPEWIRE_REMOTE at dead sockets; keep that in anything new (verify with strace -f -e trace=connect).
• Never use :0 for WE. DXVK crashes on Xvfb (0 Hz mode), hence weston + Xwayland on :98.
• Scores are only a triage hint: scroll/shake/particles, wall-clock texts and heavily downscaled 8K scenes score high while matching. Check frames.py before calling something different.
• Web wallpapers can't be compared (WE's CEF under Wine renders a white page, this engine renders black headless). The video wallpaper type is black in WE under Wine (video textures inside scenes do play).
• Texts using systemfont_* aren't drawn by WE under Wine (the prefix has no Windows fonts).
• Folder scenes with CJK texture names fail to load textures in WE under Wine: pass scene.pkg (or repack).
• Crop: WE window = [30:1080, 4:1920] of the :98 screen, ours [0:1050, 0:1916].