macOS Matrix Screen Saver

This is a macOS screen saver based on the iconic rain of characters and symbols known from the movie The Matrix.

Quick install

1. Open the latest release and download the versioned .zip file from the release assets.

2. Double-click the downloaded .zip file to extract MatrixScreenSaver.saver.

3. In Terminal, run the following commands from the directory that contains the extracted MatrixScreenSaver.saver file:

   xattr -dr com.apple.quarantine MatrixScreenSaver.saver
   mkdir -p "$HOME/Library/Screen Savers"
   rm -rf "$HOME/Library/Screen Savers/MatrixScreenSaver.saver"
   ditto MatrixScreenSaver.saver "$HOME/Library/Screen Savers/MatrixScreenSaver.saver"
   open "x-apple.systempreferences:com.apple.Wallpaper-Settings.extension"

4. In the opened Wallpaper settings, switch to Screen Saver and select MatrixScreenSaver.

5. Enjoy and donate
   
   

Options

The saver exposes a native Options… sheet. The values are stored with ScreenSaverDefaults.

Option	Description	Default
Number scene	Show the startup number scene before continuous rain.	On
Twinkle	Turn on/off the twinkling effect.	On
Diffuse	Turn on/off the glow effect.	On
Character size	Set the character cell width and height in pixels. Example pairs: 8 x 15, 9 x 17, 10 x 19, 11 x 21, 12 x 23, and 13 x 24.	9 x 17
Rain density	Set the factor for the density of rain drops. A positive number.	1.0
Frame rate	Set the frame rate per second. A positive number less than or equal to 1000.	25
Error rate	Set the factor for the rate of character changes. A non-negative number.	1.0

Development

Current state

• Native Swift/AppKit screen saver bundle
• Edge-to-edge full-screen saver output, with terminal-style chrome kept in the preview host
• In-process renderer for rain-forever with an optional upstream number intro
• Native Options… sheet for Number scene, Twinkle, Diffuse, Character size, Rain density, Frame rate, and Error rate
• Preview app for fast iteration without reinstalling

Repository layout

• Sources/MatrixScreenSaver/MatrixScreenSaverView.swift - screen saver view, layout, drawing, and option wiring
• Sources/MatrixScreenSaver/NativeMatrixRenderer.swift - native Matrix scene renderer
• Sources/MatrixScreenSaver/MatrixScreenSaverOptions.swift - options model and native configure sheet
• Sources/MatrixScreenSaver/TerminalSupport.swift - small shared terminal types used by the active renderer
• Scripts/install-saver.sh - shared ditto-based installer used by local installs
• Tools/PreviewHost.swift - local preview host used by ./preview.sh
• Resources/Info.plist - bundle metadata

Requirements

• macOS
• Xcode Command Line Tools with swiftc

Full Xcode is not required.

Build

./build.sh

This creates the screen saver bundle:

build/MatrixScreenSaver.saver

build.sh reads the current version from ./VERSION and writes it into the saver bundle metadata.

Preview without installing

./preview.sh

This rebuilds the bundle, compiles the preview host, and opens the saver in a normal macOS window for quick iteration.

Install

./install.sh

install.sh:

1. rebuilds the saver bundle
2. strips quarantine from the source bundle and copies it to ~/Library/Screen Savers/MatrixScreenSaver.saver
3. verifies the installed executable matches the build output
4. stops running ScreenSaverEngine / legacyScreenSaver processes so macOS reloads the updated bundle

After installing:

1. open System Settings > Wallpaper > Screen saver...
2. select MatrixScreenSaver

To relaunch the screen saver host manually:

open -a ScreenSaverEngine

Origin

This project started as an attempt to wrap cxxmatrix inside a macOS screen saver.

The current implementation is based on the upstream akinomyoga/cxxmatrix project and keeps its look and scene behavior, but it no longer launches an external terminal process at runtime. The active saver is a native in-process Swift/AppKit renderer because ScreenSaverEngine did not reliably render the external terminal stream.

The active renderer currently ports rain-forever and can optionally start with the upstream number intro.