Options

The AsciiOptions object controls every aspect of conversion and rendering. Start from DEFAULT_OPTIONS and override what you need.

import { DEFAULT_OPTIONS, ART_STYLE_PRESETS } from 'asciify-engine';

const options = {
  ...DEFAULT_OPTIONS,
  ...ART_STYLE_PRESETS.terminal,
  fontSize: 8,
  colorMode: 'fullcolor',
};

Core

Option	Type	Default	Description
`fontSize`	number	10	Character size in pixels. Controls grid density — smaller = denser grid.
`charSpacing`	number	1	Multiplier applied to cell width and height.
`charset`	string	' .:-=+*#%@'	Character ramp: first char = lightest luminance, last = darkest.
`renderMode`	'ascii' \| 'dots'	'ascii'	Render as ASCII characters ('ascii') or filled dot circles ('dots').
`invert`	boolean	false	Invert luminance mapping — swap light and dark assignment.
`customText`	string \| undefined	undefined	Tile a custom string across all cells instead of the charset ramp.

Color

Option	Type	Default	Description
`colorMode`	'grayscale' \| 'fullcolor' \| 'matrix' \| 'accent'	'grayscale'	grayscale = brightness-mapped, fullcolor = source pixel color, matrix = green terminal look, accent = accent color on intensity peaks.
`accentColor`	string	'#d4ff00'	Color applied to peak-intensity cells when colorMode is "accent".

Image adjustments

Option	Type	Default	Description
`brightness`	number	0	Brightness offset applied before charset mapping. Range: -1 to 1.
`contrast`	number	0	Contrast adjustment. Range: -1 to 1.
`ditherStrength`	number	0	Bayer ordered dither intensity. Range: 0 to 1.
`dotSizeRatio`	number	0.8	Dot circle radius as a fraction of cell size. Dots renderMode only.
`charAspect`	number	0.55	Width ÷ height of a single output character. Must match your rendering env: 0.5 for most terminals, 0.52 for browser line-height 1.15, 0.55 for line-height 1.09. Controls how many rows vs cols are generated so output has correct proportions.
`normalize`	boolean	false	Auto-stretch the luminance range of the frame before charset mapping. Maximises detail for low-contrast or muted images.

Animation

Option	Type	Default	Description
`animationStyle`	AnimationStyle	'none'	Per-cell animation during rendering. Values: 'wave' \| 'pulse' \| 'rain' \| 'breathe' \| 'sparkle' \| 'glitch' \| 'spiral' \| 'typewriter' \| 'scatter' \| 'waveField' \| 'ripple' \| 'melt' \| 'orbit' \| 'cellular'.
`animationSpeed`	number	1	Speed multiplier for all animation effects.

Hover effects

Option	Type	Default	Description
`hoverEffect`	HoverEffect	'spotlight'	The effect near the cursor. Values: 'spotlight' \| 'magnify' \| 'repel' \| 'glow' \| 'colorShift' \| 'attract' \| 'shatter' \| 'trail'.
`hoverStrength`	number	0	Hover effect intensity. 0 = disabled. Typical range: 0.3–0.8.
`hoverRadius`	number	0.5	Hover influence radius in normalized canvas coordinates (0–1).
`hoverColor`	string	'#ffffff'	Secondary color used by colorShift and glow effects.

Hover presets

Shorthand spreads that configure hoverEffect, hoverStrength, and hoverRadius together.

gravity

Pulls characters toward the cursor with smooth falloff.

shatter

Radial scatter outward with random jitter per cell.

ghost

Color-blended trail that smoothly follows the cursor.

import { HOVER_PRESETS, DEFAULT_OPTIONS } from 'asciify-engine';

const options = { ...DEFAULT_OPTIONS, ...HOVER_PRESETS.gravity };
// Equivalent to:
// { hoverEffect: 'attract', hoverStrength: 0.6, hoverRadius: 0.4 }