Problem
The particle background of the Karpaz website called for an element with personality, one that would move naturally without getting in the way of reading or weighing down the page.
technical case study
Front-end • Canvas animation / Library
Koi carp swimming in a pond, drawn on a canvas over the background of the Karpaz website, in two styles: ASCII, made only of characters, and smooth, a fine mosaic. A single file with no dependencies.
Demo in the smooth style: ogon and asagi koi, lily pads and plants, with the panel for style, varieties, size, pond and ready-to-paste code.
The same pond in the ASCII style: body, fins and water made only of characters, with the fin glyphs following the direction of the rays.
The five varieties: ogon, asagi, kohaku, sakura and tancho.
Minimal example: the particle background, two ASCII koi and the pond, in a few lines of code.
The particle background of the Karpaz website called for an element with personality, one that would move naturally without getting in the way of reading or weighing down the page.
A koi animation with its own simulation (swimming, current, food and curiosity about the cursor) and two drawing styles, which steers around text, pushes the background particles and reacts to clicks on the water.
A single file with no dependencies, configurable through options and published as open source, with a demo, examples and tests.
Version 1.0 published on GitHub under the MIT license.
The koi swim in a pond with stones, plants, lily pads, lotus flowers and small fish, pass under headings and text while becoming more transparent, and come closer when the cursor stops. The drawing technique was adapted from the ascii-sharks project (MIT license); the simulation, the pond, the two styles and the integration with the site background were built on top of it.
Its own canvas over the background: in the ASCII style, each cell becomes a glyph chosen by its shading; in the smooth style, a fine mosaic with continuous shading and translucent fins.
No server: the simulation runs at 60 Hz in the browser, with a body articulated in 18 nodes, wandering, a divergence-free current, chasing food and a circular dance between the koi.
No database. The repository has a demo, examples, a smoke test with Node and Playwright, ESLint and continuous integration on GitHub Actions.
The layer sits behind the content and ignores clicks on links, buttons and fields; only empty water gets food.
Drawing capped at 30 frames per second, expensive effects off by default and the background glow drawn with a sprite instead of shadowBlur.
Code under the MIT license, with the notice for the project that inspired the drawing technique in THIRD_PARTY_NOTICES.
Adapting the ascii-sharks technique to koi seen from above.
An articulated body, swimming with inertia, current, food and curiosity about the cursor.
ASCII and smooth, with five koi varieties.
Stones, plants, lily pads, lotus flowers, small fish, bubbles and petals.
Demo, examples, tests, an English README and the MIT license.
/** Correnteza sem divergência (rotacional de uma função de corrente que deriva devagar). */
function current(x, y, t, out) {
const K1 = 1 / 260, K2 = 1 / 310, K3 = 1 / 190, S = 3400;
const a = x * K1 + t * 0.07;
const b = y * K2 - t * 0.05;
const c = (x + y) * K3 + t * 0.11;
out.x = (-K2 * Math.sin(a) * Math.sin(b) + 0.5 * K3 * Math.cos(c)) * S;
out.y = (-K1 * Math.cos(a) * Math.cos(b) - 0.5 * K3 * Math.cos(c)) * S;
return out;
}
// Inércia + um leve vaguear.
let dx = Math.cos(k.heading);
let dy = Math.sin(k.heading);
k.wander = clamp(k.wander + (Math.random() - 0.5) * dt * 2.4, -0.9, 0.9);
dx += Math.cos(k.heading + k.wander) * 0.4;
dy += Math.sin(k.heading + k.wander) * 0.4;
const cruise = 20 + L * 0.06;
let targetSpeed = cruise;
let agility = 0.9;
const food = this.nearestFood(hx, hy, L * 2.5 + 260);
if (food) {
// Ração: vão direto, mais rápidas.
const tx = food.x - hx;
const ty = food.y - hy;
const d = Math.hypot(tx, ty) || 1;
dx += (tx / d) * 3.4;
dy += (ty / d) * 3.4;
targetSpeed = cruise * (1.3 + 0.8 * clamp(d / (L * 1.5), 0, 1));
agility = 1.9;
} else if (curious && Math.hypot(pointer.x - hx, pointer.y - hy) < 340 + L) {
// Curiosidade: chegam perto do cursor e ficam rodeando, como num lago.
const tx = pointer.x - hx;
const ty = pointer.y - hy;
const d = Math.hypot(tx, ty) || 1;
const stop = L * 0.6;
if (d > stop) {
dx += (tx / d) * 1.6;
dy += (ty / d) * 1.6;
} else {
const side = k.slot % 2 ? 1 : -1;
dx += (-ty / d) * side * 1.4 - (tx / d) * 0.7;
dy += (tx / d) * side * 1.4 - (ty / d) * 0.7;
}
targetSpeed = cruise * 0.9;
agility = 1.2;
feed(x, y) {
this.events.push({ kind: "drop", x, y });
const count = 4 + ((Math.random() * 3) | 0);
for (let i = 0; i < count && this.food.length < 36; i++) {
const a = rand(0, TAU);
const r = rand(0, 26);
this.food.push({ x: x + Math.cos(a) * r, y: y + Math.sin(a) * r, born: this.time, life: rand(14, 20), seed: rand(0, TAU) });
}
}
const FLAG_BODY = 1;
const FLAG_EDGE = 2;
const FLAG_FIN = 3;
const FLAG_RIDGE = 4;
const FLAG_EYE = 5;
// Glifos esparsos na pele clara, densos na sombra: a textura reforça o sombreado.
const SKIN_RAMP = ".:;=+x*%#@";
const EDGE_HEAVY = ":;";
const EDGE_LIGHT = ".',`";
const EDGE_ALL = EDGE_HEAVY + EDGE_LIGHT;
// Raios das nadadeiras: o glifo segue a direção do raio na tela.
const RAYS = "-\\|/";
const SUBSAMPLES = [0.25, 0.3, 0.75, 0.3, 0.25, 0.72, 0.75, 0.72];
const SHIMMER = ["#ffffff", "#fff1c9", "#3bd5ff", "#ffb066"];
An animation with personality for the Karpaz website, published as a reusable library with a demo and documented options.
Separating simulation from drawing made two styles with the same behavior possible, and measuring the cost of each effect shaped the defaults: whatever is expensive starts off.