Simulando um runtime que diz não: como isolamos o navegador para agir como o WeChat

Sun, 19 Jul 2026 00:00:00 GMT

Simulando um runtime que diz não: como isolamos o navegador para agir como o WeChat

Por Oleg Sidorkin, CTO e cofundador da Cinevva

Lançamos recentemente um modo de minijogo do WeChat em nosso Criador de Jogos: um perfil de build que mantém os jogos gerados por IA dentro do subconjunto da plataforma web capaz de sobreviver à portabilidade para o runtime do WeChat. O perfil consiste em um conjunto de regras de geração. Nada de interface em DOM, Pointer Lock, áudio que não seja MP3 ou código dinâmico. O modelo segue essas regras da mesma forma que modelos seguem regras, ou seja: geralmente.

“Geralmente” não basta quando toda violação é invisível no navegador e fatal após a exportação. Um jogo com uma barra de vida em HTML funciona perfeitamente em nossa prévia e produz uma tela em branco no WeChat, pois os minijogos do WeChat não têm DOM. Por isso, criamos algo que transforma essas regras de sugestões em leis da física: um sandbox de modo estrito que faz o próprio navegador se recusar a fazer o que o WeChat não consegue. Este artigo explica como ele funciona.

A decisão central: simular a ausência, não a presença

A abordagem óbvia seria emular o WeChat: implementar wx.createCanvas, wx.onTouchStart, wx.setStorageSync e executar os jogos sobre a superfície wx.* emulada. Seguimos o caminho oposto, e o motivo está no formato do pipeline de exportação.

Os jogos no modo WeChat ainda são escritos usando APIs do navegador. No empacotamento, um adaptador (seguindo a abordagem padrão da comunidade, a weapp-adapter) mapeia essas APIs do navegador para wx.*. Isso significa que nossos jogos nunca chamam wx.* diretamente, portanto um emulador de wx testaria caminhos de código que não existem. O que realmente impede uma portabilidade não é a ausência de wx.* no navegador. É a presença de APIs do navegador sem equivalente no WeChat, usadas silenciosamente durante a geração. document.createElement('div'). requestPointerLock(). IndexedDB. Um arquivo .ogg que é decodificado sem problemas no Chrome, mas nunca funcionará no WeChat para iOS.

Portanto, o sandbox simula a ausência. Tudo o que o WeChat não tem é removido, bloqueado ou sinalizado na prévia, e o jogo é desenvolvido desde o primeiro frame dentro da interseção entre as duas plataformas.

Onde ele fica: em um service worker que já existia

A prévia do nosso editor tem um caminho de entrega incomum que tornou isso quase gratuito. Os jogos no editor não são servidos pela rede. Um service worker intercepta solicitações para /game/* e entrega arquivos do IndexedDB, permitindo que o iframe da prévia seja recarregado instantaneamente sem uma ida e volta ao servidor. Esse worker já injeta dois arquivos virtuais em cada página de jogo: um script de captura de erros que encaminha a saída do console e as falhas ao editor, e um inspetor de cena em tempo real.

O sandbox é o terceiro arquivo virtual, _wechat-strict.js, injetado no da página imediatamente após o script de captura e antes da execução de qualquer código do jogo. A ordem é essencial por dois motivos. Ele precisa ser executado depois da captura para que suas chamadas a console.error já sejam interceptadas e encaminhadas ao editor, e antes dos módulos do jogo para que os bloqueios estejam ativos quando a primeira linha de código do jogo for executada.

A ativação usa um truque de uma linha. A opção WeChat no criador é persistida em localStorage, e o iframe da prévia tem a mesma origem que o editor, portanto o harness simplesmente lê o sinalizador diretamente:

try {
  if (localStorage.getItem('cinevva-gc-profile') !== 'wechat-minigame') return;
} catch (e) { return; }

Para qualquer jogo que não seja do WeChat, o script faz uma única comparação de strings e retorna imediatamente. Sem sinalizador de build, sem ida e volta ao servidor e sem estado para sincronizar com o service worker.

A lista de bloqueios e a taxonomia de dois níveis

Nem toda violação merece a mesma resposta, portanto o harness diferencia dois níveis. APIs que não existem no WeChat lançam erros, porque é isso que acontece após a exportação, e uma falha durante a geração é a prévia honesta de uma falha na análise. Recursos que existem, mas falham mais tarde são sinalizados com erros explícitos no console sem alterar o comportamento, pois bloqueá-los ocultaria o estado real do jogo da pessoa que está trabalhando nele.

O nível que lança erros: criação de qualquer elemento de interface HTML, tanto por createElement quanto por createElementNS (o Three.js cria seu canvas pela variante NS, então os dois caminhos precisam da mesma barreira), eval, new Function, requestPointerLock e registro de service workers. Cada erro lançado inclui a correção em sua mensagem:

throw violate("document.createElement('" + tag + "') — WeChat mini games have no DOM. " +
  "Draw UI on canvas (offscreen 2D canvas -> THREE.CanvasTexture on a screen-space quad) " +
  "and hit-test taps yourself.");

O nível de sinalização: leitura de indexedDB (retorna undefined, exatamente como o WeChat, além de um erro indicando o uso de localStorage), áudio em qualquer formato que o WeChat para iOS não consiga decodificar (verificado em três pontos: no construtor Audio, no setter src do protótipo do elemento de mídia e nas URLs buscadas), solicitações de rede para qualquer origem que não seja a do próprio jogo ou nossa CDN de assets (no WeChat, elas exigem um domínio incluído em uma lista de permissões e registrado no ICP) e qualquer ocorrência do Tone.js.

Também há uma auditoria pós-carregamento executada pouco depois de a página se estabilizar: ela percorre o e relata qualquer elemento HTML vindo da marcação do próprio jogo, em vez de uma criação dinâmica. HUDs estáticos passam despercebidos por uma barreira em createElement, então a barreira sozinha não é suficiente.

Cada relatório elimina duplicatas por mensagem e tem um limite de cinquenta ocorrências por sessão. Um bug de loop invertido que cria uma div por frame produz um erro, não uma enxurrada que afoga o sinal relevante.

As quatro exceções que mais nos ensinaram

Criar um sandbox consiste, em grande parte, em decidir o que não bloquear, e cada exceção que abrimos surgiu quando nossas próprias ferramentas pararam de funcionar durante o desenvolvimento.

Nosso depurador usa eval. A ferramenta execute_js do criador, usada pela IA para inspecionar o jogo em execução, avalia código pelo manipulador de mensagens do script de captura, que chama eval. Bloquear eval de forma ingênua teria cegado os próprios olhos da IA. A solução: antes de aplicar o bloqueio, o harness armazena a função real em uma propriedade não enumerável, e o manipulador do script de captura recorre a ela:

Object.defineProperty(window, '__cinevvaRealEval', { value: window.eval, enumerable: false });
window.eval = function () { throw violate('eval() is banned in WeChat mini games.'); };
// capture script, at message time:
returnValue = (window.__cinevvaRealEval || eval)(e.data.code);

O código do jogo que tentar usar eval ainda falha. O depurador não.

O gravador também cria elementos. Nosso gravador de reels é injetado no iframe do jogo como um

Cinevva Blog

Simulando um runtime que diz não: como isolamos o navegador para agir como o WeChat

Simulando um runtime que diz não: como isolamos o navegador para agir como o WeChat

A decisão central: simular a ausência, não a presença

Onde ele fica: em um service worker que já existia

A lista de bloqueios e a taxonomia de dois níveis

As quatro exceções que mais nos ensinaram