📺 Terminal Screensaver

A modern, high-performance terminal screensaver written in Python. Featuring multiple animated patterns that bring your terminal to life with smooth animations and vibrant colors.

✨ Features

• Matrix Rain: Classic digital rain effect using Katakana and numeric characters.
• Starfield: A 3D starfield simulation with depth perception and speed control.
• Bouncing Balls: Physics-based balls with trails and realistic wall/floor bounces.
• Plasma Waves: Colorful, animated plasma effect generated using interfering sine waves.
• Conway's Game of Life: Simulation of cellular automata with random seeding.
• Realistic Rain: Gentle rain effect with splashes at the bottom of your screen.
• Cross-Platform: Works seamlessly on Linux, macOS, and Windows.
• Customizable: Adjustable frame rate (FPS), monochrome mode, and more.

🚀 Quick Start

Prerequisites

• Python 3.12 or higher

Installation

Clone the repository and install in editable mode:

git clone https://github.com/youruser/terminal-screensaver.git
cd terminal-screensaver
pip install -e .

Running the Screensaver

Run with default settings (random pattern at 30 FPS):

screensaver

Runtime Controls

While the screensaver is running, you can use the following keys:

• n: Switch to the next available pattern.
• q or any other key: Exit the screensaver.

Configuration File

The screensaver looks for a configuration file at ~/.config/screensaver/config.json. You can use this to set your permanent preferences.

Example config.json:

{
  "fps": 60,
  "pattern": "plasma",
  "color_enabled": true
}

Or use the quick start script without installation:

python3 run_screensaver.py

🛠️ Usage

screensaver [OPTIONS]

Options

Option	Description
-p, --pattern PATTERN	Choose pattern: matrix, starfield, bouncing, plasma
--fps N	Set target frame rate (1-120, default: 30)
--no-color	Disable colors (monochrome mode)
--list	List all available patterns with descriptions
-h, --help	Show help message and exit

Examples

# Run the Starfield pattern at 60 FPS
screensaver -p starfield --fps 60

# Run the Matrix pattern in monochrome
screensaver -p matrix --no-color

🤝 Contributing

Contributions are welcome! Whether it's adding new patterns, fixing bugs, or improving documentation.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-pattern)
3. Run tests (python3 -m pytest)
4. Commit your changes (git commit -m 'Add amazing pattern')
5. Push to the branch (git push origin feature/amazing-pattern)
6. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.