Criar um jogo para TikTok no Combos

Vamos criar Gift Arena: o streamer enfrenta um chefe e o público ajuda com energia, cura e ataques. Você recebe o projeto completo, um simulador de presentes, as etapas de publicação no Combos e o cadastro necessário para presentes reais. Referência: Combos SDK 1.1.0.

Jogar a demonstração · Baixar o projeto completo

Atualmente não há um processo disponível para ativar a interação real com TikTok. Você pode desenvolver, simular presentes e publicar no Combos agora; publicar um post não habilita presentes reais. Os materiais de integração e a validação LIVE preparam uma futura ativação pela plataforma, não uma solicitação que já possa ser concluída.

1. Declarar presentes como efeitos do jogo

Defina as regras antes da conexão. O jogador começa com 70 de vida e 40 de energia; o chefe tem 100 de vida. Atacar gasta 10 de energia e causa 10 de dano. Se sobreviver, o chefe revida com 8. Três efeitos ajudam o jogador:

// rules.js — this game's contract
export const GIFT_CATALOG = Object.freeze({
  gift_battery: { target: 'energy', perCount: 20, max: 100 },
  gift_heal: { target: 'hp', perCount: 15, max: 100 },
  gift_flash: { target: 'bossHp', perCount: -10, max: 100 },
});

A declaração fica no código do seu jogo. Não é uma chamada de cadastro do SDK nem o catálogo de presentes do TikTok. Bateria, Cura e Clarão são efeitos do exemplo, não nomes ou IDs de presentes reais. Não presuma que uma Rosa ou determinado preço tenha correspondência automática.

O exemplo aceita quantidades inteiras de 1 a 1000, limita vida e energia a 100 e a vida do chefe a no mínimo 0. Presentes não gastam turnos. Um efeito no limite continua sendo sucesso mesmo sem aumentar o valor. Após vitória ou derrota, novos comandos retornam false até a próxima rodada. São regras do exemplo, não limites da plataforma. Defina também acúmulo, recarga, transições entre rodadas e efeitos caros, e envie as mesmas regras para quem configura o mapeamento.

2. Entender as responsabilidades

Espectador → mapeamento de presentes do TikTok → Combos → SDK onCommand → efeito → resultado booleano → Combos → ACK do TikTok.

Uma interação configurada pode gerar instruction: "gift_flash", count: "3", causando 30 de dano. count é a quantidade de comandos definida pelo mapeamento, não o preço em moedas nem necessariamente o número de presentes. Confirme também a conversão de combos no cadastro. O jogo não precisa ler launchData, assinar requisições do TikTok, criar outro WebSocket ou implementar webhooks.

3. Implementar o contrato dos comandos

type TTLiveCommand = {
  messageId: string;
  instruction: string;
  count: string;
  timestamp: string;
};

O comando público não contém ID ou apelido do espectador nem ID do presente real. Não crie um ranking por espectador usando campos que a API não fornece.

Retorne true depois de confirmar o armazenamento do efeito, false para uma rejeição conhecida e lance um erro quando o resultado for incerto, como numa falha de armazenamento. O resultado desconhecido não recebe ACK e pode ser reenviado. Não transforme todos os erros em sucesso nem uma execução parcial incerta em falha confirmada.

O SDK reenvia resultados pendentes dentro do documento. O jogo também precisa lidar com recarregamentos. O exemplo salva estado e resultado da mensagem em uma única transação IndexedDB e só retorna o booleano depois do commit. Uma duplicata retorna o resultado salvo. Novas rodadas mantêm os recibos. Os dados LIVE são separados por conta/jogo do Combos e dos dados de treino.

Ler o estado da conexão

getTTLiveClient() retorna um cliente por documento do jogo. getLiveStatus() consulta o estado; onStatusChange() emite o atual imediatamente e depois as alterações. Inclui state, reason, action e confirmedAtMs: último início/heartbeat confirmado em milissegundos, ou 0 quando desconhecido.

• connecting: iniciando. connected: sessão de interação confirmada.
• recovering: deixe o SDK reconectar. unknown: confirmação indisponível; não significa que a transmissão terminou.
• ended: sessão de interação encerrada. Siga action: wait, none ou relaunch_game. Neste último caso, reabra este jogo pelo LIVE Studio, sem reiniciar a transmissão por um simples problema de conexão.

4. Executar o projeto completo

Preparar e iniciar

Baixe e extraia o ZIP. Você precisa de um navegador atual e Python 3 para o servidor estático local; Node e npm não são necessários. Mantenha a pasta tiktok-arena completa:

cd tiktok-arena
python3 -m http.server 8080 --bind 127.0.0.1

Abra http://127.0.0.1:8080/ e escolha Iniciar treino. Não abra index.html com clique duplo: módulos JavaScript precisam de HTTP. A demonstração online dispensa instalação. O seletor de idioma oferece os mesmos dez idiomas do site.

Três demonstrações reproduzíveis

Comece uma nova rodada para cada uma das duas primeiras linhas. A terceira continua a segunda sem reiniciar. Valores iniciais: vida 70, energia 40, chefe 100. Cada botão de presente gera uma mensagem; Repetir última mensagem reutiliza o ID.

Teste 0, 1.5, 1001 e 9007199254740993: nenhum efeito e false. Vença uma nova rodada com Clarão ×10 e envie outro presente: será rejeitado até a próxima rodada. Use Atacar e Recarregar para jogar normalmente. O painel de entrega mostra entrada, resultado e valores finais. Esses comandos locais sintéticos não compram presentes nem enviam ACKs ao TikTok.

5. Conectar o mesmo jogo no Combos

Mantenha connection.js e game.js ao publicar. O host injeta window.combos; não instale outro SDK npm nem carregue um segundo script. Conectar Combos LIVE implementa:

1. init() e verificação da capacidade getTTLiveSession e do getter do cliente. O nome da capacidade não é um método público a chamar.
2. checkSession() e, se necessário, login() a partir do clique. Cancelar encerra o fluxo; sucesso continua a mesma ação.
3. getUserInfo() para separar os dados locais. IDs não são credenciais nem prova de autorização no servidor.
4. Assinatura de estado e getTTLiveClient().connect({ onCommand }) com o processador usado no treino.
5. Desconectar / cancelar disponível durante novas tentativas. Cancelar ou sair remove a assinatura e chama disconnect().

O núcleo abaixo já está no download; a versão completa também atualiza a interface. store.update() é a transação de storage.js, não uma API do SDK:

import { executeCommand } from './rules.js';
 
// `store` is the account/game-scoped store opened by prepareStore().
function commandHandler(store) {
  return async (command) => {
    const { result } = await store.update((saved) =>
      executeCommand(saved, command),
    );
    return result; // State + receipt committed; no catch-and-return-false.
  };
}

connect() pode continuar pendente durante novas tentativas. Resolver a Promise não comprova que um presente real funcionou. LIVE esconde os botões simulados. Verifique efeito e resultado em uma sessão cadastrada.

6. Publicar no Combos

Instale a CLI oficial do Combos . Clique em Salvar capa PNG e coloque cover.png ao lado da pasta tiktok-arena. Execute na pasta superior:

combos --version
combos account login
combos post create --dir ./tiktok-arena --title 'Gift Arena' --cover ./cover.png --platform pc --screen-orientation landscape --allow-recommend=false
combos post get

Conclua o login no navegador com a conta que publicará o jogo. Abra o link de compartilhamento retornado e teste dentro do player Combos. Preserve o vínculo gerado em combos.json. Atualize o mesmo post a partir desse diretório:

combos post update --dir ./tiktok-arena --platform pc

É um jogo estático para PC em paisagem. A pasta enviada deve ter index.html na raiz e todos os recursos relativos. Publicar não ativa TT. Um link compartilhado normal permite treinar, mas não cria uma sessão real sem o contexto de lançamento cadastrado no LIVE Studio. Consulte o guia H5.

7. Preparar materiais para uma futura integração

Ainda não há uma entrada de ativação ou um processo de integração real confirmado. O cadastro de jogo/conta e o mapeamento de presentes devem aguardar as orientações da plataforma; SDK e CLI não oferecem API pública de autocadastro. Prepare os materiais abaixo para esse futuro processo. Esta é uma lista de preparação, não uma inscrição aberta:

Antes do teste, obtenha a confirmação da entrada exata cadastrada, da elegibilidade do jogo/contas e do mapeamento ativo. IDs, nomes e preços reais vêm do catálogo configurado. Para uma correspondência acordada de Clarão ×3, o jogo deve receber:

{
  "instruction": "gift_flash",
  "count": "3"
}

Não coloque segredos TikTok, tokens CAS ou launchData montado manualmente no jogo. A plataforma cuida deles. Sem cadastro, você tem um jogo Combos publicado e um simulador funcional; a validação real do TikTok ainda está pendente.

8. Validar a LIVE real depois da ativação

Execute estas etapas apenas depois que a plataforma disponibilizar a ativação e confirmar a entrada do jogo, a conta elegível e o mapeamento de presentes. Por enquanto, conclua a simulação local e as verificações de publicação acima; elas não substituem a validação de uma LIVE real.

1. Use a conta aprovada para abrir a entrada cadastrada no TikTok LIVE Studio. Conecte o jogo e confirme connected.
2. Com o consentimento do participante, acione uma interação de teste configurada. Registre messageId, instrução/quantidade, valores antes/depois e resultado. Peça ao contato para confirmar o recebimento do ACK correspondente. Não registre credenciais ou dados pessoais dos espectadores.
3. Repita com o combo acordado, conferindo quantidade × efeito, limites e ausência de efeito duplicado na reentrega. Compare com os testes locais.
4. Interrompa a rede por um momento e restaure: um comando já conhecido não pode ser reaplicado. Recarregue dentro do fluxo suportado pelo host, confira estado/recibos e siga qualquer orientação para reabrir o jogo.
5. Encerre a interação e confira ended / relaunch_game, cancelamento durante conexão e saída do jogo. Comandos antigos não podem causar efeitos adicionais.

O armazenamento protege apenas o mesmo navegador/origem/conta/jogo. Não oferece recuperação entre dispositivos nem uma economia confiável. Não o limpe durante LIVE. Aos 10.000 recibos, o exemplo para de aceitar comandos novos em vez de apagar resultados antigos. Para recompensas persistentes ou escala de produção, confirme efeito e recibo no seu próprio backend autoritativo e defina retenção com base nos resultados confirmados.

Resolver problemas

Referência do SDK · Conta e idiomas