technical case study

Front-end • Canvas animation / Library

Karpaz Koi

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.

Animation, simulation and rendering Open source Version 1.0 published on GitHub
JavaScript Canvas 2D WebGL2 Node.js ESLint Playwright
executive summary

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.

Solution

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.

Result

A single file with no dependencies, configurable through options and published as open source, with a demo, examples and tests.

Current stage

Version 1.0 published on GitHub under the MIT license.

context

A whole pond made of characters

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.

goals and constraints

Goals

  • Bring the site background to life without getting in the way of reading
  • Natural movement: inertia, current, curiosity and food
  • Two visual styles on the same simulation engine
  • Simple integration: one function call and options with sensible defaults
  • Stable performance on phones and large screens

Constraints

  • A single JavaScript file, with no dependencies
  • Never steal clicks from the page's links, buttons and fields
  • Steer around headings and text and turn translucent behind them
  • Simulation at 60 Hz, independent of the drawing rate
solution architecture

Front-end

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.

Back-end

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.

Database

No database. The repository has a demo, examples, a smoke test with Node and Playwright, ESLint and continuous integration on GitHub Actions.

security and safeguards

Stays out of the way

The layer sits behind the content and ignores clicks on links, buttons and fields; only empty water gets food.

Light by default

Drawing capped at 30 frames per second, expensive effects off by default and the background glow drawn with a sprite instead of shadowBlur.

Licenses in order

Code under the MIT license, with the notice for the project that inspired the drawing technique in THIRD_PARTY_NOTICES.

process
01

Drawing technique

Adapting the ascii-sharks technique to koi seen from above.

02

Simulation

An articulated body, swimming with inertia, current, food and curiosity about the cursor.

03

Two styles

ASCII and smooth, with five koi varieties.

04

The pond

Stones, plants, lily pads, lotus flowers, small fish, bubbles and petals.

05

Open source

Demo, examples, tests, an English README and the MIT license.

behind the scenes
src/karpaz-koi.js JavaScript lines 70–79
  /** 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;
  }
The water has a current: a divergence-free field, computed as the curl of a function that changes slowly over time.
src/karpaz-koi.js JavaScript lines 476–512
        // 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;
Each koi adds up inertia, a little wandering and a goal: food nearby (it goes fast) or a resting cursor (it comes close and circles around).
src/karpaz-koi.js JavaScript lines 386–394
    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) });
      }
    }
A click on the water drops 4 to 6 scattered food pellets, with at most 36 pellets in the pond.
src/karpaz-koi.js JavaScript lines 637–651
  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"];
The ASCII palettes: light glyphs on bright skin and dense ones in shadow, dedicated edges and fin rays that follow their direction on screen.
impact

Results

An animation with personality for the Karpaz website, published as a reusable library with a demo and documented options.

Learnings

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.