GitHub - flawnn/asciitopia: A library of animated, beautiful ASCII patterns for everybody

2 min read Original article ↗

A library of animated, beautiful ASCII patterns for everybody.

asciitopia hero animation

Why?

Because. I fucking love ASCII art.

Patterns

Seven patterns and growing:

Name Description Demo
Fire pattern Fire Rising flames with fuel modes, embers, sparks, and multiple palettes. live
Rain pattern Rain Falling drops with fading trails, impact flashes, and splash particles. live
Snow pattern Snow Drifting flakes on two depth layers with sway and wind. live
Waves pattern Waves Layered sine-and-noise ocean swell in ocean or mono colors. live
Aurora pattern Aurora Northern lights from drifting fractal noise. live
Bonsai pattern Bonsai Windswept trees growing limb by limb, with turning seasons. live
Weather pattern Weather A cabin under living weather — feed it a location and it mirrors your sky. live

Weather imports from the @asciitopia/core/weather subpath; everything else from the root.

Quickstart

Vanilla JS with @asciitopia/core:

import { CanvasEngine, FirePattern } from '@asciitopia/core';

const canvas = document.querySelector('canvas')!;
canvas.width = 800;
canvas.height = 400;

const engine = new CanvasEngine(canvas);
engine.setPattern(new FirePattern());
engine.start();

React with @asciitopia/react:

import { AsciiBackground } from '@asciitopia/react';

// Give the canvas real dimensions via CSS; the engine sizes off the
// observed box (position: fixed; inset: 0; width/height: 100%; z-index: -1).
export const App = () => (
  <AsciiBackground className="ascii-bg" pattern="fire" />
);

Configuration

Every pattern takes a partial config over its own defaults. Fire, for example:

import { FirePattern } from '@asciitopia/core';

const fire = new FirePattern({
  mode: 'campfire', // 'wall' | 'campfire' | 'torch' | 'candles'
  palette: 'lava',  // 'classic' | 'blue' | 'lava' | 'matrix' | 'mono'
  intensity: 8,     // 1–10, fuel heat
  wind: 2,          // -5–+5, horizontal drift bias
});

Each pattern exports its own XxxConfig type and DEFAULT_XXX_CONFIG from @asciitopia/core.

Write your own

Every pattern implements the same interface:

export interface AsciiPattern {
  init(cols: number, rows: number): void;
  update(dt: number): void;
  render(
    ctx: CanvasRenderingContext2D,
    cols: number,
    rows: number,
    charW: number,
    charH: number,
  ): void;
  dispose?(): void;
}

See CONTRIBUTING.md for the contribution flow.

License

MIT, see LICENSE.