Arquitectura de un duelo de cartas en el navegador: React, PixiJS y validación en FastifyA fondo · digest del 22 de octubre
Diorama táctil multicapa de collage en papel de un juego de cartas online, mostrando la separación entre la interfaz React y el lienzo gráfico PixiJS sobre Fastify.
A fondo4 secciones≈ 9 min

Arquitectura de un duelo de cartas en el navegador: React, PixiJS y validación en Fastify

Crear un juego multijugador en tiempo real para el navegador es una de las mejores pruebas de choque para un desarrollador web. Aquí salen a la luz al instante todos esos compromisos de arquitectura en los que uno puede no pensar durante años maquetando tiendas online o sistemas CRM convencionales.

Imagina el reto: hay que desarrollar un duelo de cartas por turnos para dos jugadores (al estilo de Hearthstone o Magic: The Gathering). El jugador arrastra cartas de la mano al tablero, lanza bolas de fuego, ataca a las criaturas del rival, el temporizador corre y el oponente al otro lado del mundo debe ver movimientos fluidos de cartas y efectos mágicos a unos estables 60–120 fotogramas por segundo.

El primer impulso de la mayoría de los desarrolladores frontend es escribirlo todo con su stack favorito: React, Framer Motion y Tailwind CSS. Las cartas son un simple <div className="card">, el tablero es un <div className="board"> y el arrastre se resuelve con react-dnd.

Pero al cabo de un par de semanas de desarrollo, el proyecto choca inevitablemente contra dos muros de hormigón:

  1. Caída de FPS (Performance Wall): cuando en pantalla se juegan tres hechizos a la vez, vuelan chispas de partículas y el temporizador del turno actualiza el DOM cada segundo, el motor del navegador se ahoga en ciclos de Recalculate Style, Layout y Paint. La tasa de fotogramas se desploma a unos tirones de 20–30 FPS.
  2. Trampas (Security Wall): si la lógica que comprueba el coste de la carta y el maná disponible vive solo en el cliente, cualquier jugador puede abrir la consola de DevTools, llamar a playCard(legendaryDragon) sin maná y reventar la partida.

Veamos una receta de arquitectura que resuelve ambos problemas: separar la interfaz entre React y PixiJS 8, compartir un único reductor de estado isomórfico en TypeScript y validar cada jugada de forma estricta en Fastify.

Principio de separación de responsabilidades: React + PixiJS

Para librarse del lag del árbol DOM, hay que dividir con claridad los elementos de la pantalla según su naturaleza física:

  • UI estática (React DOM): panel de perfil del jugador, avatares, contador de vidas, chat de texto, botón de «Ajustes» y modales emergentes de ayuda. Estos elementos cambian poco, no requieren interpolaciones al milisegundo y se maquetan de maravilla con HTML/CSS normal y soporte de accesibilidad (a11y).
  • Escena de juego dinámica (PixiJS 8 sobre WebGL / WebGPU): el tablero, las cartas en la mano, trayectorias de proyectiles, efectos visuales de brillo, shaders de disolución y física de arrastre. El renderizado se saca a un único elemento <canvas> gobernado por el motor gráfico PixiJS.

Plano de patente del análisis del protocolo Redis RESP3: una máquina de estados finitos en streaming procesa prefijos de tipos de datos dentro del bucle de eventos de libuv.

PixiJS 8 trabaja directamente con la GPU mediante WebGL o WebGPU, aplicando Sprite Batching y dibujando miles de objetos interactivos sin tocar ni una vez el árbol DOM. El resultado es un juego que mantiene 120 FPS sólidos incluso en teléfonos móviles.

Ya tratamos a fondo cómo las reglas declarativas y las máquinas de estados ayudan a diseñar interfaces complejas en el artículo sobre qué puede aprender el desarrollo web del desarrollo de videojuegos.

El núcleo arquitectónico: reductor isomórfico determinista

El error más frecuente en juegos distribuidos es duplicar la lógica de juego: en el cliente se escriben las reglas en TypeScript y en el backend se intenta replicar esa misma lógica en Python, Go o Java. Tarde o temprano las reglas divergen y empieza la desincronización (Desync).

La solución elegante es un reductor puro isomórfico (Shared State Reducer) en TypeScript puro. Este módulo se compila como un paquete NPM compartido y se importa tanto en la aplicación web cliente como en el servicio de servidor en Fastify.

La función del reductor es estrictamente determinista:

duelReducer(currentState, action) -> newState

Con los mismos datos de entrada devuelve siempre un resultado idéntico, sin efectos secundarios.

Veamos la implementación del núcleo del reductor:

// shared/duelReducer.ts — módulo isomórfico compartido
export interface PlayerState {
  id: string;
  mana: number;
  maxMana: number;
  health: number;
  hand: Card[];
  board: Card[];
}

export interface GameState {
  matchId: string;
  turnPlayerId: string;
  turnNumber: number;
  players: Record<string, PlayerState>;
  actionHistory: CardAction[];
}

export type CardAction = 
  | { type: 'PLAY_CARD'; playerId: string; cardId: string; targetId?: string; timestamp: number }
  | { type: 'END_TURN'; playerId: string; timestamp: number };

export function duelReducer(state: GameState, action: CardAction): GameState {
  switch (action.type) {
    case 'PLAY_CARD': {
      // 1. Comprobamos el turno del jugador
      if (state.turnPlayerId !== action.playerId) {
        throw new Error('Не твой ход!');
      }

      const player = state.players[action.playerId];
      const cardIndex = player.hand.findIndex(c => c.id === action.cardId);

      // 2. Comprobamos que la carta esté en la mano
      if (cardIndex === -1) {
        throw new Error('Карта отсутствует в руке игрока');
      }

      const card = player.hand[cardIndex];

      // 3. Comprobamos el maná
      if (player.mana < card.cost) {
        throw new Error('Недостаточно маны для розыгрыша');
      }

      // 4. Construimos el nuevo estado inmutable
      const nextHand = [...player.hand];
      nextHand.splice(cardIndex, 1);

      return {
        ...state,
        players: {
          ...state.players,
          [action.playerId]: {
            ...player,
            mana: player.mana - card.cost,
            hand: nextHand,
            board: [...player.board, card]
          }
        },
        actionHistory: [...state.actionHistory, action]
      };
    }

    case 'END_TURN': {
      const opponentId = Object.keys(state.players).find(id => id !== action.playerId)!;
      const opponent = state.players[opponentId];
      const nextMaxMana = Math.min(10, opponent.maxMana + 1);

      return {
        ...state,
        turnPlayerId: opponentId,
        turnNumber: state.turnNumber + 1,
        players: {
          ...state.players,
          [opponentId]: {
            ...opponent,
            maxMana: nextMaxMana,
            mana: nextMaxMana
          }
        },
        actionHistory: [...state.actionHistory, action]
      };
    }

    default:
      return state;
  }
}

Validación en el servidor con Fastify y WebSocket

El cliente nunca se considera fuente de verdad (Never Trust the Client). El servidor actúa como árbitro incorruptible.

Usamos el framework web Fastify con el plugin @fastify/websocket. Elegimos Fastify por su mínima sobrecarga sobre el bucle de eventos de V8 y su alta capacidad de serialización JSON.

Así es como se procesa un paquete del juego en el servidor:

// server/gameSocket.ts
import Fastify from 'fastify';
import websocket from '@fastify/websocket';
import { duelReducer, GameState, CardAction } from '../shared/duelReducer';

const app = Fastify({ logger: true });
app.register(websocket);

// Almacén en memoria de las salas de juego activas
const activeMatches = new Map<string, GameState>();

app.register(async function (fastify) {
  fastify.get('/ws/duel/:matchId', { websocket: true }, (connection, req) => {
    const { matchId } = req.params as { matchId: string };
    
    connection.socket.on('message', (rawMessage: string) => {
      try {
        const action: CardAction = JSON.parse(rawMessage.toString());
        const currentState = activeMatches.get(matchId);

        if (!currentState) {
          connection.socket.send(JSON.stringify({ error: 'Матч не найден' }));
          return;
        }

        // ¡Aplicamos el reductor compartido en el servidor!
        // Si la jugada no es válida, el reductor lanzará una excepción
        const nextState = duelReducer(currentState, action);
        activeMatches.set(matchId, nextState);

        // Difundimos el estado canónico confirmado a todos los participantes del duelo
        broadcastToMatch(matchId, {
          type: 'STATE_UPDATE',
          state: nextState,
          lastAction: action
        });

      } catch (err: any) {
        // La jugada era ilegal: enviamos señal de reversión
        connection.socket.send(JSON.stringify({
          type: 'REVERT_ACTION',
          reason: err.message
        }));
      }
    });
  });
});

Actualizaciones optimistas y reversión fluida

¿Qué ve el jugador cuando suelta una carta sobre la mesa? Si tuviera que esperar la respuesta de red del servidor (un roundtrip de 50–150 ms), el juego se sentiría «espeso» y poco reactivo.

Por eso el cliente aplica actualizaciones optimistas (Optimistic UI):

  1. El jugador suelta la carta: el cliente invoca duelReducer en local, arranca al instante la animación de caída de la carta sobre la mesa y resta la barra de maná en la interfaz.
  2. En paralelo, el socket de red envía la acción PLAY_CARD al servidor.
  3. El servidor aprueba la acción y devuelve la confirmación: el cliente simplemente da por válida la transacción.
  4. Si ocurre un fallo puntual o un tramposo intentó falsificar su maná, el servidor responde con REVERT_ACTION. El cliente captura esa señal, devuelve la carta suavemente a la mano con una animación de retroceso y muestra el mensaje de error.

Este enfoque híbrido ofrece al jugador una respuesta táctil instantánea y unos fluidos 120 FPS, manteniendo intactas la honestidad y la estabilidad de un multijugador competitivo.

Quiero un análisis detalladoLos votos ayudan a elegir qué analizar a fondo. Este material tiene 0 votos.
Fuentes · 3