Assets System

Assets system

Open Wallpaper Engine ships no Wallpaper Engine files, in the repository or the app. Scenes read WE's assets from the user's own copy at run time. This page covers the resolver, the cache layout, the SteamCMD-based installer, default wallpapers and fill-assets-cache.sh.

The resolver (Core/WallpaperEngineAssets)

Assets are looked up in this order:

#	Source	Details
1	Chosen folder	A WE install (or its assets folder) chosen in Settings › Assets; stored under the defaults key WallpaperEngineAssetsDirectory; read in place
2	Cache	<Wallpaper Storage>/.owe-assets, filled from the user's Steam copy
3	None	Scenes show that they need the assets; video and web still play

• A folder counts as an asset tree when it has shaders and effects. For an install, its assets child is used.
• Under XCTest only OWE_ASSETS counts (source testEnvironment), so a developer's install or cache never leaks into tests.
• WallpaperEngineAssetsService publishes the status and posts a change so running wallpapers reload.

Cache layout (Core/WallpaperEngineAssetsCache)

The cache keeps only what wallpapers use:

Folder	Contents
effects/	Effect manifests, without editor preview art
presets/	The editor's particle presets, without their preview projects
shaders/	GLSL shaders and shared headers, without Direct3D (HLSL/) or editor shaders
fonts/, materials/, models/, particles/, scripts/, zcompat/	Copied whole (wholeFolders)
locale/ui_*.json	WE's UI strings (from beside assets), which translate label keys
Info file	What the cache was filled from: origin (Steam or folder), Steam build ID, install date, the default projects added

fill(_:from:) builds the new copy beside the old one and swaps it in, so a failure or cancellation leaves the previous cache intact. Folders are created only when they get a file.

Installing from Steam (Workshop/WallpaperEngineAssetsService, WallpaperEngineAssetsDownload)

1. Requires SteamCMD and a cached login (the Workshop login).
2. Runs SteamCMD with app_update 431960 validate into a staging folder inside the storage folder, with progress parsed from its output.
3. Copies the subset into the cache, then deletes the download.
4. Imports WE's default wallpapers from projects/defaultprojects into the storage folder (WallpaperEngineDefaultProjects). Only scene, video and web projects come in; application projects are skipped. Their folder names are recorded so Remove… can offer to remove them too (to the Trash).

SteamCMD installer (Workshop/SteamCmdInstaller, SteamCmdPackage)

• Downloads Valve's macOS package from the URL on Valve's SteamCMD wiki page, over HTTPS, at run time; never shipped.
• Checks the gzip magic, extracts with the system tar, clears the quarantine flag, verifies steamcmd.sh, then runs it once with quit so it updates itself.
• Installs into <Application Support>/Open Wallpaper Engine/steamcmd (or the isolated sibling).
• autoInstallIfNeeded runs at launch and when the Workshop tab or Assets page opens, when no working SteamCMD was found and Install SteamCMD automatically is on. A failed automatic install waits for the next such moment.
• SteamCmdLocator finds existing copies: the user's choice (SteamCmdPath), OWE's own copy, Homebrew prefixes, Steam, /Applications; a GUI app has a minimal PATH, so prefixes are checked directly and a login shell is asked last. OWE_STEAMCMD_SEARCH_ROOT redirects the search for testing.

Scripts/fill-assets-cache.sh

A development helper that copies the same subset from a local WE install:

Scripts/fill-assets-cache.sh <WE install or its assets dir> [destination]

• The destination defaults to ~/Documents/Open Wallpaper Engine/.owe-assets (the app's cache in the default storage folder).
• Point it at a folder of your own and set OWE_ASSETS to run the asset-dependent tests.
• Nothing it copies may be committed.

Rules

• Never add WE files to the repository, the app or Tests/Fixtures. Fixtures are written for the project.
• A test that needs assets starts with _ = try Fixtures.assets() and skips without OWE_ASSETS.

User guide: Wallpaper Engine assets