Create Package Format

Wallpaper Package Format — SucroseInfo.json

Audience: wallpaper creators. This is the authoritative reference for the wallpaper package: the folder layout, the canonical file names, and every field of the required manifest SucroseInfo.json. Use it when hand‑editing a manifest or building a wallpaper outside the Portal Create dialog. For the dialog walkthrough see Create Step By Step; for the overall model see Create Overview.

Contents

• Folder layout
• Canonical file names
• SucroseInfo.json field reference
• The Type enum
• The Localization object
• Annotated example
• Gotchas
• See also

Folder layout

A wallpaper is a folder containing the manifest plus its media/source files. A typical layout:

<random-25-char-id>/                <- folder name auto-generated, NOT the title
├── SucroseInfo.json                <- REQUIRED manifest
├── SucroseProperties.json          <- OPTIONAL customization controls
├── SucroseCompatible.json          <- OPTIONAL live-data JS hook templates
├── SucroseStore.json               <- OPTIONAL store metadata
├── Thumbnail.jpg (or t_*.jpg)      <- small preview image
├── Preview.gif   (or p_*.gif)      <- animated preview
├── License.txt                     <- optional, referenced by the License field
└── <source files>                  <- the .gif / .html + js/css / video / .exe etc.

When a wallpaper is created through the Portal, source files are copied in with prefixes: source = s_<name>, thumbnail = t_<name>, preview = p_<name>. The folder name is a random 25‑character string — do not rely on it.

flowchart LR
    subgraph Files["files on disk"]
      T["Thumbnail.jpg / t_*.jpg"]
      P["Preview.gif / p_*.gif"]
      S["source file (s_*)"]
      L["License.txt"]
    end
    subgraph Manifest["SucroseInfo.json fields"]
      FT["Thumbnail"]
      FP["Preview"]
      FS["Source"]
      FL["License"]
    end
    T --> FT
    P --> FP
    S --> FS
    L --> FL

Loading

Canonical file names

These names are fixed constants in the codebase and must match exactly (case‑sensitive on the wiki for clarity):

Constant	File name	Purpose
SucroseInfo	SucroseInfo.json	Required manifest.
SucroseStore	SucroseStore.json	Store metadata.
SucroseCompatible	SucroseCompatible.json	Live‑data JS hook templates.
SucroseProperties	SucroseProperties.json	Customization controls.
MpvPlayerConfig	MpvPlayer.config	Default mpv config (engine‑generated).
uMpvPlayerConfig	uMpvPlayer.config	Optional user override for mpv config (takes priority if present).
StoreFile	Store.json	Internal store file.
PatternFile	Pattern.json	Internal pattern file.

Browser engines also generate internal HTML wrappers you do not author: GifContent.html, ImageContent.html, VideoContent.html, YouTubeContent.html.

SucroseInfo.json field reference

The manifest is serialized with Newtonsoft.Json. Fields marked Always are required and must be present.

JSON field	Type	Required	Default / notes
AppVersion	Version string (yy.MM.dd.0)	Always	The Sucrose app version that created the wallpaper; default 0.0.0.0. Used to reject wallpapers newer than the running app.
Version	Version string	Always	The wallpaper's own version; default 1.0.0.0.
Title	string	Always	Display title.
Thumbnail	string	Always	File name of the thumbnail image.
Preview	string	Always	File name of the preview (often an animated GIF).
Description	string	Always
Author	string	Always
License	string	AllowNull	File name (e.g. License.txt) or null.
Contact	string	Always	A URL or email address (validated as URL or mail).
Type	int enum	Always	WallpaperType (0–5); default Gif. Serialized as a number.
Source	string	Always	Meaning depends on Type (see table below).
Tags	string[]	AllowNull	The Portal enforces 1–5 tags, each 1–20 characters.
Arguments	string	AllowNull	CLI args; used by the Application type (max 250 chars); null otherwise.
Localization	Dictionary<lang, {Title, Description}>	optional	Per‑language overrides of Title/Description.

The Type enum

Type is an integer, not a string. The value determines what Source means:

Type value	Type	Source meaning
0	Gif	Local .gif file name inside the folder
1	Url	A remote http/https URL
2	Web	Local entry HTML/web file name inside the folder
3	Video	Local video file name inside the folder
4	YouTube	A YouTube video or playlist URL
5	Application	Local executable file name inside the folder

The Localization object

Localization is an optional dictionary keyed by 2‑letter language code (e.g. DE, ES, FR, HI, PL, RU, TR, ZH). Each value is an object with exactly two required fields:

Field	Type	Required	Meaning
Title	string	Always	Localized title for this language.
Description	string	Always	Localized description for this language.

Sucrose displays the localized Title/Description when the app's language matches a key; otherwise it falls back to the top‑level Title/Description.

Annotated example

A real shipped example (Neo Matrix, a Web wallpaper — note Type: 2 and Source is the local HTML entry file):

{
  "AppVersion": "25.10.20.0",        // Sucrose version that created this wallpaper
  "Version": "7.3.0.2",              // the wallpaper's own version
  "Title": "Neo Matrix",
  "Thumbnail": "thumbnail.jpg",      // file name of the thumbnail in this folder
  "Preview": "preview.gif",          // file name of the animated preview
  "Description": "This is a highly customizable animated Matrix wallpaper.",
  "Author": "Mohammad Mahdi Nazari",
  "License": "License.txt",          // or null
  "Contact": "https://github.com/IPdotSetAF",  // URL or email
  "Type": 2,                          // 2 = Web
  "Source": "Matrix.html",           // local entry file (because Type is Web)
  "Tags": ["Science Fiction", "Sci-Fi", "Hacker", "Music"],  // 1-5 tags, <=20 chars each
  "Arguments": null,                  // only used by Application type
  "Localization": {
    "DE": { "Title": "Neo Matrix", "Description": "..." }
  }
}

Gotchas

• Type is a number (0–5), not a string. This is the most common hand‑editing mistake.
• The folder name is random, not the title; users and tools should not derive identity from it.
• Web and Application copy the whole containing folder — keep the wallpaper self‑contained in one directory, and that directory must be unlocked/writable for the Portal to import it.
• AppVersion must be ≤ the running app's version; engines refuse to load a wallpaper that claims a newer app version.
• License and Tags and Arguments may be null; the rest of the required fields must be present.
• colorpicker values in SucroseProperties.json (a separate file) are 8‑digit ARGB hex like #FF00FF00; see Create Customization Controls.

See also

• Create Overview
• Create Step By Step
• Create Customization Controls
• Create Sharing Publishing
• Create Example Wallpapers