destefanis GitHub avatar

liquid-glass-screensaver

destefanis

A macOS screensaver that renders a liquid glass shader composition with three glass orbs floating over animated water caustics.

Stars

98

7-day growth

No data

Forks

5

Open issues

0

License

MIT

Last updated

2026-07-05

AI repository intelligence
FR-AI / ANALYSIS

Why it is worth attention

Open-source Metal screensaver that documents hard-won fixes for building modern macOS screen savers, including Swift principal class, Metal library loading from bundle, self-driven rendering, and host process exit handling.

Who it is for

  • macOS users seeking a visually appealing screensaver
  • Metal graphics programmers learning shader development
  • macOS developers building screen savers
  • Open source enthusiasts interested in beautiful screen savers

Use cases

  • Personal desktop screensaver with customizable fresnel glow and dark mode
  • Learning reference for Metal shader programming and screen saver architecture
  • Base template for creating custom Metal-based screen savers
  • Testing and experimenting with macOS screen saver development

Strengths

  • Beautiful liquid glass visual effect with realistic caustics
  • Includes light/dark mode and adjustable fresnel glow
  • Open source under MIT license with prebuilt signed and notarized releases
  • Detailed build instructions with workarounds for common screen saver pitfalls

Considerations

  • Only compatible with macOS
  • Requires manual installation of .saver file
  • Host process may wedge if exit workaround is not used, affecting preview reliability

README quick start

Liquid Glass Screensaver

A macOS screensaver that renders a liquid glass shader composition: three glass orbs floating over animated water caustics. Includes a light and dark mode, with options for controlling the fresnel glow. I thought it would be fun to open source this so others could build and learn from it!

Install (prebuilt)

Grab liquid-glass-screensaver.zip from the latest release, unzip, and double-click the .saver (or copy it to ~/Library/Screen Savers/), then select it in System Settings → Screen Saver. The build is Developer ID-signed and notarized.

Build & Install

xcodebuild -project liquid-glass-screensaver.xcodeproj -scheme liquid-glass-screensaver -configuration Release build
cp -R ~/Library/Developer/Xcode/DerivedData/liquid-glass-screensaver-*/Build/Products/Release/liquid-glass-screensaver.saver ~/Library/Screen\ Savers/
killall legacyScreenSaver 2>/dev/null

Then pick liquid-glass-screensaver in System Settings → Screen Saver. Options… has a fresnel glow slider and a dark background toggle.

(Or open the project in Xcode, ⌘B, and copy the built .saver to ~/Library/Screen Savers/.)

Building Your Own Metal Screensaver

Start from Xcode's macOS → Screen Saver template, then apply these. Each one is a hard-won fix for how modern macOS hosts screensavers:

  1. Swift principal class. The template is Obj-C. For Swift, name your view @objc(your_principal_class_name) to match NSPrincipalClass in the build settings, and add SWIFT_VERSION to the project.
  2. Load your Metal library from the saver's bundle. device.makeDefaultLibrary() resolves against the host app (legacyScreenSaver), not your bundle, and silently fails. Use makeDefaultLibrary(bundle: Bundle(for: YourClass.self)).
  3. Drive rendering yourself. Run the MTKView with isPaused = false and its own display link. The host drops animateOneFrame/startAnimation calls when it gets into a bad state; a saver that depends on them renders black.
  4. Exit the host process when your saver stops. Observe the com.apple.screensaver.willstop distributed notification (and NSWorkspace.willSleepNotification) and call exit(0). Without this the host process wedges: Preview works exactly once and the process lingers until killed in Activity Monitor