particles

particles() makes a piece of particles: things born over time that move, age and die. Snow, rain, sparks, fireworks, fireflies. Eight come ready-made, and any other is a few fields of plain numbers: cells, seconds and degrees. Every frame depends only on t, so the piece loops exactly and plays as an SVG.

Snow, by name:

// snow.ts
import { particles } from "ascii.rest/kit";

export default particles({ name: "snow", cols: 48, rows: 12 }, "snow", { wind: 3 });

    .                    *
                 .                      .  +   +
                      .
    *                    .             +      .
.   .                                    +
                                            +
   *               .        .             .
                            +
        .               +        +
                           +
      .    *      .                       .
  +

Far flakes are small and slow, near ones large and quick. It repeats every 8 seconds.

Presets

particles(spec, name, options?) plays a preset. Each fits itself to the piece’s size and looks right with no options.

density is a share of the usual: 2 is twice as many.

A picture with them

front and back draw a picture with the particles, in front of them or behind: text as you would type it, or any piece, like a banner(). paint colours some of its characters:

// city.ts
import { particles } from "ascii.rest/kit";

const city = `
        ┌───┐                         ┌───┐
        │ ▪ │           ┌───┐         │ ▪ │         ┌───┐
┌─────┐ │ ▪ │           │ ▪ │ ┌─────┐ │   │         │ ▪ │
│ ▪ ▪ │ │   │ ┌───────┐ │   │ │ ▪ ▪ │ │ ▪ │ ┌─────┐ │   │ ┌────┐
│ ▪   │ │ ▪ │ │ ▪ ▪   │ │ ▪ │ │   ▪ │ │ ▪ │ │ ▪ ▪ │ │ ▪ │ │ ▪  │`;

export default particles({ name: "fireworks over the city", front: { art: city, color: "#64748b", paint: { "▪": "#f59e0b" } } }, "fireworks");

                       ****+
                    +**||../*++
                   *\..    ..-*
                 +-..        ..+
                  *-.        ..**
                  */..     ...**
                  +*+/...||.\++
                     +++|****
               .
               .

                         .
                       . .
                                             |
                                             :
                                             .

        ┌───┐                         ┌───┐
        │ ▪ │           ┌───┐         │ ▪ │         ┌───┐
┌─────┐ │ ▪ │           │ ▪ │ ┌─────┐ │   │         │ ▪ │
│ ▪ ▪ │ │   │ ┌───────┐ │   │ │ ▪ ▪ │ │ ▪ │ ┌─────┐ │   │ ┌────┐
│ ▪   │ │ ▪ │ │ ▪ ▪   │ │ ▪ │ │   ▪ │ │ ▪ │ │ ▪ ▪ │ │ ▪ │ │ ▪  │

Text sits on the bottom row by default, and a piece in the middle. at places it elsewhere: "top", "top-left" and the rest.

A system of your own

A system says where particles are born, how many, how they move, and how they look as they age. Only emitter is needed:

// embers.ts
import { particles } from "ascii.rest/kit";

export default particles({ name: "embers", cols: 48, rows: 16, period: 4 }, {
  emitter: "bottom", direction: "up", spread: 40, speed: [4, 9], life: [1.5, 3],
  sway: 1, glyphs: "*+'.", colors: ["#fde047", "#f97316", "#7f1d1d"],
});

A number or [low, high] gives each particle its own value between them. The fields:

Give a list of systems to draw several, each over the last. system({ ... }) gives a system back as it is: written apart from particles(), it is checked where it is written, and [1, 2] reads as a range.

Born on a mark

To say where in a picture particles come from without counting columns, type a mark there in the art and give the emitter { mark }. The mark is drawn as a blank. streak is a glyph that points the way each particle goes, -, \, | or /:

// cabin.ts
import { particles, streak, system } from "ascii.rest/kit";

const cabin = `
        ^
       | |
   ____|_|____
  /           \\
 /_____________\\
  |  _     _  |
  |_|_|___|_|_|`;

const smoke = system({ emitter: { mark: "^" }, direction: "up", spread: 20, speed: [1, 2], sway: 1, life: [3, 5], glyphs: "()~-." });
const rain = system({ emitter: "top", direction: "down", speed: [10, 14], wind: 8, glyph: streak, rate: 30 });

export default particles({ name: "cabin in the rain", cols: 40, rows: 14, front: cabin }, [smoke, rain]);

At 1 second:

    \        \\   \
     \\                   \\
     \ \  \ \                          \
         \    \\\  ..             \
                   -..  \
        \\ \       ))~~   \
         \\      \ ())
                \ \( \  \  \       \
               \   | |     \
               ____|_|____        \  \
              /           \  \
             /_____________\
              |  _     _  |  \
              |_|_|___|_|_|   \ \ \\

Particles off a word

An emitter of { text } gives birth on a picture’s characters. With a banner() as both the emitter and the picture behind, sparks rise off its letters:

// spark-banner.ts
import { banner } from "ascii.rest/banner";
import { particles } from "ascii.rest/kit";

const word = banner("ascii", { effect: "still", color: ["#f59e0b", "#ef4444"] });

export default particles({ name: "spark banner", back: word }, {
  emitter: { text: word }, rate: 24, direction: "up", spread: 60, speed: [3, 8], life: [1, 2.2], gravity: -2, sway: 0.6,
  glyphs: "*+'.", colors: { light: ["#7c2d12", "#c2410c", "#ea580c", "#f59e0b"], dark: ["#fffbeb", "#fde047", "#f97316", "#b91c1c"] },
});

A burst from text puts one particle on each character, drawn as that character, so the word itself comes apart.

Options

particles(spec, ...) takes a piece’s spec, as piece() does, with every field optional (64 by 24 by default), and these:

drawParticles(): particles in your own piece

drawParticles(s, systems, t, options?) draws systems into a grid you are drawing already. particlesPalette(systems) gives the piece their colours. Make the systems once, outside the drawing:

// comet.ts
import { TAU, drawParticles, particlesPalette, piece, presets, type System } from "ascii.rest/kit";

const head = (t: number) => [32 + 27 * Math.cos((TAU * t) / 8), 12 + 9 * Math.sin((TAU * t) / 8)] as const;
const tail: System = {
  emitter: { point: head }, rate: 80, life: [0.6, 1.6], speed: [0, 1.5], glyphs: "@**++:::...",
  colors: { light: ["#0f172a", "#0369a1", "#7dd3fc"], dark: ["#ffffff", "#7dd3fc", "#1d4ed8"] },
};
const sky = [...presets.stars({ cols: 64, rows: 24, period: 8 }, { shooting: 0 }), tail];

export default piece({ name: "comet", cols: 64, rows: 24, loop: 8, palette: particlesPalette(sky, { light: ["#b45309"], dark: ["#f59e0b"] }) }, (t, s) => {
  drawParticles(s, sky, t, { period: 8 });
  s.write(26, 10, "  .----.\n=(      )=\n  '----'");
});

presets.snow(size, options) and the rest return the systems, to draw yourself or to change.

Next

• materials: smoke, steam and bubbles that rise from a named object.
• effects: a glint or a shake on the whole piece.