Crear un juego de TikTok en Combos

Vamos a crear Gift Arena: el streamer lucha contra un jefe y los espectadores le ayudan con energía, curación y ataques. Recibirás el proyecto completo, un simulador de regalos, los pasos para publicar en Combos y el proceso de registro para los regalos reales. Basado en Combos SDK 1.1.0.

Jugar a la demo · Descargar el proyecto completo

Actualmente no existe un proceso disponible para activar la interacción real de TikTok. Puedes desarrollar, simular regalos y publicar en Combos; un post publicado no habilita regalos reales. Los materiales de integración y la validación LIVE preparan una futura activación de la plataforma, no una solicitud que puedas completar hoy.

1. Declarar los regalos como efectos del juego

Define las reglas antes de conectar. El jugador empieza con 70 de vida y 40 de energía; el jefe tiene 100 de vida. Atacar consume 10 de energía e inflige 10 de daño. Si sobrevive, el jefe contraataca con 8. Estos tres efectos ayudan al jugador:

// 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 },
});

Esta declaración pertenece al código de tu juego. No es una llamada de registro del SDK ni el catálogo de TikTok. Batería, Curación y Destello son nombres de efectos del ejemplo, no nombres ni ID de regalos reales. No supongas que una Rosa o un precio se asignan automáticamente.

El ejemplo admite cantidades enteras de 1 a 1000, limita vida y energía a 100 y la vida del jefe a un mínimo de 0. Los regalos no consumen turno. Un efecto limitado sigue siendo exitoso aunque no aumente más el valor. Tras victoria o derrota, los nuevos comandos devuelven false hasta una nueva ronda. Son reglas del ejemplo, no límites de la plataforma. Diseña acumulaciones, tiempos de espera, transiciones entre rondas y efectos costosos, y comparte las mismas reglas con quien configure el mapeo.

2. Entender las responsabilidades

Espectador → mapeo de regalos de TikTok → Combos → SDK onCommand → efecto → resultado booleano → Combos → ACK de TikTok.

Una interacción configurada puede producir instruction: "gift_flash", count: "3": el juego inflige 30 de daño. count es la cantidad de comandos resultante del mapeo, no el precio en monedas ni necesariamente el número de regalos. Confirma la conversión de combos al registrarte. El juego no necesita leer launchData, firmar peticiones de TikTok, crear otro WebSocket ni implementar webhooks.

3. Implementar el contrato de comandos

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

El comando público no incluye ID o apodo del espectador ni ID del regalo real. No construyas una clasificación por espectador a partir de campos que la API no proporciona.

Devuelve true después de guardar el efecto, false ante un rechazo confirmado y lanza un error si no puedes confirmar el resultado, por ejemplo cuando falla el almacenamiento. Un resultado desconocido queda sin ACK y puede reenviarse. No conviertas todos los errores en éxito ni una ejecución parcial incierta en un fallo confirmado.

El SDK reenvía resultados pendientes dentro del documento. El juego debe cubrir también las recargas. El ejemplo guarda estado y resultado del mensaje en una sola transacción IndexedDB y espera a que se confirme antes de devolver el booleano. Un duplicado devuelve el resultado guardado. Las rondas nuevas conservan los recibos. Los datos LIVE se separan por cuenta/juego de Combos y de los datos de práctica.

Interpretar el estado

getTTLiveClient() devuelve un cliente por documento. getLiveStatus() lo consulta; onStatusChange() emite de inmediato el estado actual y luego los cambios. Incluye state, reason, action y confirmedAtMs: último inicio/heartbeat confirmado en milisegundos; 0 indica desconocido.

• connecting: iniciando. connected: sesión de interacción confirmada.
• recovering: deja que el SDK reconecte. unknown: no hay confirmación actual; no significa que haya terminado la emisión.
• ended: terminó la sesión de interacción. Sigue action: wait, none o relaunch_game. En este último caso, abre este juego de nuevo desde LIVE Studio; no reinicies la emisión por un simple problema de conexión.

4. Ejecutar el proyecto completo

Preparación e inicio

Descarga y extrae el ZIP. Necesitas un navegador actual y Python 3 para el servidor estático local; no hace falta Node ni npm. Conserva completa la carpeta tiktok-arena:

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

Abre http://127.0.0.1:8080/ y pulsa Iniciar práctica. No abras index.html con doble clic: los módulos requieren HTTP. La demo en línea no necesita instalación. Su selector de idioma ofrece los mismos diez idiomas que el sitio.

Tres demos reproducibles

Inicia una nueva ronda para cada una de las dos primeras filas. La tercera continúa la segunda sin reiniciar. Valores iniciales: vida 70, energía 40, jefe 100. Cada botón de regalo crea un mensaje nuevo; Repetir último mensaje reutiliza su ID.

Prueba también 0, 1.5, 1001 y 9007199254740993: sin efecto y false. Gana una ronda nueva con Destello ×10 y envía otro regalo: se rechaza hasta la siguiente ronda. Usa Atacar y Recargar para jugar normalmente. El panel de entrega muestra entrada, resultado y valores finales. Son comandos locales sintéticos: no compran regalos ni envían ACK a TikTok.

5. Conectar el mismo juego en Combos

Conserva connection.js y game.js al publicar. El host inyecta window.combos; no necesitas otro SDK de npm ni cargar un segundo script. Conectar Combos LIVE realiza estos pasos:

1. Llama a init() y comprueba la capacidad getTTLiveSession y el getter del cliente. Ese nombre de capacidad no es un método público que debas invocar.
2. Ejecuta checkSession() y, si hace falta, login() desde el clic. Si se cancela, detiene el flujo; si tiene éxito, continúa la misma acción.
3. Usa getUserInfo() para separar los datos locales. Los ID no son credenciales ni pruebas de autorización del servidor.
4. Suscribe el estado y llama a getTTLiveClient().connect({ onCommand }) con el controlador de práctica.
5. Mantiene Desconectar / cancelar disponible durante los reintentos. Al cancelar o salir, elimina la suscripción y llama a disconnect().

Este núcleo está incluido en la descarga; la versión completa actualiza además la interfaz. store.update() es la transacción de storage.js, no una API del 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() puede seguir pendiente mientras reintenta. Resolver la promesa no demuestra que un regalo real haya funcionado. LIVE oculta los botones simulados. Verifica el efecto y su resultado dentro de una sesión registrada.

6. Publicar en Combos

Instala el CLI oficial de Combos . Pulsa Guardar portada PNG y coloca cover.png junto a la carpeta tiktok-arena. Desde esa carpeta superior, ejecuta:

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

Completa el inicio de sesión en el navegador con la cuenta de publicación prevista. Abre el enlace compartido devuelto y prueba dentro del reproductor de Combos. Conserva la vinculación combos.json generada y actualiza el mismo post desde este directorio:

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

Es un juego estático para PC en horizontal. La carpeta de subida debe contener index.html en la raíz y todos los recursos relativos. Publicar no activa TT. Un enlace compartido normal permite practicar, pero no crea una sesión real sin el contexto de lanzamiento registrado en LIVE Studio. Consulta la guía H5.

7. Preparar materiales para una futura integración

Todavía no hay una entrada de activación ni un proceso confirmado para la integración real. El registro de juego/cuenta y el mapeo de regalos deben esperar las indicaciones de la plataforma; ni el SDK ni la CLI ofrecen una API pública de autorregistro. Prepara estos materiales para el futuro proceso. Es una lista de preparación, no una solicitud abierta:

Antes de probar, solicita confirmación de la entrada de lanzamiento exacta, la elegibilidad del juego y de las cuentas, y el mapeo activo. Los ID, nombres y precios reales proceden del catálogo configurado. Si se acuerda Destello ×3, el juego debe recibir:

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

No incluyas secretos de TikTok, tokens CAS ni launchData construido a mano. La plataforma los gestiona. Sin el registro, tienes un juego publicado y un simulador funcional; la validación real de TikTok sigue pendiente.

8. Validar una LIVE real cuando se ofrezca la activación

Realiza estas etapas solo después de que la plataforma ofrezca la activación y confirme la entrada del juego, la cuenta apta y el mapeo de regalos. Por ahora, completa el simulador local y las comprobaciones de publicación anteriores; no equivalen a una validación LIVE real.

1. Con la cuenta aprobada, abre la entrada registrada en TikTok LIVE Studio, conecta el juego y comprueba connected.
2. Con el consentimiento del participante, activa una interacción de prueba configurada. Registra messageId, instrucción/cantidad, valores antes/después y resultado. Pide al contacto que confirme la recepción del ACK correspondiente. No registres credenciales ni datos personales de espectadores.
3. Repite con el combo acordado: cantidad × efecto, límites y ausencia de efecto duplicado en la reentrega. Compara con las demos locales.
4. Interrumpe brevemente la red y restáurala: el mismo comando conocido no debe ejecutarse otra vez. Recarga dentro del flujo admitido por el host, comprueba estado/recibos y sigue las indicaciones de relanzamiento.
5. Termina la interacción y comprueba ended / relaunch_game, cancelación mientras conecta y salida del juego. Los comandos antiguos no deben añadir efectos.

El almacenamiento solo protege el mismo navegador/origen/cuenta/juego. No proporciona recuperación entre dispositivos ni una economía confiable. No lo borres durante LIVE. A los 10 000 recibos, el ejemplo deja de aceptar comandos nuevos en vez de borrar resultados antiguos. Para recompensas persistentes o escala de producción, confirma efecto y recibo en tu propio backend autoritativo y define la retención según resultados confirmados.

Resolver problemas

Referencia del SDK · Cuenta e idiomas