Skip to content

Architecture

The compositor owns the desktop. Core provides the world runtime and brokers its authority. Everything else connects through explicit contracts.

Hyprune process and repository boundariesShell and extension processes connect over public Unix IPC to hypruned. The daemon uses a private bridge to the Hyprland plugin. World packages supply validated scene data. Schemas and SDK define the public boundary.ShellQuickshell or your own UIExtensionsProcesses · plannedWorldsData, glTF, provenancePublic IPC · JSON-RPCValidatehypruned · coreGrants / packages / IPC / supervisionPrivate bridge · same core buildHyprland + core pluginCapture / trusted input / GPU / authoritative sceneSchema defines the contracts. SDK makes them usable.

The plugin reads immutable frame state and draws prepared resources. Capture refresh, cursor changes, focus, workspace transitions and uploads run in a verified safe phase after the outer compositor frame. CPU workers decode assets; they never access compositor objects or GL. The simulation tick runs once per presented frame, queued outside the render pass, and moves by that frame’s real time. Pass tracking recovers when the compositor starts a pass and never finishes it (for example when a frame fails to allocate after a monitor change).

Frame ownership and deferred workSafe after-frame preparation feeds world rendering, then surfaces, then compositor layers. Only after outer endRender does the next deferred phase begin.Safe preparationCapture / upload / inputWorld passGeometry / lightingSurface passCaptured app pixelsCompositeHyprland / shell layersNext preparation only after outer endRender returns
Boundary Decision
Repositories and ownership RFC-0001
Processes, threads and frame graph RFC-0002
IPC, state, grants and failure RFC-0003
World content and validation RFC-0004
Pixels and input RFC-0005
Interaction and controllers RFC-0006
Extension hosts and SDK RFC-0007
Replaceable shells RFC-0008
Optional world-rendering process and power policy RFC-0009
World-supplied HUD styles (proposed) Amendment to RFC-0004/0008

The world renders below output resolution and is upscaled with FSR 1; dynamic resolution adjusts the scale in 1/16 steps to hold the frame rate. When nothing in view changes, core re-presents the last world frame instead of rendering a new one, and workspace walls recompose only when their windows change. A frame-rate target below the display rate renders on every second (or nth) presentation, evenly. Walls with windows are composed at the monitor’s resolution with mipmaps, so their text stays sharp. On machines with a discrete GPU, an optional worker supervised by hypruned can render the world there and return frames over DMA-BUF, under a power budget scaled to that GPU and with immediate local fallback; it also works when the compositor itself runs on an NVIDIA GPU. It is off by default (RFC-0009). Native application windows are always composited locally. The progress page has the measurements.

A shell crash releases overlay input, and a restarted shell renews its credentials and resyncs from a snapshot. A daemon crash triggers the plugin’s desktop recovery watchdog. A malformed world fails staging before activation. Extensions will run as separate supervised processes and can’t execute inside the compositor; the host isn’t built yet. A plugin bug can still crash Hyprland, which is why that boundary stays small and is built and tested against exact compositor releases (Supported Hyprland versions).

The schema repository owns the machine-readable definitions. The schema reference renders every published version of the world manifest, IPC protocol, input keymap, extension manifest and screen type descriptor, with diffs between versions and the raw JSON to download. Runtime validation uses pinned local copies, never the network.