PULAR PARA O CONTEÚDO

Matrix Rain: de um script de chuva a um vídeo wall no terminal

Comecei por birra com o cmatrix. Oito meses e 44 commits depois, o projeto tem três modos, true color, testes e várias janelas de terminal que viram uma tela só.

Nesta nota
Chuva digital em Katakana verde, com a cabeça de cada coluna em branco
Chuva digital em Katakana verde, com a cabeça de cada coluna em branco

Tudo começou com uma birra. O cmatrix promete caracteres japoneses, mas na maioria dos terminais eles não renderizavam direito. As cores eram chapadas, sem brilho, e a animação parecia presa nos anos 2000. Fiz o que dá para fazer com uma birra dessas, escrevi a minha. O código está em Serg-Ale/matrix-rain.

A primeira versão era um arquivo só, em Python, com curses. O que existe hoje não se parece com ela, e a parte mais útil de contar é como ela cresceu.

O que mudou

Três modos, trocáveis na hora. Chuva, ondas de pulso e uma rede de nós em 3D. A tecla m alterna entre eles sem reiniciar.

Cor de verdade. O primeiro gradiente tinha 8 tons e usava a paleta de 256 cores do terminal. Hoje o projeto usa 24 bits onde o terminal suporta, lendo COLORTERM, e cai de volta para a paleta de 256 quando não suporta. Para isso, a tela deixou de ser desenhada pelo curses e passou a emitir ANSI direto de um buffer de frame. Existem 11 temas e um modo arco-íris.

Chuva em nove temas de cor, mais o modo arco-íris
Chuva em nove temas de cor, mais o modo arco-íris

Pacote modular. O arquivo único virou um motor compartilhado em core/ e um arquivo por modo em modes/, com uma interface comum de duas funções, reset e render. Acrescentar um modo não toca no motor.

Testes. O motor de cor, as paletas, a lógica do vídeo wall e a divisão do buffer de tela têm mais de cem testes de unidade, com a biblioteca padrão. O que depende do curses não tem teste automático, é validado à mão, e o AGENTS.md do repositório diz isso com todas as letras.

O vídeo wall

Duas janelas de terminal lado a lado, com uma única animação de rede que continua de uma para a outra
Duas janelas de terminal lado a lado, com uma única animação de rede que continua de uma para a outra

A funcionalidade que mais gostei de construir. Rodando matrix-rain --wall em dois ou mais terminais, eles viram tiles de uma tela só. A animação roda uma vez e cada janela mostra a sua fatia do mesmo canvas.

Algumas decisões que valem registro.

  • Um host e vários clientes. O primeiro terminal vira host e calcula cada quadro. Os outros pedem a sua fatia. A comunicação usa um socket Unix privado, então o wall é local à sua máquina e ao seu usuário, e não conecta máquinas diferentes.
  • Eleição com flock. Quando dois terminais abrem ao mesmo tempo, quem vira host? A revisão do primeiro ticket do wall apontou o problema e hoje um flock decide.
  • Sucessão de host. Se o host sai, por q, Ctrl+C ou queda, o cliente mais antigo assume com as últimas configurações do wall e os demais reconectam. A animação recomeça, a imagem continua.
  • Grade 2D. --at LINHA,COLUNA diz onde cada terminal fica. Um terminal em cima e dois embaixo funciona, e a chuva passa de uma janela para a outra.
  • Modo de layout. A tecla L entra num modo em que as setas movem o tile pela grade, trocando de lugar com quem já está lá.
  • Intervalo entre janelas. Janelas reais têm moldura, e a imagem quebra na emenda. Teclas ajustam quantas colunas ou linhas do canvas ficam escondidas em cada emenda, e o valor certo depende do seu terminal e da fonte, então se acerta olhando.

O caminho de um quadro

  1. Simulação no canvas inteiro
  2. extract por tile
  3. JSON em linhas
  4. load no cliente
  5. flush no terminal
O host roda a animação uma vez. Cada cliente só desenha a sua fatia.

O host trata o conjunto de janelas como um único canvas. Os modos de animação só conhecem app.width e app.height, então rodam no wall sem mudar uma linha. A cada quadro, o Screen do host entrega um retângulo por tile com extract, que devolve as células em coordenadas locais:

def extract(self, top, left, height, width):
    cells, bgs = [], []
    for y in range(max(0, -top), min(height, self.height - top)):
        for x in range(max(0, -left), min(width, self.width - left)):
            cell = self._cells[top + y][left + x]
            if cell is not None:
                char, rgb, bold, reverse = cell
                # Um caractere de largura dupla na última coluna
                # invadiria o terminal vizinho, então é descartado.
                if not (x == width - 1 and east_asian_width(char) in ('W', 'F')):
                    cells.append((y, x, char, rgb, bold, reverse))
                    continue
            bg = self._bg[top + y][left + x]
            if bg is not None:
                bgs.append((y, x, bg))
    return cells, bgs
def extract(self, top, left, height, width):
    cells, bgs = [], []
    for y in range(max(0, -top), min(height, self.height - top)):
        for x in range(max(0, -left), min(width, self.width - left)):
            cell = self._cells[top + y][left + x]
            if cell is not None:
                char, rgb, bold, reverse = cell
                # Um caractere de largura dupla na última coluna
                # invadiria o terminal vizinho, então é descartado.
                if not (x == width - 1 and east_asian_width(char) in ('W', 'F')):
                    cells.append((y, x, char, rgb, bold, reverse))
                    continue
            bg = self._bg[top + y][left + x]
            if bg is not None:
                bgs.append((y, x, bg))
    return cells, bgs

O Katakana ocupa duas células no terminal. Esse if existe porque, sem ele, a metade direita de um caractere cortado aparece no começo do tile vizinho. O cliente faz o caminho inverso com load e escolhe true color ou 256 cores pelo suporte do próprio terminal, então um terminal sem 24 bits não degrada os outros.

Onde cada janela fica

A função que posiciona os tiles é pura, sem socket e sem curses, e é por isso que dá para testá-la:

def layout(sizes, positions=None, gap=(0, 0)):
    gap_columns, gap_rows = gap
    positions = resolve_positions(positions or [None] * len(sizes))
    rows = {}
    for index, (row, col) in enumerate(positions):
        rows.setdefault(row, []).append((col, index))

    placements = [None] * len(sizes)
    y = canvas_width = 0
    for row in sorted(rows):
        x = row_height = 0
        for _, index in sorted(rows[row]):
            width, height = sizes[index]
            placements[index] = (x, y)
            x += width + gap_columns
            row_height = max(row_height, height)
        canvas_width = max(canvas_width, x - gap_columns)
        y += row_height + gap_rows
    return placements, max(y - gap_rows, 1), max(canvas_width, 1)
def layout(sizes, positions=None, gap=(0, 0)):
    gap_columns, gap_rows = gap
    positions = resolve_positions(positions or [None] * len(sizes))
    rows = {}
    for index, (row, col) in enumerate(positions):
        rows.setdefault(row, []).append((col, index))

    placements = [None] * len(sizes)
    y = canvas_width = 0
    for row in sorted(rows):
        x = row_height = 0
        for _, index in sorted(rows[row]):
            width, height = sizes[index]
            placements[index] = (x, y)
            x += width + gap_columns
            row_height = max(row_height, height)
        canvas_width = max(canvas_width, x - gap_columns)
        y += row_height + gap_rows
    return placements, max(y - gap_rows, 1), max(canvas_width, 1)

As linhas empilham de cima para baixo e, dentro de cada uma, os tiles vão da esquerda para a direita. Uma linha tem a altura do seu tile mais alto e a largura do canvas é a da linha mais larga. O gap esconde colunas e linhas do canvas em cada emenda, para compensar a moldura da janela. Quando as linhas têm larguras diferentes, a diferença fica sem imagem, e a spec registra isso como limite conhecido.

Quando o host fecha

Se o host sai, o cliente mais antigo assume. O host informa a cada cliente o seu rank, e quem perde o host espera um tempo proporcional ao rank antes de tentar:

def promotion_delay(rank):
    """Seconds a client of this rank waits before trying to take over."""
    return min(rank or 0, PROMOTION_MAX_RANK) * PROMOTION_STEP
def promotion_delay(rank):
    """Seconds a client of this rank waits before trying to take over."""
    return min(rank or 0, PROMOTION_MAX_RANK) * PROMOTION_STEP

A espera só ordena as tentativas. Quem garante um único vencedor é o flock exclusivo e sem bloqueio no arquivo de lock, que aceita apenas um processo mesmo se duas tentativas chegarem juntas. Quem perde reconecta ao novo host. A animação recomeça, a imagem continua.

O resto da lógica de decisão do wall, intervalo, troca de posição, sucessão e protocolo de mensagens, mora no mesmo módulo puro. A casca de I/O, com o socket Unix e os laços do host e do cliente, é fina e fica separada.

Por que o frame vai inteiro

Cada quadro envia todas as células da fatia, sem diferença em relação ao anterior. Foi uma decisão deliberada da primeira versão, e o custo de CPU do JSON ficou registrado na spec como risco. A revisão final fez a medição: codificar leva cerca de 1,2 ms para 2 mil células, 3 ms para 5 mil e 7 ms para 11 mil por frame, e decodificar custa o mesmo, contra um orçamento de 30 ms. O gargalo é o redesenho completo do terminal, não o codec. Se um dia pesar, o caminho é um ticket de renderização por diferença no Screen, sem refazer o resto.

Como foi feito

O wall foi construído em tickets numerados, do #16 ao #22. O primeiro era um tracer bullet: juntava dois terminais numa tela só, ainda sem nenhuma das decisões acima. Cada ticket seguinte acrescentou uma coisa e passou por revisão antes de entrar. Foi o mesmo fluxo que uso com o Claude Code, aplicado a um projeto pessoal. As revisões acharam coisas reais, como a corrida da eleição e vazamentos de listener e socket, e isso foi antes de o código chegar à branch principal.

O que ainda não faz

Não conecta máquinas diferentes, porque o wall depende de um socket Unix local. Também não há distribuição por pip ou pipx, que está registrada como trabalho futuro. Hoje se instala clonando o repositório e criando um link no PATH. O nome definitivo do projeto também está em aberto.