Create System API modified by Bayram Emekli

Bayram Emekli — Sat, 04 Jul 2026 04:15:24 -0000

Create: System Status API

The System Status API is the set of JavaScript callbacks Sucrose pushes into a web wallpaper so it can read live hardware and OS readings — CPU/GPU load, memory, network, battery, storage, motherboard, BIOS, and the system clock. It is the companion to the Audio API: both are delivered by the same data pump (the Backgroundog service) over the same channel, and both are opt-in via SucroseCompatible.json. This page documents every system object, every field it carries, the units to expect, and the State validity flag that every object includes. Use it to build on-desktop system monitors, network meters, battery widgets, clocks, and hardware dashboards.

How it works
Opting in (SucroseCompatible.json)
The objects at a glance
SucroseProcessorData
SucroseGraphicData
SucroseMemoryData
SucroseNetworkData
SucroseBatteryData
SucroseStorageData
SucroseMotherboardData
SucroseBiosData
SucroseDateData
The State flag
Worked example: Simple System
Tips and gotchas
See also

How it works

System data is collected by the Backgroundog service. On a timer, Backgroundog calls a Get*Info() method for each category, builds a single bundle object, and JSON-serializes it. The bundle is shipped to the running web engine over the active live-data channel (named pipe, signal file, or TCP loopback — see IPC), where the engine stores each sub-object and then fans it out to your declared JavaScript callbacks via ExecuteScriptAsync.

The bundle carries ten sub-objects: Bios, Date, Audio, Memory, Battery, Graphic, Network, Storage, Processor, and Motherboard. The Audio object is documented separately on Create Audio API; the remaining nine are the System Status API covered here.

The engine only invokes a callback if you declared its template in SucroseCompatible.json. If you do not request an object, Sucrose never pushes it and your callback is never called — so request only what you use.

Only the browser-style engines (WebView and CefSharp) deliver this API. The data channel is web-engine-only. MpvPlayer, Aurora, Nebula, Vexana, and Xavier do not push the System API. See Choosing Engines.

Opting in (SucroseCompatible.json)

SucroseCompatible.json is a flat dictionary of string.Format templates. Each key names a data category; each value is the JavaScript call the engine will run, with {0} substituted for the JSON payload. The function name on the right is your choice, but the ecosystem standard — used by every shipped Showcase wallpaper — is Sucrose<Thing>Data.

{
  "SystemProcessor": "SucroseProcessorData({0});",
  "SystemGraphic":   "SucroseGraphicData({0});",
  "SystemMemory":    "SucroseMemoryData({0});",
  "SystemNetwork":   "SucroseNetworkData({0});",
  "SystemBattery":   "SucroseBatteryData({0});",
  "SystemStorage":   "SucroseStorageData({0});",
  "SystemMotherboard": "SucroseMotherboardData({0});",
  "SystemBios":      "SucroseBiosData({0});",
  "SystemDate":      "SucroseDateData({0});"
}

The mapping of SucroseCompatible.json key → JavaScript callback:

`SucroseCompatible.json` key	Payload object	Conventional callback
`SystemProcessor`	Processor JObject	`SucroseProcessorData({0});`
`SystemGraphic`	Graphic JObject	`SucroseGraphicData({0});`
`SystemMemory`	Memory JObject	`SucroseMemoryData({0});`
`SystemNetwork`	Network JObject	`SucroseNetworkData({0});`
`SystemBattery`	Battery JObject	`SucroseBatteryData({0});`
`SystemStorage`	Storage JObject	`SucroseStorageData({0});`
`SystemMotherboard`	Motherboard JObject	`SucroseMotherboardData({0});`
`SystemBios`	Bios JObject	`SucroseBiosData({0});`
`SystemDate`	Date JObject	`SucroseDateData({0});`

Then implement the matching functions on window:

window.SucroseProcessorData = function (obj) {
  if (!obj.State) return;        // data not valid this tick
  document.getElementById("cpu").textContent = obj.Now + "%";
};

For full details of the hook model, see Create JS Bridge.

The objects at a glance

Callback	What it reports	Key load/value fields
`SucroseProcessorData`	CPU model, load, per-core load, counts	`Now`, `Min`, `Max`, `Cores`, `Thread`, `ProcessorCount`
`SucroseGraphicData`	GPU model, load	`Now`, `Min`, `Max`
`SucroseMemoryData`	RAM and virtual memory usage	`MemoryLoad`, `MemoryUsed`, `MemoryAvailable`
`SucroseNetworkData`	Throughput, ping, online state	`Upload`, `Download`, `Ping`, `Online`, `Total`
`SucroseBatteryData`	Charge, status, power source	`LifePercent`, `ChargeStatus`, `PowerLineStatus`
`SucroseStorageData`	Drives (logical/physical)	`Drivers`, `LogicalDrivers`, `PhysicalDrivers`
`SucroseMotherboardData`	Board identity	`Name`, `Product`, `Manufacturer`
`SucroseBiosData`	Firmware identity	`Caption`, `Version`, `ReleaseDate`
`SucroseDateData`	System clock	`Year`, `Month`, `Day`, `Hour`, `Minute`, `Second`

Every object carries a State boolean (data validity) and most carry a Name.

SucroseProcessorData

Reports the CPU. Now is the current overall load; the Cores* arrays/fields carry per-core figures.

Field	Meaning
`State`	Validity flag (bool)
`Name`	Processor name/model
`Type`	Processor type
`Now`	Current overall load (%)
`Min`	Minimum observed load (%)
`Max`	Maximum observed load (%)
`Core`	Single-core figure
`Cores`	Per-core figures (current)
`Thread`	Thread count
`CoresNow`	Per-core current load
`CoresMin`	Per-core minimum load
`CoresMax`	Per-core maximum load
`ProcessorCount`	Logical processor count

window.SucroseProcessorData = function (obj) {
  if (!obj.State) return;
  setGauge("cpu", obj.Now);                 // % overall
  console.log(obj.Name, obj.ProcessorCount, "logical CPUs");
};

SucroseGraphicData

Reports the GPU.

Field	Meaning
`State`	Validity flag
`Name`	GPU name/model
`Manufacturer`	GPU vendor
`Now`	Current GPU load (%)
`Min`	Minimum observed load (%)
`Max`	Maximum observed load (%)

window.SucroseGraphicData = function (obj) {
  if (!obj.State) return;
  setGauge("gpu", obj.Now);
};

SucroseMemoryData

Reports physical RAM and virtual (page-file backed) memory. MemoryLoad is a percentage; the *Used/*Available figures are byte counts. To get a total, add used + available (this is exactly what the Simple System Showcase wallpaper does).

Field	Meaning
`State`	Validity flag
`Name`	Physical memory label
`VirtualName`	Virtual memory label
`MemoryLoad`	Physical memory used (%)
`MemoryUsed`	Physical memory used (bytes)
`MemoryAvailable`	Physical memory free (bytes)
`VirtualMemoryLoad`	Virtual memory used (%)
`VirtualMemoryUsed`	Virtual memory used (bytes)
`VirtualMemoryAvailable`	Virtual memory free (bytes)

window.SucroseMemoryData = function (obj) {
  if (!obj.State) return;
  const totalBytes = obj.MemoryUsed + obj.MemoryAvailable;
  const usedGiB = obj.MemoryUsed / (1024 * 1024 * 1024);
  setText("ram", usedGiB.toFixed(1) + " GiB (" + obj.MemoryLoad + "%)");
};

SucroseNetworkData

Reports throughput, latency, and connectivity. Upload and Download are bytes per second (showcase code divides by 1024 * 1024 for MB/s). Total is cumulative bytes; the *Data fields carry raw values and the Format*Data fields carry pre-formatted strings.

Field	Meaning
`State`	Validity flag
`Name`	Adapter name
`Host`	Ping host (the Performance ping target)
`Ping`	Round-trip latency (ms)
`Online`	Connectivity flag (bool)
`Upload`	Upload rate (bytes/s)
`Download`	Download rate (bytes/s)
`Total`	Cumulative bytes transferred
`PingData`	Raw ping value
`TotalData`	Raw total value
`UploadData`	Raw upload value
`DownloadData`	Raw download value
`PingAddress`	The host pinged
`FormatTotalData`	Human-readable total (string)
`FormatUploadData`	Human-readable upload (string)
`FormatDownloadData`	Human-readable download (string)

window.SucroseNetworkData = function (obj) {
  if (!obj.State) return;
  const downMBs = obj.Download / (1024 * 1024);
  setText("net", obj.Online
    ? downMBs.toFixed(2) + " MB/s · " + obj.Ping + " ms"
    : "Offline");
};

SucroseBatteryData

Reports battery charge, power state, and power-saving mode. LifePercent/BatteryLifePercent give the charge level; PowerLineStatus/ACPowerStatus indicate whether it is plugged in.

Field	Meaning
`State`	Validity flag
`Name`	Battery name
`Status`	Battery status
`Chemistry`	Battery chemistry
`SavingMode`	Energy-saver active flag
`SaverStatus`	Energy-saver status
`BatteryFlag`	Raw battery flag
`ChargeStatus`	Charging/discharging status
`Description`	Battery description
`LifePercent`	Charge level (%)
`BatteryLifePercent`	Charge level (%)
`EstimatedChargeRemaining`	Estimated remaining charge
`FullLifetime`	Full battery lifetime
`BatteryFullLifeTime`	Full battery lifetime
`BatteryLifeTime`	Remaining battery time
`LifeRemaining`	Remaining life
`EstimatedRunTime`	Estimated run time
`ACPowerStatus`	AC power status
`PowerLineStatus`	Power line status (plugged in?)
`DesignVoltage`	Designed voltage
`PowerPlanType`	Active power plan
`EnergySaverType`	Energy-saver type

window.SucroseBatteryData = function (obj) {
  if (!obj.State) return;
  setText("battery", obj.LifePercent + "%" + (obj.SavingMode ? " (saver)" : ""));
};

SucroseStorageData

Reports drives. Drivers is the combined list; LogicalDrivers and PhysicalDrivers separate logical volumes from physical disks.

Field	Meaning
`State`	Validity flag
`Drivers`	All drives
`LogicalDrivers`	Logical volumes
`PhysicalDrivers`	Physical disks

window.SucroseStorageData = function (obj) {
  if (!obj.State) return;
  console.log("Logical volumes:", obj.LogicalDrivers);
};

SucroseMotherboardData

Reports the motherboard identity.

Field	Meaning
`State`	Validity flag
`Name`	Board name
`Product`	Product identifier
`Version`	Board version
`Manufacturer`	Board manufacturer

SucroseBiosData

Reports the firmware/BIOS identity.

Field	Meaning
`State`	Validity flag
`Name`	BIOS name
`Caption`	BIOS caption
`Version`	BIOS version
`Description`	BIOS description
`ReleaseDate`	BIOS release date
`Manufacturer`	BIOS manufacturer
`SerialNumber`	Serial number
`CurrentLanguage`	BIOS language

SucroseDateData

Reports the system clock, broken into components so you can build a clock without parsing. Pushed on the same cadence as the rest of the bundle.

Field	Meaning
`State`	Validity flag
`Year`	Year
`Month`	Month (1–12)
`Day`	Day of month
`Hour`	Hour
`Minute`	Minute
`Second`	Second
`Millisecond`	Millisecond
`DayOfYear`	Day of the year
`DayOfWeek`	Day of the week
`Kind`	`DateTimeKind`

window.SucroseDateData = function (obj) {
  if (!obj.State) return;
  const pad = n => String(n).padStart(2, "0");
  setText("clock", pad(obj.Hour) + ":" + pad(obj.Minute) + ":" + pad(obj.Second));
};

The State flag

Every System object carries a State boolean. It is the data-validity flag: when State is false, the reading for that tick could not be collected (the source was unavailable, a sensor failed, or the value is not yet populated). Always guard your handler with an early if (!obj.State) return; so a transient failure does not corrupt your display. Most objects also carry a Name you can show as a label.

Worked example: Simple System

The shipped Showcase wallpaper Simple System (a Web type, Source: System.html) is the canonical System API demo: it charts hardware readings live. Its SucroseCompatible.json requests four categories:

{
  "SystemMemory":    "SucroseMemoryData({0});",
  "SystemGraphic":   "SucroseGraphicData({0});",
  "SystemNetwork":   "SucroseNetworkData({0});",
  "SystemProcessor": "SucroseProcessorData({0});"
}

Note it only requests the four it draws — CPU, GPU, memory, and network — and not battery, storage, BIOS, motherboard, or date. That is the pattern to follow: declare exactly the hooks you render. See Create Example Wallpapers for a full walkthrough of the shipped examples.

Tips and gotchas

Request only what you use. Each declared hook makes Backgroundog collect and ship that category; unused hooks waste CPU.
Always check State. A single bad tick is normal; never assume a field is populated.
Mind the units. Network Upload/Download are bytes/second; memory *Used/*Available are bytes; load fields (Now/MemoryLoad) are percentages. The Format*Data strings are pre-formatted if you would rather not convert.
Type is a number in the manifest, but the System payload uses real types — booleans for State/Online/SavingMode, numbers for loads and byte counts.
Function names are yours, but stay standard. Sucrose just runs your template; the whole ecosystem uses Sucrose<Thing>Data, so match it for portability.
Web-engine only. If your callbacks never fire, confirm the wallpaper is running on WebView or CefSharp, not a video/GIF engine — see Choosing Engines.
Cross-engine portability. When porting from Wallpaper Engine or Lively, feature-detect their hooks first and fall back to the Sucrose API — see Create Compatibility.

Recent changes to Create System API

Create System API modified by Bayram Emekli

Create System API modified by Bayram Emekli

Create System API modified by Bayram Emekli

Create: System Status API

Contents

How it works

Opting in (SucroseCompatible.json)

The objects at a glance

SucroseProcessorData

SucroseGraphicData

SucroseMemoryData

SucroseNetworkData

SucroseBatteryData

SucroseStorageData

SucroseMotherboardData

SucroseBiosData

SucroseDateData

The State flag

Worked example: Simple System

Tips and gotchas

See also