ASCIIGround - v1.1.2

ASCIIGround

A TypeScript library for creating animated ASCII canvas backgrounds.

Features

Multiple animation patterns: Perlin noise, rain, static noise with extensible pattern system.
Configuration options for font, animation speed, character sets, noise parameters, and much more.
Responsive and resizable canvas rendering.
Support for both 2D Canvas and WebGL rendering.
Comprehensive API documentation.
Mouse interaction support.
Supports both ESM and UMD/CDN usage.

Installation

NPM

npm install asciiground

CDN

<script src="https://unpkg.com/asciiground@latest/dist/asciiground.umd.js"></script>

Quick start

Basic usage

import { ASCIIGround, PerlinNoisePattern } from 'asciiground';

// Acquire canvas element.
const canvas = document.getElementById('my-canvas') as HTMLCanvasElement;

// Create pattern instance.
const pattern = new PerlinNoisePattern({ 
  characters: [' ', '.', ':', ';', '+', '*', '#'] 
});

// Create and initialize renderer.
// Notice that method chaining can be used for convenience.
const asciiGround = new ASCIIGround()
  .init(canvas, pattern, { fontSize: 12, color: '#667eea' })
  .startAnimation();

Switching patterns

import { ASCIIGround, RainPattern, PerlinNoisePattern } from 'asciiground';

// Acquire canvas element.
const canvas = document.getElementById('canvas') as HTMLCanvasElement;

// Create rain pattern instance.
const rainPattern = new RainPattern({ 
  characters: ['|', '!', '1', ':'],
  rainDensity: 0.8,
  minDropLength: 8,
  maxDropLength: 25,
});

// Create Perlin noise pattern instance.
const perlinNoisePattern = new PerlinNoisePattern({
  octaves: 4,
  frequency: 0.01,
  persistence: 0.5,
  lacunarity: 2.0,
  characters: [' ', '.', ':', ';', '+', '*', '#'],
});

// Initialize ASCIIGround with rain pattern and custom renderer options.
// You don't need to start animation immediately, it can be controlled later.
const asciiGround = new ASCIIGround()
  .init(canvas, rainPattern, { fontSize: 14, color: '#00ff00' });

// Switch to a new Perlin noise pattern.
asciiGround
  .setPattern(perlinNoisePattern)
  .startAnimation();

CDN usage

<!DOCTYPE html>
<html>
<head>
    <title>ASCIIGround demo</title>
</head>
<body>
    <canvas id="ascii-canvas" width="800" height="600"></canvas>
    <script src="https://unpkg.com/asciiground@latest/dist/asciiground.umd.js"></script>
    <script>
        const { ASCIIGround, PerlinNoisePattern } = window.ASCIIGround;

        const canvas = document.getElementById('ascii-canvas');

        const pattern = new PerlinNoisePattern({ 
          octaves: 4,
          frequency: 0.05,
          characters: [' ', '.', ':', ';', '+', '*', '#'],
        });

        const asciiGround = new ASCIIGround()
          .init(canvas, pattern, { fontSize: 14 })
          .startAnimation();
    </script>
</body>
</html>

Available patterns

Perlin noise

Creates smooth, organic-looking patterns like clouds, terrain or flowing effects.

import { PerlinNoisePattern } from 'asciiground';

const pattern = new PerlinNoisePattern({
  seed: 0,
  octaves: 4,
  frequency: 0.05,
  lacunarity: 2.0,
  persistence: 0.5,
  characters: [' ', '.', ':', ';', '+', '*', '#', '@'],
});

Rain

Creates a downward flowing effect reminiscent of digital rain.

import { RainPattern } from 'asciiground';

const pattern = new RainPattern({
  rainDensity: 0.8,
  minSpeed: 0.5,
  maxSpeed: 1.5,
  minDropLength: 8,
  maxDropLength: 25,
  mutationRate: 0.04,
  fadeOpacity: 0.2,
  headColor: '#FFFFFF',
  characters: ['|', '!', '1', ':'],
});

Static noise

Random noise effect for TV static or glitch aesthetics.

import { StaticNoisePattern } from 'asciiground';

const pattern = new StaticNoisePattern({
  seed: 42,
  characters: [' ', '.', '*', '#'],
});

Examples

Matrix-style rain

import { ASCIIGround, RainPattern } from 'asciiground';

const canvas = document.getElementById('canvas') as HTMLCanvasElement;

const pattern = new RainPattern({
  rainDensity: 0.9,
  minSpeed: 1.0,
  maxSpeed: 2.5,
  minDropLength: 3,
  maxDropLength: 15,
  fadeOpacity: 0.1,
  headColor: '#FFFFFF',
  characters: ['0', '1', '|', '!', ':', '.', ' '],
});

const asciiGround = new ASCIIGround()
  .init(canvas, pattern, {
    fontSize: 14,
    color: '#00ff00',
    backgroundColor: '#000000'
  })
  .startAnimation();

Animated perlin noise

import { ASCIIGround, PerlinNoisePattern } from 'asciiground';

const canvas = document.getElementById('canvas') as HTMLCanvasElement;

const pattern = new PerlinNoisePattern({
  octaves: 3,
  frequency: 0.02,
  persistence: 0.4,
  characters: [' ', '░', '▒', '▓', '█'],
});

const asciiGround = new ASCIIGround();

asciiGround
  .init(canvas, pattern, {
    fontSize: 12,
    color: '#667eea',
    animationSpeed: 0.5,
    backgroundColor: '#1a1a2e',
  })
  .startAnimation();

API reference

Complete API documentation is available at https://eoic.github.io/ASCIIGround/api/.

The documentation includes:

Complete class and interface references.
Pattern creation guides.
Configuration options.
Interactive examples.
Source code links.

Core classes

ASCIIGround - main entry point for static and animated backgrounds, suitable for most use cases.
ASCIIRenderer - renderer for full control over the rendering process.
Pattern classes - PerlinNoisePattern, RainPattern, StaticNoisePattern.
Custom patterns - extend the Pattern base class to create your own unique effects.

Development

Setup

git clone https://github.com/Eoic/asciiground.git
cd asciiground
npm install

Development server

npm run dev

The development server will:

Generate the demo page from the template.
Serve the demo with live library hot-reloading.
Open the demo page in your browser.
Watches for changes and reloads the page automagically.

Building the library

npm run build           # Build library (same as build:lib).
npm run build:demo      # Build demo page.

Documentation

npm run build:docs      # Generate API documentation.

The generated documentation will be available in docs/api/. You can view it by opening docs/api/index.html in your browser or by serving the docs directory with a local server.

Type checking

npm run typecheck

Testing

npm run test:watch     # Run tests in watch mode.
npm run test:run       # Run tests once.
npm run test:coverage  # Generate coverage report.

Publishing

This project uses automated publishing via GitHub Actions. See PUBLISHING.md for detailed setup instructions.

npm run publish:patch  # 1.0.0 → 1.0.1.
npm run publish:minor  # 1.0.0 → 1.1.0.
npm run publish:major  # 1.0.0 → 2.0.0.

Validate setup

Before first publish, run the setup validation:

./scripts/test-setup.sh

This checks all required files, configurations, and build processes.

Development workflow

Fork the repository.
Create a feature branch: git checkout -b feature/your-feature.
Make your changes and add tests.
Run the test suite: npm run test:run.
Run type checking: npm run typecheck.
Run linting: npm run lint.
Commit your changes: npm run commit and follow the prompts.
Push to the branch: git push origin feature/your-feature.
Create a pull request.

Repository setup (for maintainers)

Before pushing to production, ensure these secrets are configured in GitHub:

NPM_TOKEN - required for automated NPM publishing:
- Go to npmjs.com → Account → Access Tokens.
- Create "Automation" token with "Publish" permissions.
- Add to GitHub from Settings → Secrets and variables → Actions.
GitHub Pages - required for CDN deployment:
- Go to repository Settings → Pages.
- Set "Source" to "GitHub Actions".
Codecov - for coverage reporting:
- Connect repository at codecov.io.
- Add CODECOV_TOKEN to repository secrets.

See PUBLISHING.md for complete setup instructions.

Pre-push checklist

Before pushing to the remote repository:

[ ] All tests pass: npm run test:run.
[ ] Code builds successfully: npm run build.
[ ] Type checking passes: npm run typecheck.
[ ] Linting passes: npm run lint.
[ ] Setup validation passes: ./scripts/test-setup.sh.
[ ] Documentation is up to date.
[ ] NPM_TOKEN secret is configured in GitHub (for publishing).
[ ] CODECOV_TOKEN secret is configured in GitHub (for test coverage).
[ ] GitHub Pages is enabled.