SShady

Shady API Documentation

Shady exposes these extension surfaces:

  • Lua API — configuration, runtime scripting, events, window/workspace control.
  • Headless / Automation API — deterministic keyboard, pointer, timer, screenshot, and CI helpers.
  • IPC API — Unix socket with JSON lines and the shadyctl CLI: query state, send commands and subscribe to events from shells, bars and scripts.
  • Shell Lua API — configure shady-shell in Lua: bars, popups, widgets, live command output and hot reload.
  • Shell plugin API — native shady-shell plugins: publish values, register actions and draw widgets for the Lua config.
  • C Plugin API — native modules, events, window/output access, hot reload, render hooks.
  • Plugin manager — loading plugins by name from Lua, search paths, shipped plugins, and runtime state.
  • Shader API — standalone shader files, fullscreen passes, and per-window shader replacement.
  • Environment API — static 3D environments and pluggable asset loaders (OBJ today, glTF and others as plugins).

Which API should I use?

Use Lua when you are configuring Shady, writing window rules, reacting to compositor events, or scripting behavior without rebuilding a shared library.

Use the IPC API from programs that run outside the compositor: shells, bars, status scripts and anything that wants to react to window or workspace changes in another language.

Use the headless automation API for regression tests. It is part of the Lua runtime but is documented separately because its semantics are test-oriented.

Use the C plugin API when you need native performance, module state, input hooks, render hooks, custom window effects, or hot-reloadable extensions.

Use the shader API together with the C plugin API when a plugin owns custom GLSL.

Use the environment API when you want to support a new 3D file format or generate an environment procedurally. Loaders are ordinary C plugins.

Build-time availability

Some APIs depend on enabled modules. Query runtime capabilities before using optional features:

if shady.has_capability("spatial") then
    shady.camera("yaw", 0.15)
end

C plugins use api->has_capability(host, "...") for the same purpose.

Compatibility policy

Public C headers live under include/shady/. Existing fields in struct shady_plugin_api_v1 are append-only: new API entries are added at the end instead of reordering earlier fields.

Lua APIs are runtime APIs and currently do not carry a numeric compatibility version.

Shader programs are GLES2-style GLSL. Plugins should treat host-provided uniforms as optional: only uniforms declared by the shader are assigned.