Documentation

README

ASCII Pipes Screensaver

An animated terminal screensaver that draws colourful pipes growing across the screen using Unicode box-drawing characters. Built for terminal enthusiasts and developers who want a fun screensaver.

Quick Start

bash

node src/pipes.js

Press q or Ctrl+C to exit. That's it.

Installation

Prerequisites

Node.js 21.2+ (uses ES modules with import.meta)

Install

No installation needed. Clone the repository and run directly:

bash

git clone <repo-url>
cd ascii-pipes
node src/pipes.js

Verify

bash

node src/pipes.js --help

Usage

shell

node src/pipes.js [options]

Options

Flag	Description	Default	Valid Values
`--speed <ms>`	Animation speed in milliseconds per step	`80`	Positive integer
`--pipes <n>`	Number of simultaneous pipes	`3`	Integer 1-6
`--colors <mode>`	Color palette	`classic`	`classic`, `bright`
`--help`	Show help message and exit	—	—

Examples

Example 1: Default Settings

Run with 3 pipes, classic colors, 80ms speed:

bash

$ node src/pipes.js

Pipes appear as connected box-drawing characters (│, ─, ┌, ┐, └, ┘, ┼) in 6 bright ANSI colors. They grow across the screen, turn corners randomly, and when the screen fills to ~65%, the oldest completed pipes are removed to make room.

Example 2: Fast Single Pipe

Run a single fast pipe with bright colors:

bash

$ node src/pipes.js --speed 30 --pipes 1 --colors bright

A single pipe grows rapidly across the screen using all 8 bright ANSI colors (including white and grey).

Example 3: Maximum Pipes, Slow Speed

Run 6 pipes at a leisurely pace:

bash

$ node src/pipes.js --pipes 6 --speed 200

Six pipes grow simultaneously, spawning with staggered timing. The slower speed makes it easier to follow each pipe's path.

Example 4: Help Text

bash

$ node src/pipes.js --help
ASCII Pipes Screensaver

Usage: node pipes.js [options]

Options:
  --speed <ms>      Animation speed in milliseconds per step (default: 80)
  --pipes <n>       Number of simultaneous pipes, 1-6 (default: 3)
  --colors <mode>   Color palette: classic, bright (default: classic)
  --help            Show this help message and exit

How It Works

Pipe Spawning: Pipes spawn at random positions with random directions and colors. They start one at a time, staggered 8 ticks apart, until the target count is reached.

Growth: Each animation tick, every active pipe moves one cell in its current direction. There's a 20% chance of turning (10% left, 10% right) at each step.

Characters: Straight segments use │ (vertical) and ─ (horizontal). Turns use corner characters (┌, ┐, └, ┘). When a pipe crosses another pipe (or itself), the intersection character ┼ is drawn.

Lifecycle: Each pipe has a random maximum length (30-100 segments). A pipe ends when it reaches its max length or hits the terminal edge.

Recycling: When screen coverage exceeds 65%, the oldest completed pipe is removed (one per tick) to free space for new growth.

Terminal Safety: The screensaver uses the alternate screen buffer, so your terminal content is preserved. On exit (via q, Ctrl+C, SIGTERM, or error), the terminal is fully restored.

Color Palettes

Classic (default)

Six bright ANSI colors: red, green, yellow, blue, magenta, cyan.

Bright

Eight colors: grey, red, green, yellow, blue, magenta, cyan, white.

Error Messages

Error	Cause	Resolution
`Error: --speed must be a positive integer`	Invalid `--speed` value (0, negative, float, or non-numeric)	Use a positive integer like `--speed 50`
`Error: --speed requires a value`	`--speed` flag with no following value	Provide a value: `--speed 80`
`Error: --pipes must be an integer between 1 and 6`	Invalid `--pipes` value (out of range or non-integer)	Use 1-6: `--pipes 3`
`Error: --pipes requires a value`	`--pipes` flag with no following value	Provide a value: `--pipes 3`
`Error: --colors must be 'classic' or 'bright'`	Unknown color palette name	Use `classic` or `bright`
`Error: --colors requires a value`	`--colors` flag with no following value	Provide a value: `--colors classic`
`Error: Unknown option '<flag>'. Use --help for usage.`	Unrecognized command-line flag	Check spelling, use `--help`
`Error: Terminal too small (minimum 10x5)`	Terminal window is too small	Resize terminal to at least 10 columns by 5 rows

Architecture

shell

pipes.js          — Terminal I/O wrapper (rendering, input, signals)
pipes-engine.js   — Pure logic module (buffer, pipes, CLI parsing)

All game logic is in pipes-engine.js with no I/O dependencies. Random number generation is injectable for testing. The main file (pipes.js) is a thin wrapper that connects the engine to terminal I/O.