Environment Variables

Environment variables

Every OWE_* environment variable in the code. The app reads a few (three for state and assets, the rest for comparisons and debugging); the others configure tests, scripts and CI. Through xcodebuild, prefix a test variable with TEST_RUNNER_ (e.g. TEST_RUNNER_OWE_ASSETS=…) so it reaches the test host.

Read by the app

Variable	Read by	Effect
OWE_ISOLATED_STATE=<tag>	AppStorageLocation	Runs with isolated defaults, folders and keychain services (same as -OWEIsolatedState <tag>). See Building and running.
OWE_ASSETS=<folder>	WallpaperEngineAssets	Under XCTest, the only source of WE assets (an assets folder or a WE install). A developer's own install or cache never leaks into tests.
OWE_STEAMCMD_SEARCH_ROOT=<folder>	SteamCmdLocator	Redirects every SteamCMD search location except the user's path and the app's own copy, so a development copy behaves as if no SteamCMD were installed
OWE_ALLOW_DESKTOP_PICTURE=1	DesktopSnapshotCache	Lets an isolated copy change the system desktop picture anyway (a test of that path)
OWE_CEF_NO_SANDBOX=1	ChromiumBrowserHost	Debug builds only: starts the Chromium helper without its sandbox, to tell a sandbox problem from anything else
OWE_IDLE_SKIP=0, OWE_COMPOSITE_SKIP=0, OWE_NATIVE_DETAIL=0	SceneMetalRenderer	For comparisons: draw every frame, always run the composite, draw every layer in the scene pass
OWE_BLUR_DIVISOR=<1, 2, 4>	SceneMetalRenderer	For comparisons: overrides the blur-like buffer divisor of the quality setting

Note

OWE_SHADER_STAGE_VERTEX and OWE_SHADER_STAGE_FRAGMENT appear in InProcessShaderCompiler.swift but are C constants of the shader toolchain's interface, not environment variables.

Test inputs

Variable	Used by	Meaning
OWE_LIBRARY	Library sweeps and benchmarks (LibrarySweepTests, ParticleSimulationSweepTests, TimelineLibrarySweepTests, ModelLibraryRenderTests, SceneFrameBenchmarkTests, …)	Overrides the library root(s); several paths separated by :. Tests skip without a library (as on CI).
OWE_WORKSHOP	MDLLibrarySweepTests, TEXSpriteFramesTests, reference scripts	A Steam Workshop content folder to scan
OWE_WE_INSTALL	MDLLibrarySweepTests, ModelMaterialSweepTests, mdl-reference.py	A Wallpaper Engine install (for default projects)
OWE_TIMELINE_ITEMS	TimelineLibraryScenes	Comma-separated Workshop IDs to keep
OWE_WE_REFERENCE, …_ONLY, …_OUT	WEReferenceComparisonTests, ScenePuppetReferenceTests	WE's captures folder, the IDs to run, where comparison pictures go
OWE_WE_EXTRAS, …_ONLY, …_OUT	WEExtrasComparisonTests	Extra WE capture projects, a subset, and output
OWE_MODELS_GT	ModelGroundTruthLibraryTests	Model ground-truth captures
OWE_MG4_VARIANTS	SceneRootMotionTests	Root-motion variant captures
OWE_PARTICLE_FLAGTESTS	WEParticleGalleryTests	A folder of particle flag test projects
OWE_CURSOR_REQUEST	WECursorCaptureTests	The cursor capture request folder
OWE_ANDROID_SAMPLES, OWE_ANDROID_SAMPLE_ITEM	MobilePackageTests	WE's .mpkg samples; the matching Workshop item's folder
OWE_SLOW_TESTS	SlowTests (the slow tier)	1 runs tests over about a minute; nightly and Scripts/ci-local.sh set it
OWE_TEST_PHASES	TestPhaseTimer	A folder for per-test phase timings (Scripts/ci-run-tests.sh sets it)
OWE_STRICT_THREAD_GUARDS	ThreadGuardTestObserver	1 also fails a test on main-thread guard violations
OWE_RECORD_SHADER_HASH	ShaderRevisionGuardTests	1 records the translated-shader hash after a revision bump
OWE_PROPERTY_SWEEP, …_ITEMS, …_REPORT, …_RESUME	UserPropertySweepTests	1 sweeps the library's user properties; a subset; report folder; resume
OWE_BLUR_LIBRARY	EffectResolutionPolicyTests	Library folders (or all) to compare blur resolutions on

Galleries and picture output

Variable	Used by	Meaning
OWE_EFFECT_GALLERY, …_ONLY, …_OUT	WEEffectGalleryTests	Render every built-in effect; a subset; output folder
OWE_PARTICLE_GALLERY, …_ONLY, …_OUT, …_FRAMES	WEParticleGalleryTests	Render WE's particle presets; a subset (e.g. fire_1); output; 1 writes each clip frame
OWE_MODEL_LIBRARY_ONLY, …_OUT, …_FRAMES	ModelLibraryRenderTests	A subset, a table file, raw last frames and shadow atlases
OWE_GROUND_TRUTH_OUT	Media thumbnail and model ground-truth tests	Where our frames are written
OWE_REFLECTION_OUT	ScenePlanarReflectionObjectTests	A picture for review
OWE_RT_OUT	SceneRegionTransformTests	Before/after pictures
OWE_DISPLAY_HDR_OUT	SceneDisplayOutputTests	The EDR drawable for review
OWE_PUPPET_OUT	ScenePuppetLibraryTests	Source and drawn images per layer
OWE_SWORD_OUT	ScenePuppetCanvasLibraryTests	Frames as PNG

Benchmarks and reports

Variable	Used by	Meaning
OWE_SCENE_BENCH, …_SIZES, …_MODES, …_PASSES, …_TEXTURES, …_JSON	SceneFrameBenchmarkTests	Run on the default scenes or listed IDs; drawable sizes (default 1920x1080 and 4K); render-setting modes (e.g. half); time each effect pass (EffectPassTimer); 1 adds the textures row; JSON rows for later runs to diff
OWE_PACING_METRICS, …_FPS, …_STOP, …_OUT	FramePacingLibraryTests	1 measures frame pacing; frame-rate limit (default 30); stop; output
OWE_TEXTURE_GATE, …_CACHE, …_OUT	TexturePreparationTests	Workshop IDs from OWE_LIBRARY for the texture gate; cache folder; output
OWE_LOAD_BENCH	SceneBackgroundLoadTests	Wallpaper IDs to measure main-thread blocking while loading
OWE_SCENE_DETAIL, …_SIZE, …_MODES, …_OUT	SceneDetailEquivalenceTests	Compare Match Display with Full detail; drawable (default 3840x2160); modes (match, match+desktop, desktop, half); output
OWE_SHARED_BENCH, …_SIZES	SceneSharedInstanceBenchmarkTests	One instance on several displays; display sizes (default 2560x1440,1920x1080)
OWE_TEXTURE_BENCH, …_SIZE, …_PARTICLES, …_OUT, …_BASELINE	SceneTextureLoadBenchmarkTests	Texture loading; drawable; 0 hides particles; output; an earlier run to compare
OWE_LIGHTING_BENCH	LightingFrameBenchmarkTests	Lighting frame costs
OWE_BENCH_ONLY, OWE_BENCH_DETAIL	ParticleLibraryBenchmarkTests	Pick wallpapers; add a row per system
OWE_BENCH_OUT	Frame, lighting, particle and shared-instance benchmarks	Write the results there
OWE_SCRIPT_COST_REPORT	SceneScriptLibraryCostTests	Write the script cost table
OWE_TIMELINE_COST_REPORT	TimelineCostTests	Write the timeline cost table
OWE_REPLAY_REPORT	SceneScriptCorpusReplayTests	Write the corpus replay report
OWE_SCRIPT_PARITY_REPORT	SceneScriptParityTests	Write the script parity report

Scripts, CI and the build

Variable	Used by	Meaning
OWE_CI_LOCAL_DIR	Scripts/ci-local.sh	Build and results folder (default build/ci-local)
OWE_WE_ASSETS_DIR, OWE_TOOLS_DIR	Scripts/fetch-we-assets.sh	Where the downloaded assets and the download tools go
OWE_CI_STEAM_USER, OWE_CI_STEAM_PASSWORD, OWE_CI_STEAM_SHARED_SECRET	Scripts/fetch-we-assets.sh, Scripts/steam_totp.py, workflows	The CI Steam account
OWE_ASSET_CACHE_KEY	.github/actions/we-assets	Key of the encrypted asset cache
OWE_VERSION_LABEL	Build setting (OpenWallpaperEngine-Info.plist)	The version label shown in the app; defaults to $(MARKETING_VERSION)

See Testing for how these fit together.

User guide: Troubleshooting