digital-matrix-rain/README.md

A cool matrix-style digital rain animation for terminal/console applications

# 🌊 Digital Matrix Rain NPM Package

A cool matrix-style digital rain animation for terminal/console applications. Create the iconic "Matrix" falling green text effect in your Node.js applications!

## ✨ Features

- 🎨 Multiple colors (green, red, blue, yellow, magenta, cyan, white)
- ⚡ Customizable speed and density
- 🖥️ Auto-detects terminal size
- 🎮 CLI tool included
- 📦 Easy to integrate into any Node.js project
- 🔧 Highly configurable

## 🚀 Installation

```bash
npm install digital-matrix-rain
```

## 🎯 Quick Start

### Command Line Usage

```bash
# Basic matrix animation
npx digital-matrix-rain

# Or if installed globally
npm install -g digital-matrix-rain
digital-matrix

# With custom options
digital-matrix --speed 50 --color cyan --density 0.2
```

### Programmatic Usage

```javascript
const { matrix, MatrixRain } = require('digital-matrix-rain');

// Quick start - classic green matrix
matrix();

// Custom configuration
const animation = new MatrixRain({
  color: 'red',
  speed: 80,
  density: 0.15
});
animation.start();

// Run for specific duration (5 seconds)
animation.run(5000);
```

## 🎨 API Reference

### `MatrixRain` Class

Main class for creating matrix animations.

```javascript
const animation = new MatrixRain(options);
```

#### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `width` | number | Terminal width | Animation width in characters |
| `height` | number | Terminal height | Animation height in lines |
| `speed` | number | 100 | Animation speed in milliseconds |
| `density` | number | 0.1 | Drop density (0.0 - 1.0) |
| `color` | string | 'green' | Color theme |
| `chars` | string | Mixed alphanumeric | Custom character set |

#### Methods

- `start()` - Start the animation
- `stop()` - Stop the animation
- `run(duration)` - Run for specific duration in milliseconds

### Helper Functions

```javascript
// Quick matrix with default settings
matrix();

// Create animation instance
const animation = createMatrixAnimation(options);

// Run demo
demo();
```

## 🎨 Available Colors

- `green` (classic Matrix)
- `red`
- `blue` 
- `yellow`
- `magenta`
- `cyan`
- `white`

## 🛠️ CLI Options

```bash
digital-matrix [options]

Options:
  -s, --speed <number>     Animation speed in ms (default: 100)
  -c, --color <color>      Color theme (default: green)
  -d, --density <number>   Drop density 0.0-1.0 (default: 0.1)
  -h, --help              Show help

Examples:
  digital-matrix
  digital-matrix --speed 50 --color cyan
  digital-matrix -s 150 -c red -d 0.2
```

## 🎮 Examples

### Basic Example

```javascript
const { MatrixRain } = require('digital-matrix-rain');

const matrix = new MatrixRain();
matrix.start();

// Stop after 10 seconds
setTimeout(() => {
  matrix.stop();
}, 10000);
```

### Custom Animation

```javascript
const { MatrixRain } = require('digital-matrix-rain');

const customMatrix = new MatrixRain({
  color: 'cyan',
  speed: 60,
  density: 0.2,
  chars: '01ⱦ⌘▓▒░█'  // Custom cyberpunk characters
});

customMatrix.start();
```

### Multiple Animations

```javascript
const { MatrixRain } = require('digital-matrix-rain');

// Sequence of different colored animations
const colors = ['green', 'red', 'blue', 'cyan'];
let index = 0;

function nextAnimation() {
  if (index >= colors.length) return;
  
  const matrix = new MatrixRain({ 
    color: colors[index],
    speed: 80 
  });
  
  matrix.run(3000);
  index++;
  
  setTimeout(nextAnimation, 3500);
}

nextAnimation();
```

## 📝 Scripts

```bash
npm test          # Run tests
npm start         # Start basic animation
npm run matrix    # CLI matrix animation
npm run demo      # Run color demo
```

## 🎬 Demo

Run the included demo to see all colors and effects:

```bash
npm run demo
```

## 🕹️ Controls

- **Ctrl+C**: Stop the animation and exit

## 🔧 Development

```bash
git clone <your-repo>
cd digital-matrix-rain
npm install
npm test
```

## 📄 License

ISC

## 👨‍💻 Author

arsh

## 🤝 Contributing

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

## 🌟 Inspiration

Inspired by the iconic digital rain effect from "The Matrix" movie series. Perfect for:

- Terminal applications
- CLI tools
- Cyberpunk-themed projects
- Screen savers
- Demo applications
- Educational projects

---

*"Welcome to the Matrix... 🕶️"*