MatrixRainColors.mp4
MatrixRain is available through winget:
winget install relmer.MatrixRainI built this Win32/DirectX C++ Matrix-rain screensaver/demo as a test project to try out SpecKit, which worked really well. The app supports configurable density, color schemes, and has some snazzy glow effects for that classic CRT vibe.
Status: Active — complete demo with unit & integration tests. Fully functional as both a standalone desktop app and Windows screensaver.
- Overview — Quick project summary and screenshot.
- Screensaver Installation — How to install MatrixRain as a Windows screensaver.
- Screensaver Usage — Command-line arguments and Control Panel integration.
- Hotkeys — List of hotkeys and the features they control (desktop mode).
- Debug Helpers — Some debug displays I found useful.
- Specs & SpecKit — Spec-driven development and extensive specs for the app.
- Requirements — Required tools and SDKs.
- Build (Visual Studio) — How to open and build in Visual Studio.
- Build (VS Code) — How to build from VS Code / command line.
- Run — Running the built app and tests.
- Code Organization — Where the major components live.
- Contributing — How to help.
MatrixRain is a small C++ project that implements the classic "Matrix" falling-character animation using a lightweight animation + rendering architecture. It works as both a standalone desktop application and a fully-featured Windows screensaver with configurable settings. The video above is included as assets/MatrixRainColors.mp4.
After building the project, you'll find MatrixRain.exe in the output directory (x64\Debug or x64\Release).
To install as a screensaver:
MatrixRain.exe /install
This copies the executable to C:\Windows\System32\MatrixRain.scr, sets it as the active screensaver, and opens the Screen Saver Settings dialog. A UAC elevation prompt will appear since writing to System32 requires admin privileges.
To uninstall:
MatrixRain.exe /uninstall
This removes the .scr file from System32 and cleans up the screensaver registry entries. A confirmation message is displayed on completion.
Note: Certain Group Policy settings can block screensaver use. If a device lock or screensaver-blocking policy is detected, the install is aborted with an error message showing the specific policy. You can override the policy check with
/install /force, but the policy may still block the screensaver from running.
MatrixRain supports the following command-line arguments:
| Argument | Description |
|---|---|
| (none) | Run as desktop application with hotkeys enabled |
/? |
Display usage (command-line switches) |
/install |
Install MatrixRain as system screensaver |
/uninstall |
Uninstall MatrixRain screensaver |
/force |
Skip policy checks (use with /install) |
The following switches are part of the Windows screensaver protocol and are invoked automatically by the operating system. They are not intended for manual use:
| Argument | Description |
|---|---|
/s |
Screensaver mode (fullscreen, exit on input) |
/p <HWND> |
Preview mode in Control Panel window |
/c[:<HWND>] |
Settings dialog parented to HWND, if present |
/a |
Password change (not supported, handled gracefully) |
- Density: Control the number of falling character streaks (0-100%)
- Animation Speed: Adjust how fast characters fall (1-200%)
- Glow Intensity: Control the bloom effect strength (0-200%)
- Glow Size: Adjust bloom spread radius (50-200%)
- Color Scheme: Choose from green, blue, red, amber, or color cycle mode
- Start Fullscreen: Toggle whether app launches in fullscreen mode
- Show Debug Stats: Display FPS and density information (disabled in screensaver modes)
- Show Fade Timers: Display per-character fade countdown (disabled in screensaver modes)
- Reset: Restore all settings to defaults
When MatrixRain is running as a desktop app, you can launch /c without an HWND to get a live configuration dialog that updates the animation in real-time as you adjust settings. Press OK to save changes, or Cancel to revert to previous values.
Press ? to show the hotkey reference overlay in-app:
| Key | Action |
|---|---|
| Space | Pause / resume animation |
| Enter | Open settings dialog (live overlay) |
| C | Cycle color schemes (green, blue, red, amber, color cycle) |
| S | Toggle statistics (FPS / other stats) |
| ? | Show hotkey reference overlay |
| + | Increase density 5% |
| - | Decrease density 5% |
| Alt + Enter | Toggle display mode (windowed ↔ fullscreen) |
| Esc | Exit application |
Press S to toggle the statistics display for nerdy debugging information:
- Density (percentage of maximum streaks for the window size)
- Number of rain streak heads on screen
- Number of rain streaks (including partials still fading off) on screen
- FPS
Press ` (backtick) to toggle the per-character fade timer. This gets pretty cluttered with more than just a few streaks, so you probably want to dial down the density first.
- My main goal with this project was to learn about spec-driven development with SpecKit. Starting with a short description of the app's purpose and behavior, SpecKit generated a detailed spec with five user stories, assigned priorities to them, and generated acceptance criteria for each. It came up with a set of edge cases to be clarified and tested, and 27 functional requirements.
- The next step was to start plan mode. Using the spec from the previous step, and some high-level implementation requirements from me (e.g., use DirectX), it generated a plan. It also did research into DX, text rendering options, etc. and generated a data-model.
- SpecKit was then ready to generate tasks--lots of tasks; 192 of them. These were organized into implementation phases to achieve specific high-level outcomes, and also included annotation about which user story they accrued to and which tasks were parallelizable.
- At this point, SpecKit was ready to start implementing tasks. It can work on individual tasks, whole phases, or anything in between. It will go in its recommended order, but you can override that if you like.
- Throughout the various stages of work, SpecKit is constantly cross-checking that the LLM's output remains aligned with the defined constitution, spec, plan, and related documents. Compared to working in Cline, this kept the LLM better focused and moving in the right direction. These files provide better, more specific context to the model throughout the journey. While Cline is very good, it is largely at the mercy of the current chat history which can rapidly lose critical context as the implementation moves forward.
SpecKit docs: https://github.com/github/spec-kit
- OS: Windows (tested on Windows 11).
- Compiler / Build tools: Visual Studio 2026 with C++ desktop workload (MSVC toolchain), Windows SDK.
- Build system: MSBuild (used by Visual Studio) and
msbuildCLI. - Optional tools: VS Code with C/C++ extension and the MSVC command-line toolchain available in PATH (or via Developer Command Prompt).
- Open the solution:
MatrixRain.slnin Visual Studio. - Select configuration
DebugorReleaseand platformx64. - Build the solution using the Build menu ->
Build Solution.
- Open the workspace file
MatrixRain.code-workspacein VS Code. - From the menu:
Terminal->Run Task...and chooseBuild Debug (current arch)orBuild Release (current arch). - Or open the Command Palette (Ctrl+Shift+P) and run
Tasks: Run Task, then pick the desired build task.
- After building, run the executable from
x64\Debug\MatrixRain.exeorx64\Release\MatrixRain.exe.
- Unit and integration tests are in the
MatrixRainTestsproject. - To run tests with the Visual Studio Test Runner or
vstest.console.exe(example):
vstest.console.exe .\x64\Debug\MatrixRainTests.dllMatrixRain/— Top-level app project (Win32 entry, resources, and launcher).main.cpp,MatrixRain.rc, and project fileMatrixRain.vcxproj.
MatrixRainCore/— Core engine and subsystems (preferred place for unit-testing).- All headers and source files in flat structure at root level:
AnimationSystem.h/.cpp,Application.h/.cpp,ApplicationState.h/.cpp,CharacterSet.h/.cpp,RenderSystem.h/.cpp,Timer.h/.cpp,Viewport.h/.cpp, etc.
pch.h/pch.cpp— Precompiled headers for faster buildsEhm.h/Ehm.cpp— Error handling macros and utilities
- All headers and source files in flat structure at root level:
MatrixRainTests/— Unit and integration tests.specs/— Human-readable specification files (generated/managed with SpecKit in our workflow).
- The project uses precompiled headers (
pch.h/pch.cpp) to speed builds; ensure PCH settings are preserved when importing files into the project. - Error handling uses the project's
Ehm.*facilities — seeMatrixRainCore/Ehm.hfor patterns and macros used throughout the codebase. - Keep formatting and alignment consistent with existing code conventions when contributing.
- Fork, create a feature branch, and open a pull request against
master. - Run unit and integration tests locally before submitting.
- If you're adding features that affect rendering, include a short spec in
specs/describing behavior and configuration knobs.
