Engines Overview

Engines Overview

Sucrose renders every wallpaper through one of eight separate rendering executables ("Live engines"), each a standalone WPF process living under src/Live/. A wallpaper has a type (one of six), and Sucrose maps each type to a configurable engine. When you apply a wallpaper, the resolved engine .exe is launched as a child process and draws into the desktop behind your icons. This page explains the engine roster, the EngineType enum, the per-type allowed-engine rules, the default mappings, how an engine is selected and launched, and how it attaches to the desktop.

Table of contents

• The eight engines
• Wallpaper types
• The EngineType enum
• Per-type allowed engines and defaults
• Where you change engines
• How an engine is selected and launched
• Desktop attach (WorkerW / Progman)
• Shared engine layer
• Platform support
• Audio-reactive and system-status wallpapers
• See also

The eight engines

Each engine is a distinct process under src/Live/. They are branded with internal codenames (Aurora, Nebula, Vexana, Xavier) or named after their underlying tech (WebView, CefSharp, MpvPlayer, VlcPlayer).

Engine project	Assembly	Underlying tech	Renders these wallpaper types
Sucrose.Live.MpvPlayer	Sucrose.Live.MpvPlayer.exe	libmpv (native, via Sucrose.Mpv.NET)	Gif, Video
Sucrose.Live.VlcPlayer	Sucrose.Live.VlcPlayer.exe	libVLC (native, via LibVLCSharp.WPF)	Gif, Video
Sucrose.Live.WebView	Sucrose.Live.WebView.exe	Microsoft Edge WebView2 (Chromium)	Gif, Url, Web, Video, YouTube
Sucrose.Live.CefSharp	Sucrose.Live.CefSharp.exe	CEF / CefSharp (Chromium Embedded Framework, windowed HwndHost)	Gif, Url, Web, Video, YouTube
Sucrose.Live.Nebula	Sucrose.Live.Nebula.exe	WPF MediaElement (Windows Media / DirectShow)	Video
Sucrose.Live.Vexana	Sucrose.Live.Vexana.exe	WPF image + in-house frame-by-frame GIF decode	Gif
Sucrose.Live.Xavier	Sucrose.Live.Xavier.exe	Sucrose.XamlAnimatedGif (XAML attached behavior)	Gif
Sucrose.Live.Aurora	Sucrose.Live.Aurora.exe	External process embedding (reparents a real app/game per monitor)	Application

Each engine project defines the ENGINE preprocessor symbol plus an engine-specific symbol (LIVE_MPVPLAYER, LIVE_VLCPLAYER, LIVE_WEBVIEW, LIVE_CEFSHARP, LIVE_NEBULA, LIVE_VEXANA, LIVE_XAVIER, LIVE_AURORA). Shared rendering logic lives in src/Shared/Engine/Sucrose.Shared.Engine.* shared-item projects, imported into the matching engine .csproj; the common base is Sucrose.Shared.Engine.

flowchart LR
    Info["SucroseInfo.json<br/>Type (0-5)"] --> Run["Run.cs<br/>resolve engine setting"]
    Run --> Cmd["Commandog<br/>✔Live✖&lt;enginePath&gt;"]
    Cmd --> Exe["Sucrose.Live.&lt;Name&gt;.exe"]
    Exe --> Cfg["App.Configure()<br/>switch on Type, show Window"]
    Cfg --> Attach["Event/Handler.cs<br/>attach behind desktop icons<br/>(WorkerW / Progman)"]

Loading

Wallpaper types

The six wallpaper types are defined in src/Shared/Sucrose.Shared.Dependency/Enum/WallpaperType.cs. The integer order is significant because Type is stored as an integer in SucroseInfo.json:

internal enum WallpaperType { Gif, Url, Web, Video, YouTube, Application }

Value	Type	Meaning
0	Gif	Animated GIF file
1	Url	A remote web address shown as a single static page
2	Web	An interactive local web theme (HTML/CSS/JS bundle, supports audio reactivity + system-status APIs)
3	Video	A local video file (mp4, etc.)
4	YouTube	A YouTube video/playlist URL
5	Application	An external program/game run as the wallpaper

See Wallpaper Types for the user-facing description of each.

The EngineType enum

src/Shared/Sucrose.Shared.Dependency/Enum/EngineType.cs lists every engine. The order matters because the values are used as integer indices (for example, into the EngineLive path dictionary):

internal enum EngineType { AuroraLive, NebulaLive, VexanaLive, XavierLive, WebViewLive, CefSharpLive, MpvPlayerLive, VlcPlayerLive }

Index	Member	Engine
0	AuroraLive	Aurora
1	NebulaLive	Nebula
2	VexanaLive	Vexana
3	XavierLive	Xavier
4	WebViewLive	WebView
5	CefSharpLive	CefSharp
6	MpvPlayerLive	MpvPlayer
7	VlcPlayerLive	VlcPlayer

Per-type allowed engines and defaults

Each type has a sub-enum (GifEngineType, UrlEngineType, etc.) whose members alias back to EngineType. Only those members appear as choices in the Portal for that type, so you can never assign an incompatible engine through the UI. The defaults are the fields in src/Shared/Sucrose.Shared.Space/Manage/Internal.cs:

Type	Allowed engines (enum)	Default
GifEngineType	Vexana, Xavier, WebView, CefSharp, MpvPlayer, VlcPlayer	MpvPlayer
UrlEngineType	WebView, CefSharp	CefSharp
WebEngineType	WebView, CefSharp	CefSharp
VideoEngineType	Nebula, WebView, CefSharp, MpvPlayer, VlcPlayer	MpvPlayer
YouTubeEngineType	WebView, CefSharp	CefSharp
ApplicationEngineType	Aurora (only)	Aurora

The default fields, verbatim:

public static SSDEUET UrlEngine = SSDEUET.CefSharp;
public static SSDEWET WebEngine = SSDEWET.CefSharp;
public static SSDEGET GifEngine = SSDEGET.MpvPlayer;
public static SSDEVET VideoEngine = SSDEVET.MpvPlayer;
public static SSDEAET ApplicationEngine = SSDEAET.Aurora;
public static SSDEYTET YouTubeEngine = SSDEYTET.CefSharp;

In short: the default Gif/Video engine is MpvPlayer, the default Url/Web/YouTube engine is CefSharp, and WebView is the everything-capable alternative for browser content.

Where you change engines

Open the Portal and go to Settings → Wallpaper. The page (ViewModel WallpaperSettingViewModel.cs) builds ComboBoxes for GifPlayer and VideoPlayer (in the "Extensions" area) and UrlPlayer, WebPlayer, YouTubePlayer, ApplicationPlayer (in the "Engines" area). Each selection writes an engine setting key.

The engine setting keys (src/Library/Sucrose.Memory/Manage/Constant/Engine.cs) are: Gif, Url, Web, Video, YouTube, Application. The effective value is resolved by src/Shared/Sucrose.Shared.Dependency/Manage/Manager/Engine.cs, which falls back to the Space defaults above when a key is unset.

See Choosing Engines for the task-oriented walkthrough and Settings Wallpaper for the full key list.

📷 Screenshot needed: Portal → Settings → Wallpaper page showing the per-type engine selectors (GifPlayer / VideoPlayer / UrlPlayer / WebPlayer / YouTubePlayer / ApplicationPlayer).

How an engine is selected and launched

When a wallpaper is applied, src/Shared/Sucrose.Shared.Live/Helper/Run.cs reads the wallpaper's Info.Type and runs the resolved engine path through Commandog:

switch (Info.Type) {
  case Gif:         run EngineLive[Engine.Gif]
  case Url:         run EngineLive[Engine.Url]
  case Web:         run EngineLive[Engine.Web]
  case Video:       run EngineLive[Engine.Video]
  case YouTube:     run EngineLive[Engine.YouTube]
  case Application: run EngineLive[Engine.Application]
}

The command sent to Commandog takes the form {StartCommand}{CommandType.Live}{ValueSeparator}{enginePath}. If PerformanceCounter is enabled, Backgroundog is also started. Engine .exe paths come from Shared.Space.Manage.Internal.EngineLive, a Dictionary<EngineType, string>.

The decision tree, in words:

Wallpaper applied
  → Run.Start() reads SucroseInfo.Type
     ├ Gif         → engine = setting "Gif"         (default MpvPlayer; or Vexana/Xavier/WebView/CefSharp/VlcPlayer)
     ├ Url         → engine = setting "Url"         (default CefSharp; or WebView)
     ├ Web         → engine = setting "Web"         (default CefSharp; or WebView)
     ├ Video       → engine = setting "Video"       (default MpvPlayer; or Nebula/WebView/CefSharp/VlcPlayer)
     ├ YouTube     → engine = setting "YouTube"     (default CefSharp; or WebView)
     └ Application → engine = setting "Application"  (Aurora only)
  → Commandog launches the engine .exe
  → Engine App.Configure() switches on Type again and shows the matching Window

Switching wallpapers kills the previous engine process and launches the new one via Commandog. If a type is somehow assigned to an engine that cannot render it, that engine's Configure() switch hits default → Close() and nothing displays — the Portal UI prevents this by only offering compatible engines per type. See Commandog Dispatcher for the broker that performs the launch.

Desktop attach (WorkerW / Progman)

After an engine window loads, it attaches itself behind the desktop icons. The shared Event/Handler.cs handles WindowLoaded, ContentRendered, DisplaySettingsChanged, and the application-embed events, performing the WorkerW/Progman handling that places the rendering window beneath the desktop icon layer. Display changes (resolution, monitor add/remove) re-trigger the attach via DisplaySettingsChanged. See Multi-Monitor for per-display behavior and Lifecycle for the full process startup sequence.

Shared engine layer

Every engine imports the base Sucrose.Shared.Engine shared-item project, which provides the common skeleton and helpers:

• Helper/Run.cs — Control(): per-tick housekeeping called from each engine's GeneralTimer.
• Helper/Awakening.cs — the "Stay Awake" execution-state loop.
• Helper/Crashing.cs — crash / Explorer recovery (CrashExplorer setting).
• Helper/Cycyling.cs — wallpaper cycling / shuffle / loop scheduling.
• Helper/Data.cs — GetLoop(), GetVolume(), GetStretch().
• Helper/Source.cs — resolves Info.Source to a URL/path (screen layout, multi-monitor, screenshots, base64).
• Helper/Volume.cs — volume monitoring loop.
• Helper/Properties.cs — property-file watcher + JS property injection.
• Manage/Internal.cs — global engine state (Info, Host, Properties, Compatible, WindowHandle, timers) and the base64 panel definitions and config defaults.

All engines share the same App.xaml.cs skeleton: wire up the exception handlers (Thread, FirstChance, Unhandled, UnobservedTask, Dispatcher) routed to Sucrose.Shared.Watchdog; on startup run the single-instance mutex check (SMMRM.Live), apply security, then Checker()/Configure(); Configure() loads the SucroseInfo JSON, verifies Info.AppVersion <= app version, resolves Source, then switches on Info.Type and shows the matching window. By default the Backgroundog flags PipeRequired, AudioRequired, SignalRequired, PausePerformance, and TransmissionRequired are off; Web wallpapers turn the audio/IPC flags back on.

The PropertiesType enum (Shared.Dependency/Enum/PropertiesType.cs) — Base, WebView, CefSharp, MpvPlayer, VlcPlayer — determines which property-panel JSON a wallpaper exposes in the Portal. See Customizing Wallpaper and Property Service.

Platform support

All engines target .NET 10.0-windows (WPF + WinForms interop) and build for x86, x64, ARM64, each with separate output folders. Engine-specific notes:

• MpvPlayer ships its own libmpv-{arch}.dll; needs Windows 10 1607+ (Redstone 1).
• VlcPlayer ships its own bundled libVLC (VideoLAN.LibVLC.Windows, one architecture per build); no OS-version check and no runtime download.
• WebView needs the Edge WebView2 runtime ≥ 131.0.2903.70 (auto-download offered).
• CefSharp needs the VC++ Redistributable ≥ 14.40.33816.0 (auto-download offered); CEF native binaries ship with the engine.
• Nebula depends on OS media codecs.
• Vexana / Xavier / Aurora are pure managed (WPF) + Skylark; no extra native runtime beyond .NET.

See System Requirements and Runtime Dependencies.

Audio-reactive and system-status wallpapers

Only the browser engines (WebView and CefSharp) rendering the Web type support live data injection. A theme declares the data hooks it wants in a SucroseCompatible.json; if SystemAudio is declared, the engine flips Backgroundog's AudioRequired flag, opens a communication channel, and injects audio/system data into the page via ExecuteScriptAsync. Video, Gif, and Application engines do not inject system data (Aurora apps receive volume only; MpvPlayer and Nebula are pure media playback). See Create Audio API, Create System API, and Create Web Architecture.

See also

• Engine Comparison
• Engine MpvPlayer
• Engine VlcPlayer
• Engine WebView
• Engine CefSharp
• Engine Nebula
• Choosing Engines
• Wallpaper Types
• Architecture Overview