SC2 Build HUD

Overlay para Windows que mostra build orders do StarCraft II durante a partida: relógio alinhável ao tempo do jogo, lista de passos com ícones e custos estimados, e um editor para importar builds a partir de texto colado ou URL direta de uma página de build no Spawning Tool (ex.: build 200997).

Este projeto é independente e não é endossado pela Blizzard Entertainment.

Origem e estado do projeto

Este repositório foi construído com Vibe Coding (desenvolvimento assistido por IA em fluxo conversacional): o autor não escreveu manualmente uma linha de código — a implementação resultou desse processo.

O projeto não está completo: pode faltar imagens (os ícones em data/icons/ são opcionais e, por defeito, costumam estar incompletos), podem existir bugs, comportamentos inconsistentes ou funcionalidades por acabar.

Queres ajudar? Faz fork deste repositório, implementa correções ou novas funcionalidades e abre pull requests para o desenvolvimento coletivo.

---

Changelog

Registo das alterações recentes de comportamento e documentação.

2026-05-02 — Filtro por raça no separador Builds

• Filtrar a lista de builds: após Atualizar lista, o painel mostra Todas as raças e três botões com ícone (Terran, Protoss, Zerg). Com uma raça escolhida, o menu pendente só lista ficheiros .json cujo campo "race" corresponde a essa raça (valores como terran, protoss, zerg ou formas curtas já reconhecidas pelo parser).
• Builds sem "race" (ou raça desconhecida) só aparecem quando Todas as raças está ativo.
• Ícones do filtro vivem em data/icons/common/ com os nomes terran.png, protoss.png e zerg.png. O carregamento é restrito a esta pasta e a estes ficheiros (sem procurar por sufixos nas pastas terran/ / protoss/ / zerg/), para evitar confusão com ícones de unidades (ex.: infested terran a aparecer no botão Terran).

2026-05 — Importação por URL (Spawning Tool)

• No separador Editor → Importar do site ou clipboard, podes colar o URL completo de uma página de build em lotv.spawningtool.com (só são aceites hosts que terminam em .spawningtool.com e endereços com /build/ no caminho) e carregar em Importar pela URL para descarregar a página por HTTPS (winhttp), extrair o título (<h1>) e as linhas da tabela da build order, e preencher o editor automaticamente — sem copiar a tabela à mão.
• Exemplo de ligação: https://lotv.spawningtool.com/build/200997/ — página DnS's Adept/Immortal All-In (PvP All-In) no Spawning Tool.
• Depois ajusta nome, raça e ficheiro em user/ como já fazias com a colagem; a raça continua a poder ser inferida do título (ex.: PvP → Protoss).
• Nota: se o HTML do site mudar, a importação por URL pode falhar; nesse caso usa Converter para editor com o texto colado da tabela. Usa importações moderadas e respeita os termos do serviço.

2026-05 — Desempenho da overlay

• O intervalo principal do ciclo da aplicação adapta-se ao estado (por exemplo HUD compacta com relógio a correr, rato sobre a janela, ou configurações abertas), para reduzir uso de CPU em repouso sem sacrificar fluidez quando o temporizador ou o HUD estão activos.

---

Funcionalidades

• HUD compacta em tela cheia (sempre no topo): tempo decorrido, passo atual, lista COMING UP, ícones e custos (mineral/gás) quando disponíveis.
• Painel de configuração (tecla INSERT): separadores Match (relógio), Builds (ficheiros JSON), HUD (ajuda e colunas), Editor (importar por colagem ou URL do Spawning Tool / editar / gravar builds).
• Idioma: Português (Brasil) e inglês, guardados em ficheiro de definições.
• Builds em JSON em data/builds/presets/ e data/builds/user/.
• Ícones opcionais em data/icons/ (PNG), organizados por raça e pasta common (incluindo terran.png / protoss.png / zerg.png em common/ para os botões de filtro no separador Builds).

---

Capturas de ecrã

Painel de configuração — docs/BuildHud.PNG

A janela de configuração (abre com INSERT) mostra o tema azul neon inspirado no SC2: atalhos (INSERT para o menu, END para sair), escolha de idioma, separadores Partida / Builds / HUD / Editor e, neste exemplo, o separador Editor com importação de texto (Spawning Tool), botão para abrir o site de builds, área de colagem, conversão para passos e secção Nome, raça e gravação antes de salvar na lista.

Overlay compacta — docs/BuildOverlay.PNG

Com o menu fechado (INSERT), fica a HUD compacta por cima do jogo: tempo decorrido, título da build, controlos de temporizador, histórico recente de passos, passo atual com ícone e supply / mineral / gás, e a lista PRÓXIMOS com timings, ícones e custos. O rodapé lembra INSERT — configurar.

---

Requisitos

• Windows 10 ou superior (x64 recomendado).
• Visual Studio 2022 (ou build tools) com carga de trabalho Desktop development with C++.
• Windows SDK compatível.
• Direct3D 9 (normalmente disponível no sistema).
• Bibliotecas ligadas pelo projeto: d3d9, windowscodecs, ole32, shell32, winhttp (HTTPS para importar builds por URL).

---

Como compilar

1. Clonar o repositório.
2. Abrir SC2Hud.sln no Visual Studio.
3. Selecionar configuração Release e plataforma x64 (recomendado).
4. Build → Build Solution.
5. O executável fica em x64\Release\SC2Hud.exe (ou pasta equivalente à configuração escolhida).

Importante: ao correr a partir da pasta de saída, mantém a estrutura data\ ao lado do .exe (ou copia a pasta data do repositório para junto do executável). O programa procura builds e ícones relativamente ao diretório do executável.

---

Estrutura de dados

data/
  builds/
    presets/     ← exemplos incluídos (JSON)
    user/        ← builds que gravares no Editor
  icons/
    terran/      ← PNGs por nome (ex.: supply_depot.png)
    protoss/
    zerg/
    common/      ← minerals.png, gas.png (custos); terran/protoss/zerg.png (filtro de raça em Builds)

Definições da interface (idioma):

• %LOCALAPPDATA%\SC2Hud\settings.ini
  Se LOCALAPPDATA não estiver disponível, usa-se uma pasta junto ao executável.

---

Uso do aplicativo

Primeira execução

1. Coloca SC2Hud.exe com a pasta data (com pelo menos data/builds).
2. Inicia o programa. A overlay cobre o ambiente de trabalho (janela transparente por chroma key magenta nas áreas vazias).
3. Com o jogo ou outra janela à frente, usa os atalhos abaixo.

Atalhos globais

Tecla	Ação
INSERT	Abre ou fecha o menu de configuração (painel grande).
F11	Alterna o modo em que a overlay pode receber foco de teclado (útil para escrever em campos com o menu fechado).
END	Encerra a aplicação.

Separador Match

• Alinha o relógio do HUD com o tempo da partida no StarCraft II.
• Na hora em que a partida marca 0:00, usa Iniciar agora (ou sincroniza mais tarde com o tempo em segundos e Aplicar).

Separador Builds

• Lista ficheiros .json em data/builds (presets e user/).
• Atualizar lista se gravaste um ficheiro novo noutro sítio.
• Filtro por raça: Todas as raças ou ícones Terran / Protoss / Zerg (data/icons/common/*.png — ver Changelog). A lista obedece ao campo race em cada JSON.
• Escolhe uma build no menu pendente e Carregar esta build para usar no HUD.

Separador HUD

• Explica o comportamento da overlay compacta (INSERT fechado).
• Opções de colunas visíveis na tabela de pré-visualização.

Separador Editor

1. Abre o site de builds (botão que abre https://lotv.spawningtool.com/ no navegador).
2. Por URL: cola o link da página da build (ex.: build 200997) no campo URL da build (Spawning Tool) e usa Importar pela URL — ou por texto: cola a tabela no campo grande e usa Converter para editor (supply, tempo, ação; tab ou espaços como antes).
3. Ajusta nome, raça e nome do ficheiro em user/ (sem .json).
4. Salvar na lista de builds grava em data/builds/user/. Depois, em Builds, usa Atualizar lista e carrega o ficheiro.
5. Usar no HUD agora aplica a build atual ao overlay sem obrigar a gravar ficheiro.

Overlay compacta (INSERT fechado)

• Mostra tempo, passo atual e próximos passos.
• Ícones vêm dos PNG em data/icons/ quando o nome coincide com o passo/ico do JSON.
• Clicar numa linha da lista (quando aplicável) pode ajudar a sincronizar o tempo com aquele passo.

---

Créditos e atribuições

Blizzard Entertainment

• StarCraft II e toda a propriedade visual e de marca associada (unidades, edifícios, logótipos, etc.) são propriedade da Blizzard Entertainment, Inc.
• Este repositório não inclui gráficos oficiais extraídos do jogo. Os ficheiros em data/icons/ são opcionais e cabe ao utilizador obtê-los e utilizá-los de acordo com os termos da Blizzard e políticas aplicáveis.
• O HUD é uma ferramenta de apoio não oficial para prática pessoal.

Spawning Tool (build orders)

• As builds em formato de texto colado são muitas vezes inspiradas ou copiadas de guias do site Spawning Tool — Legacy of the Void, um recurso da comunidade para ordens de construção e replays.
• Crédito e agradecimento aos autores e maintainers do Spawning Tool. O aplicativo abre esse site para facilitar a obtenção de builds; não há afiliação entre este projeto e o Spawning Tool ou a Blizzard.

Bibliotecas de terceiros (incluídas ou referenciadas no código)

• Dear ImGui — interface imediata.
• nlohmann/json — parsing JSON (third_party/nlohmann/json.hpp).

---

Aviso legal

Software fornecido “como está”, sem garantias. Usa por tua conta e risco. Não uses em violação dos termos do StarCraft II ou de serviços terceiros.

Uso comercial

É proibido vender este projeto ou qualquer derivado com o propósito de comercialização (por exemplo: vender o executável, pacotes fechados ou cobrar por licenças sobre este código sem autorização explícita do titular do repositório). O objetivo é partilha gratuita com a comunidade; forks e contribuições devem respeitar essa intenção.

---