Skip to main content
A plugin is a small widget you place on your desktop: a stock ticker on the wallpaper, a photo beside the clock, a panel that melts out of the screen edge on hover. The author writes the logic and one view; Ryoku owns where it lives, how it looks, how it moves, and how it sizes. That split is the whole point, a plugin always looks and behaves like a native part of the shell, because the shell draws the surface around it.
Plugins are widgets, not applications. To install real software (game launchers, dev stacks, security tools), use Extras bundles, a separate system.

​
The two hosts

When you enable a plugin you pick one host for it. The same widget can run in either; Ryoku just renders it differently.
A tile on the wallpaper, next to the clock and weather, with the same machinery they have:
  • Left-drag to move it (snaps to a grid).
  • Right-click for its menu: Lock to freeze it in place, Hide to turn it off.
  • Drag the bottom-right corner to resize, live, from 50% to 250%.
  • It rides on a card (rounded, translucent, soft shadow) that matches the clock and weather.
You arrange desktop widgets directly on the wallpaper, not from Settings.
Island, top-bar glyph, and window hosts are planned but not built yet. Today a plugin declares desktopWidget, framePopout, or both.

​
Install, enable, place

1

Install from the Store

Press Mod + , for Ryoku Settings and open Store (under Add-ons). It opens on a grid of plugin cards with live previews; open one and choose Install. The source downloads to ~/.local/share/ryoku/plugins/<id>/.
2

Enable it

Switch to Installed (also under Add-ons) and toggle the plugin Enabled.
3

Pick a host and place it

In the same panel choose the host. For a frame popout, set the edge and alignment there. A desktop widget appears on the wallpaper, where you drag, corner-resize, lock, or hide it directly.
Placement and settings persist to ~/.config/ryoku/plugins.json. The shell watches that file and retunes every surface live, no reload, no restart. Removing a plugin (from Installed) deletes its files but keeps your placement, so reinstalling drops it back where you had it.

​
Example plugins

Ryoku ships two official plugins in the catalogue, both desktop widgets:

Market

Track any Yahoo Finance symbol, a crypto pair (BTC-USD), a stock (AAPL), or an index (^GSPC), with live price, change, and history in one of four faces: dossier, line, area, or minimal.

Photo Frame

Pin any photo to your wallpaper in a chosen style (rounded, square, polaroid, framed, or film) with a tunable drop shadow and colour filters. Ships with a sample photo so it looks right the moment you enable it.
Each plugin’s own options (Market’s symbol and face, Photo Frame’s style and filter) live in its settings, edited from Installed or the desktop widget’s right-click menu.

​
From a terminal

The Hub is the normal path, but the same actions have commands. Ids are the ones in the ryoku-extras plugin catalogue (market, photo-frame).

​
Write your own

Yes, Ryoku has a plugin SDK. A plugin is a folder with a manifest.json, a non-visual service/Main.qml (your logic and state), and one content/Widget.qml (your view), installed to ~/.local/share/ryoku/plugins/<id>/. Your view imports the Ryoku.PluginKit deck kit, so it picks up the shell’s colours, type, and motion automatically.
The golden rule: never set your own position, never draw your own window chrome, never assume your size. You report your content’s natural implicitWidth and implicitHeight; Ryoku sizes the card or grows the popout around it. Break this rule and your plugin looks bolted-on instead of native.
The full authoring guide, the manifest schema, the three densities (glyph, compact, full), and the settings schema live in the repo:

​
See also

Extras

Software bundles, the other half of how Ryoku grows beyond its core.

Ryoku Settings

The Store and Installed panels, and everything else the Hub tunes.
Last modified on July 4, 2026