Developer Guide

Developer Guide

This track is for people who want to build Open Wallpaper Engine, understand how it works, or contribute. It summarises the design documents in the repository's docs/ folder and links to them.

Note

The project's goal: run every Wallpaper Engine wallpaper except application, faithfully, with fixes that work for all wallpapers and no per-name hacks. Read WE-fidelity principles before changing rendering code.

Getting started

Page	Contents
Building and running	Xcode 26.3+, the macOS 26 SDK, the scheme, signing, isolated state
Environment variables	Every OWE_* variable
Contributing	Where code goes, the rules, commits and PRs
WE-fidelity principles	How behaviour is matched to Wallpaper Engine and verified

How it works

Page	Contents
Architecture	Modules, dependency rules, data flow, wallpaper instances
Scene pipeline	Format loaders, values and bindings, the renderer, the effect graph, render targets, text
Shader translator	GLSL → SPIR-V → MSL in process, combos, caches, the binary archive
Particles	GPU/CPU simulation parity, children, the budget
Models, puppets and lighting	3D models, puppets, lights, shadows, reflections, bloom/HDR
SceneScript runtime	JavaScriptCore runtime, object table, extensions
Timelines and the SceneClock	Timeline evaluation and the per-wallpaper clock
Audio system	Capture, spectrum, per-consumer clocks, sound layers
Video and web internals	AVKit, Metal video, WebKit WebM, web wallpapers
Assets system	The resolver, cache layout, installer, fill-assets-cache.sh
Workshop and Steam integration	SteamCMD, the Web API, downloads and dependencies
UI, localization and settings storage	Liquid Glass, xcstrings, UserDefaults.app

Shipping

Page	Contents
Testing	Targeted, library, asset-gated and benchmark tests; CI
Releasing	Signing, notarization, secrets, cutting a release
Website	site/ and GitHub Pages
Performance notes	What the optimisation work found and changed
Roadmap and known issues	What's next and what's open

Key documents in the repository

File	What it is
CONTRIBUTING.md	The rules for changing the code
docs/architecture.md	Module layout and invariants
docs/scenescript-plan.md, docs/timeline-plan.md, docs/lighting-plan.md, docs/models-plan.md	Evidence and plans per area
docs/test-risks.md	Adversarial risk list for the renderer and shaders
docs/localization-glossary.md	Terms every translation uses
docs/releasing.md	The release workflow

User guide: User Guide