🌑 Terminal Black Hole

A mesmerizing, physics-inspired black hole animation for your terminal

        ·  ✦        ·    ✧         ·
    ✧       ·    ░░▒▒▓▓▓▓▒▒░░    ·      ✦
         ✦    ░▒▓███████████▓▒░    ✧
      ·     ▒▓███████████████████▓▒     ·
   ✧      ▓███████           ███████▓      ✦
        ▓██████                 ██████▓
  ·    ▓█████        ███        █████▓    ·
      ▒█████       ███████       █████▒     ✧
      ▓████       █████████       ████▓
  ✦   ▓████       █████████       ████▓   ·
      ▒█████       ███████       █████▒
  ·    ▓█████        ███        █████▓    ✦
        ▓██████                 ██████▓
   ✧      ▓███████           ███████▓      ·
      ·     ▒▓███████████████████▓▒     ✦
         ✧    ░▒▓███████████▓▒░    ·
    ·       ✦    ░░▒▒▓▓▓▓▒▒░░    ✧      ·
        ✧  ·        ✦    ·         ✦

Watch particles spiral into the void with realistic orbital mechanics!

Installation • Quick Start • CLI Usage • API • Examples

✨ Features

| Feature | Description | |---------|-------------| | 🌀 Realistic Physics | Particles orbit and spiral into the black hole with simulated gravitational effects | | 🎨 Multiple Color Schemes | Choose from 5 stunning color palettes | | 💫 Accretion Disk | Beautiful rotating disk of matter around the event horizon | | ⚡ Relativistic Jets | Animated jets shooting from the black hole's poles | | ✨ Twinkling Stars | Dynamic background starfield | | 🌊 Gravitational Lensing | Visual distortion effects near the event horizon | | 🔧 Highly Configurable | Customize every aspect of the animation | | 📦 Dual Usage | Use as a CLI tool or import as a library | | 🚀 Zero Dependencies | Pure Node.js, no external packages required |

📦 Installation

Global Installation (CLI)

npm install -g terminal-blackhole

Local Installation (Library)

npm install terminal-blackhole

Using npx (No Installation)

npx terminal-blackhole

🚀 Quick Start

CLI

# Simply run
blackhole

# Or with npx
npx terminal-blackhole

Programmatic

const { showBlackHole } = require('terminal-blackhole');

// Start the animation
showBlackHole();

💻 CLI Usage

Basic Command

blackhole [options]

Options

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --preset <name> | -p | Use a preset configuration | default | | --color <scheme> | -c | Set color scheme | classic | | --particles <n> | | Number of orbiting particles | 100 | | --stars <n> | | Number of background stars | 50 | | --fps <n> | | Frames per second | 30 | | --radius <n> | -r | Event horizon radius | 4 | | --no-disk | | Hide the accretion disk | false | | --no-stars | | Hide background stars | false | | --help | -h | Show help message | | | --version | -v | Show version number | |

Examples

# Default animation
blackhole

# Fire-themed with more particles
blackhole --color fire --particles 200

# Minimal matrix-style
blackhole --preset minimal --color matrix

# Large black hole, high FPS
blackhole --radius 8 --fps 60 --preset large

# No accretion disk, blue theme
blackhole --no-disk --color blue

# Small and lightweight
blackhole --preset small

🎨 Color Schemes

🟠 Classic

blackhole --color classic

Orange/yellow accretion disk with blue outer glow

🔵 Blue

blackhole --color blue

Cool blue tones throughout

🔴 Fire

blackhole --color fire

Hot red, orange, and yellow gradient

🟣 Purple

blackhole --color purple

Cosmic purple and violet theme

🟢 Matrix

blackhole --color matrix

Classic green monochrome terminal style

📦 Presets

| Preset | Description | Best For | |--------|-------------|----------| | default | Balanced configuration | General use | | small | Smaller size, fewer particles | Low-powered terminals | | large | Bigger black hole, more particles | Large terminal windows | | minimal | No disk/stars, clean look | Minimalist aesthetic | | intense | Max particles, 60 FPS, fire colors | High-performance terminals |

# Using presets
blackhole --preset small
blackhole --preset large
blackhole --preset minimal
blackhole --preset intense

📚 API Reference

Importing

const { 
  BlackHole,        // Main class
  createBlackHole,  // Factory function
  showBlackHole,    // Quick start function
  presets           // Preset configurations
} = require('terminal-blackhole');

showBlackHole(options?)

Immediately starts the animation and returns the BlackHole instance.

const blackhole = showBlackHole({
  colorScheme: 'fire',
  particleCount: 150
});

// Stop after 30 seconds
setTimeout(() => blackhole.stop(), 30000);

createBlackHole(options?)

Creates a BlackHole instance without starting it.

const blackhole = createBlackHole({
  width: 100,
  height: 40,
  fps: 60
});

// Start when ready
blackhole.start();

Options Object

{
  // Dimensions (auto-detected if not specified)
  width: number,              // Terminal width
  height: number,             // Terminal height
  
  // Black hole properties
  eventHorizonRadius: number, // Size of the black hole (default: 4)
  
  // Particles
  particleCount: number,      // Orbiting particles (default: 100)
  starCount: number,          // Background stars (default: 50)
  
  // Animation
  fps: number,                // Frames per second (default: 30)
  
  // Visual options
  showAccretionDisk: boolean, // Show/hide disk (default: true)
  showStars: boolean,         // Show/hide stars (default: true)
  
  // Theme
  colorScheme: string         // 'classic'|'blue'|'fire'|'purple'|'matrix'
}

BlackHole Instance Methods

| Method | Description | |--------|-------------| | start() | Begin the animation loop | | stop() | Stop the animation and cleanup | | renderOnce() | Render a single frame, returns string |

Using Presets

const { showBlackHole, presets } = require('terminal-blackhole');

// Use a preset directly
showBlackHole(presets.intense);

// Combine preset with custom options
showBlackHole({
  ...presets.large,
  colorScheme: 'purple'
});

📝 Examples

Basic Animation

const { showBlackHole } = require('terminal-blackhole');

showBlackHole();

Custom Configuration

const { showBlackHole } = require('terminal-blackhole');

const blackhole = showBlackHole({
  eventHorizonRadius: 6,
  particleCount: 200,
  starCount: 100,
  fps: 60,
  colorScheme: 'fire',
  showAccretionDisk: true,
  showStars: true
});

// Handle graceful shutdown
process.on('SIGINT', () => {
  blackhole.stop();
  console.log('\nBlack hole collapsed!');
  process.exit(0);
});

Timed Display

const { showBlackHole } = require('terminal-blackhole');

async function displayBlackHole(duration = 10000) {
  const blackhole = showBlackHole({ colorScheme: 'blue' });
  
  return new Promise(resolve => {
    setTimeout(() => {
      blackhole.stop();
      resolve();
    }, duration);
  });
}

// Show for 10 seconds
displayBlackHole(10000).then(() => {
  console.log('Animation complete!');
});

Cycling Through Color Schemes

const { createBlackHole } = require('terminal-blackhole');

const colors = ['classic', 'blue', 'fire', 'purple', 'matrix'];
let colorIndex = 0;
let blackhole = null;

function cycleColors() {
  if (blackhole) blackhole.stop();
  
  blackhole = createBlackHole({
    colorScheme: colors[colorIndex],
    particleCount: 100
  });
  
  blackhole.start();
  colorIndex = (colorIndex + 1) % colors.length;
}

// Change color every 5 seconds
cycleColors();
setInterval(cycleColors, 5000);

Single Frame Render

const { createBlackHole } = require('terminal-blackhole');

const blackhole = createBlackHole({
  width: 60,
  height: 20
});

// Get a single frame as a string
const frame = blackhole.renderOnce();
console.log(frame);

Integration with Other Tools

const { createBlackHole } = require('terminal-blackhole');
const blessed = require('blessed');

// Create a blessed screen
const screen = blessed.screen({ smartCSR: true });

const box = blessed.box({
  top: 'center',
  left: 'center',
  width: '80%',
  height: '80%',
  border: { type: 'line' },
  label: ' Black Hole '
});

screen.append(box);

const blackhole = createBlackHole({
  width: box.width - 2,
  height: box.height - 2
});

setInterval(() => {
  box.setContent(blackhole.renderOnce());
  screen.render();
}, 33);

screen.key(['escape', 'q', 'C-c'], () => process.exit(0));

🖥️ Terminal Compatibility

| Terminal | Status | Notes | |----------|--------|-------| | iTerm2 | ✅ Full Support | Best experience with true color | | macOS Terminal | ✅ Supported | Good performance | | Windows Terminal | ✅ Supported | Enable virtual terminal | | VS Code Terminal | ✅ Supported | Works great | | Hyper | ✅ Supported | Full color support | | GNOME Terminal | ✅ Supported | Linux default | | Konsole | ✅ Supported | KDE terminal | | CMD.exe | ⚠️ Limited | Basic support only | | PowerShell | ✅ Supported | Windows PowerShell 5.1+ |

Requirements

• Node.js: >= 14.0.0
• Terminal: True color support recommended (256 colors minimum)
• Size: Minimum 60x20 characters recommended

🔧 Troubleshooting

Animation is flickering

Try reducing the FPS:

blackhole --fps 20

Colors look wrong

Your terminal might not support true colors. Try:

export COLORTERM=truecolor
blackhole

Animation is too slow

Reduce particle count:

blackhole --particles 50 --stars 20

Terminal size issues

Specify dimensions manually:

createBlackHole({
  width: 80,
  height: 24
});

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

📄 License

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

🙏 Acknowledgments

• Inspired by the beauty of cosmic phenomena
• Thanks to all contributors and stargazers
• Special thanks to the Node.js community

Made with ❤️ and JavaScript

⭐ Star this repo if you find it useful! ⭐

Report Bug • Request Feature