Jacob SabellaandGitHub
68c64f31b1
Noctalia derives its color scheme from whatever image is set as the wallpaper. A live Wallpaper Engine scene is not an image the shell can read, so the palette stayed pinned to whatever wallpaper came before. Applying a wallpaper now also hands Noctalia a still of it -- the Workshop preview, or a decoded frame for video wallpapers when ffmpeg is present -- so the configured generator, scheme, mode and templates all run exactly as they do for an ordinary wallpaper. The previous wallpaper is saved per output and restored on stop. Toggle: sync_colors. Add multi-select with timed cycling. Selected wallpapers carry a badge showing their place in the rotation, and play in selection order or shuffled; random plays a full pass before reshuffling so nothing repeats back to back. Selection, interval and order are per output. Add per-wallpaper settings behind a gear on each tile: the linux-wallpaperengine switches (scaling, clamp, layer, FPS, volume, mute, particles, mouse, parallax, fullscreen pause), plus the wallpaper's own properties parsed from project.json and rendered by declared type, honoring each property's visibility condition. Move process ownership, the palette sync and the cycle timer into the service. The panel is now pure UI talking over noctalia.state, so a cycle keeps running while the panel is closed and one owner holds the pid files. Fix three process-handling bugs along the way: - The running-process check anchored on "^linux-wallpaperengine", but packagers ship a wrapper that execs ./linux-wallpaperengine from its own directory, so no process ever matched and every apply leaked another GPU client onto the same output. - Current builds ignore both SIGTERM and SIGINT, so the kill never landed either. Stopping now escalates to SIGKILL after a grace period. - The reload sweep used pkill -f, which matches the shell running the command itself and killed it part way through, leaving orphans. Cache a static still per wallpaper for the grid. Workshop previews are frequently animated GIFs, and the grid decoded and animated all of them continuously for as long as the panel was open. plugin_api moves 3 -> 9: tile and control callbacks are Luau closures rather than named globals, which the host resolves from API 9 onwards. This is what the plugin already required; the manifest understated it.
137 lines
7.1 KiB
Markdown
137 lines
7.1 KiB
Markdown
# W Engine
|
|
|
|
A [Noctalia](https://github.com/noctalia-dev/noctalia) v5 plugin for applying Wallpaper Engine wallpapers from Steam Workshop.
|
|
|
|
## Dependencies
|
|
|
|
Before installing this plugin, make sure you already have Wallpaper Engine installed from Steam. Without it, the plugin will not work.
|
|
|
|
You need Steam itself to download wallpapers from the Workshop, plus the `linux-wallpaperengine` tool.
|
|
|
|
You also need `kill` to stop duplicate wallpaper processes when changing wallpapers, and `setsid` to start the wallpaper process correctly.
|
|
|
|
`ffmpeg` is optional. It is used to take a still frame from video wallpapers for the color sync, and to build the panel's preview thumbnails.
|
|
|
|
For more details, see the install section below.
|
|
|
|
## Plugin
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| ID | `tadomika_ari/w-engine` |
|
|
| Entries | Bar widget: `w-engine-widget`; panel: `w-engine-panel`; Service: `start`|
|
|
|
|
## Usage
|
|
|
|
Add the `W Engine` widget from Noctalia's widget picker, then click it to open the panel. You can also open the panel directly or bind it in your compositor:
|
|
|
|
```sh
|
|
noctalia msg panel-toggle tadomika_ari/w-engine:w-engine-panel
|
|
```
|
|
|
|
| Action | Effect |
|
|
| --- | --- |
|
|
| Left click on the bar glyph | Open or close the W Engine panel |
|
|
| Click a wallpaper entry in the panel | Apply that wallpaper |
|
|
| Select an output | Change the monitor where the wallpaper is displayed |
|
|
| Click the gear on a wallpaper | Open that wallpaper's own settings |
|
|
| Click `Select multiple` | Pick several wallpapers and cycle through them on a timer |
|
|
| Click `Stop` | Stop the wallpaper on that output and restore the previous Noctalia wallpaper |
|
|
|
|
## Settings
|
|
|
|
Shell colors:
|
|
|
|
Noctalia builds its color scheme from the current wallpaper image, which a live Wallpaper Engine scene is not, so without this the shell stays themed for whatever wallpaper was set before. With `Sync shell colors with the wallpaper` enabled, which is the default, applying a wallpaper also hands Noctalia a still of it, and the usual palette generator, scheme, mode and templates all run as they do for a normal wallpaper. The still is the Workshop preview, or a frame decoded from the video for video wallpapers when `ffmpeg` is installed. The wallpaper Noctalia had before is saved per output and restored by `Stop`.
|
|
|
|
Wallpapers per row:
|
|
|
|
How many wallpapers the panel shows in each row, from 2 to 8, 4 by default. The panel is a fixed size, so fewer columns means larger previews.
|
|
|
|
Cycling:
|
|
|
|
Press `Select multiple`, then click the wallpapers you want. Each one is numbered with its place in the rotation, in the order you clicked them. Set how long each stays up in minutes, pick `In order` or `Random`, then press `Start cycle`. Random plays a shuffled pass over the whole selection before reshuffling, so a wallpaper cannot come up twice in a row. Each output keeps its own selection, interval and order, and the cycle keeps running once the panel is closed. Applying a single wallpaper stops the cycle on that output.
|
|
|
|
Global defaults:
|
|
|
|
The wrench beside the screen selector opens the same `Playback` controls, applied to every wallpaper. Setting `Mute this wallpaper` there mutes the whole library in one step rather than one wallpaper at a time. A wallpaper's own settings override these key by key, and anything left on `Engine default` falls through to `linux-wallpaperengine`.
|
|
|
|
Applying defaults can optionally clear the matching per-wallpaper overrides. That only affects the settings actually changed at the same time, so an override left untouched keeps its value.
|
|
|
|
Per-wallpaper settings:
|
|
|
|
The gear icon on a wallpaper opens its own settings, saved per wallpaper and used every time it is applied, including inside a cycle.
|
|
|
|
`Playback` holds the `linux-wallpaperengine` switches: scaling and clamp mode, Wayland layer, FPS limit, volume, mute, automute, audio processing, particles, mouse interaction, parallax and the fullscreen pause behavior. Anything left on `Engine default` emits no flag, so the engine's own default applies.
|
|
|
|
`Wallpaper properties` is whatever that wallpaper exposes. Wallpaper Engine items declare their own settings in `project.json`, so this part is built fresh for each one: `bool` becomes a toggle, `slider` a slider using the declared min, max and step, `color` a swatch that opens Noctalia's color picker, `combo` a dropdown of the author's options and `textinput` a text field. `text` and `group` are headings, and `file`, `directory` and `scenetexture` are left alone because they point into the wallpaper's own assets. Properties can declare a condition on another property and the form honors it, so switching off `Audio Bar` also hides its color and count. Some authors never rename the properties they add, leaving Wallpaper Engine's placeholder names; those are collected behind a toggle at the end of the list. Property labels are frequently authored as HTML, using `<br>` to separate a translated label from its English counterpart, so the markup is stripped and headings that consist only of decoration are omitted.
|
|
|
|
These are command-line arguments, so `Apply` restarts the wallpaper on any output showing it, and the restore icon clears everything back to the wallpaper's own defaults.
|
|
|
|
Custom path:
|
|
|
|
To define a custom path for Steam or the Workshop, you can add a specific path for W Engine.
|
|
You can create a `data.json` file in `$NOCTALIA_STATE_HOME` based on this example:
|
|
|
|
```json
|
|
{
|
|
"personnalPath": ["path1"]
|
|
}
|
|
```
|
|
|
|
Replace `path1` with your personal path or add other paths. The path is loaded after a reload or if you reopen the widget.
|
|
|
|
The same file also stores the selection, cycle and per-wallpaper settings, so keep the other keys if it already exists.
|
|
|
|
## IPC
|
|
|
|
Beyond opening the panel, the service accepts:
|
|
|
|
```sh
|
|
# Advance to the next wallpaper in the selection now
|
|
noctalia msg plugin tadomika_ari/w-engine:start all next [connector]
|
|
|
|
# Pause the cycle, leaving the current wallpaper up
|
|
noctalia msg plugin tadomika_ari/w-engine:start all cycle-stop [connector]
|
|
|
|
# Stop the wallpaper and restore the previous Noctalia wallpaper
|
|
noctalia msg plugin tadomika_ari/w-engine:start all stop [connector]
|
|
```
|
|
|
|
The optional payload is an output connector such as `DP-1`. Without it, the focused output is used.
|
|
|
|
## Requirements
|
|
|
|
- noctalia ≥ 5.0.0
|
|
- `linux-wallpaperengine`
|
|
- `kill`
|
|
- `pkill`
|
|
- `setsid`
|
|
- `ffmpeg` (optional, for video wallpaper colors and preview thumbnails)
|
|
- Wallpaper Engine
|
|
- Steam for Workshop access
|
|
|
|
## Install
|
|
|
|
Install **W Engine** from Noctalia's plugin store (*Settings → Plugins*), then add the widget to a bar from *Settings → Bar*. Plugin options live in *Settings → Plugins*.
|
|
|
|
Next, install Wallpaper Engine from Steam: https://store.steampowered.com/app/431960/Wallpaper_Engine/
|
|
|
|
Then install `linux-wallpaperengine` from its project page: https://github.com/Almamu/linux-wallpaperengine
|
|
|
|
Note that some Wallpaper Engine wallpapers may not work correctly on Linux, especially ones with advanced visual effects.
|
|
|
|
If you use NixOS, be aware that the package version in nixpkgs may lag behind upstream.
|
|
|
|
For local development, add your working copy as a path source instead
|
|
(`.luau` edits hot-reload):
|
|
|
|
```sh
|
|
noctalia msg plugins source add dev path /path/to/plugins
|
|
noctalia msg plugins enable tadomika_ari/w-engine
|
|
```
|
|
|
|
## License
|
|
|
|
MIT.
|