Settings Overview

Settings Overview

Sucrose keeps all of its persistent configuration as a set of small JSON files under %AppData%\Sucrose\Setting\ — one file per topical category (General.json, Engine.json, Portal.json, and so on). There is no monolithic config file and no application-specific registry usage for settings (the only registry writes Sucrose performs are the standard Windows uninstall entry written by the installer under HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\Sucrose and removed by the uninstaller, plus Windows' own DirectX GPU‑preference key under HKCU\Software\Microsoft\DirectX\UserGpuPreferences — Sucrose never stores configuration in the registry). The Settings UI inside the Portal is just a friendly editor over these JSON files: each setting card reads its current value from a strongly‑typed, defaulted, clamped accessor and writes the new value back through a SettingManager. This page explains how settings are stored, how the Portal pages map onto the JSON files, and how changes take effect at runtime. Use it as the entry point to the per‑page references.

Contents

• How settings work
• Where settings live on disk
• Portal page → JSON file map
• The full set of settings JSON files
• JSON file format
• How changes are applied
• Defaults, ranges, and clamping
• See also

How settings work

Three shared libraries collaborate to make settings work:

Library	Role
Sucrose.Memory	Pure constant/readonly definitions. Holds the key strings, folder names, and file names. The single source of truth for magic strings (keys live in Sucrose.Memory.Manage.Constant.*).
Sucrose.Manager	The persistence engine. SettingManager reads/writes the JSON files; Manage.* static classes expose strongly‑typed, defaulted, clamped accessors for each setting (defaults live in Sucrose.Manager.Manage.*).
Sucrose.Resources	UI localization (one XAML ResourceDictionary per language) — not a settings store, but supplies every label and description shown on the Settings pages.

The Settings UI is built in code, not XAML. Each Settings page's ViewModel constructs every card as an ExpanderCard with a LeftIcon, Title, Description, a primary control (ComboBox / ToggleSwitch / Slider / NumberBox / Button), and an optional expandable footer for sub‑settings. When you change a control, the ViewModel writes the value with SetSetting(<Key>, value) into the appropriate JSON file.

Where settings live on disk

All settings JSON files live in the Roaming AppData tree:

%AppData%\Sucrose\Setting\*.json

That is Environment.SpecialFolder.ApplicationData (Roaming) + Sucrose (the AppName) + Setting. The directory is auto‑created the first time a SettingManager is constructed. Note that the installed application binaries live under a different root — %LocalAppData%\Sucrose — not under %AppData%. See Data Locations for the complete folder map.

Portal page → JSON file map

Each Settings page in the Portal writes to one or more JSON files. A single page can span several files because settings are grouped by topic, not by page.

Settings page	Primary JSON file(s)	Documented in
General	General.json, Portal.json, Engine.json, Library.json	Settings-General
Personal	Portal.json, Library.json, Engine.json	Settings-Personal
Performance	Backgroundog.json	Settings-Performance
Wallpaper	Engine.json	Settings-Wallpaper
System	(action‑only — operates on Setting/Cache/Log/Library folders)	Settings-System
Other	General.json, Hook.json, Update.json, Objectionable.json, Engine.json	Settings-Other

The top-toolbar dialogs reachable from the Library/Store view also persist to JSON: Wallpaper Cycling → Cycling.json (Wallpaper-Cycling), Display Preferences → Engine.json (Multi-Monitor).

For a single master table that aggregates every setting → file/key/type/default/range, see Settings-All-Keys.

The full set of settings JSON files

Sucrose.Manager.Manage.Internal instantiates one SettingManager per JSON file. This is the authoritative list of every settings file on disk:

Manager field	File	Backing accessor class
GeneralSettingManager	General.json	Manage.General
EngineSettingManager	Engine.json	Manage.Engine
PortalSettingManager	Portal.json	Manage.Portal
LibrarySettingManager	Library.json	Manage.Library
SystemSettingManager	System.json	Manage.System
UpdateSettingManager	Update.json	Manage.Update
CyclingSettingManager	Cycling.json	Manage.Cycling
BackgroundogSettingManager	Backgroundog.json	Manage.Backgroundog
HookSettingManager	Hook.json	Manage.Hook
DonateSettingManager	Donate.json	Manage.Donate
AuroraSettingManager	Aurora.json	Manage.Aurora
WarehouseSettingManager	Warehouse.json	Manage.Warehouse
ObjectionableSettingManager	Objectionable.json	Manage.Objectionable
KernelSettingManager	Kernel.json	(no Manage.* wrapper; key Information)

Warehouse.json and System.json hold runtime/cached state (first‑run flags, enumerated hardware) rather than user‑facing settings; Donate.json backs a page that is present but hidden in current builds.

JSON file format

Every settings file is a single JSON object with one property, Properties, a string→object dictionary:

{
  "Properties": {
    "Culture": "EN",
    "AppVisible": true,
    "WallpaperVolume": 100
  }
}

Key facts about the format:

• Serializer: Newtonsoft.Json, Formatting.Indented.
• Enums are stored as their string name (via a custom EnumConverter, parsed case‑insensitively). When hand‑editing, use the enum member name (e.g. Mica), never its integer.
• IP addresses are stored as strings (via IPAddressConverter).
• The JSON key name equals the constant value (e.g. the key "Culture").
• Files are self‑healing: if a file is missing, empty, or contains invalid JSON, it is reset to { "Properties": {} } on next access, and defaults are used from then on.

Reads and writes are guarded by a named Mutex keyed to an MD5 hash of the file path, so the many Sucrose processes can read/write settings concurrently without corruption. See Settings-Persistence for the internals (the three SettingManager variants, converters, and mutex‑guarded I/O).

How changes are applied

Most settings apply live rather than requiring a restart of the app. There are two mechanisms:

1. Engine restart. Many wallpaper‑affecting settings take effect immediately by stopping and restarting the live wallpaper engine. This is why changing certain options briefly flickers or reloads the wallpaper.
2. Command dispatch via Commandog. Some changes (startup mode, settings backup/import/reset, cache/log clearing) are carried out by sending a command to the short‑lived Commandog broker process, which performs the action and exits. See Commandog-Dispatcher and Command-Reference.

A few toggles start or stop a background service directly — for example, Performance Counter starts/kills the Backgroundog-Service, and Report Data / Statistics Data start/kill the Reportdog process.

Defaults, ranges, and clamping

• Defaults come from the second argument of each accessor in Sucrose.Manager.Manage.* / Sucrose.Shared.Dependency.Manage.Manager.*. A missing key always returns the default.
• Ranges (Min/Max) are enforced with Skymath.Clamp(...) and the NumberBox Minimum/Maximum. Values clamp on read: an out‑of‑range value in the JSON is silently clamped when read (the file is not rewritten).
• Some defaults are platform‑conditional — for example, the default engine per wallpaper type depends on architecture and installed runtimes.

To back up, restore, or factory‑reset all of these files, see Backup-Restore-Reset.

See also

• Settings-All-Keys — master table of every setting, file, key, type, default, and range
• Settings-Persistence — the SettingManager internals, converters, and mutex‑guarded I/O
• Data-Locations — the complete %AppData% / %LocalAppData% folder map
• Backup-Restore-Reset — exporting, importing, and resetting settings
• Settings-General · Settings-Personal · Settings-Performance · Settings-Wallpaper · Settings-System · Settings-Other
• Portal-Interface-Tour — where the Settings pages live in the Portal