asciiquarium 2.3.1

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
• 🍤 Feed the fish with F and watch them chase the flakes down
• 🎨 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
• F or f - Drop a flake of food (up to 10 at a time)
• 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, run the same three commands CI does. All three are clean on main, so anything they report came from your change:

uvx ruff check asciiquarium tests
uvx mypy --ignore-missing-imports asciiquarium
uvx pytest -q

The tests need no terminal — they cover the geometry, the art invariants and the version arithmetic. They cannot tell you whether the aquarium looks right: for that, run it at 80×24 and at the 40×15 minimum, with and without --classic, and press r. See .github/CONTRIBUTING.md.

🌟 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: 12 designs with unique ASCII art and swimming patterns (8 ported from the Perl original, 4 new — --classic shows only the original 8)
• 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

• Animation: roughly 10 frames per second, paced by the 100 ms input timeout
• 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
│   ├── __version__.py       # Single source of truth for the version
│   ├── main.py              # CLI entry point, argparse, --info
│   ├── entity.py            # Base entity class
│   ├── animation.py         # Animation engine, depth map, draw loop
│   ├── version_checker.py   # PyPI update poll
│   └── entities/
│       ├── __init__.py
│       ├── fish.py          # Fish designs, bubbles, feeding behaviour
│       ├── food.py          # Food flakes
│       ├── environment.py   # Waterlines, castle, seaweed
│       └── special.py       # Sharks, whales, ships, monsters, ducks, ...
├── tests/                   # No terminal required
├── scripts/release_version.py
├── .github/workflows/       # validate.yml, release.yml
├── AGENTS.md                # How to work in this repo
├── ROADMAP.md               # What is queued next
├── CHANGELOG.md
├── 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