qmatrix 1.3.1
A high-performance, aesthetically pleasing Matrix rain TUI with horror elements.

# QMATRIX

![License](https://img.shields.io/badge/license-MIT-green)
![Python](https://img.shields.io/badge/python-3.8%2B-blue)
![Platform](https://img.shields.io/badge/platform-linux-lightgrey)

**QMatrix** is not just another Matrix rain script. It is a high-performance, precision-tuned TUI engine designed to replicate the authentic "Digital Rain" aesthetic of the original 1999 masterpiece, infused with modern "horror" glitch mechanics and premium terminal visuals.

> Crafted by **Rex Ackermann**

---

## ⚡ Features

### 🟢 Matrix Aesthetic
*   **The Wall of Code**: Optimized for high-density rendering (Density=1), creating a solid curtain of raining data.
*   **Precision Gradient**: A bespoke 4-stage color engine:
    1.  **Head**: Blinding White lead characters.
    2.  **Body**: A vibrant, alternating mix of **Sushi Green (#86ab48)** and **Neon Bright Green**.
    3.  **Tail**: Deep Green fade-out.
*   **True Physics**: Quotes don't just fade; they **physically slide** down the screen like heavy blocks of data.
*   **Katakana Glyphs**: Full support for half-width Katakana, achieving the iconic "Matrix" look.

### 👻 Horror & Glitch Mechanics
*   **Stationary Persistence**: Quotes type out, **freeze** in mid-air, and then drop or vanish.
*   **Hybrid Logic**:
    *   **90%**: Quotes slide down ("Rain").
    *   **10%**: Quotes glitch and **vanish instantly** ("Ghost in the Shell").
*   **Subliminal Corruption**: Rare chance for text to shatter, flip, or invert during the fall.

### 🚀 Production Ready
*   **Crash-Proof**: Robust signal handling (`Ctrl+C` safe).
*   **Clean Exit**: Leaves your terminal spotless on quit.
*   **Performance**: `stdscr.timeout` based loop for smooth 20FPS rendering without CPU hogging.
*   **Terminal Optimization**: Special color overrides for **Kitty** and **Ghostty** terminals.

---

## 📦 Installation

Since this is a production-grade Python package, you can install it directly from PyPI:

```bash
pip install qmatrix
```

Or build from source:

```bash
git clone https://github.com/rexackermann/qmatrix.git
cd qmatrix
pip install .
```

---

## 🎮 Usage

Run it simply by typing:

```bash
qmatrix
```

### Premium Flags

Customize the simulation to your exact mood:

| Flag | Description | Default |
| :--- | :--- | :--- |
| `-d`, `--density` | Spacing between columns (1 = Max Density) | `1` |
| `--tail-min` | Minimum length of rain trails | `25` |
| `--tail-max` | Maximum length of rain trails | `50` |
| `-m`, `--mix` | Ratio of Quotes vs Normal Rain | `0.15` |
| `--horror` | Enable subliminal glitch effects | `False` |
| `--sexy` | Force high-fidelity colors for modern terminals | `False` |
| `--fps` | Target Frame Rate (Smoothness) | `60` (Sexy) / `20` |
| `--transparent` | Use terminal's native background (Images/Wallpaper) | `False` |
| `--bg-color` | Set solid background color (e.g., `red`, `blue`) | `black` |

**Example Production Run:**
```bash
qmatrix --density 1 --tail-min 30 --mix 0.2 --horror --transparent
```

---

## 🛠 Configuration

QMatrix supports XDG configuration. You can place a persistent config file at:
`~/.config/qmatrix/config.json`

```json
{
    "speed": 0.2,
    "color": "green",
    "density": 1,
    "tail_min": 30,
    "horror": true
}
```

---

## 📜 License

Distributed under the **MIT License**. See `LICENSE` for more information.

---

## 💡 Credits

Special thanks to the [Tmatrix](https://github.com/M4444/Tmatrix) project for the original inspiration and physics concepts.

> "The Matrix is everywhere. It is all around us."