GitHub - sin-ack/papertoy: Run a Shadertoy-compatible shader as an animated wallpaper on Wayland

2 min read Original article ↗

Papertoy

justforfunnoreally.dev badge

Run a Shadertoy-compatible shader as an animated wallpaper on Wayland. Requires running a wlroots-compatible Wayland compositor.

Showcase

2025-05-18_21-12-16.mp4

Shader: Balatro main menu background shader (not publicly available)

Papertoy running the "Seascape" shader

Shader: Seascape by TDM - https://www.shadertoy.com/view/Ms2SD1

Papertoy running the "Auroras" shader

Shader: Auroras by Nimitz - https://www.shadertoy.com/view/XtGGRt

Dependencies

You'll most likely have these installed if you have a Wayland compositor anyway.

  • Debian and variants: libwayland-client0 libwayland-egl1 libegl1 libglvnd0 libffi8
  • Gentoo: dev-util/wayland media-libs/glvnd dev-libs/libffi

Install

Either download the latest release or follow the build instructions below.

Place papertoy somewhere in your PATH (e.g. .local/bin).

Once I'm happy with the stability I'll probably go for system packages.

Usage

Run the binary with the path to a Shadertoy shader as an argument:

$ zig-out/bin/papertoy /path/to/shader.glsl

Important

Currently, only shaders that don't use any channels are supported. This is being worked on.

Options:

  • --output <id>: Render to this Wayland output index (default: 0)
  • --frame-rate <fps>: Limit the frame rate of the shader (default: output refresh rate)
  • --resolution <WxH>: Limit the resolution the shader is rendered at (default: output native resolution)

Build

Nix

  1. nix run .
  2. There is no second step.

You can add the flake to your profile with: nix profile install github:sin-ack/papertoy/<version>

Bare metal

Dependencies

  • Zig 0.15.2
  • libwayland
    • Debian and variants: libwayland-dev
    • Gentoo: dev-util/wayland
  • libglvnd
    • Debian and variants: libglvnd-dev
    • Gentoo: media-libs/glvnd

Steps

  1. Install the listed dependencies above.
  2. Clone the repository.
  3. Run zig build -Doptimize=ReleaseFast

The binary will be located at zig-out/bin/papertoy.

License

Copyright (c) 2025, sin-ack. Released under the GNU General Public License, version 3.

The Shadertoy preamble is from the Ghostty project. Copyright (c) 2024 Mitchell Hashimoto, License: MIT

The wlr-layer-shell-unstable-v1 protocol is from the wlr-protocols project. Copyright (c) 2017 Drew DeVault, License: MIT