asciiquarium 2.2.0

An aquarium/sea animation in ASCII art for your terminal

🐠 Asciiquarium - Python Edition

🌐 Website • 📦 PyPI • 🚀 Quick Start • 💬 Support

---

An aquarium/sea animation in ASCII art for your terminal! This is a Python reimplementation of the classic Perl asciiquarium, designed to work cross-platform on Windows, Linux, and macOS.

✨ Features

• 🐟 Multiple fish species with different sizes and colors
• 🦈 Sharks that hunt small fish
• 🐋 Whales with animated water spouts
• 🚢 Ships sailing on the surface
• 🐙 Sea monsters lurking in the depths
• 🌊 Animated blue water lines and seaweed
• 🏰 Castle decoration
• � Blue bubbles rising from fish
• 🎨 Full color support
• ⌨️ Interactive controls
• 🌍 Cross-platform (Windows, Linux, macOS)

🚀 Installation

Using pip (Standard)

pip install asciiquarium

Using pipx (Isolated)

pipx installs the package in an isolated environment:

pipx install asciiquarium

🎯 Usage

After installation, simply run:

asciiquarium

That's it! Enjoy your ASCII aquarium! 🐠

🎮 Controls

• Q or q - Quit the aquarium
• P or p - Pause/unpause the animation
• R or r - Redraw and respawn all entities
• I or i - Show/hide info overlay

� Requirements

• Python 3.8+ - Works with Python 3.8 through 3.14+
• Terminal - Any terminal with color support (minimum 40x15, recommended 80x24)
• Dependencies - Automatically handled:
  • windows-curses - Auto-installed on Windows (Python < 3.13)
  • curses - Built-in on Linux/macOS

Python 3.13+ Support

For Python 3.13+ on Windows, you may need to install windows-curses manually:

pip install windows-curses

If you encounter issues, consider using Python 3.12 or earlier for the most stable experience.

🌍 Platform Support

Platform	Status	Notes
🪟 Windows	✅ Fully Supported	Auto-installs windows-curses
🐧 Linux	✅ Fully Supported	Uses built-in curses
🍎 macOS	✅ Fully Supported	Uses built-in curses

📦 What Gets Installed

The package includes:

• Main application and animation engine
• All entity types (fish, sharks, whales, ships, etc.)
• ASCII art designs and color schemes
• Cross-platform terminal handling

Size: ~50KB (minimal footprint!)

🛠️ Development Installation

If you want to contribute or modify the code:

# Clone the repository
git clone https://github.com/MKAbuMattar/asciiquarium-python.git
cd asciiquarium-python

# Install in editable mode with development dependencies
uv pip install -e ".[dev]"

# Run from source
python -m asciiquarium.main

Development Requirements

Before submitting any changes, ensure your code passes all checks:

# Run the formatter
uv run hatch run fmt

# Run linters (must pass without errors)
uv run hatch run lint

All contributions must pass both formatting and linting checks before being merged.

🌟 Features Details

Cross-Platform Support

This implementation uses Python's curses library and automatically installs windows-curses on Windows systems, making it truly cross-platform.

Entity Types

• Fish: 7 different species with unique ASCII art designs and swimming patterns
• Sharks: Predators that hunt and eat smaller fish with collision detection
• Whales: Large creatures with animated water spout effects
• Ships: Sail across the surface of the water
• Sea Monsters: Mysterious creatures lurking in the depths
• Big Fish: Large colorful fish with randomized color schemes
• Environment: Seaweed, castle decorations, and blue water lines
• Bubbles: Rise from fish in blue color

Animation Features

• Smooth Animation: 30 FPS for fluid motion
• Z-depth Layering: Proper entity overlapping
• Color Masking: Detailed multi-color ASCII art
• Frame Animation: Multi-frame animations for complex entities
• Collision Detection: Sharks interact with small fish
• Auto Cleanup: Off-screen entities are automatically removed

📁 Project Structure

asciiquarium-python/
├── asciiquarium/
│   ├── __init__.py
│   ├── main.py              # Entry point
│   ├── entity.py            # Base entity class
│   ├── animation.py         # Animation engine
│   └── entities/
│       ├── __init__.py
│       ├── fish.py          # Fish entities
│       ├── environment.py   # Environment entities
│       └── special.py       # Special entities (sharks, whales, etc.)
├── pyproject.toml
├── uv.lock
└── README.md

🎨 Customization

You can easily add new entities by creating them in the appropriate module:

from asciiquarium.entity import Entity

def add_my_entity(old_ent, anim):
    anim.new_entity(
        entity_type='my_type',
        shape=my_ascii_art,
        color=my_color_mask,
        position=[x, y, z],
        callback_args=[dx, dy, dz, frame_speed],
        die_offscreen=True,
        death_cb=add_my_entity,
    )

🐛 Troubleshooting

Command Not Found

If asciiquarium command is not found after installation:

On Windows:

# Add Python Scripts to PATH
python -m asciiquarium.main

On Linux/macOS:

# Make sure ~/.local/bin is in PATH
export PATH="$HOME/.local/bin:$PATH"
asciiquarium

Windows Issues

The windows-curses package is automatically installed on Windows. If you encounter issues:

pip install --upgrade windows-curses

Terminal Size

Minimum terminal size: 80 columns × 24 rows

Check your terminal size and resize if needed.

Color Support

Most modern terminals support colors. If colors don't appear:

• Ensure your terminal emulator supports ANSI colors
• Try a different terminal (Windows Terminal, iTerm2, GNOME Terminal, etc.)

Python Version

Make sure you're using Python 3.8 or higher:

python --version

💡 Tips

• Full Screen: Press F11 in most terminals for fullscreen mode
• Better Experience: Use a larger terminal window for more entities
• Dark Theme: Works best with dark terminal backgrounds
• Font: Use a monospace font for best ASCII art rendering

📜 License

GPL-3.0-or-later

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

🙏 Credits

Original Asciiquarium

• Author: Kirk Baucom
• Website: http://robobunny.com/projects/asciiquarium
• Language: Perl

Python Port

• Author: Mohammad Abu Mattar
• Email: [e-mail]
• Website: https://mkabumattar.com/
• Repository: https://github.com/MKAbuMattar/asciiquarium-python

All ASCII art designs and animation concepts are credited to the original author, Kirk Baucom. This Python port maintains the spirit and fun of the original while providing modern cross-platform compatibility.

🔗 Links

• 📦 PyPI Package
• 🐙 GitHub Repository
• 🌐 Author Website
• � Original Perl Version

🤝 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

---

Made with ❤️ by Mohammad Abu Mattar
Based on the original Perl ASCIIQuarium by Kirk Baucom