qmatrix 1.3.1

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

QMATRIX

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:

pip install qmatrix

Or build from source:

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

---

🎮 Usage

Run it simply by typing:

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:

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

{
    "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 project for the original inspiration and physics concepts.

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