ASCII Backdrop

A subject paints brightness or colour on a small canvas; the engine prints every character cell as a glyph, dot or tile. Anything that can paint on a canvas can be the subject.

How it works

Every frame, each layer's subject draws itself on a small offscreen canvas (a few pixels per character cell). The engine reads those pixels and prints them in the layer's mode. A lower depth dims a layer, which gives depth for free; a clear zone fades output around the UI so headings and inputs stay readable. Changing the subject means changing one draw function; the engine does not change.

Print mode	Layer setting	Look	Frame cost at 1440×900 (measured)
Brightness glyphs	default mode: 'glyph'	Glyph from the density ramp; the brightest cells print as filled boxes	~8 ms
Edge glyphs	glyph: { edges: true }	/ \ | - follow strong edges	~8 ms
Shape matching	glyph: { match: 'shape' }	Samples a 2×3 grid per cell and picks the glyph whose shape fits best, for crisper outlines (after Alex Harri)	~5 ms (cached)
Braille	mode: 'braille'	2×4 dots per cell, twice the resolution, optional Bayer dither	~6 ms
Dither	mode: 'dither'	Bayer 4×4 ordered dither, dots or squares sized by level	~6 ms
Colour tiles	mode: 'tile'	Rounded squares in the colours the subject paints	~3 ms

Subjects paint in white (brightness = density); only tile layers paint real colours. Layers in different modes can share one scene.

Files

• assets/ascii-backdrop.js: engine, built-in subjects and page helpers, no dependencies, exposed as window.AsciiBackdrop. Copy it into the project.
• assets/demo.html: a dark prompt page with the backdrop behind it; switch subjects, print modes, glyph sets, CRT and palettes; the heading decodes; a corner card shows the image dissolve; upload an image or video.
• scripts/check.mjs: screenshots desktop, phone and reduced-motion views and reports errors and frame rate (needs Playwright).

Steps

1. Choose the subject. Ask what it should say (a brand mascot, a product, a mood) instead of assuming a creature. Pick the source in this order:
   • Existing image, SVG, video or logo: subjects.image(src, { invert, motion }). Use invert: true for dark art on a light background.
   • A word, name or emoji: subjects.text('…').
   • A mathematical field (plasma, interference, noise, gradients): subjects.field((u, v, t) => brightness) with u, v in [-0.5, 0.5], like a fragment shader.
   • A shaded 3D solid: subjects.sdf({ shape: 'torus' | 'sphere' | 'box' | 'capsule' }), or pass your own (p) => distance.
   • Presets: jellyfish, school (many small bodies), cloud (smoke, nebula), strands (kelp, hair; flip: true for flames), rising (fire, bubbles, sparks; fall: true for snow or rain), solid (spinning wireframe), ripples (ambient rings plus a ring per click), wanderers (tile-mode segmented bodies that wander and veer away from the cursor).
   • Nothing fits: subjects.custom((ctx, t, s, env) => { … }) (see "Write a subject"). Presets are starting points, not the menu.
2. Choose the print mode. Edge glyphs or shape matching for clean outlines; braille for fine shading; dither for a printed, retro look; tiles for coloured subjects.
3. Compose the layers. Each layer is { subject, mode, x, y, scale, depth, drift, speed, timeOffset, rotate }; x and y are 0–1 of the screen. A layout that works: one hero below the input, one above it, two faint ones at the sides (depth 0.4–0.6). Give repeats different seed or timeOffset values so they do not move in sync.
4. Palette, glyphs and finish. palette lists 3–5 colours from dark to bright; built-ins are PALETTES.abyss / ember / mono / phosphor / amber / duo. background matches the page. Glyph sets: RAMPS.dense / soft / classic / binary / blocks / dots / katakana. Add crt for a terminal look and keep it subtle. Aim clear at the heading and input.
5. Wire it in. Put a full-screen <canvas> behind the content (position: fixed; inset: 0), keep content above it, and give panels a translucent fill with backdrop-filter. React notes are below.
6. Verify. Run node scripts/check.mjs page.html and look at the three images: is the subject recognisable, are the heading and input clear, is the phone view too busy, does reduced motion show one still frame? Completed-frame rate should track the configured fps; a stopped backdrop reports 0. Fields and CRT cost about 16–17 ms per frame; if frames drop, raise cell, lower fps, or lower the field's resolution.

Wiring

<canvas id="bd" style="position:fixed;inset:0;width:100%;height:100%"></canvas>
<script src="ascii-backdrop.js"></script>
<script>
  const { subjects: S, PALETTES } = AsciiBackdrop;
  const bd = AsciiBackdrop.create(document.getElementById('bd'), {
    palette: PALETTES.abyss,
    clear: { x: 0.5, y: 0.46, rx: 0.3, ry: 0.2, strength: 0.85 },
    glyph: { edges: true },                                    // outlines in / \ | -
    interactive: true, pointerGlow: { radius: 110, strength: 0.35 },
    layers: [
      { subject: S.jellyfish({ seed: 1 }), x: 0.56, y: 0.76, scale: 0.72, depth: 1 },
      { subject: S.sdf({ shape: 'torus' }), mode: 'braille', x: 0.15, y: 0.3, scale: 0.45, depth: 0.6 },
    ],
  });
  bd.start();
</script>

React: call create inside useEffect and return () => bd.destroy(). When layers change, call bd.setLayers(...); when options change, call bd.set({...}). Do not recreate the backdrop on every render.

Tile mode and interaction

const bd = AsciiBackdrop.create(canvas, {
  interactive: true,
  background: '#1b1a18', grid: 'dots',
  palette: ['#34322f', '#5f5c56', '#9a968e', '#e6e2da'],
  tile: { size: 12, gap: 2, radius: 2 },            // square size, gap, corner radius
  layers: [
    { subject: S.ripples(), x: 0.5, y: 0.5, scale: 1.9, depth: 0.7 },                  // glyph ripples
    { subject: S.wanderers({ count: 7 }), mode: 'tile', x: 0.5, y: 0.5, scale: 1.7 },  // tile bodies
  ],
});

• Tile layers paint real colours. Use dark grey instead of pure black for dark markings; pure black reads as empty. Pass your own colours with wanderers({ colors: [{ base, mark, accent }] }).
• With interactive: true, subjects receive env.pointer (the cursor in that layer's local units) and env.clicks (recent clicks with their age). pointerGlow brightens output near the cursor on every non-tile layer without any subject code.
• Read interaction from env instead of storing state in the subject. Write fleeing as "the closer the cursor, the further the push" so any moment can still be sampled directly.

Page helpers

// Heading text cycles through noise and settles left to right. trigger: 'load' | 'hover' | 'view' | 'manual'
AsciiBackdrop.scramble(document.querySelector('h1'), { trigger: 'view', duration: 900 });

// An image shows as characters, then dissolves cell by cell into the picture.
// trigger: 'hover' | 'scroll' | 'load' | 'manual'; pattern: 'center' | 'edges' | 'down' | 'up' | 'random'.
// The image needs a positioned parent and must be same-origin.
const r = AsciiBackdrop.reveal(document.querySelector('.hero img'), { trigger: 'scroll', pattern: 'edges' });
r.progress(0.5); // drive it yourself, 0–1

Both show the final state immediately under reduced motion.

Write a subject

const lighthouse = AsciiBackdrop.subjects.custom((ctx, t, s) => {
  // Draw around the origin, roughly inside [-s/2, s/2]. Brighter, more opaque white = denser output.
  ctx.fillRect(-s * 0.05, -s * 0.3, s * 0.1, s * 0.6);                    // tower
  AsciiBackdrop.helpers.softDot(ctx, 0, -s * 0.32, s * 0.12, 0.9);        // lamp
  ctx.save(); ctx.rotate(t * 0.8);                                          // beam
  ctx.globalAlpha *= 0.35; ctx.fillRect(0, -s * 0.33, s * 0.6, s * 0.03); ctx.restore();
});
const plasma = AsciiBackdrop.subjects.field((u, v, t) => 0.5 + 0.5 * Math.sin(10 * u + t) * Math.cos(8 * v - t));

• Brightness is the whole language: use alpha, gradients and line width to decide where output is dense. A flat white area becomes a wall of filled boxes; give it a gradient or lower alpha.
• Animate from t (seconds) and env only, never from the previous frame, so reduced motion, screenshots and recordings can sample any moment.
• Keep lines at least about one cell wide (s * 0.015 or more), or they break into scattered dots.
• Helpers: helpers.softDot(ctx, x, y, r, alpha) for soft glows; helpers.strand(ctx, points, w0, w1, a0, a1) for lines that taper and fade from root to tip.

Options

Option	Default	Meaning
cell	{w:9,h:15}	Character cell size; larger is coarser and cheaper
ramp	RAMPS.dense	Glyphs from sparse to dense
glyph	{ edges:false, match:'ramp' }	Edge glyphs and shape matching; edgeStrength sets edge sensitivity, contrast the shape-match contrast
braille	{ threshold:0.35, dither:true }	Dot threshold and Bayer dither
dither	{ size:6, shape:'dot', levels:4 }	Grid size, 'dot' or 'square', brightness levels
tile	{ size:12, gap:2, radius:2, color:'source' }	Tile size, gap, corner radius, colour source
pointerGlow	null	{ radius, strength }; needs interactive: true
crt	null	{ scanlines, glow, vignette, flicker }; 0.15–0.35 reads well
cutoff / highlight	0.06 / 0.9	Below cutoff stays empty; above highlight prints a filled box
texture / shimmer	0.3 / 0.12	Brightness grain and glyph flicker; set 0 for a still poster
grid	'lines'	Background grid: 'lines', 'dots' or false
fps	30	30 is enough for a character backdrop

Out of scope

Character fluid simulation (needs per-frame state), morphing between two ASCII images, webcam input (needs device permission), and a WebGL shader build. Build those separately instead of growing this engine.

Gotchas

• Cross-origin images taint the canvas and the engine cannot read pixels. Use same-origin, data: or blob: URLs, or a server that sends CORS headers. Pages opened from file:// treat local images as cross-origin too.
• Keep CRT scanlines and flicker subtle; flicker is skipped under reduced motion. Do not put body text under the CRT finish.
• Handled by the engine: high-DPI sharpness, resize, pausing in hidden tabs, and a single still frame under prefers-reduced-motion.
• Keep the UI copy neutral; do not copy another product's name or interface text.