effects

An effect takes a piece and returns a new one. It works on anything: a library piece like rust, a banner(), a piece you made with the kit, or plain text. The new piece plays everywhere, keeps its source’s colours on both pages, and loops when they both do.

// glint-rust.ts
import { glint } from "ascii.rest/kit";
import { rust } from "ascii.rest/pieces";

export default glint(rust, { every: 3, options: { shine: 0 } });

options passes options to the source: shine: 0 stops the logo’s own glint, so only this one shows.

Text works as it is. This types a command in, holds for 2 seconds, then types it again:

// command.ts
import { typeIn } from "ascii.rest/kit";

export default typeIn("$ npx ascii.rest add kit", { hold: 2 });

At 1 second it is all typed, the cursor blinking after it:

$ npx ascii.rest add kit▌

Every effect

Every effect also takes name, note, and options for its source. mode is "in", "out" or "inout". Times are in seconds. An option the effect doesn’t have throws, and lists the ones it has.

The numbers have words too: every is "often", "sometimes" or "rarely" for glint(), glitch() and shake(); amount is "subtle", "medium" or "strong" for glitch(), shake() and wave(); and speed is "slow", "normal" or "fast" for glint(), typeIn() and wave(). So glitch(rust, { every: "rarely", amount: "subtle" }) reads as it plays. A colour is #rrggbb, { light, dark } or a palette’s name.

hues is the twelve colours rainbow() uses by default, { light, dark }, deeper for a light page; outlines is outline()’s line styles, each 16 characters by the edges that meet in a cell (up 1, down 2, left 4, right 8), for a style of your own.

Every effect is also a step on any piece the kit makes, so gauge().glint({ every: "rarely" }) is glint(gauge(), { every: "rarely" }). A library piece or a banner() gets the steps through pieceOf() or chained().

Effects that grow the piece, like wave, shake, outline and shadow, add room round it so nothing is cut off. Between bursts, a glint, a glitch or a shake leaves the piece exactly its source.

chain(): one after another

chain(src, ...effects) gives each effect the piece the last one made. An effect with options goes in as a function:

// card.ts
import { chain, outline, shadow, typeIn } from "ascii.rest/kit";

const commands = "$ npx ascii.rest donut\n$ npx ascii.rest banner hello\n$ npx ascii.rest add donut";

export default chain(
  commands,
  (p) => typeIn(p, { name: "terminal", hold: 2 }),
  (p) => outline(p, { style: "rounded" }),
  shadow,
);

At 1 second, the outline grows round the commands as they type:

╭──────────────────────╮
│$ npx ascii.rest donut╰───╮
│$ npx ascii.rest banner h▌│░
╰──────────────────────────╯░
 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░

A rainbow banner that sways:

// hello.ts
import { banner } from "ascii.rest/banner";
import { chain, rainbow, wave } from "ascii.rest/kit";

export default chain(banner("hello", { effect: "still" }), rainbow, wave);

Its loop is worked out from both: 6 seconds, when the rainbow’s 3 and the wave’s 2 come round together.

effect(): your own

effect(src, spec?, draw) makes an effect of your own. The kit plays the source and hands your drawing each of its frames as a grid, src, with an empty grid, s, to draw into. It works out the size, the colours and the loop.

This draws a banner over its reflection, each row of the reflection rippling:

// reflection.ts
import { banner } from "ascii.rest/banner";
import { effect } from "ascii.rest/kit";

const word = banner("ascii.rest", { effect: "still", color: ["#f97316", "#f778ba"] });
const letter = (ch: string) => ch >= "▀" && ch <= "▟";

export default effect(word, { name: "reflection", period: 2, pad: { bottom: word.meta.rows } }, (t, s, src) => {
  s.paste(src, 0, 0);
  for (let y = 0; y < src.rows; y++) {
    const dx = Math.round(Math.sin(Math.PI * (t + y / 3)));
    for (let x = 0; x < src.cols; x++) if (letter(src.get(x, y))) s.set(x + dx, 2 * src.rows - 1 - y, "░", src.colorAt(x, y));
  }
});

What effect()’s spec takes:

The drawing’s fourth argument, ctx, has ctx.x and ctx.y, where the source’s top left sits in the new grid, and ctx.at(t), the source’s frame at another moment, for trails and echoes.

Next

• layouts: pieces side by side, over each other, or in turn.
• banners: every option of banner().