Serious games na web:
do build leve
ao dado de aprendizagem

Este guia trata de um fluxo específico e muito comum em educação corporativa, escolas, saúde e treinamento técnico: um jogo feito em Unity, publicado como build Web, entregue por um LMS (ou por um link) e capaz de devolver dados sobre o que o jogador fez. Cada elo desse fluxo tem armadilhas próprias, e a maioria delas só aparece quando o jogo já está pronto.

1.1 O que é um serious game

O termo vem de Clark Abt, que em Serious Games (1970) descreveu jogos com finalidade educacional explícita e cuidadosa, e não apenas de entretenimento. Michael & Chen (2005) popularizaram a expressão para jogos digitais que educam, treinam e informam. A fronteira com termos vizinhos costuma confundir:

Se você quer aprofundar a diferença entre essas categorias, veja Gamification. Aqui o foco é técnico: colocar o jogo no ar e medir.

1.2 Por que publicar na web

1.3 O fluxo completo, do editor ao dado

2.1 WebGL, WebAssembly e o nome da plataforma

A build Web da Unity roda no navegador combinando duas tecnologias: WebGL 2 (a API gráfica do navegador) e WebAssembly (o código do seu jogo e do motor, compilado via IL2CPP para um binário compacto). Nas versões mais antigas a plataforma se chamava WebGL; no Unity 6 ela aparece como Web, nos Build Profiles. Neste guia, "build Web" e "build WebGL" significam a mesma coisa. Os nomes exatos de menus e opções mudam entre versões: use este texto como mapa e confirme na documentação da sua versão.

2.2 O que sai da pasta Build

Com compressão ligada (cap. 7), os arquivos da pasta Build ganham sufixo .gz ou .br. O servidor precisa então avisar o navegador de que estão comprimidos, o que é a causa mais frequente de "a build não abre depois de publicar".

2.3 O que muda em relação ao desktop

3.1 Os cinco estágios

Do clique no link até o primeiro frame jogável, acontece sempre a mesma sequência. Role o bloco abaixo: o painel escuro fica fixo e destaca o estágio que cada cartão descreve.

3.2 Uma tabela de remédios

3.3 Como medir de verdade

• Aba Network do DevTools (com "Disable cache" ligado): mostra o tamanho transferido de cada arquivo, o cabeçalho Content-Encoding e o tempo. Use um perfil de rede lenta para simular escola ou celular.
• Aba Performance: grava a carga inteira e mostra a compilação do WebAssembly e o trabalho da CPU.
• Aba Application → IndexedDB: confirma se o caching de dados está guardando algo.
• Marcos próprios: registre performance.now() quando a instância termina de criar e quando a primeira tela interativa aparece. O que interessa ao aluno é o tempo até poder jogar, não o tempo até o download acabar.

4.1 Da rede do aluno ao orçamento

A conta do estágio de download é simples: segundos ≈ megabytes × 8 ÷ megabits por segundo. Ela ignora descompressão e compilação, então é um piso, não uma previsão. Use a calculadora para testar o tamanho da sua build contra conexões típicas.

4.2 Faixas de orçamento (uma sugestão de partida)

Não existe um limite oficial. As faixas abaixo são um ponto de partida para a primeira jogada, e você deve ajustá-las com a ficha do exercício 1.2:

4.3 O peso do "vazio"

Uma medição pública de Aras Pranckevičius (engenheiro da Unity) num projeto vazio do Unity 6 mostra a ordem de grandeza do que o motor sozinho custa: o template 3D com URP passou de 10 MB comprimidos (cerca de 3,7 MB de dados e 6,9 MB de código), enquanto o mesmo tipo de projeto, com Built-in, código otimizado, exceções desligadas, sem Input System nem Unity UI e com a compressão Brotli, ficou em torno de 2 MB. O que mais pesou na redução foi remover pacotes que puxam código de motor mesmo sem uso. Os números mudam a cada versão; o aprendizado é que o "vazio" já pode consumir a maior parte do seu orçamento se você aceitar os padrões.

4.4 Como ver o que pesa

• Build Report no Editor.log: depois de cada build, o log do Editor traz um relatório com o tamanho por categoria (texturas, malhas, áudio, shaders, scripts, DLLs incluídas) e os maiores assets. É o primeiro lugar a olhar.
• Pasta Build: compare o tamanho dos arquivos comprimidos, que é o que trafega. O tamanho no Editor.log é antes da compressão do transporte.
• Web Stripping Tool e análise do wasm: ferramentas da Unity para enxergar o quanto do motor está entrando (cap. 5).

# tamanhos dos arquivos comprimidos que realmente trafegam
cd Builds/Web/Build
ls -lh
du -sh .

4.5 O hábito: diário de builds

Mude uma coisa por vez e registre o resultado. Uma planilha de cinco colunas basta:

Sem o diário, você não sabe qual mudança valeu a pena e nem qual quebrou o jogo.

5.1 De onde vem o peso do código

• O motor: cada subsistema (física, animação, UI, áudio, vídeo, partículas) entra no wasm se algo o referenciar, inclusive por dependência de pacote.
• O seu C#: o IL2CPP converte tudo em C++ e depois em WebAssembly. Genéricos, LINQ e reflexão aumentam o código gerado.
• Bibliotecas gerenciadas: DLLs de terceiros e pacotes entram inteiros ou quase, dependendo do stripping. Um pacote "inocente" pode custar centenas de KB.

5.2 A ordem certa de ataque

Comece pelos ganhos baratos e seguros, e deixe para o fim os que trazem risco de quebrar o jogo:

5.3 Stripping sem quebrar: link.xml e [Preserve]

O linker da Unity remove o que parece não usado. Quem carrega tipos por reflexão, por serialização (JSON, por exemplo) ou por AssetBundles/Addressables pode ter uma classe removida e receber um erro só na build. Duas defesas:

<!-- Assets/link.xml -->
<linker>
  <assembly fullname="Assembly-CSharp">
    <type fullname="MeuJogo.Perguntas.PerguntaData" preserve="all"/>
  </assembly>
</linker>

using UnityEngine.Scripting;

[Preserve]   // impede o stripping desta classe
public class PerguntaData { public string enunciado; public string[] opcoes; public int correta; }

Regra prática: suba o nível de stripping e teste o jogo inteiro, com foco em tudo o que é lido de arquivo, rede ou dado dinâmico. Sempre que aparecer um erro de tipo ou método ausente só na build, preserve o tipo e registre no diário de builds.

5.4 Ferramentas para enxergar o motor

A Unity oferece o pacote Web Stripping Tool, que analisa o código do motor incluído no WebAssembly e permite remover submódulos que o seu projeto não usa (por exemplo, partes de gráficos 3D num jogo 2D). O fluxo é instalar o pacote, perfilar a build para ver o que é usado e configurar o stripping por submódulo. É uma otimização de segunda etapa, para quando os passos 1 a 7 já foram feitos.

6.1 Texturas: o maior alvo

• Max Size por plataforma: na aba de plataforma Web do Inspector da textura, reduza o tamanho máximo. Uma textura de 2048 px ocupa quatro vezes a de 1024 px. Pergunte sempre: em que tamanho ela aparece na tela?
• Formato de compressão: navegadores de desktop usam DXT; navegadores móveis usam ASTC. Se o formato escolhido não é suportado pelo dispositivo, a Unity usa uma descompressão por software em execução, o jogo ainda roda, mas usa mais memória e pode ficar mais lento. A documentação mostra como gerar um arquivo de dados por formato e escolher o correto com JavaScript no template; se isso for complexo demais para o seu caso, escolha o formato do seu público principal (escolas com PCs e Chromebooks: DXT).
• Crunch: compressão adicional que reduz bastante o tamanho em disco. O custo é um build mais demorado e alguma perda de qualidade. A documentação da Unity a recomenda para reduzir o tamanho da distribuição.
• Mipmaps: desligue em interface e em 2D sem redução de escala (economiza ~33% de memória por textura).
• Read/Write Enabled: mantenha desligado, senão a Unity guarda uma cópia extra na memória.
• Sprite Atlas: agrupe sprites de interface para reduzir chamadas de desenho e desperdício de espaço.

6.2 Áudio

• Comprima (Vorbis) e reduza a qualidade onde ninguém ouve a diferença; efeitos curtos em mono.
• Efeitos curtos podem usar "Decompress On Load"; músicas longas não: descomprimidas, ocupam muito espaço em memória. Prefira "Compressed In Memory" e teste, porque o comportamento de streaming varia entre plataformas.
• Narração e trilhas longas são bons candidatos a carregamento sob demanda (cap. 8), ou até a um servidor de mídia, em vez de irem no .data.
• O áudio só começa depois de um gesto do usuário (cap. 2), então a tela "Toque para começar" é obrigatória, não estética.

6.3 Malhas e animações

• Modele com poucos vértices; simplifique no Blender antes de exportar. Em serious games, clareza pesa mais que realismo.
• No importador do modelo: ative Mesh Compression, desligue Read/Write, não importe o que não usa (câmeras, luzes, materiais embutidos duplicados) e evite tangentes se o material não usa normal map.
• Ative a compressão de animação e remova curvas que não são usadas.

6.4 Shaders

• Cada combinação de palavras-chave gera uma variante de shader, e o total pode explodir. Use shaders simples e limpe a lista de shaders sempre incluídos e as variantes desnecessárias nas configurações de gráficos.
• A compilação de shaders na primeira vez que aparecem causa engasgos no estágio 5 (cap. 3). Use ShaderVariantCollection.WarmUp() durante a tela de loading para adiantar esse custo.

6.5 Fontes, vídeo e a pasta Resources

• TextMesh Pro: gere atlas estáticos só com os caracteres necessários (letras, números, pontuação e acentos do português: ãõçáéíóúâêôà). Uma fonte com milhares de glifos (CJK, por exemplo) pesa muito.
• Vídeo: na build Web, o VideoPlayer reproduz por URL, não a partir de um clipe incluído no projeto. Hospede o vídeo em servidor de mídia ou CDN e referencie a URL; não o coloque no .data.
• Pasta Resources/: tudo o que está dentro entra na build, mesmo que nada use. Evite-a; use referências diretas e Addressables (veja também Unity Essencial).
• Duplicatas: a mesma textura em dois lugares vira dois assets. O Build Report ajuda a achar.

7.1 As opções de compressão da Unity

7.2 O que o servidor precisa dizer

Para cada arquivo comprimido, o servidor deve responder com dois cabeçalhos: Content-Encoding (como está comprimido) e Content-Type do conteúdo original, não do arquivo comprimido:

O tipo application/wasm importa por dois motivos: é ele que permite ao navegador compilar o WebAssembly enquanto baixa (estágio 3 do cap. 3), e a falta dele gera avisos ou perda dessa otimização. Se algo estiver errado, o loader da Unity costuma exibir uma mensagem como "não foi possível ler o arquivo… a compressão da build foi ativada, mas o servidor não entregou o cabeçalho Content-Encoding".

7.3 Exemplos de servidor

Nginx, servindo arquivos Brotli pré-comprimidos:

location ~ \.data\.br$ {
    types {} default_type application/octet-stream;
    add_header Content-Encoding br;
}
location ~ \.wasm\.br$ {
    types {} default_type application/wasm;
    add_header Content-Encoding br;
}
location ~ \.js\.br$ {
    types {} default_type application/javascript;
    add_header Content-Encoding br;
}

Apache (o servidor trata cada extensão separadamente: .br é a codificação, .wasm é o tipo):

<IfModule mod_mime.c>
  AddEncoding br .br
  AddEncoding gzip .gz
  AddType application/wasm .wasm
  AddType application/javascript .js
  AddType application/octet-stream .data
</IfModule>

Para Vercel e Netlify, defina os cabeçalhos por padrão de caminho no arquivo de configuração da plataforma (headers no vercel.json; arquivo _headers no Netlify), seguindo a tabela 7.2. Em S3 + CloudFront, defina Content-Encoding e Content-Type como metadados de cada objeto ao enviar. Sempre teste:

curl -sI -H "Accept-Encoding: br, gzip" https://seu-site/Build/jogo.wasm.br | grep -i -E "content-(type|encoding)"
# esperado:  content-encoding: br   e   content-type: application/wasm

7.4 Cache

• Arquivos da pasta Build com hash no nome: Cache-Control: public, max-age=31536000, immutable. O hash muda a cada versão, então o cache de um ano é seguro.
• index.html: sem cache longo (no-cache ou poucos minutos), para que uma nova versão apareça imediatamente.
• CDN: hospedar perto do aluno (no Brasil, uma CDN com pontos de presença no país) reduz a latência do estágio 1.

7.5 Onde hospedar: o que muda

8.1 Addressables: build pequena + conteúdo remoto

A ideia: a build Web inicial contém apenas um "bootstrap" (menu, tela de loading, sistema de dados) e o conteúdo de cada fase ou módulo vive em grupos Addressables hospedados numa CDN. O jogador baixa cada fase quando precisa dela, e o navegador guarda os pacotes em cache.

using System.Collections;
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;
using UnityEngine.SceneManagement;
using UnityEngine.UI;

public class CarregadorDeFase : MonoBehaviour
{
    [SerializeField] Slider barra;

    public IEnumerator Carregar(string chaveDaFase)
    {
        // 1) Quanto falta baixar? (0 se já está em cache)
        var tamanho = Addressables.GetDownloadSizeAsync(chaveDaFase);
        yield return tamanho;

        if (tamanho.Result > 0)
        {
            var baixar = Addressables.DownloadDependenciesAsync(chaveDaFase);
            while (!baixar.IsDone) { barra.value = baixar.PercentComplete; yield return null; }
            Addressables.Release(baixar);
        }
        Addressables.Release(tamanho);

        // 2) Entrar na fase (a cena é um endereço)
        yield return Addressables.LoadSceneAsync(chaveDaFase, LoadSceneMode.Single);
    }
}

Pontos de atenção específicos da web:

• CORS: se a CDN está em outro domínio, ela precisa enviar Access-Control-Allow-Origin para o domínio do jogo, senão o navegador bloqueia os pacotes.
• Compressão dos bundles: prefira LZ4 ou sem compressão do bundle, deixando a compressão de transporte para o servidor; LZMA é desaconselhada na web. Confirme na documentação da sua versão.
• Agrupe por uso: assets usados juntos ficam no mesmo grupo (uma fase, um módulo), para não baixar 30 arquivinhos.
• Falha de rede: trate o erro e ofereça "Tentar de novo". Redes escolares caem.

Para outras cenas grandes que ficam na própria build, use SceneManager.LoadSceneAsync: o progresso reportado para em 0,9 até você liberar allowSceneActivation, o que permite terminar a tela de loading antes de trocar.

8.2 Tela de loading no template

O carregador da Unity só cria o jogo depois que createUnityInstance termina, e aceita um callback de progresso de 0 a 1. Personalize um WebGL Template (pasta Assets/WebGLTemplates/SuaMarca, escolhida em Player Settings → Resolution and Presentation) para mostrar marca, barra e mensagem em HTML:

<canvas id="unity-canvas" tabindex="-1"></canvas>
<div id="loading">
  <div id="bar"><div id="fill"></div></div>
  <p id="msg">Carregando o jogo…</p>
</div>
<script>
  var s = document.createElement("script");
  s.src = "Build/{{{ LOADER_FILENAME }}}";
  s.onload = function () {
    createUnityInstance(document.querySelector("#unity-canvas"), {
      dataUrl: "Build/{{{ DATA_FILENAME }}}",
      frameworkUrl: "Build/{{{ FRAMEWORK_FILENAME }}}",
      codeUrl: "Build/{{{ CODE_FILENAME }}}",
      streamingAssetsUrl: "StreamingAssets",
      companyName: "{{{ COMPANY_NAME }}}",
      productName: "{{{ PRODUCT_NAME }}}",
      productVersion: "{{{ PRODUCT_VERSION }}}",
      devicePixelRatio: 1            // menos pixels em telas de alta densidade
    }, function (p) {
      document.getElementById("fill").style.width = (p * 100) + "%";
    }).then(function (u) {
      window.unityInstance = u;
      document.getElementById("loading").hidden = true;
    }).catch(function (e) {
      document.getElementById("msg").textContent =
        "Não foi possível carregar o jogo. Recarregue a página.";
      console.error(e);
    });
  };
  document.body.appendChild(s);
</script>

As variáveis {{{ … }}} são preenchidas pela Unity na hora do build, com os nomes reais dos arquivos. Repare no .catch: uma mensagem humana vale mais que uma tela em branco. E o devicePixelRatio: 1 reduz a resolução interna em telas de alta densidade, o que ajuda bastante em celulares.

8.3 Percepção de espera

• Barra honesta: não invente progresso. Use o valor real do callback.
• Diga o que está acontecendo e dê algo para ler: dica de jogo, objetivo da fase, aviso de que "na primeira vez demora mais; depois é rápido".
• Termine com um gesto: "Toque para começar" libera áudio e tela cheia (cap. 2) e evita que o aluno perca a introdução.
• Pré-aqueça: compile shaders e carregue a primeira fase durante o loading (cap. 6).

8.4 Data caching

Em Player Settings → Publishing Settings, a opção Data Caching guarda o .data no IndexedDB do navegador, evitando baixá-lo de novo em visitas seguintes (útil em turmas que jogam toda semana). Três ressalvas: ele não evita o desempacotar (estágio 4); a cada versão nova, o cache precisa ser reconstruído; e o navegador pode limitar ou negar armazenamento (janela privada, cotas, iframes de terceiros em alguns navegadores). Sempre teste em janela anônima e não dependa dele para a jogabilidade.

8.5 Memória: o limite silencioso

A memória da aba tem três áreas: o heap da Unity (objetos, cenas, shaders), os dados (o .data desempacotado) e o comportamento do coletor de lixo. Nas configurações da build Web, o Initial Memory Size (tamanho inicial do heap) e o Memory Growth Mode controlam como a memória cresce. Recomendações:

• Em celulares, ajuste o tamanho inicial ao uso típico do jogo; crescer o heap durante a partida custa tempo e pode falhar.
• Como o GC só roda entre frames, alocações repetidas em um mesmo laço acumulam sem serem coletadas: use StringBuilder, pré-aloque listas e prefira NativeArray para dados temporários.
• Use uma build de desenvolvimento com Profiler para medir o heap; desligue-a na entrega.

8.6 Celulares e tablets

As versões recentes da Unity suportam navegadores móveis (Chrome no Android, Safari no iOS), mas com limites de memória menores e comportamentos próprios: teclado virtual em campos de texto do jogo historicamente exige soluções em HTML/.jslib; a tela cheia no iPhone tem restrições; e a orientação da tela precisa ser tratada. Se o seu público usa celular, inclua-o na matriz de testes desde o começo (cap. 12).

9.1 O que é o SCORM

SCORM (Sharable Content Object Reference Model) é um conjunto de especificações da ADL que faz duas coisas: define como empacotar um conteúdo (um zip com um arquivo imsmanifest.xml) e como esse conteúdo conversa com o LMS (uma API em JavaScript que o LMS expõe). As versões que você encontra são a 1.2 (a mais compatível) e a 2004 (várias edições; com sequenciamento mais rico e mais complexidade). O que o SCORM registra é pouco: status de conclusão, nota, tempo e um pouco de estado salvo. Para dados mais ricos, veja o cap. 10.

9.2 Como a conversa acontece

O LMS abre o seu conteúdo (o index.html da build) dentro de uma janela ou iframe e coloca nessa hierarquia um objeto: window.API (SCORM 1.2) ou window.API_1484_11 (SCORM 2004). O seu código procura esse objeto subindo pela cadeia de window.parent e depois chama métodos:

9.3 A ponte JavaScript ↔ C#

O jogo em C# não enxerga window.API. A ponte tem três peças: um bridge em JavaScript no template (acha a API e a envolve), um plugin .jslib (a ponte entre o wasm e o JavaScript) e uma classe C# que o resto do jogo chama. Este exemplo é SCORM 1.2.

1) No index.html do template:

<script>
window.scormBridge = (function () {
  function achar(win) {
    for (var n = 0; n < 10; n++) {
      try { if (win.API) return win.API; } catch (e) { return null; } // outro domínio: bloqueado
      if (!win.parent || win.parent === win) return null;
      win = win.parent;
    }
    return null;
  }
  var api = achar(window) || (window.opener ? achar(window.opener) : null);
  var ok = !!api && String(api.LMSInitialize("")) === "true";
  return {
    ativo:    function ()    { return ok; },
    setValue: function (k, v){ return ok && String(api.LMSSetValue(k, v)) === "true"; },
    getValue: function (k)   { return ok ? String(api.LMSGetValue(k)) : ""; },
    commit:   function ()    { return ok && String(api.LMSCommit("")) === "true"; },
    finish:   function ()    { if (ok) { api.LMSCommit(""); api.LMSFinish(""); ok = false; } }
  };
})();
window.addEventListener("beforeunload", function () { window.scormBridge.finish(); });
</script>

2) Assets/Plugins/WebGL/ScormBridge.jslib:

mergeInto(LibraryManager.library, {
  ScormSetValue: function (keyPtr, valuePtr) {
    var k = UTF8ToString(keyPtr), v = UTF8ToString(valuePtr);
    return (window.scormBridge && window.scormBridge.setValue(k, v)) ? 1 : 0;
  },
  ScormCommit: function () {
    if (window.scormBridge) window.scormBridge.commit();
  },
  ScormAtivo: function () {
    return (window.scormBridge && window.scormBridge.ativo()) ? 1 : 0;
  }
});

3) Scorm12.cs:

using System.Runtime.InteropServices;
using UnityEngine;

public static class Scorm12
{
#if UNITY_WEBGL && !UNITY_EDITOR
    [DllImport("__Internal")] static extern int  ScormSetValue(string key, string value);
    [DllImport("__Internal")] static extern void ScormCommit();
    [DllImport("__Internal")] static extern int  ScormAtivo();
#else
    // No Editor e fora do LMS, apenas registra no Console.
    static int  ScormSetValue(string k, string v) { Debug.Log($"[SCORM] {k} = {v}"); return 1; }
    static void ScormCommit() { }
    static int  ScormAtivo() { return 0; }
#endif

    public static bool Ativo => ScormAtivo() == 1;

    public static void ReportarResultado(int notaPercentual, bool aprovado, int segundos)
    {
        ScormSetValue("cmi.core.score.raw", Mathf.Clamp(notaPercentual, 0, 100).ToString());
        ScormSetValue("cmi.core.lesson_status", aprovado ? "passed" : "failed");
        ScormSetValue("cmi.core.session_time", $"{segundos / 3600:0000}:{segundos % 3600 / 60:00}:{segundos % 60:00}");
        ScormCommit();
    }
}

Três cuidados: chame LMSCommit em marcos (fim de fase), não a cada frame; guarde suspend_data num formato compacto (o limite do 1.2 é de 4096 caracteres); e, se o manifesto define uma nota mínima (adlcp:masteryscore), muitos LMS decidem aprovado ou reprovado a partir da nota, ignorando o status que você enviou.

9.4 O manifesto e o pacote

O pacote é um zip com imsmanifest.xml na raiz, ao lado de index.html, Build/, TemplateData/ etc. Um manifesto mínimo do SCORM 1.2:

<?xml version="1.0" encoding="UTF-8"?>
<manifest identifier="br.com.exemplo.jogo-fracoes" version="1"
  xmlns="http://www.imsproject.org/xsd/imscp_rootv1p1p2"
  xmlns:adlcp="http://www.adlnet.org/xsd/adlcp_rootv1p2"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <metadata>
    <schema>ADL SCORM</schema>
    <schemaversion>1.2</schemaversion>
  </metadata>
  <organizations default="org1">
    <organization identifier="org1">
      <title>Jogo das Frações</title>
      <item identifier="item1" identifierref="res1">
        <title>Jogo das Frações</title>
      </item>
    </organization>
  </organizations>
  <resources>
    <resource identifier="res1" type="webcontent" adlcp:scormtype="sco" href="index.html">
      <file href="index.html"/>
      <!-- liste todos os arquivos do pacote (ou gere a lista com uma ferramenta) -->
    </resource>
  </resources>
</manifest>

Repare no adlcp:scormtype em minúsculas: é o nome no SCORM 1.2; no 2004 é adlcp:scormType. Erros de manifesto são a segunda causa de "o LMS não aceita o pacote". Teste sempre no SCORM Cloud (serviço da Rustici para validar pacotes) e em um Moodle local antes de entregar.

9.5 Os quatro problemas que só aparecem no LMS

9.6 O pacote-casca (hospedar fora, reportar dentro)

Quando a build é grande demais para o LMS ou precisa de cabeçalhos que ele não permite, o pacote SCORM contém só uma página-casca pequena. Ela encontra a API do SCORM (está na mesma origem do LMS) e embute o jogo hospedado na sua CDN num iframe, trocando mensagens com ele via postMessage: o jogo envia "fim da fase, nota 80" e a casca traduz para LMSSetValue. É o mesmo desenho do bridge do 9.3, com uma camada de mensagens no meio. Validar a origem da mensagem (event.origin) é obrigatório, senão qualquer página poderia registrar notas.

// Na página-casca (dentro do pacote SCORM), escutando o jogo hospedado fora:
var ORIGEM_DO_JOGO = "https://jogos.exemplo.com.br";
window.addEventListener("message", function (ev) {
  if (ev.origin !== ORIGEM_DO_JOGO) return;          // ignora qualquer outra origem
  var m = ev.data || {};
  if (m.tipo === "resultado") {
    scormBridge.setValue("cmi.core.score.raw", String(m.nota));
    scormBridge.setValue("cmi.core.lesson_status", m.aprovado ? "passed" : "failed");
    scormBridge.commit();
  }
});

9.7 Limites do SCORM (e por que o cap. 10 existe)

• Só existe dentro do LMS, aberto pelo LMS. Sem app nativo, sem jogo fora dele.
• Modelo de dados pobre: uma nota e um status. Você não descobre em qual pergunta o aluno errou, quanto tempo passou em cada fase ou que escolha fez.
• Depende da janela do navegador aberta: perder a conexão no fim da sessão pode perder o registro.

10.1 O modelo em uma frase

O xAPI (Experience API, também chamado Tin Can) registra experiências de aprendizagem como statements, frases estruturadas em JSON no formato ator + verbo + objeto: "Ana respondeu à pergunta 4 do nível 2". Os statements vão por HTTP para um LRS (Learning Record Store), que os guarda e permite consultar. Ao contrário do SCORM, o jogo não precisa estar dentro do LMS: pode estar em qualquer lugar da web. A versão 1.0.3 é a mais implantada; o xAPI 2.0 foi padronizado pelo IEEE em 2023.

10.2 Anatomia de um statement

{
  "actor": {
    "objectType": "Agent",
    "account": { "homePage": "https://jogos.exemplo.com.br", "name": "aluno-4f2a91" }
  },
  "verb": {
    "id": "http://adlnet.gov/expapi/verbs/answered",
    "display": { "pt-BR": "respondeu" }
  },
  "object": {
    "objectType": "Activity",
    "id": "https://jogos.exemplo.com.br/fracoes/nivel-2/pergunta-4",
    "definition": { "name": { "pt-BR": "Fração equivalente a 3/4" }, "type": "http://adlnet.gov/expapi/activities/cmi.interaction" }
  },
  "result": {
    "success": false,
    "response": "6/9",
    "duration": "PT23S"
  },
  "context": {
    "registration": "0b3f5ec3-2d09-4b9e-9f4a-6a1a8f5e7a10",
    "contextActivities": { "parent": [ { "id": "https://jogos.exemplo.com.br/fracoes/nivel-2" } ] }
  },
  "timestamp": "2026-09-19T14:03:22.000Z"
}

10.3 Demo: monte um statement

Altere os campos e veja o JSON mudar. Repare que o ator usa uma conta pseudônima e que a duração é convertida para o formato ISO 8601.

10.4 O LRS

Um LRS expõe um endpoint /statements: você faz POST com o JSON, envia o cabeçalho X-Experience-API-Version (por exemplo, 1.0.3) e credenciais. Há LRS de código aberto que você hospeda (como o Learning Locker, o Yet Analytics SQL LRS e o Trax LRS), LRS comerciais com plano gratuito para testes e o LRS embutido do SCORM Cloud. Confirme os planos e a manutenção atuais antes de escolher.

10.5 Enviando statements do Unity

Na build Web, use UnityWebRequest (nada de HttpClient ou sockets). Bibliotecas de xAPI para .NET existem, mas confirme a manutenção e a compatibilidade com IL2CPP e WebGL antes de adotar; para um envio simples, cerca de trinta linhas resolvem e você controla tudo:

using System.Collections;
using System.Text;
using UnityEngine;
using UnityEngine.Networking;

public class XapiSender : MonoBehaviour
{
    [SerializeField] string endpoint = "https://lrs.exemplo.com.br/xapi/statements";
    string authorization;  // recebido em tempo de execução; nunca escrito no projeto

    public void Configurar(string valorAuthorization) => authorization = valorAuthorization;

    public IEnumerator Enviar(string statementJson)
    {
        using var req = new UnityWebRequest(endpoint, UnityWebRequest.kHttpVerbPOST);
        req.uploadHandler   = new UploadHandlerRaw(Encoding.UTF8.GetBytes(statementJson));
        req.downloadHandler = new DownloadHandlerBuffer();
        req.SetRequestHeader("Content-Type", "application/json");
        req.SetRequestHeader("X-Experience-API-Version", "1.0.3");
        req.SetRequestHeader("Authorization", authorization);

        yield return req.SendWebRequest();

        if (req.result != UnityWebRequest.Result.Success)
            Debug.LogWarning($"xAPI falhou ({req.responseCode}): {req.error}");  // enfileirar para tentar de novo
    }
}

10.6 Robustez: rede, CORS e fim de sessão

• CORS: o LRS precisa aceitar requisições do domínio do jogo, inclusive a requisição de verificação (OPTIONS) e os cabeçalhos Authorization, Content-Type e X-Experience-API-Version.
• Fila com reenvio: guarde os statements pendentes numa lista e tente de novo com espera crescente. Redes de escola caem.
• Envie em lote: o endpoint aceita um array de statements; agrupe eventos de baixa importância em vez de enviar um por clique.
• Fim de sessão: ao fechar a aba, use fetch(url, { keepalive: true, headers: … }) para o statement final. O navigator.sendBeacon não permite definir os cabeçalhos que o xAPI exige.
• Idempotência: gere um UUID por statement (id) para que um reenvio não duplique o evento.

10.7 cmi5: o xAPI lançado por um LMS

O cmi5 é um perfil do xAPI para conteúdo lançado por um LMS: ele resolve o que o SCORM não resolve, porque não depende da janela pai, então o jogo pode estar hospedado em qualquer domínio. O LMS abre a URL do jogo com parâmetros de lançamento:

• endpoint: o LRS que receberá os statements;
• fetch: uma URL de uso único que devolve o token de autorização da sessão (a credencial de curta duração da caixa acima);
• actor: quem está jogando;
• registration: o identificador da matrícula, que deve constar em todo statement;
• activityId: o IRI da atividade.

O perfil também define um ciclo de vida: initialized deve ser o primeiro statement da sessão e terminated o último; no meio ficam completed, passed, failed, abandoned, waived e quantos statements xAPI próprios você quiser. O suporte a cmi5 varia entre LMS: confira o do seu cliente antes de prometê-lo.

10.8 Comparando os três caminhos

11.1 Comece pela decisão, não pelos eventos

O erro típico é registrar tudo "porque pode ser útil". Você acaba com milhões de linhas e nenhuma resposta. Faça o caminho inverso, inspirado no Evidence-Centered Design (Mislevy, Almond e Lukas, 2003):

Essa cadeia liga cada evento a uma pergunta. É também a base da avaliação embutida (stealth assessment), defendida por Valerie Shute: a avaliação acontece dentro do jogo, sem interromper a experiência com um teste.

11.2 Taxonomia de eventos de um serious game

• Agregue no cliente o que puder (um resumo por fase em vez de um evento por clique).
• Diferencie erro de ruído: um clique sem intenção não é evidência. Registre o contexto (tempo de reação, tentativas) para poder filtrar depois.
• Cuidado com métricas de fachada: tempo de tela não é aprendizagem. Quando a métrica vira meta, o aluno passa a jogar para a métrica.

11.3 Perfis e padrões

Para não reinventar a semântica, procure perfis xAPI existentes. O xAPI Serious Games Profile (xAPI-SG), produzido por pesquisadores da Universidad Complutense de Madrid, define verbos, atividades e extensões para eventos de jogos educativos (iniciar e completar níveis, escolhas, uso de itens). Vale conhecê-lo como referência de vocabulário; confirme a versão e a manutenção antes de basear o projeto nele. Um vocabulário compartilhado é o que permite comparar resultados entre jogos e turmas.

11.4 Privacidade: LGPD e minimização

Statements descrevem pessoas, muitas vezes crianças. Trate-os como dados pessoais:

• Minimize: colete só o que responde à decisão do 11.1. Se você não vai usar, não colete.
• Pseudonimize: use um identificador que só o cliente consegue ligar à pessoa (o account.name do exemplo), nunca e-mail, CPF ou nome real dentro do statement.
• Crianças e adolescentes: a LGPD (art. 14) tem regras específicas para o tratamento de dados desse público, com o consentimento de responsável em muitos casos. Consulte o jurídico do cliente; este texto não é aconselhamento jurídico.
• Retenção e acesso: defina por quanto tempo os dados ficam guardados, quem os vê e como um aluno pede a exclusão.
• Transparência: diga ao aluno e ao responsável, em linguagem simples, o que o jogo registra e para quê.

11.5 Acessibilidade em jogos web

Um jogo em canvas é opaco para leitores de tela: o navegador enxerga um retângulo de pixels. Se o serious game é para um público amplo (e em contexto educacional ou corporativo, frequentemente há obrigação de acessibilidade), planeje desde o início:

• Teclado: tudo o que se faz com o mouse deve ser possível pelo teclado.
• Contraste e tamanho: texto legível, sem depender só de cor para informar.
• Legendas e alternativas sonoras para narração e efeitos importantes.
• Sem limite de tempo rígido ou com opção de ampliá-lo.
• Alternativa em HTML: para conteúdo essencial, considere oferecer a atividade também fora do canvas, ou expor texto real na página ao redor.

12.1 Automatizando o build

Faça a build Web em integração contínua para que qualquer commit gere um pacote testável. O projeto de código aberto GameCI oferece ações do GitHub para compilar projetos Unity (é preciso configurar a licença); o resultado é uma pasta Build pronta para publicar. Depois da build, verifique o orçamento do cap. 4 automaticamente:

#!/usr/bin/env bash
# Falha o pipeline se o total transferido passar do orçamento (em MB)
ORCAMENTO_MB=12
TOTAL_KB=$(du -sk Builds/Web/Build | cut -f1)
LIMITE_KB=$((ORCAMENTO_MB * 1024))
echo "Build: $((TOTAL_KB / 1024)) MB (limite: ${ORCAMENTO_MB} MB)"
if [ "$TOTAL_KB" -gt "$LIMITE_KB" ]; then
  echo "ERRO: a build estourou o orçamento de tamanho"; exit 1
fi

Faça o mesmo com o servidor: um passo de curl -I que confere Content-Encoding e Content-Type depois de cada deploy (7.3). Para o lado de infraestrutura, veja DevOps, Docker e Kubernetes.

12.2 Matriz de testes

12.3 Cenários de decisão (ilustrativos)

Os cenários abaixo são hipotéticos, construídos para treinar a decisão; não descrevem projetos reais.

12.4 Checklist de entrega

12.5 Plano de 30 dias (~45 min/dia)

12.6 Bibliografia e fontes para seguir

• Serious games: Clark Abt, Serious Games (1970) · David Michael e Sande Chen, Serious Games: Games That Educate, Train, and Inform (2005) · James Paul Gee, What Video Games Have to Teach Us About Learning and Literacy (2003)
• Avaliação e dados: Valerie Shute, "Stealth assessment in computer-based games to support learning" (2011) · Mislevy, Almond e Lukas, "A Brief Introduction to Evidence-Centered Design" (ETS, 2003) · Serrano-Laguna e colegas, "Applying standards to systematize learning analytics in serious games" (2017)
• Especificações: ADL, xAPI Specification (repositório adlnet/xAPI-Spec) · cmi5 Specification (repositório AICC/CMI-5_Spec_Current) · documentação do SCORM 1.2 e 2004 da ADL; guias e explicações em scorm.com e xapi.com
• Unity: Manual da Unity, seção Web (build, compressão, memória, otimização de tamanho, Addressables) · Unity · Unity Essencial · C#
• Na trilha do site: Game Design · Gamification · Técnicas Modernas de Ensino e Aprendizagem · Spatial Computing, XR & WebXR