Full Code of rmaake1/terminal-rain-lightning for AI

Repository: rmaake1/terminal-rain-lightning
Branch: master
Commit: 8b2ed390fef9
Files: 5
Total size: 21.6 KB

Directory structure:
gitextract_les5p2h8/

├── .gitignore
├── LICENSE
├── README.md
├── pyproject.toml
└── terminal_rain_lightning.py

================================================
FILE CONTENTS
================================================

================================================
FILE: .gitignore
================================================
# Python
__pycache__/
*.py[cod]
*$py.class

# Virtual environment
venv/
*.venv/
env/
ENV/
.env

# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
pip-wheel-metadata/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST

# IDE / Editor specific
.vscode/
.idea/
*.swp
*.swo

# MyPy cache
.mypy_cache/

# Pytest cache
.pytest_cache/


================================================
FILE: LICENSE
================================================
MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


================================================
FILE: README.md
================================================
# Terminal Rain

A Python script that creates a mesmerizing rain and lightning animation directly in your terminal using the `curses` library.

## Calm Rain
![Calm Rain](calmrain.gif)

## Thunderstorm
![Thunderstorm](thunderstorm.gif)

## Disclaimer

I'm a hobby coder and write most of my scripts with Cursor's help, apologies if anything is broken or especially wonky in the source code.

I'm relatively new to Linux and wanted to make something like this for fun after seeing some of the other projects like bash-pipes, asciiquarium, etc.

## Features

*   Smooth ASCII rain effect with varying drop characters.
*   Toggleable "Thunderstorm" mode for more intense rain and lightning.
*   Customizable rain and lightning colors via command-line arguments.
*   Responsive to terminal resizing (clears and redraws).
*   Lightweight and runs in most modern terminals.

## Requirements

*   Python 3.6+
*   A terminal that supports `curses` and color attributes (most modern terminals)

## Installation

The recommended way to install `terminal-rain-lightning` is using `pipx`. This will make the `terminal-rain` command available globally while keeping its dependencies isolated.

### Using `pipx` (Recommended)

`pipx` installs Python command-line applications into isolated environments and makes them globally available without polluting your global Python installation or requiring manual virtual environment activation to run.

1. **Install `pipx`** (if you haven't already):

The best way to install `pipx` on Linux is through your distribution's package manager, if available. This ensures proper system integration and updates.

Common distro installs pulled from the [pipx repo](https://github.com/pypa/pipx):

- Ubuntu 23.04 or above

```
sudo apt update
sudo apt install pipx
pipx ensurepath
sudo pipx ensurepath --global # optional to allow pipx actions with --global argument
```

- Fedora:

```
sudo dnf install pipx
pipx ensurepath
sudo pipx ensurepath --global # optional to allow pipx actions with --global argument
```

- Arch:

```
sudo pacman -S python-pipx
pipx ensurepath
sudo pipx ensurepath --global # optional to allow pipx actions with --global argument
```

- Using `pip` on other distributions:

```
python3 -m pip install --user pipx
python3 -m pipx ensurepath
sudo pipx ensurepath --global # optional to allow pipx actions with --global argument
```

2. **Install `terminal-rain-lightning`:**

- From GitHub (directly):

```bash
pipx install git+https://github.com/rmaake1/terminal-rain-lightning.git
```

- From a local clone:

```bash
git clone https://github.com/rmaake1/terminal-rain-lightning.git
cd terminal-rain-lightning
pipx install .
```

## Usage

Once installed:

*   If you used `pipx` simply type:

```bash
terminal-rain
```

### Controls

*   `t` or `T`: Toggle thunderstorm mode on/off.
*   `q` or `Q` or `Esc`: Quit the animation.
*   `Ctrl+C`: Also quits the animation.
*   The animation will adapt if you resize your terminal window.

### Command-line Options

Customize the appearance of the animation:

```bash
terminal-rain [OPTIONS]
```

## Options:
* --rain-color COLOR: Set the color for the rain. Default: cyan.
* --lightning-color COLOR: Set the color for the lightning. Default: yellow.
* --help: Show this help message and exit.
* Available COLOR choices: black, red, green, yellow, blue, magenta, cyan, white.

Example:

```bash
terminal-rain --rain-color blue --lightning-color white
```

## Troubleshooting

"curses.error: ..." / Garbled Output / Colors Not Working:

* Ensure your terminal emulator fully supports curses, 256 colors, and attributes like bold/dim. Modern terminals like Alacritty or Kitty generally work well.
* Check your TERM environment variable (e.g., echo $TERM). Values like xterm-256color are good.
* The script attempts to use default terminal colors if color changing isn't supported, but full support provides the best experience.

## License

Distributed under the MIT License. See LICENSE file for more information. Do whatever you want with this script.

## Acknowledgements

Inspired by classic terminal screensavers and effects, asciiquarium, bash-pipes, etc.

Built with Python and the curses library.


================================================
FILE: pyproject.toml
================================================
[build-system]
requires = ["setuptools>=42", "wheel"]
build-backend = "setuptools.build_meta"
# backend-path = "." # Optional, default is "." - indicates setup.cfg/setup.py is in the same dir if needed

[project]
name = "terminal-rain-lightning"
version = "0.1.0" # Start with an initial version
authors = [
    { name = "ryan", email = "hello@rmaake.com" }, # UPDATE THIS
]
description = "A terminal rain and lightning animation using Python and curses."
readme = "README.md" # We'll create this next
license = { file = "LICENSE" }
requires-python = ">=3.6"
classifiers = [
    "Development Status :: 4 - Beta",
    "Environment :: Console :: Curses",
    "Intended Audience :: End Users/Desktop",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.6",
    "Programming Language :: Python :: 3.7",
    "Programming Language :: Python :: 3.8",
    "Programming Language :: Python :: 3.9",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Topic :: Artistic Software",
    "Topic :: Games/Entertainment :: Simulation",
    "Topic :: Terminals",
    "Operating System :: POSIX",
    "Operating System :: MacOS",
]

[project.urls]
"Homepage" = "https://github.com/rmaake1/terminal-rain-lightning" # UPDATE THIS
"Bug Tracker" = "https://github.com/rmaake1/terminal-rain-lightning/issues" # UPDATE THIS

# This section makes your script runnable from the command line after installation
[project.scripts]
terminal-rain = "terminal_rain_lightning:main"


================================================
FILE: terminal_rain_lightning.py
================================================
#!/usr/bin/env python3

import curses
import time
import random
import os
import argparse # Added for command-line arguments

UPDATE_INTERVAL = 0.015 # Speed up slightly again w/o clouds/complex bolts

# --- Rain Configuration ---
RAIN_CHARS = ['|', '.', '`'] # Characters for raindrops
COLOR_PAIR_RAIN_NORMAL = 1
COLOR_PAIR_LIGHTNING = 4

# Defined curses color names (lowercase) for argument parsing
CURSES_COLOR_MAP = {
    'black': curses.COLOR_BLACK,
    'red': curses.COLOR_RED,
    'green': curses.COLOR_GREEN,
    'yellow': curses.COLOR_YELLOW,
    'blue': curses.COLOR_BLUE,
    'magenta': curses.COLOR_MAGENTA,
    'cyan': curses.COLOR_CYAN,
    'white': curses.COLOR_WHITE,
}


class Raindrop:
    def __init__(self, x, y, speed, char):
        self.x = x
        self.y = y
        self.speed = speed # How many steps to fall per update
        self.char = char
        # self.state = "falling" # Removed state
        # self.splash_timer = 0 # Removed timer

# --- Cloud Configuration --- # Removed
# ...

# --- Lightning ---
LIGHTNING_COLOR_ATTR = None # Will be set in setup_colors
LIGHTNING_CHANCE = 0.005 # Slightly higher chance
LIGHTNING_CHARS = ['*', '+', '#'] # Different intensity characters [dimmest -> brightest]
LIGHTNING_GROWTH_DELAY = 0.002 # Grow slightly faster
LIGHTNING_MAX_BRANCHES = 2
LIGHTNING_BRANCH_CHANCE = 0.3
# LIGHTNING_FADE_DURATION = 30 # Removed - Bolt removed when all segments expired
# LIGHTNING_TAIL_FADE_LENGTH = 15 # Removed - Fade based on segment lifespan
FORK_CHANCE = 0.15 # Chance for a side fork to spawn during growth
FORK_HORIZONTAL_SPREAD = 3 # Max horizontal distance a fork segment can jump
SEGMENT_LIFESPAN = 0.8 # Seconds for a segment to fade from # to invisible


# class Cloud: # Removed
#     ...


class LightningBolt:
    def __init__(self, start_row, start_col, max_y, max_x):
        self.start_col = start_col
        self.target_length = random.randint(max_y // 2, max_y - 2) # Random length
        # Segments store: (y, x, creation_time)
        self.segments = [(start_row, start_col, time.time())]
        self.last_growth_time = time.time() # Renamed from last_segment_time
        self.is_growing = True
        # self.fade_timer = LIGHTNING_FADE_DURATION # Removed
        self.max_y = max_y # Store for boundary checks
        self.max_x = max_x # Store for boundary checks
        # self.age_offset = 0 # Removed

    def update(self):
        """Updates bolt growth and checks if it should be removed."""
        current_time = time.time()

        # --- Growth ---
        if self.is_growing and (current_time - self.last_growth_time >= LIGHTNING_GROWTH_DELAY):
            self.last_growth_time = current_time
            new_segments_this_step = [] # Store segments added *this* step
            added_segment = False
            last_y, last_x, _ = self.segments[-1] # Ignore creation_time for position

            if len(self.segments) < self.target_length and last_y < self.max_y - 1 :
                 branches = 1
                 if random.random() < LIGHTNING_BRANCH_CHANCE:
                     branches = random.randint(1, LIGHTNING_MAX_BRANCHES + 1)

                 current_x = last_x
                 next_primary_x = current_x # Track primary path for fork check
                 for i in range(branches):
                     offset = random.randint(-2, 2)
                     next_x = max(0, min(self.max_x - 1, current_x + offset))
                     # Allow reaching bottom row (max_y - 1)
                     # next_y = last_y + 1
                     next_y = min(self.max_y - 1, last_y + 1)
                     # if next_y < self.max_y: # Check was redundant with min()
                     # Add new segment with current time
                     new_segments_this_step.append((next_y, next_x, current_time))
                     if i == 0: next_primary_x = next_x # Store first path pos
                     current_x = next_x
                     added_segment = True

                 # --- Add Secondary Forks --- #
                 if random.random() < FORK_CHANCE:
                     fork_offset = random.randint(-FORK_HORIZONTAL_SPREAD, FORK_HORIZONTAL_SPREAD)
                     if fork_offset == 0: fork_offset = random.choice([-1, 1])
                     fork_x = max(0, min(self.max_x - 1, last_x + fork_offset))
                     # Allow fork reaching bottom row
                     # fork_y = last_y + 1
                     fork_y = min(self.max_y - 1, last_y + 1)
                     # if fork_y < self.max_y and fork_x != next_primary_x:
                     if fork_x != next_primary_x:
                          # Add new fork segment with current time
                          new_segments_this_step.append((fork_y, fork_x, current_time))
                          added_segment = True

            # Stop growing if no new segments were added or target length reached
            # Also stop if we hit the bottom edge
            if not added_segment or len(self.segments) >= self.target_length or last_y >= self.max_y -1:
                self.is_growing = False

            # Add the newly created segments to the main list
            if new_segments_this_step:
                 # Optional: Add only unique positions added this step?
                 unique_new = list({(s[0], s[1]): s for s in new_segments_this_step}.values())
                 self.segments.extend(unique_new)


        # --- Check for Removal ---
        # Bolt should be removed if all its segments have exceeded their lifespan
        all_expired = True
        if not self.segments: # Should not happen, but safe check
            return False # Remove empty bolt

        for _, _, creation_time in self.segments:
            if (current_time - creation_time) <= SEGMENT_LIFESPAN:
                all_expired = False
                break
        # Return False if all segments are expired (signal removal)
        return not all_expired


    def draw(self, stdscr):
        """Draws segments based on their individual age."""
        current_time = time.time()
        max_char_index = len(LIGHTNING_CHARS) - 1

        for y, x, creation_time in self.segments:
            segment_age = current_time - creation_time
            is_visible = True
            char = ' ' # Default to invisible

            if segment_age <= SEGMENT_LIFESPAN:
                # Determine character based on age progress through lifespan
                # Normalize age (0.0 = new, 1.0 = lifespan reached)
                norm_age = segment_age / SEGMENT_LIFESPAN

                # Map normalized age (0->1) to char index (max->0)
                # Example mapping: 0-0.33 -> #, 0.33-0.66 -> +, 0.66-1.0 -> *
                if norm_age < 0.33:
                    char_index = 2 # '#'
                elif norm_age < 0.66:
                    char_index = 1 # '+'
                else:
                    char_index = 0 # '*'

                # Ensure index is valid (should be by logic)
                char_index = max(0, min(max_char_index, char_index))
                char = LIGHTNING_CHARS[char_index]
                is_visible = True
            else:
                is_visible = False # Segment is older than lifespan

            if not is_visible:
                continue

            # Apply attributes (always bold for now)
            attr = LIGHTNING_COLOR_ATTR

            try:
                max_r, max_c = stdscr.getmaxyx()
                if y < max_r and x < max_c:
                   stdscr.addstr(int(y), int(x), char, attr)
            except curses.error:
                pass


def setup_colors(rain_color_str='cyan', lightning_color_str='yellow'):
    """Initializes color pairs for the rain and lightning based on input strings."""
    global LIGHTNING_COLOR_ATTR
    if curses.has_colors():
        curses.start_color()
        if curses.can_change_color():
             curses.use_default_colors()
             bg = -1
        else:
             bg = curses.COLOR_BLACK # Fallback background

        # --- Get curses color constants from strings --- #
        rain_fg = CURSES_COLOR_MAP.get(rain_color_str.lower(), curses.COLOR_CYAN)
        lightning_fg = CURSES_COLOR_MAP.get(lightning_color_str.lower(), curses.COLOR_YELLOW)
        # ------------------------------------------------ #

        curses.init_pair(COLOR_PAIR_RAIN_NORMAL, rain_fg, bg)
        # curses.init_pair(COLOR_PAIR_RAIN_SPLASH, curses.COLOR_BLUE, bg) # Removed
        # curses.init_pair(COLOR_PAIR_CLOUD, curses.COLOR_WHITE, bg) # Removed
        curses.init_pair(COLOR_PAIR_LIGHTNING, lightning_fg, bg)
        LIGHTNING_COLOR_ATTR = curses.color_pair(COLOR_PAIR_LIGHTNING) | curses.A_BOLD

        return True
    else:
        # --- Non-color fallback --- #
        # We still need LIGHTNING_COLOR_ATTR for non-color bold
        rain_fg = curses.COLOR_WHITE # Ignored, but keep variable
        lightning_fg = curses.COLOR_WHITE # Ignored, but keep variable
        bg = curses.COLOR_BLACK
        # -------------------------- #

        curses.init_pair(COLOR_PAIR_RAIN_NORMAL, curses.COLOR_WHITE, curses.COLOR_BLACK)
        # curses.init_pair(COLOR_PAIR_RAIN_SPLASH, curses.COLOR_WHITE, curses.COLOR_BLACK) # Removed
        # curses.init_pair(COLOR_PAIR_CLOUD, curses.COLOR_WHITE, curses.COLOR_BLACK) # Removed
        curses.init_pair(COLOR_PAIR_LIGHTNING, curses.COLOR_WHITE, curses.COLOR_BLACK)
        LIGHTNING_COLOR_ATTR = curses.color_pair(COLOR_PAIR_LIGHTNING) | curses.A_BOLD
        return False

def simulate_rain(stdscr, rain_color_str='cyan', lightning_color_str='yellow'):
    """Main curses visualization loop for rain simulation."""
    curses.curs_set(0) # Hide cursor
    stdscr.nodelay(True) # Non-blocking input
    stdscr.timeout(1) # ms, minimal timeout

    has_colors = setup_colors(rain_color_str, lightning_color_str)
    raindrops = []
    active_bolts = [] # List of active LightningBolt objects
    rows, cols = stdscr.getmaxyx()
    is_thunderstorm = False

    last_update_time = time.time()

    while True:
        # --- Input --- #
        key = stdscr.getch()
        if key == curses.KEY_RESIZE:
             rows, cols = stdscr.getmaxyx()
             stdscr.clear()
             raindrops.clear()
             active_bolts.clear()
        elif key == ord('q') or key == ord('Q') or key == 27:
            break
        elif key == ord('t') or key == ord('T'):
            is_thunderstorm = not is_thunderstorm
            stdscr.clear()

        # --- Frame Rate Control --- #
        current_time = time.time()
        delta_time = current_time - last_update_time
        if delta_time < UPDATE_INTERVAL:
             # Reduce sleep time if many bolts exist? Maybe not necessary yet.
             time.sleep(UPDATE_INTERVAL - delta_time)
        last_update_time = time.time() # Use the time *after* sleep for age calcs

        # --- Update --- #

        # 1. Lightning Bolts
        next_bolts = []
        if is_thunderstorm and len(active_bolts) < 3 and random.random() < LIGHTNING_CHANCE:
             start_col = random.randint(cols // 4, 3 * cols // 4)
             start_row = random.randint(0, rows // 5)
             active_bolts.append(LightningBolt(start_row, start_col, rows, cols))

        for bolt in active_bolts:
             if bolt.update(): # update now returns True if bolt should *keep* existing
                 next_bolts.append(bolt)
        active_bolts = next_bolts

        # 2. Raindrops (generation and update)
        generation_chance = 0.5 if is_thunderstorm else 0.3
        max_new_drops = cols // 8 if is_thunderstorm else cols // 15
        min_speed = 0.3 if is_thunderstorm else 0.3
        max_speed = 1.0 if is_thunderstorm else 0.6

        if random.random() < generation_chance:
            num_new_drops = random.randint(1, max(1, max_new_drops))
            for _ in range(num_new_drops):
                 x = random.randint(0, cols - 1)
                 y = 0 # Start at top row
                 speed = random.uniform(min_speed, max_speed)
                 char = random.choice(RAIN_CHARS)
                 raindrops.append(Raindrop(x, y, speed, char))

        next_raindrops = []
        for drop in raindrops:
            drop.y += drop.speed
            # Let drop fall off the bottom edge
            # if drop.y < rows - 1:
            if int(drop.y) < rows:
                next_raindrops.append(drop)
        raindrops = next_raindrops

        # --- Drawing --- #
        stdscr.clear()

        # 1. Lightning
        for bolt in active_bolts:
             bolt.draw(stdscr)

        # 2. Raindrops
        for drop in raindrops:
             try:
                 attr = curses.color_pair(COLOR_PAIR_RAIN_NORMAL)
                 if is_thunderstorm:
                     attr |= curses.A_BOLD
                 elif drop.speed < 0.8:
                     attr |= curses.A_DIM
                 # Prevent drawing on bottom line
                 # if int(drop.y) < rows -1:
                 # Allow drawing on bottom line now
                 if int(drop.y) < rows:
                    stdscr.addstr(int(drop.y), drop.x, drop.char, attr)
             except curses.error:
                 pass
                
        stdscr.noutrefresh()
        curses.doupdate()


def main():
    if not os.isatty(1) or os.environ.get('TERM') == 'dumb':
        print("Error: This script requires a TTY with curses support.")
        return

    # --- Argument Parsing --- #
    parser = argparse.ArgumentParser(description="Simulates rain and thunderstorms in the terminal.")
    valid_colors = list(CURSES_COLOR_MAP.keys())
    parser.add_argument(
        '--rain-color',
        type=str,
        default='cyan',
        choices=valid_colors,
        help=f"Color for the rain. Default: cyan. Choices: {', '.join(valid_colors)}"
    )
    parser.add_argument(
        '--lightning-color',
        type=str,
        default='yellow',
        choices=valid_colors,
        help=f"Color for the lightning. Default: yellow. Choices: {', '.join(valid_colors)}"
    )
    args = parser.parse_args()
    # ------------------------ #

    try:
        # Pass parsed colors to the main simulation function
        curses.wrapper(simulate_rain, args.rain_color, args.lightning_color)
    except curses.error as e:
        try: curses.endwin()
        except Exception: pass
        print(f"\nA curses error occurred: {e}")
        print("Terminal might not fully support curses features (like color/attributes).")
        print("Try resizing the terminal or using a different terminal emulator.")
    except KeyboardInterrupt:
        print("\nExiting...")
    except Exception as e:
        try: curses.endwin()
        except Exception: pass
        print(f"\nAn unexpected error occurred: {e}")
        import traceback
        traceback.print_exc()

if __name__ == "__main__":
    main()