Introducing asciiquarium: A Terminal Aquarium Screensaver for npm
I published asciiquarium on npm — a faithful reproduction of Kirk Baucom's classic Asciiquarium screensaver, rewritten in Node.js so anyone can run it without dealing with Perl and CPAN dependencies.
What Is It?
It's exactly what it sounds like — an animated ASCII art aquarium that runs in your terminal. Fish swim across the screen, sharks eat fish (with blood splat effects), whales shoot water spouts, sea monsters lurk in the depths, and seaweed sways at the bottom. It's delightful.
Quick Start
npx asciiquarium
That's it. One command and you've got an aquarium in your terminal.
What's Inside
The simulation features 11 different entity types:
- 18 fish variants — each with left and right facing, random colors with white eyes, bubble generation
- Sharks — hunt and eat smaller fish with collision detection
- Whales — animated 7-frame water spouts on the surface
- Sea Monsters — multi-frame animation, fast movers
- Big Fish — two massive variants cruising through
- Ships — sailing across the water surface
- Bubbles — rising from fish, popping at the surface
- Castle — decorative background at the bottom
- Seaweed — procedurally generated with wave animation
- 4-layer parallax water surface
How It Works
Under the hood, the animation engine runs at 10 FPS to match the original Perl timing. It uses z-depth sorting (0-22 range) for proper entity layering, AABB collision detection for shark-fish interactions, and a color masking system for visual variety.
The Node.js version uses the blessed library for terminal rendering and supports terminal resize handling, pause/resume, and screen redraw.
Controls
| Key | Action |
|---|---|
q / Ctrl+C / ESC | Quit |
r | Redraw screen |
p | Pause/unpause |
-c flag | Classic mode (original ASCII art) |
The Rewrite Journey
The original asciiquarium is a Perl script that requires Term::Animation from CPAN. Getting Perl dependencies set up is a pain on modern systems, so I decided to port the whole thing to Node.js.
The current published version (v1.1.3) defaults to the Perl implementation for stability, but v2.0 with the full Node.js rewrite is in beta. The goal is to eventually remove the Perl dependency entirely and have a pure JavaScript implementation.
Check It Out
Find it on npm or contribute on GitHub. And if you just want to watch some fish swim, run npx asciiquarium and enjoy.