Como Exportar um Jogo Godot para a Web (Guia HTML5, 2026)

O Godot exporta para a web como HTML5 e WebAssembly, o que significa que seu jogo roda em uma aba do navegador sem download e sem plugin. Essa e a forma mais rapida de colocar uma build jogavel na frente de alguem: voce manda o link, a pessoa clica e ja esta jogando.

O problema e que "exportar para a web" sao dois trabalhos, nao um. Gerar os arquivos e facil e leva cerca de um minuto. Fazer esses arquivos funcionarem de verdade no navegador e onde quase todo mundo se depara com uma tela preta, porque os navegadores modernos exigem dois headers HTTP especificos dos quais a build WebAssembly com threads depende. Este guia cobre as duas partes, as configuracoes exatas e os tres erros responsaveis pela maioria das exportacoes que falham.

Ele se aplica ao Godot 4 e ao Summer Engine, que e compativel com o Godot 4 e usa o mesmo pipeline de exportacao. Se voce construiu seu jogo descrevendo-o em linguagem natural, a etapa de exportacao e identica a de um projeto Godot codificado manualmente.

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

O que a "exportacao web" produz de fato

Quando voce exporta, o Godot nao cria um unico arquivo. Ele gera uma pequena pasta de assets estaticos:

• index.html e a pagina que carrega tudo. E o que o navegador abre.
• Um arquivo .wasm e o proprio engine Godot, compilado para WebAssembly. Esse e o maior componente.
• Um arquivo .pck e o pacote de dados do seu jogo: cenas, scripts e assets compactados.
• Um arquivo .js e o codigo de carregamento que conecta o engine a pagina.
• Frequentemente tambem um .worker.js e um .audio.worklet.js para threading e audio.

Todos esses arquivos precisam estar juntos e ser servidos via HTTP. Voce nao pode dar um duplo clique no index.html esperando que funcione, e esse e o primeiro tropeço que pega muita gente. Vamos voltar a isso em breve.

Etapa 1: Instale os templates de exportacao

O Godot distribui o editor e os templates de exportacao separadamente. Os templates sao os binarios pre-compilados do engine para cada plataforma, incluindo a build WebAssembly para o navegador. Uma instalacao nova nao os inclui.

Va em Editor e depois Gerenciar Templates de Exportacao e clique em Baixar e Instalar. Isso busca os templates para a versao exata do seu engine.

Esta e a regra mais importante de todo o processo: os templates precisam corresponder exatamente a versao do seu engine. Templates para a 4.3 nao vao rodar um projeto exportado da 4.4. Uma incompatibilidade de versao e a segunda causa mais comum de uma build web quebrada, logo atras dos headers. Se voce atualizar o engine, reinstale os templates.

Etapa 2: Adicione um preset de exportacao Web

Abra Projeto e depois Exportar. Clique em Adicionar e escolha Web.

Um painel de opcoes aparece. Os valores padrao sao razoaveis, mas duas configuracoes importam especificamente para a web:

• Tipo de Exportacao. "Regular" gera a build com threads, que e mais rapida e o padrao. Antes havia uma opcao sem threads para hosts que nao conseguiam enviar os headers especiais. No Godot 4 voce quase sempre vai querer a build com threads e corrigir os headers no lado do host, o que cobrimos abaixo.
• Compressao de Texturas VRAM. Marque a opcao para os alvos que voce precisa. O navegador usa o caminho "Para Desktop" na maioria das maquinas, entao deixe essa ativada. Navegadores moveis podem precisar da opcao de compressao mobile tambem.

Deixe o Head Include e o shell HTML personalizado em branco a menos que tenha um motivo para muda-los. O shell padrao cuida do carregamento e da barra de progresso para voce.

Etapa 3: Exporte o projeto

Escolha uma pasta de destino. Crie uma vazia chamada algo como web-build para que os arquivos de saida nao se misturem com nada mais.

Nomeie o arquivo principal como index.html, nao com o nome do seu jogo. A maioria dos hosts, incluindo o itch.io, procura um index.html como ponto de entrada. Se voce nomeiar como myjogo.html, o host nao vai encontrar e voce vera uma listagem de diretorio em branco em vez do seu jogo.

Clique em Exportar Projeto. Em alguns segundos a pasta se preenche com os arquivos listados anteriormente. Essa e a parte facil concluida.

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

Etapa 4: O problema dos headers, explicado de forma direta

Esta e a parte que nenhum tutorial rapido menciona, e a razao pela qual a maioria das primeiras exportacoes web mostra uma tela preta.

A build com threads do Godot 4 usa o SharedArrayBuffer, um recurso do navegador que permite ao engine WebAssembly rodar em multiplas threads. Por razoes de seguranca, os navegadores so ativam o SharedArrayBuffer quando a pagina e servida com dois headers de resposta HTTP especificos:

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

Esses dois headers colocam a pagina no que os navegadores chamam de estado "cross origin isolated". Sem eles, o SharedArrayBuffer fica indefinido, o engine nao consegue iniciar suas threads e voce recebe um canvas preto e um erro no console mencionando SharedArrayBuffer is not defined ou crossOriginIsolated is false.

Voce nao define esses headers no Godot. Voce os define no que quer que sirva os arquivos. Esse e o segredo todo. Tres consequencias disso:

1. Abrir o index.html do seu disco rigido nunca vai funcionar, porque nao ha servidor para enviar os headers.
2. Um host que nao consegue enviar headers personalizados (o GitHub Pages simples, por exemplo) nao consegue rodar a build com threads como esta.
3. Um host que os envia automaticamente (itch.io com o toggle certo) simplesmente funciona.

Etapa 5: Teste localmente antes de fazer o upload

Nunca depure uma exportacao web fazendo upload e atualizando a pagina. Teste na sua propria maquina primeiro com um servidor local que defina os headers.

A opcao mais rapida, se voce tiver o Python instalado, e um pequeno script que serve a pasta com ambos os headers. Salve isso como serve.py dentro da sua pasta web-build:

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 exportacao esta correta e qualquer problema restante e uma questao de configuracao do host, nao do Godot.

Se preferir nao escrever um script, a opcao Remote Debug no editor do Godot (o menu suspenso ao lado do botao de play, "Run in Browser") sobe um servidor local corretamente configurado e abre a build. Esse e o teste mais rapido durante o desenvolvimento.

Etapa 6: Hospede o jogo

itch.io (mais facil, gratis)

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

1. Compacte toda a pasta web-build em um zip. Compacte o conteudo, nao a pasta pai, para que o index.html fique no nivel raiz do zip.
2. No itch.io, crie um novo projeto e defina Tipo de projeto como HTML.
3. Faca o upload do zip e marque Este arquivo sera jogado no navegador.
4. Nas opcoes de embed, defina um tamanho de viewport que corresponda a resolucao do seu jogo e marque Suporte a SharedArrayBuffer se o itch oferecer essa opcao (ele define os dois headers por voce).

O itch.io cuida dos headers automaticamente, e por isso e o caminho mais direto. Se o jogo funciona localmente com o script acima mas nao no itch, o toggle do SharedArrayBuffer e quase sempre o que esta faltando.

Netlify, Vercel ou seu proprio servidor

Esses hosts permitem definir headers personalizados, entao a build com threads funciona bem apos a configuracao.

No Netlify, adicione um arquivo _headers na raiz do deploy:

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

No Vercel, defina os mesmos dois headers em vercel.json dentro de uma regra headers. No seu proprio servidor nginx ou Apache, adicione-os ao bloco de location. O principio e identico em todos os casos: envie esses dois headers para a pagina e os assets.

GitHub Pages

O GitHub Pages simples nao consegue enviar headers personalizados, entao a build com threads nao vai funcionar la diretamente. As pessoas contornam isso com um pequeno service worker que injeta os headers no lado do cliente (a abordagem "coi-serviceworker" e a mais comum), mas e uma solucao alternativa e nem todo navegador a respeita. Se o GitHub Pages for uma exigencia, espere precisar adicionar esse recurso alternativo. Caso contrario, use o itch.io ou o Netlify e evite o trabalho extra.

Corrigindo a tela preta: checklist de tres perguntas

Se voce ver um canvas preto, abra o console de desenvolvedor do navegador (pressione F12 e va para a aba Console) e leia o primeiro erro em vermelho. Ele vai corresponder a uma de tres causas.

1. Voce abriu o arquivo diretamente? Se o URL comecar com file://, esse e o problema. Sirva-o via HTTP com o script local descrito acima.
2. O erro menciona SharedArrayBuffer ou crossOriginIsolated? Os headers estao ausentes. Adicione-os no host ou ative o toggle de SharedArrayBuffer no itch.io.
3. O erro menciona versao ou falha no carregamento de templates? Seus templates de exportacao nao correspondem a versao do engine. Reinstale-os via Gerenciar Templates de Exportacao.

Noventa por cento das exportacoes web que falham se enquadram em um desses tres casos. Passe por eles em ordem antes de presumir que seu jogo tem um problema mais profundo.

O que nao funciona no navegador

A exportacao web e real, mas nao e o desktop com um URL. Algumas coisas se comportam de forma diferente:

• O acesso ao sistema de arquivos e isolado por sandbox. Os dados salvos vao para o IndexedDB do navegador, nao para uma pasta no disco. Planeje seu sistema de save em torno disso se a web for seu alvo.
• Plugins nativos (bibliotecas GDExtension compiladas para desktop) geralmente nao funcionam no navegador. Qualquer coisa que vincule um .dll ou .so nativo precisa de uma alternativa compativel com a web ou precisa ser removida para a build web.
• O tamanho do carregamento importa mais do que em qualquer outro lugar. Na web o jogador baixa o engine, o pacote de dados e todos os assets antes do jogo comecar. Comprima texturas, remova assets nao utilizados e mantenha o escopo 3D realista se a web for seu canal principal. Um jogo 3D pesado pode ter um primeiro carregamento de 30 a 100 MB, o que e doloroso em dados moveis.
• A latencia de audio e levemente maior no navegador do que no desktop. Geralmente nao e um problema, mas pode ser perceptivel em jogos com timing musical preciso.

Se voce construiu o jogo com o Summer Engine

As etapas de exportacao acima sao identicas, porque o Summer Engine e compativel com o Godot 4 e usa o mesmo pipeline HTML5 e WebAssembly. A diferenca esta na etapa anterior, em como o jogo e construido. Em vez de escrever manualmente o controlador do jogador, a configuracao das cenas e a logica do jogo, voce descreve o que quer em linguagem natural e a IA constroi tudo. Quando estiver pronto para compartilhar, voce exporta para a web exatamente como descrito aqui.

A exportacao web faz parte do plano gratuito. Construir e exportar sao gratuitos, e o plano pago cobre apenas maior uso de IA e recursos para times, entao o ciclo completo de ideia a link jogavel nao custa nada para experimentar.

Se voce ainda nao comecou um projeto, o caminho mais rapido para uma build pronta para a web e comecar de um template que ja tem movimentacao e camera configurados, descrever as mecanicas que voce quer adicionar e seguir as seis etapas acima para colocar o jogo no navegador. O ciclo completo, de projeto em branco a um link jogavel no itch.io, cabe em uma tarde.