Unity na web:
da página ao motor
e de volta

Esta apostila trata de experiências interativas dentro de páginas web: configuradores de produto, visualizadores 3D em sites de marca, demonstrações de produto, mini-jogos promocionais, visualizações de dados em 3D, simuladores embutidos em portais. O denominador comum é que o Unity não é a página — é uma peça dentro dela, que precisa conversar com o resto.

1.1 As alternativas que você precisa conhecer

Para aprofundar as alternativas, veja Computação Gráfica com Three.js e 3D em Tempo Real e Motion Graphics na Web.

1.2 A pergunta que decide

O que você perderia se reescrevesse isto em Three.js?

Se a resposta for "quase nada" (um modelo girando, trocar cor, algumas anotações), use a alternativa web: vai carregar mais rápido, pesar menos no celular e ser mais fácil de indexar e tornar acessível. Se a resposta for "a física, o sistema de interação, seis meses de trabalho já feito em Unity, e a versão mobile e desktop do mesmo produto", o Unity se paga.

2.1 O que sai do build

No Unity 6 a plataforma chama-se Web (antes, WebGL). Um build produz uma pasta com o index.html do template e uma subpasta Build/ com quatro arquivos principais:

2.2 O único ponto de entrada

<canvas id="unity-canvas" tabindex="-1"></canvas>
<script src="Build/app.loader.js"></script>
<script>
  createUnityInstance(document.querySelector("#unity-canvas"), {
    dataUrl:      "Build/app.data",
    frameworkUrl: "Build/app.framework.js",
    codeUrl:      "Build/app.wasm",
    companyName:  "Uniana",
    productName:  "Configurador",
    productVersion: "1.0",
  }, (progresso) => {
    barra.style.width = (progresso * 100) + "%";   // 0 a 1
  }).then((unityInstance) => {
    window.unityInstance = unityInstance;           // guarde: é por aqui que se fala com o motor
  }).catch((erro) => {
    mostrarErro(erro);                              // navegador sem suporte, falta de memória…
  });
</script>

createUnityInstance devolve uma promise que resolve com a instância. Tudo o que a página faz com o motor passa por esse objeto: SendMessage (cap. 3), SetFullscreen (cap. 6) e Quit (cap. 5).

2.3 Templates

O index.html gerado vem de um template. Os embutidos (Default, Minimal, PWA) servem para testar; para produção, crie o seu em Assets/WebGLTemplates/NomeDoTemplate/index.html e escolha-o nas Player Settings. O template aceita variáveis que o Unity substitui no build, como {{{ LOADER_FILENAME }}}, {{{ DATA_FILENAME }}} e {{{ PRODUCT_NAME }}} — assim o nome dos arquivos não fica escrito à mão.

Mas numa integração real você frequentemente não usa o index.html do Unity: copia a pasta Build/ para o site e chama createUnityInstance a partir da sua própria página ou componente (cap. 5). O template passa a ser só o ambiente de teste.

3.1 SendMessage

// JavaScript, na página
unityInstance.SendMessage("Ponte", "TrocarCor", "#C0392B");

// C#, num componente do GameObject chamado "Ponte"
public class Ponte : MonoBehaviour
{
    [SerializeField] Configurador configurador;

    // chamado pela página — público, um parâmetro (string, int ou float) ou nenhum
    public void TrocarCor(string hex)
    {
        if (ColorUtility.TryParseHtmlString(hex, out var cor))
            configurador.AplicarCor(cor);
    }
}

Três regras: o nome do GameObject tem de existir na cena e ser único (é procurado por nome); o método tem de ser público e aceitar no máximo um parâmetro, do tipo string ou número; e não há valor de retorno — se a página precisa de uma resposta, o Unity responde pelo caminho inverso (cap. 4).

3.2 Um só objeto, um contrato em JSON

Espalhar SendMessage para vinte objetos diferentes acopla a página à hierarquia da cena: renomeou um objeto, a página quebra em silêncio. Melhor: um único GameObject "Ponte", persistente, com poucos métodos que recebem JSON, e que distribui internamente. O contrato fica documentado num lugar só.

// JavaScript
function enviar(comando, dados) {
  unityInstance.SendMessage("Ponte", "Receber",
    JSON.stringify({ v: 1, comando, dados }));
}
enviar("trocarCor", { peca: "porta", cor: "#C0392B" });

// C#
[System.Serializable] class Mensagem { public int v; public string comando; public string dados; }
public void Receber(string json) { /* desserializa e despacha por 'comando' */ }

O campo v (versão do contrato) parece excessivo até o dia em que o site e o build são publicados em momentos diferentes e um lado passa a mandar um formato que o outro não conhece.

3.3 A mensagem antes do motor estar pronto

O erro mais frequente: a página chama SendMessage antes de createUnityInstance resolver, ou antes de a cena com o objeto "Ponte" ter carregado. A mensagem se perde. Solução: uma fila na página que acumula comandos até o Unity avisar que está pronto (o aviso vem pelo cap. 4), e só então os despacha.

const fila = []; let pronto = false;
function enviar(comando, dados) {
  const msg = JSON.stringify({ v: 1, comando, dados });
  if (pronto) unityInstance.SendMessage("Ponte", "Receber", msg);
  else fila.push(msg);
}
window.unityPronto = function () {
  pronto = true;
  fila.splice(0).forEach(m => unityInstance.SendMessage("Ponte", "Receber", m));
};

4.1 O caminho de um clique, ida e volta

Role o bloco abaixo: o painel escuro acompanha cada etapa de uma interação completa — o visitante clica num botão HTML, a peça muda no 3D, e o painel HTML mostra o novo preço.

4.2 O plugin .jslib

// Assets/Plugins/WebGL/Ponte.jslib
mergeInto(LibraryManager.library, {

  PonteEmitir: function (nomePtr, jsonPtr) {
    var nome = UTF8ToString(nomePtr);          // ponteiro de memória → string JS
    var dados = JSON.parse(UTF8ToString(jsonPtr));
    window.dispatchEvent(new CustomEvent("unity:" + nome, { detail: dados }));
  },

  PonteLerQuery: function (chavePtr) {        // devolver uma string ao C#
    var valor = new URLSearchParams(location.search).get(UTF8ToString(chavePtr)) || "";
    var tamanho = lengthBytesUTF8(valor) + 1;
    var buffer = _malloc(tamanho);
    stringToUTF8(valor, buffer, tamanho);
    return buffer;                              // o runtime converte e libera
  }
});

// C#
using System.Runtime.InteropServices;

public static class PonteWeb
{
#if UNITY_WEBGL && !UNITY_EDITOR
    [DllImport("__Internal")] static extern void PonteEmitir(string nome, string json);
    [DllImport("__Internal")] static extern string PonteLerQuery(string chave);
#else
    static void PonteEmitir(string nome, string json) => UnityEngine.Debug.Log($"[web] {nome}: {json}");
    static string PonteLerQuery(string chave) => "";
#endif
    public static void Emitir(string nome, object dados) =>
        PonteEmitir(nome, UnityEngine.JsonUtility.ToJson(dados));
    public static string LerQuery(string chave) => PonteLerQuery(chave);
}

// JavaScript, na página
window.addEventListener("unity:precoMudou", (e) => {
  document.querySelector("#preco").textContent =
    e.detail.total.toLocaleString("pt-BR", { style: "currency", currency: "BRL" });
});

5.1 A biblioteca react-unity-webgl

O pacote comunitário react-unity-webgl envolve o loader num hook e num componente, com estado de carregamento, envio de mensagens e escuta de eventos:

import { Unity, useUnityContext } from "react-unity-webgl";

export default function Configurador() {
  const { unityProvider, isLoaded, loadingProgression, sendMessage,
          addEventListener, removeEventListener } = useUnityContext({
    loaderUrl:    "/unity/Build/app.loader.js",
    dataUrl:      "/unity/Build/app.data",
    frameworkUrl: "/unity/Build/app.framework.js",
    codeUrl:      "/unity/Build/app.wasm",
  });

  useEffect(() => {
    const aoMudarPreco = (json) => setPreco(JSON.parse(json).total);
    addEventListener("precoMudou", aoMudarPreco);
    return () => removeEventListener("precoMudou", aoMudarPreco);
  }, [addEventListener, removeEventListener]);

  return (<>
    {!isLoaded && <Progresso valor={loadingProgression} />}
    <Unity unityProvider={unityProvider} style={{ width: "100%", aspectRatio: "16/9" }} />
    <button onClick={() => sendMessage("Ponte", "Receber", JSON.stringify({ v:1, comando:"trocarCor", dados:{ cor:"#C0392B" } }))}>
      Vermelho
    </button>
  </>);
}

Para o sentido Unity → React, a biblioteca usa um despachante próprio chamado a partir do .jslib (dispatchReactUnityEvent), em vez do CustomEvent do cap. 4. Os dois modelos são equivalentes; escolha um e seja consistente. Confira a documentação da versão que instalar — a API mudou entre versões principais.

5.2 Next.js: só no cliente

• O Unity precisa de window, canvas e WebAssembly: nunca renderiza no servidor. Marque o componente com "use client" e carregue-o com dynamic(() => import("./Configurador"), { ssr: false }).
• Coloque a pasta Build/ em public/ (ou numa CDN) e confira os cabeçalhos de compressão no servidor ou na plataforma de hospedagem — um arquivo .br servido sem Content-Encoding é a falha mais comum depois do deploy.
• Mais sobre o framework em Next.js.

5.3 Desmontar sem vazar

6.1 Tamanho: o CSS decide

Por padrão (matchWebGLToCanvasSize: true), o Unity ajusta a resolução de renderização ao tamanho do canvas na página. Portanto, o layout é assunto do CSS: largura 100%, aspect-ratio para manter a proporção, e o Unity acompanha. No C#, Screen.width e Screen.height refletem esse tamanho — use-os, e não valores fixos, para posicionar UI.

6.2 Densidade de pixels: o custo escondido

O aparelho que tem a GPU mais fraca (o celular) é o que pede mais pixels. A configuração devicePixelRatio no objeto passado a createUnityInstance permite limitar:

const dpr = Math.min(window.devicePixelRatio || 1, 1.5);
createUnityInstance(canvas, { ...config, devicePixelRatio: dpr });

A diferença visual entre 1,5 e 3 num celular é pequena; a diferença de desempenho e aquecimento, não.

6.3 Tela cheia

unityInstance.SetFullscreen(1) coloca o canvas em tela cheia — mas navegadores só permitem isso em resposta a um gesto do usuário (clique, toque). Chamado a partir de um temporizador ou logo no carregamento, é ignorado. Ligue-o a um botão. No iPhone, o suporte a tela cheia de elementos é limitado; ofereça um layout que ocupe a viewport inteira como alternativa.

7.1 O teclado roubado

Por padrão o build Web captura o teclado da página inteira — e o campo de busca, o formulário de contato e o chat do site deixam de receber teclas. A correção fica no C#:

#if UNITY_WEBGL && !UNITY_EDITOR
    WebGLInput.captureAllKeyboardInput = false;   // o Unity só recebe teclas quando o canvas tem foco
#endif

Com isso, o canvas precisa de foco para receber teclado: dê-lhe tabindex e deixe o foco visível, para que quem navega por teclado saiba onde está.

7.2 A rolagem sequestrada

Se o Unity usa a roda do mouse para zoom, o visitante que só queria rolar a página fica "preso" no canvas. Padrões que funcionam: zoom só com Ctrl/⌘ + roda, ou só depois de um clique que "ativa" o 3D; e botões de zoom na interface. No toque, o mesmo dilema com o gesto de arrastar: o arrastar com um dedo rola a página e o de dois dedos gira o modelo, ou há um modo de interação explícito. Não existe resposta universal — mas "o canvas captura tudo" quase nunca é a certa numa página com conteúdo abaixo dele.

7.3 Gestos obrigatórios

7.4 Teclado virtual no celular

Campos de texto dentro do Unity não abrem o teclado do celular sozinhos; há suporte (WebGLInput.mobileKeyboardSupport), mas a experiência é inferior à de um <input> HTML. Para qualquer coisa além de uma palavra — nome, e-mail, observações — use um campo HTML sobreposto ou fora do canvas e envie o valor pela ponte.

8.1 O que mudou

Versões anteriores exibiam um aviso de que navegadores móveis não eram suportados. As versões recentes suportam oficialmente o navegador do celular — o que não significa que qualquer projeto de desktop rode bem nele. A restrição dominante passa a ser a memória que a aba pode usar, especialmente no Safari do iOS, que encerra abas que passam do limite sem aviso ao usuário além de um recarregamento.

8.2 As alavancas

• Memória do WebAssembly: as Player Settings controlam o tamanho inicial e máximo da memória (heap). Um máximo generoso demais pode falhar a alocação no celular; um inicial pequeno com crescimento gradual costuma ser mais seguro.
• Formato de textura: desktops usam formatos DXT/BC; celulares, ASTC ou ETC2. Uma textura num formato que a GPU não suporta é descomprimida pelo navegador e ocupa várias vezes mais memória. Gere o build com o formato do público principal, ou builds diferentes para desktop e mobile servidos conforme o aparelho.
• Menos coisa carregada ao mesmo tempo: Addressables e carregamento por partes — detalhados em Serious Games na Web, cap. 8.
• Uma instância por página (cap. 5.3) — duas instâncias raramente cabem num celular.

9.1 O que o WebGPU traz

9.2 No Unity

O Unity 6 inclui um backend gráfico WebGPU, marcado como experimental/acesso antecipado à data desta apostila. Ele abre a porta a recursos que dependem de compute shaders (como o VFX Graph na GPU) em builds Web. A estratégia sensata hoje: WebGPU com fallback para WebGL 2 — as Player Settings permitem listar as APIs gráficas por ordem de preferência — e testar os dois caminhos, porque o visitante com navegador sem WebGPU verá a versão WebGL.

async function temWebGPU() {
  if (!("gpu" in navigator)) return false;
  try { return !!(await navigator.gpu.requestAdapter()); }
  catch { return false; }
}

10.1 O que o canvas esconde

O conteúdo desenhado no canvas não existe no DOM: não é lido por leitores de tela, não é indexado, não é traduzível pelo navegador, não aceita "buscar na página". Por isso, a arquitetura recomendada no cap. 4 — controles e informação em HTML, só o 3D no canvas — não é só conveniência: é o que torna a experiência acessível e encontrável.

10.2 Práticas

• Nomeie a região: o contêiner do canvas com role="region" e um aria-label ("Visualizador 3D do sofá, girável").
• Anuncie mudanças: um elemento com aria-live="polite", atualizado pela página quando o Unity emite eventos ("Cor alterada para vermelho. Preço: R$ 4.290").
• Tudo operável sem o 3D: toda escolha feita arrastando no canvas precisa de um equivalente em controle HTML.
• Movimento reduzido: leia matchMedia("(prefers-reduced-motion: reduce)") na página e envie ao Unity pela ponte, para desligar rotação automática e animações de câmera.
• Alternativa sem WebGL: se o carregamento falhar, mostre imagens do produto e o conteúdo em HTML — nunca uma área vazia.
• Busca e compartilhamento: título, descrição, texto do produto e imagem de pré-visualização vivem no HTML; o 3D é um complemento.

Critérios de acessibilidade em detalhe estão na apostila de Acessibilidade (WCAG).

11.1 Eventos de analytics pela ponte

O Unity não precisa de um SDK de analytics próprio: emite eventos pela ponte e a página os entrega à ferramenta que o site já usa.

window.addEventListener("unity:analytics", (e) => {
  if (typeof gtag === "function")
    gtag("event", e.detail.nome, e.detail.params);   // respeita o modo de consentimento já configurado no site
});

Eventos que valem ouro: unity_carregamento_inicio, unity_pronto (com o tempo decorrido), unity_erro, e as ações de negócio (config_cor, config_concluida). A diferença entre quem começou a carregar e quem chegou a unity_pronto é a métrica mais honesta sobre o custo do Unity na página.

11.2 Depurar

• Debug.Log vai para o console do navegador. Em builds de desenvolvimento, as mensagens vêm com pilha de chamadas mais legível.
• Development Build + Autoconnect Profiler permite ligar o Profiler do editor ao build rodando no navegador.
• O painel de memória e de desempenho das ferramentas de desenvolvedor do navegador mostra o que o Profiler do Unity não vê: o tempo de download e compilação, o JavaScript da página, o layout.

11.3 Erros em produção

Capture as falhas no catch de createUnityInstance, em window.onerror e pelo evento unity:erro emitido a partir de Application.logMessageReceived no C# (filtrando por exceções), e envie a um serviço de monitoramento. As causas mais comuns, em ordem: falta de memória em celular, navegador sem WebGL 2 ou com GPU bloqueada, arquivos comprimidos mal servidos após um deploy, e versões misturadas de arquivos em cache (cap. 2).

12.1 O roteiro

12.2 Checklist de publicação

12.3 Projetos de portfólio

1. Configurador completo seguindo o roteiro acima, com um README mostrando o funil e o tempo de carga medido em celular.
2. O mesmo produto em Unity e em Three.js, com comparação medida (tamanho, tempo até interativo, memória no celular) e a sua recomendação — mostra que você sabe escolher, não só executar.
3. Componente React reutilizável que encapsula loader, fila, eventos e desmontagem segura, publicado como pacote ou repositório.
4. Visualização de dados em 3D alimentada por uma API, com os controles e a tabela de dados em HTML acessível.

12.4 Fontes para continuar

• Manual do Unity, secção da plataforma Web: interação com o navegador (.jslib, SendMessage), templates, configurações de memória, WebGPU.
• react-unity-webgl: documentação da versão que for usar.
• MDN: WebAssembly, Canvas, WebGPU, políticas de autoplay e Fullscreen API.
• Na Uniana: Serious Games na Web (tamanho e carregamento), Unity para Aplicações, WebGPU, Three.js.