DROPTRACE — PUBG Match Intelligence

Alpha 0.5 — visualizador tático independente para reconstrução de partidas do PUBG.

O DROPTRACE consulta a PUBG Developer API, organiza o histórico de um jogador e reproduz a telemetria sobre o mapa original da partida. A aplicação foi construída em JavaScript e combina perfil, ranking, inventário, combate, veículos, zonas e movimentação de todos os participantes em uma timeline interativa.

Este repositório está em fase Alpha. A interface e os formatos normalizados da API local ainda podem mudar antes da versão estável.

Visão geral

• Busca de jogador por nickname e plataforma.
• Perfil completo separado do visualizador de partidas.
• Histórico em lista, organizado entre competitivo, casual e mata-mata.
• Ranking oficial por plataforma, região e modo, com Top 10, Top 100 e paginação até o Top 500 quando a PUBG disponibiliza os dados.
• Reprodução 2D no mapa original em alta resolução.
• Seleção e foco em qualquer jogador da partida.
• Timeline do jogador ou da partida completa, com velocidade configurável.
• Cache, deduplicação e fila global para respeitar o limite de 10 RPM da PUBG API.
• Análise explicável de padrões incomuns no histórico, sem acusar o jogador de cheat.

Alpha 0.5 — o que já foi implementado

Visualizador e mapas

Safe zones

• Blue zone que causa dano em azul.
• Safe atual com círculo branco contínuo.
• Próxima safe com círculo branco tracejado.
• Interpolação temporal dos círculos.
• Zoom automático acompanhando o fechamento da zona.
• Entrada e saída da safe no estado do jogador.
• Contador de jogadores vivos sincronizado com a timeline.

Jogador, equipe e combate

Perfil e histórico

Ranking

• Página própria em /ranking.
• Escolha primeiro da plataforma e depois da região compatível.
• Filtros por modo.
• Pódio e lista com emblema do rank do jogador.
• Top 10 inicial.
• Expansão para Top 100 e paginação até o Top 500 retornado pela API.
• Clique em jogador abre a consulta de seu histórico.

Backend e segurança

• Servidor customizado Node.js + Express integrado ao Next.js.
• JavaScript ES6+ e CommonJS no backend, sem TypeScript.
• Authorization: Bearer <PUBG_API_KEY> somente no servidor.
• Cache em memória separado para jogadores, partidas, telemetria, temporadas, rankings e perfis.
• Deduplicação de chamadas simultâneas para a mesma chave.
• Fila com janela deslizante limitada a no máximo 10 chamadas upstream por minuto.
• Limite local por cliente e cabeçalhos de segurança com Helmet.
• Tratamento padronizado de 400, 404, 429 e falhas 5xx.

Tecnologias

• Node.js 18.17+
• Express
• Next.js 15 com App Router
• React 19
• Canvas 2D
• node-cache
• Helmet
• PUBG Developer API
• JavaScript puro — não há TypeScript no projeto

Estrutura

app/                         páginas Next.js e rota /ranking
components/                  mapa, perfil, histórico, selects e emblemas
public/
  brand/                     identidade visual
  item-art/                  artes dos itens e armas
  items/                     fallbacks dos itens
  maps/                      mapas oficiais otimizados
  rank-assets/               emblemas dos ranks
scripts/                     download e otimização de assets
src/
  middleware/                erros da API local
  routes/                    endpoints Express
  services/                  PUBG API, cache e fila
  utils/                     normalização e análises
test/                        testes unitários
server.js                    servidor Express + Next.js

Como executar

1. Requisitos

• Node.js 18.17 ou superior
• Uma chave criada em https://developer.pubg.com/

2. Instalação

Com npm:

npm install

Com pnpm:

corepack enable
pnpm install

No Windows também é possível iniciar pelo script:

.\dev.cmd

3. Ambiente

No PowerShell:

Copy-Item .env.example .env

No Linux ou macOS:

cp .env.example .env

Preencha apenas o .env local:

PUBG_API_KEY=sua_chave_privada
PORT=3000

Nunca envie o .env para o GitHub.

4. Desenvolvimento

npm run dev

Acesse http://localhost:3000.

5. Testes e produção

npm test
npm run build
npm start

Pipeline e proteção da main

O workflow .github/workflows/ci.yml é executado em todo pull request destinado à main e também após pushes na branch principal. O merge só deve ser liberado quando o job Tests and build concluir:

1. instalação reproduzível com pnpm install --frozen-lockfile;
2. execução dos testes unitários;
3. build otimizado do Next.js.

A main é protegida contra push direto, force-push e exclusão. Mudanças devem passar por pull request, receber aprovação e resolver todas as conversas antes do merge.

API local

Método	Rota	Uso
GET	/api/health	Estado da chave, cache e fila
GET	/api/leaderboards/regions	Plataformas, regiões e modos suportados
GET	/api/leaderboards/:region/:gameMode	Ranking oficial da temporada
GET	/api/players/:platform/:nickname	Jogador e IDs de partidas
GET

Plataformas aceitas: steam, kakao, psn, xbox e tournament.

Cache e rate limit

Os TTLs padrão são:

Recurso	TTL
Jogador	5 minutos
Perfil	30 minutos
Partida	1 hora
Temporada	2 horas
Leaderboard	2 horas
Telemetria	24 horas

A fila permite iniciar no máximo 10 requisições upstream dentro de qualquer janela de 60 segundos. Requisições repetidas são atendidas pelo cache sempre que possível.

Como as coordenadas são exibidas

A PUBG fornece coordenadas em centímetros. O frontend converte o mundo para a imagem quadrada correspondente:

pixelX = (apiX / worldSize) * imageWidth
pixelY = (apiY / worldSize) * imageHeight

O tamanho lógico varia entre os mapas. Lobby e posições anteriores à partida são tratados separadamente para não criar trajetórias falsas sobre o mapa.

Bugs e limitações conhecidos da Alpha 0.5

Próximos passos sugeridos

• Persistir cache e perfis em Redis ou banco de dados.
• Adicionar autenticação e favoritos.
• Criar testes de integração e testes visuais automatizados.
• Processar históricos grandes em tarefas assíncronas.
• Adicionar observabilidade, métricas e logs estruturados.
• Evoluir o mapa 2D para uma camada 3D opcional sem perder a fidelidade do mapa.
• Permitir comparação entre jogadores e partidas.
• Criar sistema de comentários privados para revisão em equipe.

Segurança e colaboração

• A PUBG_API_KEY nunca é enviada ao navegador.
• .env, caches, builds, dependências e logs locais são ignorados pelo Git.
• Para colaborar, convide o usuário pelo menu Settings → Collaborators do repositório privado.
• Bugs devem informar nickname, plataforma, ID da partida, instante da timeline e uma captura de tela, sem incluir a chave da API.

Avisos

O DROPTRACE é um projeto independente, não afiliado à KRAFTON ou à PUBG Studios. Mapas, nomes, emblemas e artes pertencem aos respectivos titulares. Dados de partidas são fornecidos pela PUBG Developer API.