Settings Wallpaper

Settings — Wallpaper

The Wallpaper Settings page (WallpaperSettingPage, the MenuWallpaper item in the Settings-mode navigation) controls how wallpapers are rendered: which render engine handles each wallpaper type, how input is forwarded to interactive wallpapers, how the wallpaper is stretched and laid out across the screen, and a set of global behavioral toggles (loop, shuffle, hardware acceleration, stay-awake, etc.). Almost every value on this page is applied live — changing it kills and restarts the live engine (respecting any Backgroundog Close/Pause state), which is why your wallpaper briefly disappears and reappears after a change. Every setting is persisted to Engine.json under %AppData%\Sucrose\Setting\.

Contents

• Where these settings live
• Input and interactivity
• Screen layout and stretch
• Global behavior toggles
• Per-type engine selectors
• Engine enumeration reference
• How changes are applied
• See also

Where these settings live

Property	Value
Portal page	WallpaperSettingPage (Setting5, icon Image16)
Localization key	Portal.MainWindow.MenuWallpaper
JSON file	Engine.json
Folder	%AppData%\Sucrose\Setting\
Backing accessor	Sucrose.Manager.Manage.Engine (with engine selectors resolved through Sucrose.Shared.Dependency)

The page is organized into three areas: AppearanceBehavior, Extensions, and Engines.

Input and interactivity

These settings decide whether (and how) mouse and keyboard events reach interactive wallpapers (Web, Url, YouTube, Application).

Setting	Control	Key	Default	Options / range	Effect
Input Mode	ComboBox	InputType	MouseKeyboard	Close / OnlyMouse / OnlyKeyboard / MouseKeyboard (Skylark.Enum.InputType)	Which input streams are forwarded to the wallpaper. Close disables all interaction.
Input module	ComboBox	InputModuleType	RawInput	RawInput (only enabled value; Native is commented out)	The Win32 capture mechanism used to grab desktop input.
Input on desktop	CheckBox	InputDesktop	false	true / false	When on, input is forwarded only while the desktop is shown (not while another window is focused).
Hide desktop icons	CheckBox	(live OS state)	reflects SWUD.GetDesktopIconVisibility()	true / false	Toggles Windows desktop icon visibility directly; this is a live OS state, not a stored Sucrose key.

Screen layout and stretch

Setting	Control	Key	Default	Options	Effect
Screen Layout	ComboBox	ScreenType	DisplayBound	Skylark.Enum.ScreenType	How the wallpaper surface is bounded relative to the display geometry.
Stretch Mode	ComboBox	StretchType	UniformToFill	None / Fill / Uniform / UniformToFill	How the wallpaper content is scaled to fill the target screen.

Multi-monitor placement (per-display vs. span vs. duplicate, and the target ScreenIndex) is configured in the separate Display Preferences dialog, not on this page. See Multi-Monitor.

Global behavior toggles

Setting	Control	Key	Default	Effect
Stay Awake	ToggleSwitch	StayAwake	false	Prevents the system from sleeping / starting the screensaver while a wallpaper is active.
Crash Mode	ToggleSwitch	CrashExplorer	false	Restart Windows Explorer if the wallpaper host crashes (recovers a black/frozen desktop).
Loop Mode	ToggleSwitch	WallpaperLoop	true	Loop video/GIF playback.
Shuffle Mode	ToggleSwitch	WallpaperShuffle	true	Shuffle when multiple media are present (and during cycling).
Background Image	ToggleSwitch	BackgroundImage	false	Also sets/resets the static Windows desktop wallpaper (so the desktop isn't blank behind a transparent/letterboxed wallpaper).
Hardware Acceleration	ToggleSwitch	HardwareAcceleration	true	Enables GPU-accelerated rendering paths in the engines. Disable only to work around buggy drivers.

Disabling Hardware Acceleration can dramatically increase CPU usage. Leave it on unless you are troubleshooting GPU driver problems. See Performance-Rules.

Per-type engine selectors

Each of the six wallpaper types has its own engine selector. The list of choices is restricted per type — the per-type sub-enums in Sucrose.Shared.Dependency only allow engines that can actually render that type. The default for each selector is a fixed value (the engine defaults come from Sucrose.Shared.Space.Manage.Internal.{Gif,Video,Web,Url,YouTube,Application}Engine); the same default applies across all x86/x64/ARM64 builds.

Setting	Control	Key	Default	Allowed engines
Gif Player	ComboBox	Gif	MpvPlayer	Vexana, Xavier, WebView, CefSharp, MpvPlayer, VlcPlayer
Video Player	ComboBox	Video	MpvPlayer	Nebula, WebView, CefSharp, MpvPlayer, VlcPlayer
Url Player	ComboBox	Url	CefSharp	WebView, CefSharp
Web Player	ComboBox	Web	CefSharp	WebView, CefSharp
YouTube Player	ComboBox	YouTube	CefSharp	WebView, CefSharp
Application Player	ComboBox	Application	Aurora	Aurora

If you select an engine whose runtime is not yet installed (for example WebView2 for the WebView engine), Sucrose prompts to auto-download the missing runtime before switching. See Runtime-Dependencies.

For a task-oriented walkthrough of choosing engines per type, see Choosing-Engines. For per-engine technical detail, see Engines-Overview.

Engine enumeration reference

The engine selectors map to members of Sucrose.Shared.Dependency.Enum.EngineType:

Enum member	Engine page
AuroraLive	Engine-Aurora
NebulaLive	Engine-Nebula
VexanaLive	Engine-Vexana
XavierLive	Engine-Xavier
WebViewLive	Engine-WebView
CefSharpLive	Engine-CefSharp
MpvPlayerLive	Engine-MpvPlayer
VlcPlayerLive	Engine-VlcPlayer

How changes are applied

Changing a Wallpaper setting takes effect immediately. The Portal either kills and restarts the live engine via Sucrose.Shared.Live.Helper.Kill.Stop() / Run.Start(), or sends a command to the Commandog process. If the Backgroundog performance monitor has Closed or Paused the engine for a performance rule, the restart respects that state. This is why a wallpaper flickers (briefly disappears and reappears) when you change the engine, stretch, or input settings.

Settings keys for this page are defined as constants in Sucrose.Memory.Manage.Constant.Engine; their defaults and clamps live in Sucrose.Manager.Manage.Engine. Out-of-range numeric values in Engine.json are silently clamped on read (the file is not rewritten). Enums are stored as their string member name, so when hand-editing Engine.json use the member name (e.g. UniformToFill), not an integer.

See also

• Settings-Overview — how all settings pages and JSON files fit together
• Choosing-Engines — task-oriented guide to per-type engine selection
• Engines-Overview — the eight render engines and what each supports
• Multi-Monitor — per-display placement and ScreenIndex
• Performance-Rules — automatic Close/Pause/Resume behavior
• Settings-All-Keys — every setting key, file, default, and range