Créer un jeu interactif TikTok dans Combos

Construisez Gift Arena : le streamer combat un boss, tandis que le public lui offre énergie, soins et attaques. Ce guide fournit le projet complet, un simulateur de cadeaux, la publication sur Combos et les démarches nécessaires aux vrais cadeaux TikTok. Version : Combos SDK 1.1.0.

Jouer à la démo · Télécharger le projet complet

Aucun parcours d’activation de l’interaction TikTok réelle n’est actuellement disponible. Tu peux développer, simuler les cadeaux et publier sur Combos ; un post publié n’active pas les vrais cadeaux. Les éléments d’intégration et la validation LIVE préparent une future activation par la plateforme, pas une demande réalisable aujourd’hui.

1. Déclarer les cadeaux comme effets du jeu

Définissez les règles avant la connexion. Le joueur commence avec 70 PV et 40 points d’énergie ; le boss a 100 PV. Une attaque coûte 10 points d’énergie et inflige 10 dégâts. Si le boss survit, il riposte avec 8 dégâts. Trois effets permettent au public d’aider :

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

Cette déclaration appartient au code de votre jeu. Ce n’est ni un appel d’enregistrement du SDK ni le catalogue TikTok. Batterie, Soin et Éclair sont les noms des effets de l’exemple, pas des noms ou identifiants de vrais cadeaux TikTok. Ne supposez pas qu’une Rose ou un prix donné y correspond automatiquement.

L’exemple accepte des quantités entières de 1 à 1000, plafonne les PV et l’énergie à 100 et limite les PV du boss à 0 au minimum. Les cadeaux ne consomment pas de tour. Un effet plafonné reste un succès même si la valeur n’augmente plus. Après victoire ou défaite, les nouvelles commandes renvoient false jusqu’à la manche suivante. Ce sont des règles du jeu, pas des limites de la plateforme. Définissez aussi le cumul, les délais de recharge, les transitions entre manches et les effets coûteux, puis transmettez ces règles à la personne qui configure les correspondances.

2. Répartir les responsabilités

Spectateur → correspondance de cadeau TikTok → Combos → SDK onCommand → effet du jeu → résultat booléen → Combos → ACK TikTok.

Une interaction configurée peut produire instruction: "gift_flash", count: "3" : le jeu inflige 30 dégâts. count est la quantité de commandes issue de la correspondance, pas un prix en pièces ni nécessairement le nombre de cadeaux. Confirmez aussi la conversion des combos. Le jeu n’a pas à lire launchData, signer des requêtes TikTok, ouvrir son propre WebSocket ou implémenter un webhook.

3. Implémenter le contrat des commandes

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

La commande publique ne fournit ni identifiant de spectateur, ni pseudonyme, ni identifiant du vrai cadeau. Ne construisez pas un classement par spectateur à partir de champs absents.

Renvoyez true après validation de l’enregistrement de l’effet, false pour un refus certain, et levez une exception si le résultat est inconnu, notamment en cas d’échec du stockage. Ce résultat reste sans ACK et peut être renvoyé. Ne transformez pas toutes les erreurs en succès, ni une exécution partielle incertaine en échec déclaré.

Le SDK peut retransmettre les résultats en attente dans le document courant. Le jeu doit aussi gérer le rechargement. L’exemple enregistre l’état du jeu et le résultat du message dans une seule transaction IndexedDB et attend sa validation avant de renvoyer le booléen. Un doublon renvoie le résultat enregistré. Une nouvelle manche conserve les reçus. Les sauvegardes LIVE sont isolées par compte/jeu Combos et séparées de l’entraînement.

Lire l’état de connexion

getTTLiveClient() renvoie un client par document de jeu. getLiveStatus() vérifie l’état ; onStatusChange() émet immédiatement l’état actuel, puis ses changements. Il contient state, reason, action et confirmedAtMs : dernier démarrage/heartbeat confirmé en millisecondes, ou 0 si inconnu.

• connecting : démarrage. connected : session d’interaction confirmée.
• recovering : laisser le SDK reconnecter. unknown : confirmation indisponible, pas une preuve de fin du direct.
• ended : session d’interaction terminée. Suivre action : wait, none ou relaunch_game. Dans ce dernier cas, rouvrir ce jeu depuis LIVE Studio, sans demander de redémarrer le direct pour un simple problème de connexion.

4. Exécuter le projet complet

Préparer et démarrer

Téléchargez et extrayez le ZIP. Un navigateur récent et Python 3 suffisent pour le serveur statique local ; Node et npm ne sont pas nécessaires. Conservez le dossier tiktok-arena intact :

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

Ouvrez http://127.0.0.1:8080/ et choisissez Démarrer l’entraînement. Ne double-cliquez pas sur index.html : les modules nécessitent une origine HTTP. La démo en ligne ne demande aucune installation. Son sélecteur de langue couvre les dix langues du site.

Trois démonstrations reproductibles

Démarrez une nouvelle manche pour chacune des deux premières lignes. La troisième poursuit la deuxième sans réinitialiser. Valeurs initiales : 70 PV, 40 énergie, 100 PV du boss. Chaque bouton de cadeau crée un message ; Répéter le dernier message réutilise son ID.

Essayez aussi 0, 1.5, 1001 et 9007199254740993 : aucun effet et false. Gagnez une nouvelle manche avec Éclair ×10, puis envoyez un nouveau cadeau : il sera refusé jusqu’à la manche suivante. Attaquer et Recharger permettent de jouer le combat normal. Le panneau de réception affiche entrée, résultat et valeurs finales. Ces commandes locales synthétiques n’achètent aucun cadeau et n’envoient aucun ACK TikTok.

5. Connecter le même jeu dans Combos

Conservez connection.js et game.js lors de la publication. Combos injecte window.combos ; aucun package SDK npm ni deuxième script SDK n’est nécessaire. Le bouton Connecter Combos LIVE :

1. Appelle init() et vérifie la capacité getTTLiveSession et le getter du client. Le nom de cette capacité n’est pas une méthode publique à appeler.
2. Exécute checkSession(), puis login() si nécessaire depuis le clic. Une annulation arrête le flux ; une réussite reprend la même action.
3. Utilise getUserInfo() pour isoler la sauvegarde. Ces ID ne constituent pas des identifiants secrets ou une preuve d’autorisation serveur.
4. S’abonne à l’état puis appelle getTTLiveClient().connect({ onCommand }) avec le gestionnaire de l’entraînement.
5. Laisse Déconnecter / annuler disponible pendant les tentatives. L’annulation ou la sortie du document supprime l’abonnement et appelle disconnect().

Le code ci-dessous figure déjà dans le téléchargement ; la version complète actualise aussi l’interface. store.update() est la transaction de storage.js, pas une API 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() peut rester en attente pendant les tentatives. Sa résolution ne prouve pas qu’un vrai cadeau a fonctionné. Les boutons de simulation sont masqués en mode LIVE. Vérifiez l’effet visible et son résultat dans une session enregistrée.

6. Publier sur Combos

Installez le CLI officiel Combos . Cliquez sur Enregistrer la couverture PNG, puis placez cover.png à côté du dossier tiktok-arena. Dans ce dossier parent, exécutez :

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

Terminez la connexion dans le navigateur avec le compte de publication prévu. Ouvrez le lien partagé renvoyé et testez dans le lecteur Combos. Conservez le fichier de liaison combos.json. Depuis le même répertoire, mettez à jour ce post avec :

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

C’est un jeu statique PC en paysage. Le dossier envoyé doit contenir index.html à sa racine et toutes les ressources relatives. La publication n’active pas TT. Un lien partagé normal permet l’entraînement, mais ne crée pas de session réelle sans le contexte de lancement LIVE Studio enregistré. Voir le guide H5.

7. Préparer les éléments d’une future intégration

Aucune entrée d’activation ni procédure confirmée d’intégration réelle n’est actuellement disponible. L’enregistrement du jeu/des comptes et le mappage des cadeaux doivent attendre les consignes de la plateforme ; ni le SDK ni la CLI ne proposent d’API publique d’enregistrement en libre-service. Prépare les éléments suivants pour cette future procédure. Il s’agit d’une préparation, pas d’une inscription ouverte :

Faites confirmer l’entrée exacte de lancement enregistrée, l’éligibilité du jeu et des comptes, ainsi que les correspondances actives avant le test. Les vrais ID, noms et prix viennent du catalogue configuré. Pour une correspondance Éclair ×3 convenue, le jeu doit recevoir :

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

Ne mettez ni secret TikTok, ni token CAS, ni launchData construit manuellement dans le jeu : la plateforme s’en charge. Sans enregistrement, vous avez un jeu Combos publié et un simulateur fonctionnel ; la validation TikTok réelle reste à faire.

8. Valider le vrai LIVE après disponibilité de l’activation

Ces étapes seront exécutables uniquement après la mise à disposition de l’activation et la confirmation de l’entrée du jeu, du compte éligible et du mappage des cadeaux par la plateforme. Pour le moment, réalise la simulation locale et les vérifications de publication ci-dessus ; elles ne constituent pas une validation LIVE réelle.

1. Avec le compte autorisé, ouvrez l’entrée enregistrée dans TikTok LIVE Studio, connectez le jeu et confirmez connected.
2. Avec l’accord du participant, déclenchez une interaction de test configurée. Relevez messageId, instruction/quantité, valeurs avant/après et résultat. Faites confirmer la réception de l’ACK correspondant par le contact d’intégration. Excluez secrets et données personnelles des spectateurs.
3. Testez le combo convenu : quantité × effet, plafonds, absence de double effet lors d’une nouvelle livraison. Comparez aux démonstrations locales.
4. Coupez brièvement le réseau puis rétablissez-le : une commande connue ne doit pas être réappliquée. Rechargez dans le parcours pris en charge par l’hôte et vérifiez état/reçus ; suivez toute demande de relancement.
5. Terminez l’interaction, vérifiez ended / relaunch_game, l’annulation pendant la connexion et la sortie du jeu. Les anciennes commandes ne doivent pas produire un effet supplémentaire.

Le stockage local couvre seulement le même navigateur/origine/compte/jeu. Il n’offre ni reprise entre appareils ni économie fiable. Ne l’effacez pas pendant LIVE. À 10 000 reçus, l’exemple refuse les nouvelles commandes au lieu d’éliminer les anciens résultats. Pour des récompenses persistantes ou une exploitation à grande échelle, validez effet et reçu dans votre propre backend faisant autorité, avec une rétention fondée sur les résultats confirmés.

Résoudre les blocages

Référence SDK · Compte et langues