Combos で TikTok 連動ゲームを作る

Gift Arena を作りましょう。配信者がボスと戦い、視聴者がエネルギー、回復、攻撃のギフトで応援するゲームです。完成したプロジェクト、ローカルのギフトテスト、Combos への公開手順、実際の TikTok 接続に必要な登録まで説明します。対象は Combos SDK 1.1.0 です。

デモを遊ぶ · プロジェクト全体をダウンロード

現在、実際の TikTok 連動を有効にする利用可能な手続きはありません。ローカル開発、ギフトのシミュレーション、Combos への公開は進められますが、公開だけで実際のギフトを受信できるわけではありません。後半の接続資料とLIVE 検証は、将来プラットフォームが接続を開放した際の準備です。現在申し込める手続きではありません。

1. ギフトをゲームの効果として定義する

接続コードより先にルールを決めます。プレイヤーの初期 HP は 70、エネルギーは 40、ボスの HP は 100。攻撃はエネルギーを 10 消費して 10 ダメージを与え、生き残ったボスは 8 ダメージを返します。視聴者の効果は次の 3 種類です。

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

これはゲーム自身のコードに置く定義です。SDK の登録 API でも TikTok のギフト一覧でもありません。電池・回復・閃光はデモの効果名であり、実際の TikTok ギフト名や ID ではありません。「バラ」や特定の価格が自動的に対応するとは考えないでください。

このゲームでは数量を 1〜1000 の整数に制限し、HP とエネルギーの上限を 100、ボス HP の下限を 0 にします。ギフトはターンを消費しません。上限到達で値が増えなくても成功と扱います。勝敗決定後の新しい指令は false となり、次のラウンドで再び受け付けます。これはデモの設計であり、プラットフォームの上限ではありません。自分のゲームでも連続ギフト、クールダウン、ラウンド切り替え、高コスト効果の扱いを決め、設定担当者と共有してください。

2. ゲームとプラットフォームの役割を理解する

視聴者 → TikTok のギフト対応付け → Combos → SDK の onCommand → ゲームの効果 → 真偽値の結果 → Combos → TikTok の ACK。

対応付けの結果が instruction: "gift_flash", count: "3" なら 30 ダメージを与えます。count は変換後の指令数量で、コイン価格や送られたギフト数とは限りません。コンボの数量換算も登録時に確認します。ゲーム側で launchData の解析、TikTok リクエストへの署名、独自 WebSocket、webhook を実装する必要はありません。

3. 受信する指令の契約を実装する

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

公開コマンドには視聴者 ID、ニックネーム、実ギフト ID はありません。存在しないフィールドで視聴者別ランキングを作ることはできません。

効果の保存後に true、確定した拒否には false、結果が不明なら例外を返します。保存障害などの不明な結果は ACK されず、再配信されることがあります。すべての例外を成功に変えたり、部分実行が不明なまま失敗に変えたりしないでください。

SDK は同じページ内で未確認の結果を再送しますが、再読み込み後はゲーム側でも重複を防ぐ必要があります。デモはゲーム状態と実行結果を同じ IndexedDB トランザクションで保存し、コミット後に真偽値を返します。重複時は保存済みの結果を返し、新しいラウンドでも記録を残します。LIVE の保存先は Combos のアカウント・ゲーム別で、練習とも分離されています。

接続状態を読む

getTTLiveClient() はゲームの各ページにつき同じクライアントを返します。getLiveStatus() は現在の状態を確認し、onStatusChange() は現在値を直ちに通知した後、変化を通知します。状態には state、reason、action、confirmedAtMs（直近の起動・ハートビート確認時刻、ミリ秒。0 は不明）が含まれます。

• connecting：接続開始中。connected：連動セッション確認済み。
• recovering：SDK の再接続を待つ。unknown：状態を確認できない。配信終了を意味しません。
• ended：連動セッション終了。action の wait、none、relaunch_game に従います。relaunch_game なら LIVE Studio からこのゲームを開き直すよう案内し、接続障害だけで配信の再起動を求めないでください。

4. 完成したデモを実行する

準備と起動

ZIP を展開します。新しいブラウザーとローカル静的サーバー用の Python 3 が必要です。Node や npm は不要です。tiktok-arena フォルダー構成を保って実行します。

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

http://127.0.0.1:8080/ を開き、練習を開始を押します。JavaScript モジュールには HTTP が必要なので、index.html を直接開かないでください。オンラインデモならインストール不要です。ゲームもサイトと同じ 10 言語に対応しています。

再現できる 3 つのデモ

最初の 2 行は、それぞれ新しいラウンドで開始します。3 行目は 2 行目からリセットせずに続けます。初期値は HP 70、エネルギー 40、ボス HP 100。ギフトボタンは新規メッセージを作り、直前のメッセージを再送は同じ ID を使います。

数量 0、1.5、1001、9007199254740993 も、効果なし・false になることを確認します。新ラウンドで閃光 ×10 を使って勝利した後、新たなギフトは次のラウンドまで拒否されます。攻撃・充電で通常の戦闘も試してください。受信欄で入力、結果、最終値を確認できます。ローカルの合成指令なので、購入も TikTok への ACK 送信も行いません。

5. 同じゲームを Combos 内で接続する

公開時も connection.js と game.js を保持します。Combos が window.combos を注入するので、別の npm SDK や二重の SDK スクリプトは不要です。Combos LIVE に接続ボタンは次を実装しています。

1. init() の getTTLiveSession 機能とクライアント getter を確認。この機能名は直接呼ぶ公開メソッドではありません。
2. ボタン操作から checkSession()、必要なら login()。キャンセル時は停止し、成功時は同じ操作を続行。
3. getUserInfo() で保存先を分離。ID を認証情報やサーバーの認可証明として扱わない。
4. 状態を購読して getTTLiveClient().connect({ onCommand }) を実行。練習と同じハンドラーを渡す。
5. 再試行中も切断 / キャンセルを有効にする。キャンセル・ページ離脱時に購読を解除し disconnect() を呼ぶ。

以下の処理はダウンロードに実装済みです。完全版は画面も更新します。store.update() は storage.js のトランザクションであり、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() は再試行中に待機し続けることがあります。Promise の成功だけで実ギフトの動作は証明できません。LIVE では模擬ボタンを隠し、登録済みセッションで効果と結果の両方を確認します。

6. Combos に公開する

公式 Combos CLI  をインストールします。デモの PNG カバーを保存で cover.png を保存し、tiktok-arena フォルダーと同じ階層に置きます。その親フォルダーで実行します。

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

公開用アカウントでブラウザーログインを完了し、返された共有 URL を開いて Combos プレイヤー内で動作を確認します。生成された combos.json を保持し、同じディレクトリから同じ投稿を更新します。

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

静的な PC 横画面ゲームです。アップロード先フォルダーの直下に index.html と相対参照する全リソースを含めます。公開だけでは TT は有効になりません。通常の共有 URL で練習はできますが、登録された LIVE Studio の起動情報なしに実セッションを作ることはできません。詳細は H5 公開ガイドを参照してください。

7. 将来の接続に必要な資料を準備する

現在、実際の TikTok 連動を有効にする入口や、確定した申し込み手順はありません。ゲーム・アカウントの登録とギフトの対応付けは、プラットフォームの接続案内を待つ必要があります。SDK と CLI に公開のセルフサービス登録 API はありません。以下は将来に備える資料で、現在受け付けている申請ではありません。

テスト前に、担当者から登録済みの正確な起動入口、ゲーム・アカウント資格、ギフト対応付けの完了を確認します。実際のギフト ID・名前・価格は設定済みカタログに従います。閃光 ×3 と合意した場合、受信内容は次のとおりです。

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

TikTok の秘密鍵、CAS トークン、自作の launchData をゲームに入れないでください。プラットフォームが処理します。登録前の成果は「公開した Combos ゲームと動くシミュレーター」であり、実際の TikTok 受入確認は未完了です。

8. 接続開放後に実際の LIVE を検証する

以下を実行できるのは、プラットフォームが有効化手順を提供し、ゲームの起動入口、対象アカウント、ギフトの対応付けを確認した後です。現時点では上記のローカルテストと Combos 公開の確認を進めてください。これらは実際の LIVE 検証の代わりにはなりません。

1. 許可されたアカウントで TikTok LIVE Studio の登録済み入口から起動し、ゲーム内で接続して connected を確認。
2. テスト参加者の同意のもと、設定済みのテストインタラクションを 1 回実行。messageId、指令・数量、効果前後の値、返した結果を記録し、担当者に対応する ACK の受領を確認してもらう。認証情報や視聴者の個人情報は記録しない。
3. コンボ数量、数量 × 効果、上限、再配信時に二重適用されないことをローカル例と照合。
4. 一時的な切断と復帰で同じ指令が再実行されないことを確認。ホストが対応する起動手順内で再読み込みし、状態と記録の復元を確認。再起動の指示があれば従う。
5. 終了後の ended / relaunch_game、接続中のキャンセル、ページ離脱を確認。古い指令で追加効果が起きないことを確かめる。

ブラウザー保存は同じブラウザー・オリジン・アカウント・ゲーム内に限られます。端末間の復元や信頼できる報酬管理は提供しません。LIVE 中に削除しないでください。10,000 件で古い結果を捨てず新規指令を停止します。永続報酬や本番規模では、効果と結果を自分の信頼できるバックエンドで同時に確定し、確認済みの結果に基づいて保存期間を決めます。

問題の切り分け

SDK リファレンス · アカウントと言語