An ASCII-based renderer for creating animations directly in the browser. ASCII Engine allows for dynamic, grid-based animations displayed as text. This package is still under development.
The library utilizes DOM to render characters on the screen.
You can install ASCII Engine via npm:
npm install ascii-engineor use the script directly in your HTML:
https://ozencb.github.io/ascii-engine/latest/ascii-engine.js
Create a placeholder container element with an id of your choice, and pass this element down to the render function's first argument. For the second parameter, pass an animation function.
The container element should ideally have a height of 100vh.
Inspired by ertdfgcvb's work.
Include the ASCII Engine script in your HTML file and call the render function:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Document</title>
<script src="https://ozencb.github.io/ascii-engine/latest/ascii-engine.js"></script>
</head>
<body style="background-color: black; color: white">
<div id="background" style="height: 100vh"></div>
<script>
const density = [' ', '░', '▒', '▓', '█'];
const animation = () => {
return density[Math.floor(Math.random() * density.length)];
};
AsciiEngine.render(document.getElementById('background'), animation);
</script>
</body>
</html>Import the render function from the ASCII Engine package and use it in your JavaScript code:
import { render } from 'ascii-engine';
const density = [' ', '░', '▒', '▓', '█'];
const animation = () => {
return density[Math.floor(Math.random() * density.length)];
};
render(document.getElementById('background'), animation);Here is a simple example of an animation module you can use with ASCII Engine:
export const CheckerBoard: Animation = (coords, context, buffer, cursor) => {
// create a static checkboard pattern
return (coords.x + coords.y) % 2 === 0 ? '█' : ' ';
};render(target: HTMLElement, animation: Animation, options?: RenderOptions): void
Renders the ASCII animation on the specified target element.
target: The HTML element where the animation will be rendered.animation: The animation module containing themainfunction.options: Optional rendering options.resolution: Controls the size of each character cell. Accepts numbers between1 to 10orResolutionenum values (TypeScript only).
An animation module should have the following structure:
// anim.ts
export const CheckerBoard: Animation = (coord: Coordinates, context: AnimationContext, buffer: FrameBuffer, cursor: CursorContext): string | null => {
// do stuff and return back a character
};coords: The coordinates of the current cell.x: (number) Column indexy: (number) Row index
context: The animation context, providing cell metrics and frame information.frame: (number) Current frame countdeltaTime: (number) Time in seconds since the last frameelapsedTime: (number) Total elapsed time in secondscellWidth, cellHeight: (number) Dimensions of each cellrows: (number) Grid dimensionscols: (number) Grid dimensions
buffer: (string[][]) The frame buffer, allowing direct mutation of the grid.cursor: The cursor’s position and state, including:x: (number) Cursor coordinates in pixelsy: (number) Cursor coordinates in pixelscol: (number) Cursor location in grid cellsrow: (number) Cursor location in grid cellspressed: (boolean) Whether the cursor button is pressed
Please check demo animations under src/demo for different use cases for these parameters.
You can simply clone the repo and then use yarn to install dependencies, and then yarn build to build the project. You can then use the index.html for demo and development purposes.
- Colored characters
- Pre and post render functions
This project is licensed under the GNU Public License.