Como exportar um jogo Godot para a web (HTML5 e itch.io)

O Godot exporta para a web em HTML5 e WebAssembly, o que significa que seu jogo roda em uma aba do navegador sem download e sem plugin. É a forma mais rápida de colocar uma build jogável na frente de alguém. Você cola um link, a pessoa clica e joga.

"Exportar para a web" são dois trabalhos, não um. Gerar os arquivos leva cerca de um minuto. Fazer esses arquivos rodarem no navegador é onde as pessoas esbarram em uma tela preta, geralmente por causa da forma como os arquivos são servidos ou porque uma opção de exportação ativou, sem avisar, um requisito que a hospedagem não consegue cumprir. Este guia cobre as duas metades, as configurações exatas e os erros por trás da maioria das exportações que falham.

Ele vale para o Godot 4.3 e versões posteriores. Versões 4.x mais antigas sempre usavam uma build com threads, então, se você ainda está no 4.0, 4.1 ou 4.2, leia com atenção a seção sobre headers ou atualize o editor.

{/* IMAGE: The Godot Export dialog open with a Web preset selected, the Export Project button highlighted. 1200x675 editor screenshot. */}

O que a "exportação web" realmente gera

Quando você exporta, o Godot não cria um único arquivo. Ele gera uma pequena pasta de arquivos estáticos.

• index.html é a página que carrega tudo. É ela que o navegador abre.
• Um arquivo .wasm é o próprio engine Godot, compilado para WebAssembly. É a maior parte.
• Um arquivo .pck são os dados do seu jogo, ou seja, cenas, scripts e assets empacotados juntos.
• Um arquivo .js é o código de carregamento que conecta o engine à página.
• Às vezes um .áudio.worklet.js e, em builds com threads, arquivos de worker extras.

Todos eles precisam ficar juntos e ser servidos por HTTP. Você não pode dar duplo clique no index.html e esperar que rode, e é isso que pega muita gente logo de cara.

Etapa 1. Instale os templates de exportação

O Godot distribuí o editor e os templates de exportação separadamente. Os templates são os binários pré-compilados do engine para cada plataforma, incluindo a build WebAssembly para o navegador. Uma instalação nova não vem com eles.

Vá em Editor e depois em Manage Export Templates (gerenciar templates de exportação) e clique em Download and Install. Isso baixa os templates da versão exata do seu engine.

Os templates precisam corresponder exatamente à versão do seu editor. Um editor 4.4 não exporta com templates 4.3, e vice-versa. Essa incompatibilidade é uma das causas mais comuns de build web quebrada. Sempre que atualizar o editor, reinstale os templates.

Etapa 2. Adicione um preset de exportação Web

Abra Project e depois Export. Clique em Add e escolha Web.

Os padrões são sensatos. Três grupos de opções importam para a web.

• Variant, Thread Support. Desativado por padrão desde o Godot 4.3. Deixe desativado, a menos que você tenha medido uma necessidade real de threads. Uma build single-thread roda em qualquer hospedagem estática e dentro de iframes em portais de jogos. Ativar essa opção exige os dois headers Cross-Origin descritos na etapa 4.
• Variant, Extensions Support. Só é necessário se o seu projeto usa GDExtension. Também exige os headers Cross-Origin, e cada extensão nativa precisa de uma build web própria.
• VRAM Texture Compression. "For Desktop" vem ativado por padrão e "For Mobile" vem desativado. Ativar os dois deixa a exportação maior, porém mais compatível, o que importa se você espera jogadores no celular, porque os celulares geralmente não suportam os formatos de textura de desktop.

Deixe Head Include e o shell HTML personalizado vazios, a menos que tenha um motivo para mudá-los. O shell padrão cuida do carregamento e da barra de progresso.

Etapa 3. Exporte o projeto

Escolha uma pasta de destino. Crie uma pasta vazia com um nome como web-build para que os arquivos gerados não se misturem com mais nada.

Dê ao arquivo principal o nome index.html, não o nome do seu jogo. A maioria das hospedagens, incluindo o itch.io, procura um index.html como ponto de entrada. Se você chamar o arquivo de mygame.html, a hospedagem não vai encontrá-lo.

Clique em Export Project. Em poucos segundos a pasta se enche com os arquivos listados antes.

{/* IMAGE: A file explorer showing the exported web-build folder contents: index.html, .wasm, .pck, .js files. 1000x500. */}

Etapa 4. Quando você precisa dos headers Cross-Origin

A maioria dos tutoriais antigos diz que toda build web do Godot 4 precisa de headers especiais. Isso era verdade antes do 4.3. Hoje depende de duas caixas de seleção.

Uma build com Thread Support ou Extensions Support ativado usa SharedArrayBuffer, e os navegadores só permitem isso quando a página é servida com estes dois headers de resposta.

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Sem eles o engine não consegue iniciar, e o console mostra um erro que menciona SharedArrayBuffer ou crossOriginIsolated. Você não define esses headers no Godot. Você os define em quem estiver servindo os arquivos.

Uma build com as duas opções desativadas, que é o padrão, não precisa de nenhum dos dois headers. É por isso que a exportação single-thread é a escolha certa para o itch.io, portais de jogos e hospedagem estática simples. Threads podem ajudar o desempenho em jogos pesados, mas custam flexibilidade de hospedagem e compatibilidade com embeds.

Etapa 5. Teste localmente antes de enviar

Nunca depure uma exportação web enviando e recarregando. Teste primeiro na sua máquina.

A verificação mais rápida é o deploy de um clique (one-click deploy) do editor. Depois que existe um preset Web, aparece um ícone de navegador no canto superior direito do editor. Clicar nele inicia um servidor web local, exporta o projeto e o abre no seu navegador padrão. Esse servidor envia os headers Cross-Origin, então também roda builds com threads.

Para uma build que você já exportou, qualquer servidor local funciona se Thread Support e Extensions Support estiverem desativados. Com o Python instalado, rode python -m http.server 8000 dentro da pasta web-build e abra http://localhost:8000.

Para uma build com threads, sirva os arquivos com os dois headers. Salve isto como serve.py dentro da pasta.

import http.server, socketserver

class Handler(http.server.SimpleHTTPRequestHandler):
    def end_headers(self):
        self.send_header("Cross-Origin-Opener-Policy", "same-origin")
        self.send_header("Cross-Origin-Embedder-Policy", "require-corp")
        super().end_headers()

with socketserver.TCPServer(("", 8000), Handler) as httpd:
    print("Serving on http://localhost:8000")
    httpd.serve_forever()

Rode python serve.py e abra http://localhost:8000. Se o jogo carregar aqui, a exportação está correta e qualquer problema restante é de configuração da hospedagem.

Etapa 6. Hospede o jogo

itch.io (o mais fácil, grátis)

Este é o caminho recomendado para compartilhar e para game jams.

1. Compacte o conteúdo da pasta web-build, não a pasta pai, para que o index.html fique no nível principal do zip.
2. No itch.io, crie um novo projeto e defina Kind of project (tipo de projeto) como HTML.
3. Envie o zip e marque This file will be played in the browser (este arquivo será jogado no navegador).
4. Nas opções de embed, defina um tamanho de viewport que corresponda à resolução do seu jogo.

O itch.io aceita até 500 MB de conteúdo extraído, 200 MB para um único arquivo e 1.000 arquivos. Uma build single-thread não precisa de mais nada. Para uma build com threads, o itch.io oferece a caixa SharedArrayBuffer support nas opções do frame de embed, anunciada como um recurso experimental que pode quebrar partes da página, então teste a página publicada em mais de um navegador.

Netlify, Vercel, GitHub Pages ou seu próprio servidor

Uma build single-thread roda como está em qualquer hospedagem estática, incluindo o GitHub Pages simples. Garanta que o servidor envie os arquivos .wasm com o content type application/wasm e os comprima, já que o WebAssembly encolhe para cerca de um quarto do tamanho com gzip.

Para uma build com threads, a hospedagem precisa enviar os dois headers. No Netlify, adicione um arquivo _headers à raiz do deploy.

/*
  Cross-Origin-Opener-Policy: same-origin
  Cross-Origin-Embedder-Policy: require-corp

Na Vercel, defina os mesmos dois headers no vercel.json em uma regra headers. No nginx ou no Apache, adicione-os ao bloco location. O GitHub Pages não consegue enviar headers personalizados, então builds com threads ali precisam de um service worker como paliativo, como o coi-serviceworker, que nem todo navegador respeita. Se você não precisa de threads, a resposta mais simples é desativar Thread Support.

Como corrigir uma tela preta, a checklist

Se você vê um canvas preto, abra o console de desenvolvedor do navegador (pressione F12 e vá na aba Console) e leia o primeiro erro em vermelho. Siga estes itens em ordem.

1. Você abriu o arquivo diretamente? Se a URL começa com file://, sirva o jogo por HTTP.
2. O erro menciona SharedArrayBuffer ou crossOriginIsolated? Thread Support ou Extensions Support está ativado e a hospedagem não está enviando os headers. Desative as duas opções e exporte de novo, ou adicione os headers na hospedagem.
3. O erro menciona uma versão ou uma falha ao carregar o template? Seus templates de exportação não correspondem à versão do editor. Reinstale-os em Manage Export Templates.
4. É um projeto C#? O Godot 4 não exporta projetos C# para a web. A build web precisa de um projeto GDScript.
5. O arquivo .wasm está sendo servido com o tipo errado? Algumas hospedagens o enviam como download genérico. Defina o content type application/wasm.

A maioria das exportações web que falham cai em um destes cinco casos.

O que não funciona igual no navegador

Uma build web não é o desktop com uma URL. Algumas coisas se comportam de outro jeito.

• Dados salvos vão para o IndexedDB do navegador, não para uma pasta no disco, e os jogadores precisam permitir o armazenamento do site para que eles persistam. Dentro de um iframe em um portal, isso pode exigir armazenamento de terceiros, então teste o salvamento na hospedagem que você vai usar.
• O áudio só começa depois que o jogador clica, toca na tela ou aperta uma tecla, porque os navegadores bloqueiam a reprodução automática. Uma tela de "clique para começar" resolve isso.
• Plugins nativos (bibliotecas GDExtension compiladas para desktop) não carregam, a menos que tenham uma build web e Extensions Support esteja ativado.
• C# não exporta para a web no Godot 4.
• A renderização usa o renderizador Compatibility (WebGL 2) na web, então um projeto criado com Forward+ ou Mobile fica com outra aparência. Efeitos como SDFGI, névoa volumétrica e reflexos em espaço de tela não são renderizados. Crie jogos pensados para a web no Compatibility desde o início, para que o que você vê no editor seja o que chega ao jogador. O template web próprio do Summer é diferente, porque usa WebGPU com Forward+ ou Mobile.
• O tamanho do carregamento importa mais do que em qualquer outro lugar. O jogador baixa o engine, o pacote de dados e todos os assets antes de o jogo começar. O guia para desenvolvedores do Poki observa que os jogadores costumam desistir se o carregamento leva mais de dez segundos, então mantenha o primeiro download pequeno.

Summer Engine e exportação web

O Summer Engine é um engine desktop para macOS e Windows que mantém os fluxos de trabalho do Godot 4, com uma IA que cria cenas, scripts e assets a partir de linguagem natural. Ele gera versões desktop do seu jogo, que você pode vender na Steam ou enviar para o itch.io como download, e também exporta builds web.

Desde o engine 0.7, o editor inclui o template de exportação web próprio do Summer, que usa WebGPU com o renderizador Forward+ ou Mobile. A exportação web funciona para projetos em GDScript. Projetos que usam C# não podem ser exportados para a web, a mesma limitação do Godot 4. A build web é um .zip estático padrão com index.html na raiz. Você a publica no Summer Games, onde as pessoas jogam no navegador. O Summer Games também aceita a exportação web padrão do Godot descrita acima, feita com o renderizador Compatibility. Agentes podem fazer as duas etapas com as ferramentas MCP summer_export_game (destino web) e depois summer_publish_build.

Se você quer começar um jogo no Summer hoje, parta de um template que já tenha movimento e câmera configurados, descreva as mecânicas que você quer por cima e exporte uma build quando o jogo estiver bom de jogar.