Repository navigation
WE Fidelity Principles
Open Wallpaper Engine's goal is to run every Wallpaper Engine wallpaper except application, and to draw each one the way Wallpaper Engine draws it. This page explains the principles behind that and how behaviour is verified.
Wallpaper Engine's own shaders, effect definitions, materials and formats are the reference. OWE runs WE's GLSL through the shader translator instead of hand-written Metal "equivalents". The early renderer had around 48 native approximations; they were technical debt and have been replaced by WE's own passes.
No special case may be keyed on a layer, effect, file or property name ("cloud", "clock", "snow", "4k"…). When a wallpaper renders wrong, the fix is the missing general feature, which then fixes every wallpaper that uses it. Past heuristics (a snow-particle check, a "4k" particle scale, a parallax fallback depth, textures generated from their names, a sidebar toggle singled out by name) were found by sweeps and removed. WE's own type identifiers (sprite, rope…) are data, not names.
Compatibility data that WE itself ships (its per-item web patches in zcompat) is applied, because it is WE's behaviour.
Every default, threshold, range, step, option list, label and unit comes from WE's data: effect.json, materials, shader annotations and [COMBO] lines, project.json properties, the scene.json general block, particle JSON and SceneScript's createScriptProperties. No invented constants or magic factors. Where WE authors nothing, OWE uses WE's own engine default and records where it comes from. WEAuthoredValuesTests checks the values the app shows and uses against WE's own data.
Render on the GPU. Don't silently cap effects, passes, shaders or particles. Where a limit helps performance (the particle budget, texture resolution, scene detail, render resolution), it is a user setting mirroring WE's own settings where WE has one, with a full-quality option ("Unlimited", "Full (Wallpaper Engine)").
A shader that fails, a layer that can't decode, a script that throws: logged once, with the wallpaper, layer and reason. Caches are keyed on their inputs and a code revision. See Contributing.
State belongs to a wallpaper instance, so two wallpapers (or one wallpaper with two sets of properties) never interfere.
Wallpaper Engine is a Windows app and cannot run on the development Macs. Ground truth therefore comes from what WE ships and documents, and from captures made on Windows:
| Source | Used for |
|---|---|
| WE's shipped files | Shaders, effect and material definitions, util passes, the SceneScript prelude and modules, UI strings: the reference for rendering, taken from a local install |
| WE's official documentation and editor type declarations | The SceneScript API surface, user properties, effects |
| Analysis of WE's program files | Behaviour the documentation doesn't state (clock stepping, timeline maths, particle flags, text layout, shadow packing). The design documents describe the resulting behaviour in prose and cite where it was found; code is never copied |
| Reference captures | WE's rendered stills and clips of real wallpapers and purpose-built test projects, compared with OWE's frames (WEReferenceComparisonTests, model and puppet ground truths) |
| Reference models | Small scripts in Scripts/ (timeline-reference.py, mdl-reference.py, skinning-reference.py, lightingv1-reference.py) that model WE's maths for bit-exact comparisons |
| Library sweeps | Every wallpaper in a real library loaded, translated, simulated and drawn, to find failures (LibrarySweepTests and friends) |
| Other implementations | linux-wallpaperengine and wallpaper-scene-renderer, compared but not trusted over WE's own evidence |
Where the evidence leaves a value open, the plans mark it as open or as an inference, instead of guessing silently. Items that need new captures are listed under "needs WE ground truth" in docs/test-risks.md.
User guide: Scene wallpapers
Open Wallpaper Engine · GPL-3.0 · Released by Deepratna Awale · Based on Open Wallpaper Engine by Haren Chen and MrWindDog · Not affiliated with Wallpaper Engine or Valve · Home · User Guide · Developer Guide