Guia de integração para desenvolvedores

Traga seu jogo para o Combos, seja ele de um estúdio ou criado com Codex, Claude Code ou Cursor. O fluxo é preparar uma versão para navegador → testar localmente → enviar com Combos CLI → jogar online → atualizar.

Escolha seu caminho

• Já tem uma versão Web? Leia Antes de começar e Publicar e atualizar.
• Precisa gerar os arquivos? Siga H5, Unity ou Roblox e depois publique.
• Quer acompanhar um projeto? Veja os três exemplos completos, com imagens, código-fonte e resultados registrados.
• Encontrou um problema? Consulte Solução de problemas.

Versões e evidências

O guia original foi verificado em 2026-10-08 com Combos CLI v1.14.2, usando macOS 15.3, Node.js 25.7.0 e Unity 6.3 LTS 6000.3.25f1. Os resultados descrevem essas execuções. Caminhos, configurações e patches específicos dos exemplos não são requisitos universais. Envio concluído, versão publicada e jogo funcionando são verificações distintas.

Antes de começar

O Combos hospeda jogos que rodam no navegador. Envie um site estático completo, normalmente na pasta dist. A pasta pode ter outro nome: informe o caminho real. A ferramenta de criação não muda o formato final.

Prepare os arquivos do seu projeto

A instalação do Combos CLI não exige Node.js, plugin Unity ou SDK. O Vite precisa de seu ambiente Node.js; o Unity, do Web Build Support oficial.

Localize os arquivos

my-game/
├── source/
├── dist/
│   ├── index.html
│   └── assets/
├── cover.png
└── combos.json

A raiz guarda o código editável. ./dist é relativo ao diretório atual do terminal. Mantenha cover.png e o combos.json gerado na raiz. Este último registra o vínculo com o jogo publicado; não é código-fonte.

Abra a pasta inteira no Codex e use seu terminal, ou abra o terminal do sistema. Substitua o caminho entre aspas e preserve as aspas se houver espaços. Confirme que a pasta mostrada contém dist e cover.png; caso contrário, prepare-os primeiro.

cd "/path/to/project"
pwd
ls

Set-Location "C:\path\to\project"
Get-Location
Get-ChildItem

Ambientes locais e na nuvem

Codex e Cursor gravam no espaço de trabalho selecionado. Antes de publicar, peça ao agente o caminho completo, o comando de build, a pasta de saída, o endereço de prévia e a verificação da jogabilidade principal.

Na nuvem, você pode gerar e enviar onde o CLI está instalado ou baixar o projeto para trabalhar localmente. O 127.0.0.1 da nuvem não é o seu computador: use a prévia da ferramenta ou um servidor local após baixar. A prévia local depende do servidor; o link do Combos funciona de forma independente.

Interprete os exemplos

Execute comandos no ambiente e diretório indicados. Troque caminhos, títulos, capas e dispositivos pelos seus. O commit e patch do BoatAttack e as coordenadas do Ball Game são exclusivos desses exemplos. Trechos Lua/JavaScript explicam o código; não são comandos de terminal nem conversores universais.

Publicar e atualizar

1. Instale e entre na conta

Peça ao agente para instalar o Combos CLI e sua skill pelas instruções oficiais , verificar a instalação e orientar o login. Veja também a página do CLI .

combos --version
combos account status
combos account login

Execute combos account login apenas se não estiver conectado e conclua no navegador. Confira a versão e a conta antes do envio. combos update --check verifica atualizações; combos update instala uma.

2. Prepare a versão e a capa

Coloque index.html na raiz da saída completa e crie cover.png com uma imagem real do jogo. HTML/JS pode já ser a versão final. Para Vite, Webpack e Unity, envie a saída gerada, sem node_modules, Library ou o projeto de desenvolvimento inteiro. Exclua credenciais, segredos do servidor e combos.json dos arquivos do navegador.

Limites: total descompactado ≤ 200 MiB, arquivo individual ≤ 100 MiB, até 2.000 arquivos. Não há um limite de produto separado para ZIP; o ZIP registrado do BoatAttack tinha 124,88 MiB.

O jogo roda em um subcaminho. Use URLs locais relativas como ./assets/game.js; no Vite, base: './'. Os caminhos Build/... e StreamingAssets/... do Unity já são relativos. Preserve URLs HTTPS externas e não faça substituições indiscriminadas na saída validada do motor.

3. Teste a saída exata

Com Python instalado, execute o comando adequado na raiz e mantenha o servidor aberto. Acesse http://127.0.0.1:8000/.

python3 -m http.server 8000 --bind 127.0.0.1 --directory dist

py -m http.server 8000 --bind 127.0.0.1 --directory dist

Você também pode usar preview do Vite ou Build And Run do Unity. Teste a pasta que será enviada, não apenas o servidor de desenvolvimento. Não abra o HTML Unity via file://. Verifique início, movimento ou ação principal, encerramento e reinício. Procure falhas e arquivos ausentes em Console/Network. Peça ao agente para testar a mesma saída em um subcaminho, corrigir problemas e gerar novamente antes de enviar.

4. Crie seu jogo

Substitua o título e os caminhos. Escolha pc, mobile ou pc,mobile, e landscape ou portrait, conforme o suporte verificado.

combos post create --dir ./dist --title "My Game" --cover ./cover.png --platform pc --screen-orientation landscape
combos post get

A primeira criação exige capa; uma nova versão exige --platform. Os parâmetros de dispositivo e orientação não criam controles de toque nem alteram o layout. O CLI retorna link, código de busca Canvas, Post e resultado da publicação, e gera combos.json na raiz.

O CLI compacta automaticamente. Se entregar um ZIP manualmente, compacte todo o conteúdo de dist, com index.html na raiz extraída. Em macOS/Linux com zip:

cd dist
zip -r ../game-dist.zip .
cd ..

No Windows, selecione todos os arquivos e pastas dentro de dist e compacte.

5. Verifique o link público

Pare a prévia com Ctrl+C, abra o link retornado e jogue novamente. Busque no Canvas pelo código de cinco dígitos, preservando zeros iniciais. Confira status, revision e submission_is_current. Se o envio ainda não for a versão atual, siga a resposta real e verifique a versão pública.

short_url: https://share.combos.game/p/0875954
game_code: 08759
status: POST_STATUS_PUBLISHED
revision: 2
submission_is_current: true

6. Atualize o mesmo jogo

Guarde seu combos.json, altere o código, gere novamente e repita os testes locais antes de atualizar:

combos post update --dir ./dist --platform pc --screen-orientation landscape
combos post get

Confirme a nova revisão e teste online pelo mesmo link. Não crie outro Post a cada alteração. Ao partir do código de outra pessoa, crie seu próprio jogo primeiro. Título e capa podem ser atualizados como metadados; um novo dist continua exigindo platform.

Peça ao agente para executar o fluxo

Localize o projeto e confira o login do CLI. Gere a saída estática completa com caminhos relativos. Inicie a prévia, informe o endereço e verifique a jogabilidade. Prepare uma capa real. Crie meu primeiro jogo ou atualize o vínculo do meu combos.json, com os dispositivos e a orientação realmente suportados. Pare o servidor local, jogue pelo Combos e informe URL, código Canvas, revisão e resultado. No Unity, use WebGL nativo sem plugin Combos Editor.

Fonte: Guia de integração de desenvolvedores Combos , verificado em 2026-10-08 com CLI v1.14.2. Os resultados são os registrados no guia original.