case técnico

Front-end • Animação em canvas / Biblioteca

Karpaz Koi

Carpas koi nadando num lago, desenhadas num canvas por cima do fundo do site da Karpaz, em dois estilos: ASCII, feito só de caracteres, e suave, um mosaico fino. Um arquivo só, sem dependências.

Animação, simulação e renderização Código aberto Versão 1.0 publicada no GitHub
JavaScript Canvas 2D WebGL2 Node.js ESLint Playwright
resumo executivo

Problema

O fundo de partículas do site da Karpaz pedia um elemento com personalidade, que se movesse de forma natural sem atrapalhar a leitura nem pesar a página.

Solução

Uma animação de carpas koi com simulação própria (nado, correnteza, ração e curiosidade pelo cursor) e dois estilos de desenho, que desvia dos textos, empurra as partículas do fundo e reage a cliques na água.

Resultado

Um arquivo só, sem dependências, configurável por opções e publicado como código aberto, com demo, exemplos e testes.

Estado atual

Versão 1.0 publicada no GitHub com licença MIT.

contexto

Um lago inteiro feito de caracteres

As carpas nadam num lago com pedras, plantas, vitórias-régias, lótus e peixinhos, passam por baixo dos títulos e textos ficando mais transparentes e vêm ver quando o cursor para. A técnica de desenho foi adaptada do projeto ascii-sharks (licença MIT); a simulação, o lago, os dois estilos e a integração com o fundo do site foram construídos em cima dela.

objetivos e restrições

Objetivos

  • Dar vida ao fundo do site sem atrapalhar a leitura
  • Movimento natural: inércia, correnteza, curiosidade e ração
  • Dois estilos visuais com o mesmo motor de simulação
  • Integração simples: uma chamada de função e opções com padrões sensatos
  • Desempenho estável em celulares e telas grandes

Restrições

  • Um único arquivo JavaScript, sem dependências
  • Não roubar cliques de links, botões e campos da página
  • Desviar e ficar translúcido atrás de títulos e textos
  • Simulação a 60 Hz, independente da taxa de desenho
arquitetura da solução

Front-end

Canvas próprio por cima do fundo: no estilo ASCII, cada célula vira um glifo escolhido pelo sombreado; no suave, um mosaico fino com sombreamento contínuo e nadadeiras translúcidas.

Back-end

Sem servidor: a simulação roda a 60 Hz no navegador, com corpo articulado em 18 nós, vaguear, correnteza sem divergência, perseguição da ração e uma dança em círculo entre as carpas.

Banco de dados

Sem banco de dados. O repositório tem demo, exemplos, teste de fumaça com Node e Playwright, ESLint e integração contínua no GitHub Actions.

segurança e prevenções

Não atrapalha a página

A camada fica atrás do conteúdo e ignora cliques em links, botões e campos; só a água vazia recebe ração.

Leve por padrão

Desenho limitado a 30 quadros por segundo, efeitos caros desligados de início e o brilho do fundo feito com sprite em vez de shadowBlur.

Licenças em dia

Código sob licença MIT, com o aviso do projeto que inspirou a técnica de desenho no arquivo THIRD_PARTY_NOTICES.

processo
01

Técnica de desenho

Adaptação da técnica do ascii-sharks para carpas vistas de cima.

02

Simulação

Corpo articulado, nado com inércia, correnteza, ração e curiosidade pelo cursor.

03

Dois estilos

ASCII e suave, com cinco variedades de koi.

04

O lago

Pedras, plantas, vitórias-régias, lótus, peixinhos, bolhas e pétalas.

05

Código aberto

Demo, exemplos, testes, README em inglês e licença MIT.

bastidores técnicos
src/karpaz-koi.js JavaScript linhas 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;
  }
A água tem correnteza: um campo sem divergência, calculado como o rotacional de uma função que muda devagar com o tempo.
src/karpaz-koi.js JavaScript linhas 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;
Cada carpa soma inércia, um leve vaguear e um objetivo: ração por perto (vai rápido) ou o cursor parado (chega perto e fica rodeando).
src/karpaz-koi.js JavaScript linhas 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) });
      }
    }
Um clique na água solta de 4 a 6 grãos de ração espalhados, com no máximo 36 grãos no lago.
src/karpaz-koi.js JavaScript linhas 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"];
As paletas do ASCII: glifos leves na pele clara e densos na sombra, bordas próprias e raios das nadadeiras que seguem a direção na tela.
impacto

Resultados

Uma animação com personalidade para o site da Karpaz, publicada como biblioteca reutilizável, com demo e opções documentadas.

Aprendizados

Separar simulação e desenho permitiu ter dois estilos com o mesmo comportamento, e medir o custo de cada efeito guiou os padrões: o que é caro vem desligado.