Ein TikTok-Spiel in Combos entwickeln

Baue Gift Arena: Der Streamer kämpft gegen einen Boss, das Publikum hilft mit Energie, Heilung und Angriffen. Du erhältst das vollständige Projekt, einen Geschenkesimulator, die Veröffentlichungsschritte und die nötige Übergabe für echte TikTok-Geschenke. Grundlage: Combos SDK 1.1.0.

Demo spielen · Vollständiges Projekt herunterladen

Für echte TikTok-Interaktionen gibt es derzeit keinen verfügbaren Freischaltungsprozess. Du kannst lokal entwickeln, Geschenke simulieren und auf Combos veröffentlichen. Ein veröffentlichter Post aktiviert keine echten Geschenke. Die Integrationsunterlagen und LIVE-Abnahme bereiten einen künftigen Plattformprozess vor; sie sind kein heute abschließbarer Antrag.

1. Geschenke als Spieleffekte definieren

Lege die Regeln vor dem Verbindungscode fest. Der Spieler startet mit 70 LP und 40 Energie, der Boss mit 100 LP. Ein Angriff kostet 10 Energie, verursacht 10 Schaden und löst 8 Gegenschaden aus, wenn der Boss überlebt. Drei Effekte helfen dem Spieler:

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

Diese Definition liegt in deinem Spielcode. Sie ist weder ein SDK-Registrierungsaufruf noch ein TikTok-Geschenkkatalog. Batterie, Heilung und Blitz sind Effektnamen des Beispiels, keine echten TikTok-Geschenknamen oder IDs. Eine Rose oder ein bestimmter Preis wird nicht automatisch zugeordnet.

Das Beispiel akzeptiert ganze Mengen von 1 bis 1000, begrenzt LP/Energie auf 100 und Boss-LP nach unten auf 0. Geschenke kosten keinen Zug. Ein begrenzter Effekt gilt auch dann als erfolgreich, wenn der Wert nicht weiter steigen kann. Nach Sieg/Niederlage liefern neue Befehle bis zur nächsten Runde false. Das sind Spielregeln, keine Plattformgrenzen. Definiere auch Kombinationen, Abklingzeiten, Rundenwechsel und aufwendige Effekte und übergib dieselben Regeln an die Person, die die Zuordnung konfiguriert.

2. Zuständigkeiten verstehen

Zuschauer → TikTok-Geschenkzuordnung → Combos → SDK onCommand → Spieleffekt → boolesches Ergebnis → Combos → TikTok-ACK.

Die Zuordnung könnte instruction: "gift_flash", count: "3" erzeugen; das Spiel verursacht 30 Schaden. count ist die zugeordnete Befehlsmenge, kein Münzpreis und nicht zwangsläufig die Anzahl der Geschenke. Kläre auch die Umrechnung von Combos bei der Registrierung. Das Spiel muss weder launchData auslesen noch TikTok-Anfragen signieren, einen eigenen WebSocket öffnen oder Webhooks implementieren.

3. Den Befehlsvertrag implementieren

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

Der öffentliche Befehl enthält keine Zuschauer-ID, keinen Spitznamen und keine echte Geschenk-ID. Darauf lässt sich keine Zuschauer-Rangliste aufbauen.

Gib nach dem Speichern des Effekts true, bei einer sicheren Ablehnung false zurück und wirf einen Fehler, wenn das Ergebnis unklar ist, etwa bei einem Speicherfehler. Unklare Ergebnisse bleiben unbestätigt und können erneut zugestellt werden. Wandle nicht pauschal Fehler in Erfolg oder eine unsichere Teilausführung in einen bestätigten Fehlschlag um.

Das SDK sendet ausstehende Ergebnisse innerhalb des Dokuments erneut. Für Neuladen ist auch dein Spiel verantwortlich. Das Beispiel speichert Spielzustand und Nachrichtenergebnis in einer IndexedDB-Transaktion und gibt den booleschen Wert erst nach deren Abschluss zurück. Duplikate erhalten das gespeicherte Ergebnis. Neue Runden behalten die Belege. LIVE-Spielstände sind nach Combos-Konto/Spiel sowie von der Übung getrennt.

Verbindungsstatus lesen

getTTLiveClient() liefert einen Client je Spieldokument. getLiveStatus() prüft ihn; onStatusChange() meldet sofort den aktuellen Status und anschließend Änderungen. Enthalten sind state, reason, action und confirmedAtMs: zuletzt bestätigter Start/Heartbeat in Millisekunden, 0 bedeutet unbekannt.

• connecting: Verbindungsaufbau. connected: Interaktionssitzung bestätigt.
• recovering: SDK wiederverbinden lassen. unknown: keine aktuelle Bestätigung; der Stream ist damit nicht nachweislich beendet.
• ended: Interaktionssitzung beendet. Folge action: wait, none oder relaunch_game. Bei Letzterem dieses Spiel aus LIVE Studio erneut öffnen; wegen eines Verbindungsfehlers nicht den Stream neu starten lassen.

4. Das vollständige Projekt ausführen

Vorbereiten und starten

ZIP herunterladen und entpacken. Du brauchst einen aktuellen Browser und Python 3 als lokalen statischen Server, weder Node noch npm. Behalte den Ordner tiktok-arena vollständig bei:

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

Öffne http://127.0.0.1:8080/ und wähle Übung starten. index.html nicht doppelklicken: JavaScript-Module benötigen HTTP. Die Online-Demo braucht keine Installation. Das Spiel unterstützt dieselben zehn Sprachen wie diese Website.

Drei reproduzierbare Demos

Beginne jede der ersten beiden Zeilen mit einer neuen Runde. Die dritte setzt die zweite ohne Zurücksetzen fort. Startwerte: 70 LP, 40 Energie, 100 Boss-LP. Jede Geschenkschaltfläche erzeugt eine neue Nachricht; Letzte Nachricht wiederholen verwendet dieselbe ID.

Teste auch 0, 1.5, 1001 und 9007199254740993: kein Effekt und false. Gewinne eine neue Runde mit Blitz ×10 und sende ein weiteres Geschenk: Es wird bis zur nächsten Runde abgelehnt. Spiele mit Angreifen und Aufladen den normalen Kampf. Die Empfangsanzeige zeigt Eingabe, Ergebnis und Endwerte. Diese synthetischen lokalen Befehle kaufen keine Geschenke und senden keine TikTok-ACKs.

5. Dasselbe Spiel in Combos verbinden

Behalte connection.js und game.js bei der Veröffentlichung. Combos stellt window.combos bereit; ein zusätzliches npm-SDK oder zweites SDK-Skript ist nicht nötig. Combos LIVE verbinden führt Folgendes aus:

1. init() aufrufen, Fähigkeit getTTLiveSession und Client-Getter prüfen. Der Fähigkeitsname ist keine direkt aufzurufende öffentliche Methode.
2. Beim Klick checkSession() und gegebenenfalls login() ausführen. Abbruch beendet den Ablauf, Erfolg setzt dieselbe Aktion fort.
3. Mit getUserInfo() den lokalen Speicher trennen. IDs sind keine Zugangsdaten und kein serverseitiger Berechtigungsnachweis.
4. Status abonnieren und getTTLiveClient().connect({ onCommand }) mit dem Handler der Übung aufrufen.
5. Trennen / abbrechen auch bei laufenden Wiederholungen verfügbar halten. Bei Abbruch oder Verlassen des Dokuments abmelden und disconnect() aufrufen.

Der folgende Kern ist im Download enthalten; die Vollversion aktualisiert auch die Oberfläche. store.update() ist die Transaktion aus storage.js, keine SDK-API:

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() kann während Wiederholungen offen bleiben. Ein erfülltes Promise beweist noch keinen funktionierenden echten Geschenkeffekt. Im LIVE-Modus sind die Testschaltflächen verborgen. Prüfe Effekt und Ergebnis in einer registrierten Sitzung.

6. Auf Combos veröffentlichen

Installiere die offizielle Combos CLI . Wähle PNG-Titelbild speichern und lege cover.png neben den Ordner tiktok-arena. Führe im übergeordneten Ordner aus:

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

Melde dich im Browser mit dem vorgesehenen Veröffentlichungskonto an. Öffne den zurückgegebenen Freigabelink und teste im Combos-Player. Behalte die erzeugte Zuordnung combos.json. Aktualisiere denselben Post aus demselben Verzeichnis:

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

Das Beispiel ist ein statisches PC-Spiel im Querformat. index.html muss direkt im Uploadordner liegen, zusammen mit allen relativ verknüpften Ressourcen. Die Veröffentlichung aktiviert TT nicht. Ein normaler Freigabelink erlaubt Übung, erzeugt aber ohne registrierten LIVE-Studio-Startkontext keine echte Sitzung. Details stehen im H5-Leitfaden.

7. Unterlagen für eine künftige Integration vorbereiten

Derzeit gibt es weder einen verfügbaren Freischaltungseinstieg noch einen bestätigten Antragsablauf für echte TikTok-Interaktionen. Spiel-/Kontoregistrierung und Geschenkzuordnung müssen auf Plattformanweisungen warten. SDK und CLI bieten keine öffentliche Selbstregistrierungs-API. Bereite diese Unterlagen für den künftigen Prozess vor. Dies ist eine Vorbereitungsliste, kein offener Antrag:

Lass vor dem Test den genauen registrierten Spieleinstieg, die Berechtigung von Spiel/Konten und die aktive Geschenkzuordnung bestätigen. Echte IDs, Namen und Preise stammen aus dem konfigurierten Katalog. Für die vereinbarte Zuordnung Blitz ×3 sollte das Spiel Folgendes empfangen:

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

TikTok-Geheimnisse, CAS-Tokens und manuell erzeugtes launchData gehören nicht in das Spiel. Die Plattform übernimmt sie. Ohne Registrierung hast du ein veröffentlichtes Combos-Spiel und einen funktionierenden Simulator; die echte TikTok-Abnahme steht noch aus.

8. Echte LIVE-Abnahme nach verfügbarer Freischaltung

Diese Schritte sind erst möglich, wenn die Plattform die Freischaltung bereitstellt und Spieleinstieg, berechtigtes Konto und Geschenkzuordnung bestätigt. Schließe derzeit die lokale Simulation und die Veröffentlichungsprüfungen oben ab; sie ersetzen keine echte LIVE-Abnahme.

1. Öffne mit dem genehmigten Konto den registrierten Einstieg in TikTok LIVE Studio. Verbinde das Spiel und prüfe connected.
2. Löse mit Zustimmung der Testperson eine konfigurierte Testinteraktion aus. Erfasse messageId, Befehl/Menge, Vorher-/Nachherwerte und Ergebnis. Lass den Integrationskontakt das zugehörige ACK bestätigen. Keine Zugangsdaten oder persönlichen Zuschauerdaten protokollieren.
3. Prüfe die vereinbarte Combo-Menge, Menge × Effekt, Grenzen und fehlende Doppelwirkung bei erneuter Zustellung. Vergleiche mit der lokalen Demo.
4. Unterbrich kurz das Netz und stelle es wieder her: bekannte Befehle dürfen nicht erneut wirken. Lade innerhalb des unterstützten Host-Ablaufs neu und prüfe Zustand/Belege; folge einer Aufforderung zum erneuten Start.
5. Beende die Interaktion und prüfe ended / relaunch_game, Abbruch während des Verbindens und Verlassen des Spiels. Alte Befehle dürfen keine zusätzliche Wirkung erzeugen.

Der Browserspeicher schützt nur dasselbe Browser-/Origin-/Konto-/Spiel-Umfeld. Er bietet keine geräteübergreifende Wiederherstellung oder vertrauenswürdige Spielökonomie. Während LIVE nicht löschen. Nach 10.000 Belegen stoppt das Beispiel neue Befehle, statt alte Ergebnisse zu verwerfen. Für dauerhafte Belohnungen oder Produktionslast müssen Effekt und Beleg gemeinsam in deinem maßgeblichen Backend gespeichert werden; die Aufbewahrung richtet sich nach bestätigten Ergebnissen.

Fehler eingrenzen

SDK-Referenz · Konto und Sprachen