Skip to content

Create System API

Jump to bottom
Taiizor edited this page Jun 19, 2026 · 3 revisions

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.

Contents

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, VlcPlayer, 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 already in gibibytes (GiB — the raw byte count divided by 1024^3). 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 (GiB)
MemoryAvailable Physical memory free (GiB)
VirtualMemoryLoad Virtual memory used (%)
VirtualMemoryUsed Virtual memory used (GiB)
VirtualMemoryAvailable Virtual memory free (GiB) 
window.SucroseMemoryData = function (obj) {
  if (!obj.State) return;
  const totalGiB = obj.MemoryUsed + obj.MemoryAvailable;
  const usedGiB = obj.MemoryUsed;            // already in GiB
  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 gibibytes (GiB); 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.

See also

License: GPL-3.0

Issues · Discussions · Discord · Store · Website

Version: release line 26.6.4.0 — version format yy.MM.dd.0.

Documentation generated for the Sucrose Wallpaper Engine.

Home

Getting Started

Wallpaper Types

Using Sucrose

Settings Reference

Creating Wallpapers

Engine Reference

Automation & Command Line

Architecture & Internals

Data, Files & Diagnostics

Building & Contributing

Help & Support

Clone this wiki locally