Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
Exportando para a Web
Ver também
Esta página descreve como exportar um projeto Godot para HTML5. Se você deseja compilar o editor ou exportar binários de modelo do código-fonte, leia Compilando para Web.
A exportação HTML5 permite publicar jogos feitos no Godot Engine para o navegador. Isso requer suporte a WebAssembly e WebGL 2.0 no navegador do usuário.
Atenção
Projetos escritos em C# usando o Godot 4 atualmente não podem ser exportados para a web. Veja esta postagem no blog para mais informações.
To usar C# em plataformas web, use o Godot 3 em vez disso.
Dica
Use o console de desenvolvedor integrado ao navegador, normalmente aberto com F12 ou Ctrl + Shift + I (Cmd + Option + I no macOS), para visualizar informações de depuração, como erros de JavaScript, do motor e do WebGL.
Se o atalho não funcionar, é porque o Godot na verdade captura a entrada de dados. Você ainda pode abrir o console do desenvolvedor acessando o menu do navegador.
Nota
Devido a preocupações de segurança com o SharedArrayBuffer por conta de vários exploits, o uso de múltiplas threads para a plataforma Web possui várias desvantagens, incluindo a necessidade de cabeçalhos específicos do lado do servidor e isolamento completo de origem cruzada (cross-origin isolation - significando sem anúncios ou integrações de terceiros no site que hospeda seu jogo).
Desde o Godot 4.3, o Godot suporta a exportação do seu jogo em uma única thread, o que resolve esse problema. Embora tenha algumas desvantagens próprias (não pode usar threads e não é tão performático quanto a exportação multi-thread), não exige tanto processamento para instalar. Também é mais compatível no geral com lojas como o itch.io ou publicadoras Web como a Poki ou CrazyGames. A exportação em thread única funciona muito bem no macOS e iOS também, onde sempre houve problemas de compatibilidade com exportações de múltiplas threads.
Por esses motivos, esta é a forma preferida e agora padrão de exportar seus jogos para a Web.
Para mais informações, veja esta postagem no blog sobre exportação Web em thread única.
Ver também
Consulte a lista de problemas abertos no GitHub relacionados à exportação web para uma lista de bugs conhecidos.
Nome do arquivo exportado
Sugerimos aos usuários que exportem seus projetos Web com o nome de arquivo index.html. O index.html costuma ser o arquivo padrão carregado pelos servidores web ao acessar o diretório pai, geralmente ocultando o nome desse arquivo.
Atenção
The Godot 4 Web export expects some files to be named the same name as the one set in the initial export. Some issues could occur if some exported files are renamed, including the main HTML file.
Versão WebGL
O Godot 4 só pode ter como alvo o WebGL 2.0 (usando o método de renderização Compatibility). Forward+/Mobile não são suportados na plataforma web, pois esses métodos de renderização foram projetados em torno de APIs gráficas modernas de baixo nível. O Godot atualmente não suporta WebGPU, que é um pré-requisito para permitir que o Forward+/Mobile rodem na plataforma web.
Veja Can I use WebGL 2.0 para uma lista de versões de navegadores que suportam WebGL 2.0. Note que o Safari possui vários problemas com o suporte ao WebGL 2.0 que outros navegadores não têm, por isso recomendamos usar um navegador baseado no Chromium ou o Firefox, se possível.
Considerações para dispositivos móveis
A exportação Web pode rodar em plataformas móveis com algumas ressalvas. Embora as exportações nativas para Android e iOS sempre tenham um desempenho significativamente melhor, a exportação Web permite que as pessoas rodem seu projeto sem passar pelas lojas de aplicativos.
Lembre-se de que o desempenho da CPU e da GPU é limitado ao rodar em dispositivos móveis. Isso é ainda mais evidente ao rodar um projeto exportado para a Web (já que é WebAssembly em vez de código nativo). Veja a seção Desempenho da documentação para conselhos sobre como otimizar seu projeto. Se o seu projeto roda em outras plataformas além da Web, você pode usar Tags de funcionalidade para aplicar configurações voltadas para hardware de baixo custo ao rodar o projeto exportado para a Web.
Para acelerar os tempos de carregamento em dispositivos móveis, você também deve compilar um template de exportação otimizado com recursos não utilizados desativados. Dependendo dos recursos usados pelo seu projeto, isso pode reduzir significativamente o tamanho do payload do WebAssembly, tornando-o mais rápido para baixar e inicializar (mesmo quando armazenado em cache).
Reprodução de áudio
Desde o Godot 4.3, a reprodução de áudio é feita usando a Web Audio API na plataforma web. Este modo de reprodução Sample permite baixa latência mesmo quando o projeto é exportado sem suporte a threads, mas possui várias limitações:
AudioEffects (Efeitos de Áudio) não é suportado.
Efeitos de reverberação e doppler não são suportados.
A geração procedural de áudio não é suportada.
O áudio posicional pode nem sempre funcionar corretamente dependendo das propriedades do nó.
Para usar o próprio sistema de reprodução de áudio do Godot na plataforma web, você pode alterar o modo de reprodução padrão usando a configuração de projeto Audio > General > Default Playback Type.web, ou alterar a propriedade Playback Type para Stream em um nó AudioStreamPlayer, AudioStreamPlayer2D ou AudioStreamPlayer3D. Isso leva a um aumento na latência (especialmente quando o suporte a threads está desativado), mas permite que todo o conjunto de recursos de áudio do Godot funcione.
Opções de exportação
Se uma exportação executável web está disponível, um botão aparecerá entre os botões Pausar cena e Jogar Cena editada no editor para abrir o jogo rapidamente no seu navegador padrão para teste.
Se o seu projeto usa GDExtension, a opção Extension Support precisa estar ativada.
Se você planeja usar a compressão VRAM, certifique-se de que a VRAM Texture Compression esteja ativada para as plataformas alvo (ativar tanto For Desktop quanto For Mobile resultará em uma exportação maior, porém mais compatível).
Se um caminho para o arquivo Página HTML personalizado for especificado, ele será utilizado ao invés da página HTML padrão. Veja Personalizar página HTML para exportação Web.
Incluído no Cabeçalho é inserido no elemento <head> da página HTML gerada. Isso permite, por exemplo, carregar webfonts e APIs JavaScript, incluindo CSS, ou executar código JavaScript.
O tamanho da janela corresponderá automaticamente ao tamanho da janela do navegador por padrão. Se você quiser usar um tamanho fixo em vez disso, independentemente do tamanho da janela do navegador, altere a Canvas Resize Policy para None. Isso permite controlar o tamanho da janela com código JavaScript personalizado na shell HTML. Você também pode defini-la como Project para fazer com que se comporte de forma mais próxima a uma exportação nativa, de acordo com as configurações do projeto.
Importante
Cada projeto deve gerar seu próprio arquivo HTML. Na exportação, vários marcadores de posição de texto são substituídos no arquivo HTML gerado especificamente para as opções de exportação dadas. Quaisquer modificações diretas nesse arquivo HTML serão perdidas em exportações futuras. Para personalizar o arquivo gerado, use a opção Custom HTML shell.
Thread (Tópico) e suporte de extensões
Se o Thread Support estiver ativado, o projeto exportado poderá fazer uso de multithreading para melhorar o desempenho. Isso também permite a reprodução de áudio de baixa latência quando o tipo de reprodução está definido como Stream (em vez do padrão Sample que é usado em exportações web). A ativação deste recurso requer o uso de cabeçalhos de isolamento de origem cruzada (cross-origin isolation headers), que são descritos na seção Servindo os arquivos abaixo.
Se o Extensions Support estiver ativado, as GDExtensions poderão ser carregadas. Note que as GDExtensions ainda precisam ser compiladas especificamente para a plataforma web para funcionarem. Assim como o suporte a threads, a ativação deste recurso exige o uso de cabeçalhos de isolamento de origem cruzada (cross-origin isolation headers).
Exportando como um Aplicativo Web Progressivo (PWA)
Se o Progressive Web App > Enable estiver ativado, isso terá vários efeitos:
Configurar ícones de alta resolução, um modo de exibição e a orientação da tela. Estes são configurados no final da seção Progressive Web App nas opções de exportação. Essas opções são usadas se o usuário adicionar o projeto à tela inicial do seu dispositivo, o que é comum em plataformas móveis. Isso também é suportado em plataformas desktop, embora com uma capacidade mais limitada.
Permitir que o projeto seja carregado sem uma conexão com a Internet se ele tiver sido carregado pelo menos uma vez antes. Isso funciona graças ao service worker que é instalado quando o projeto é carregado pela primeira vez no navegador do usuário. Esse service worker fornece uma alternativa local quando nenhuma conexão com a Internet está disponível.
Note que os navegadores web podem optar por remover os dados em cache se o usuário ficar com pouco espaço em disco, ou se o usuário não abrir o projeto por um tempo. Para garantir que os dados fiquem em cache por mais tempo, o usuário pode favoritar a página ou, idealmente, adicioná-la à tela inicial do seu dispositivo.
Se os dados offline não estiverem disponíveis porque foram removidos do cache, você pode configurar uma Offline Page que será exibida nesse caso. A página deve estar no formato HTML e será salva na máquina do cliente na primeira vez que o projeto for carregado.
Garantir que os cabeçalhos de isolamento de origem cruzada estejam sempre presentes, mesmo que o servidor web não tenha sido configurado para enviá-los. Isso permite que as exportações com threads ativadas funcionem quando hospedadas em qualquer site, mesmo que não haja como você controlar os cabeçalhos que ele envia.
Esse comportamento pode ser desativado desmarcando Enable Cross Origin Isolation Headers na seção Progressive Web App.
Limitações
Por motivos de segurança e privacidade, muitas funcionalidades que funcionam sem problemas nas plataformas nativas são mais complicadas na plataforma web. A seguir há uma lista das limitações que se deve estar ciente quando for portar um game do Godot para a web.
Importante
Os fornecedores de navegadores estão tornando cada vez mais funcionalidades disponíveis apenas em contextos seguros, o que significa que tais recursos só estarão disponíveis se a página web for servida através de uma conexão HTTPS segura (o localhost geralmente é isento dessa exigência).
Processamento em segundo plano
O projeto será pausado pelo navegador quando a aba não for mais a aba ativa no navegador do usuário. Isso significa que funções como _process() e _physics_process() não rodarão mais até que a aba seja tornada ativa novamente pelo usuário (ao alternar de volta para a aba). Isso pode fazer com que jogos em rede se desconectem se o usuário alternar de abas por um longo período.
Essa limitação não se aplica a janelas do navegador desfocadas. Portanto, por parte do usuário, isso pode ser contornado executando o projeto em uma janela separada em vez de uma aba separada.
Tecla cheia e captura do mouse
Navegadores não permitem entrar em tela cheia livremente. O mesmo vale para capturar o cursor. Para isso, essas ações devem ocorrer como uma resposta para um evento de input no JavaScript. No Godot, isso significa entrar em tela cheia a partir de um evento de input como _input ou _unhandled_input. Acessar o singleton Input não é suficiente, o evento relevante precisa estar ativo no momento.
Pelo mesmo motivo, a opção de projeto de tela cheia não funciona a não ser que o motor seja iniciado a partir de um manipulador de evento de entrada válido. Isso requer uma personalização da página HTML.
Áudio
Alguns navegadores restringem a reprodução automática (autoplay) de áudio em sites. A maneira mais fácil de contornar essa limitação é pedir para o jogador clicar, tocar ou pressionar uma tecla/botão para ativar o áudio, por exemplo, ao exibir uma tela de carregamento (splash screen) no início do seu jogo.
Ver também
A Google oferece informações adicionais sobre suas políticas de reprodução automática do Web Audio.
A equipe do Safari da Apple também publicou informações adicionais sobre suas Mudanças na Política de Reprodução Automática para o macOS.
Aviso
O acesso ao microfone requer um contexto seguro.
Aviso
Since Godot 4.3, by default Web exports will use samples instead of streams to play audio.
Isso se deve à maneira como os navegadores preferem reproduzir áudio e à falta de poder de processamento disponível ao exportar jogos Web com a opção de exportação Use Threads desativada.
Por favor, note que os efeitos de áudio ainda não estão implementados para samples.
Redes
Redes de baixo nível não são implementadas devido à falta de suporte nos navegadores.
Atualmente, apenas cliente HTTP, requisições HTTP, WebSocket (cliente) e WebRTC são suportados.
As classes HTTP também possuem várias restrições na plataforma HTML5:
Não é possível acessar ou alterar o
StreamPeerO modo Threaded/Blocking não está disponível
Não pode progredir mais de uma vez por quadro, então a sondagem em loop irá congelar
Sem respostas fragmentadas
A verificação de host não pode ser desativada
Sujeito à política de mesma origem
Área de transferência
A sincronização da área de transferência entre a engine e o sistema operacional requer um navegador que suporte a Clipboard API, além disso, devido à natureza assíncrona da API, ela pode não ser confiável quando acessada a partir do GDScript.
Aviso
Requer um secure context.
Controles de jogo (Gamepads)
Os gamepads não serão detectados até que um de seus botões seja pressionado. Os gamepads podem ter o mapeamento incorreto dependendo da combinação de navegador/SO/gamepad; infelizmente, a Gamepad API não fornece uma maneira confiável de detectar as informações do gamepad necessárias para mapeá-los com base no modelo/fabricante/SO devido a considerações de privacidade.
Aviso
Requer um secure context.
Servindo os arquivos
Exportar para a web gera muitos arquivos que serão servidos a partir de um servidor web, incluindo uma página HTML padrão para apresentação. Um arquivo HTML personalizado pode ser usado, veja Personalizar página HTML para exportação Web.
Aviso
Only when exporting with Use Threads, to ensure low audio latency and the ability to use Thread in web exports, Godot 4 web exports use SharedArrayBuffer. This requires a secure context, while also requiring the following CORS headers to be set when serving the files:
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
Se você não controla o servidor web ou não consegue adicionar cabeçalhos de resposta, marque Progressive Web App > Enable nas opções de exportação. Isso aplica uma solução alternativa baseada em service worker que permite que o projeto seja executado simulando a presença desses cabeçalhos de resposta. Um contexto seguro ainda é necessário neste caso.
Se o cliente não receber os cabeçalhos de resposta exigidos ou se a solução alternativa baseada em service worker não for aplicada, o projeto não será executado.
O arquivo .html gerado pode ser usado como DirectoryIndex em servidores Apache e pode ser renomeado para, por exemplo, index.html a qualquer momento. Seu nome nunca é utilizado por padrão.
A página HTML desenha o jogo no tamanho máximo dentro da janela do navegador. Dessa forma, ela pode ser inserida em um <iframe> com o tamanho do jogo, como é comum na maioria dos sites de hospedagem de jogos web.
Os demais arquivos exportados são disponibilizados como estão, ao lado do arquivo .html, sem alteração nos nomes. O arquivo .wasm é um módulo binário WebAssembly que implementa a engine. O arquivo .pck é o pacote principal do Godot contendo o seu jogo. O arquivo .js contém o código de inicialização e é utilizado pelo arquivo .html para acessar a engine. O arquivo .png contém a imagem da tela de boot.
O arquivo .pck é binário, normalmente entregue com o tipo MIME application/octet-stream. O arquivo .wasm é entregue como application/wasm.
Aviso
Entregar o módulo WebAssembly (.wasm) com um tipo MIME diferente de application/wasm pode impedir algumas otimizações de inicialização.
Recomenda-se servir os arquivos com compressão no servidor, especialmente os arquivos .pck e .wasm, que geralmente são grandes. O módulo WebAssembly comprime particularmente bem, chegando a cerca de um quarto do tamanho original com compressão gzip. Considere usar pré-compressão Brotli, se suportada pelo seu servidor web, para reduzir ainda mais o tamanho dos arquivos.
Hospedagens que fornecem compressão em tempo de execução: GitHub Pages (gzip)
Hospedagens que não fornecem compressão em tempo de execução: itch.io, GitLab Pages (suporta pré-compressão manual em gzip)
Dica
O repositório do Godot inclui um script em Python para hospedar um servidor web local. Este script é destinado a testar o editor web, mas também pode ser usado para testar projetos exportados.
Salve o script vinculado em um arquivo chamado serve.py, mova este arquivo para a pasta que contém o index.html do projeto exportado e, em seguida, execute o seguinte comando em um prompt de comando dentro da mesma pasta:
# You may need to replace `python` with `python3` on some platforms.
python serve.py --root .
No Windows, você pode abrir um prompt de comando na pasta atual segurando Shift e clicando com o botão direito em um espaço vazio no Windows Explorer, escolhendo então Abrir janela do PowerShell aqui.
Isso servirá o conteúdo da pasta atual e abrirá o navegador web padrão automaticamente.
Note que para casos de uso em produção, este servidor web baseado em Python não deve ser usado. Em vez disso, você deve usar um servidor web estabelecido, como o Apache ou o nginx.
Interagindo com o navegador e JavaScript
Veja a página dedicada sobre como interagir com o JavaScript e acessar alguns recursos exclusivos do navegador Web.
Variáveis de ambiente
Você pode usar as seguintes variáveis de ambiente para definir opções de exportação fora do editor. Durante o processo de exportação, elas substituem os valores que você definiu no menu de exportação.
Opção de exportação |
Variável de ambiente |
|---|---|
Encryption / Encryption Key (Criptografia / Chave de Criptografia) |
|
Solução de problemas
Executar a exportação localmente mostra outro projeto em vez do atual
Se você usa a implantação com um clique (one-click deploy) em múltiplos projetos, você pode notar que um dos projetos que você implantou anteriormente é exibido em vez do projeto no qual está trabalhando atualmente. Isso se deve ao cache do service worker, que atualmente carece de um mecanismo automatizado de invalidação de cache.
Como uma solução alternativa, você pode desregistrar manualmente o service worker atual para que o cache seja redefinido. Isso também permite que um novo service worker seja registrado. Em navegadores baseados no Chromium, abra as Ferramentas do Desenvolvedor pressionando F12 ou Ctrl + Shift + I (Cmd + Option + I no macOS), depois clique na aba Application no DevTools (pode estar escondida atrás de um ícone de chevron se o painel do devtools for estreito). Você pode marcar e recarregar a página, ou clicar em ao lado do service worker que está registrado atualmente e recarregar a página.
Desregistrando o service worker no DevTools de navegadores baseados no Chromium
O procedimento é semelhante no Firefox. Abra as ferramentas de desenvolvedor pressionando F12 ou Ctrl + Shift + I (Cmd + Option + I no macOS), clique na aba Application no DevTools (pode estar escondida atrás de um ícone de chevron se o painel do devtools for estreito). Clique em ao lado do service worker que está registrado atualmente e recarregue a página.
Desregistrando o service worker no DevTools do Firefox
Opções de exportação
Você pode encontrar uma lista completa das opções de exportação disponíveis na referência da classe EditorExportPlatformWeb.