asciiground
Version:
Library for creating animated ASCII canvas backgrounds supporting generative patterns and extensive configuration options.
360 lines (273 loc) • 9.61 kB
Markdown
# ASCIIGround
[](https://github.com/Eoic/asciiground/actions)
[](https://codecov.io/gh/Eoic/asciiground)
[](https://www.npmjs.com/package/asciiground)
[](https://unpkg.com/asciiground@latest/dist/)
[](https://www.jsdelivr.com/package/npm/asciiground)
[](https://opensource.org/licenses/MIT)
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
```bash
npm install asciiground
```
### CDN
```html
<script src="https://unpkg.com/asciiground@latest/dist/asciiground.umd.js"></script>
```
## Quick start
### Basic usage
```typescript
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
```typescript
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
```html
<!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.
```typescript
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.
```typescript
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.
```typescript
import { StaticNoisePattern } from 'asciiground';
const pattern = new StaticNoisePattern({
seed: 42,
characters: [' ', '.', '*', '#'],
});
```
## Examples
### Matrix-style rain
```typescript
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
```typescript
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/](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
```bash
git clone https://github.com/Eoic/asciiground.git
cd asciiground
npm install
```
### Development server
```bash
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
```bash
npm run build # Build library (same as build:lib).
npm run build:demo # Build demo page.
```
### Documentation
```bash
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
```bash
npm run typecheck
```
### Testing
```bash
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](./PUBLISHING.md) for detailed setup instructions.
```bash
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:
```bash
./scripts/test-setup.sh
```
This checks all required files, configurations, and build processes.
### Development workflow
1. Fork the repository.
2. Create a feature branch: `git checkout -b feature/your-feature`.
3. Make your changes and add tests.
4. Run the test suite: `npm run test:run`.
5. Run type checking: `npm run typecheck`.
6. Run linting: `npm run lint`.
7. Commit your changes: `npm run commit` and follow the prompts.
8. Push to the branch: `git push origin feature/your-feature`.
9. Create a pull request.
### Repository setup (for maintainers)
Before pushing to production, ensure these secrets are configured in GitHub:
1. **NPM_TOKEN** - required for automated NPM publishing:
- Go to [npmjs.com](https://npmjs.com) → Account → Access Tokens.
- Create "Automation" token with "Publish" permissions.
- Add to GitHub from Settings → Secrets and variables → Actions.
2. **GitHub Pages** - required for CDN deployment:
- Go to repository Settings → Pages.
- Set "Source" to "GitHub Actions".
3. **Codecov** - for coverage reporting:
- Connect repository at [codecov.io](https://codecov.io).
- Add `CODECOV_TOKEN` to repository secrets.
See [PUBLISHING.md](./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.