sf6-battlegraph

Live demo

安定版Chrome拡張は最新のGitHub Releaseからダウンロードできます。変更履歴はCHANGELOGを参照してください。

Street Fighter 6 の Buckler's Boot Camp から自分のバトルログを取得し、長期間保存してグラフや集計として閲覧するためのセルフホスト型 Web アプリケーションです。

Buckler で参照できる対戦履歴には件数上限があるため、定期的に履歴を取り込み、過去の試合を失わずに蓄積することを目的としています。

v1.1.1を最新の安定版として公開しています。Chrome拡張からBucklerの総合履歴を直接取得し、検証、replay_idによる重複排除、対象プレイヤー基準の正規化、Firestore同期までをボタン一回で実行できます。保存後は期間・Act・実際の対戦モード・使用キャラクターによる絞り込み、保存済みバージョンが複数ある場合のゲームバージョン絞り込み、全期間の戦績集計、1P・2P別勝率、直近14日の日別記録、キャラクター別のランクマッチにおけるLP/MR直近100試合を表示します。Actはuploaded_atとメンテナンス終了日時から判定します。LP/MRの初期対象は、最新のランクマッチで使用したキャラクターです。

現在のデフォルト対象はユーザーコード1134991793です。環境変数を変更すれば、cloneした利用者が自身のユーザーコードとFirebaseプロジェクトでセルフホストできます。

1. FirebaseプロジェクトでWebアプリ、Cloud Firestore、Google Authenticationを有効にする
2. firestore.rulesをFirebase ConsoleまたはFirebase CLIで対象プロジェクトへ反映する
3. .env.exampleを.env.localへコピーし、自分のユーザーコード、Firebase Web設定、配信originを入力する
4. npm run devでBattlegraphを開いてGoogleログインし、Firebase ConsoleのAuthentication → Usersで自分のUIDを確認する
5. そのUIDと同じdocument IDでadmins/{uid}をFirestore Consoleから作成し、Battlegraphを再読み込みする
6. npm run buildを実行し、dist/extensionをChromeへ読み込む
7. Battlegraphの「Bucklerから再取得・同期」を押す

Chrome拡張の詳しい導入・更新方法はChrome connectorを参照してください。

Node.js 26以降を使用します。Firestore Security RulesのテストにはJava 21以降も必要です。

npm install
npm run dev

検証コマンド:

npm run check
npm test
npm run test:rules
npm run typecheck
npm run build

コード整形にはnpm run format、変更を加えないフォーマット・Lint検査にはnpm run checkを使用します。開発規約と変更手順はContributingを参照してください。

管理者ログイン後にChrome拡張から受信したbundleを検証し、既存履歴とreplay_idで統合して、raw snapshot、完全な試合、全履歴のquery chunk、manifestをFirestoreへ同期します。次回以降はprivate構成では管理者ログイン後、public構成ではページ表示時に保存済み戦績を自動表示します。日常の同期にJSONファイルのダウンロードや選択は必要ありません。

管理者は画面上部の「全データをバックアップ」から、Firestoreに保存したplayer、完全match、raw snapshot/page/part、query chunk、manifest、sync記録を単一JSONへ書き出せます。バックアップ時だけ全対象documentを読み取るため、実行前に確認画面を表示します。ダウンロード前に必須document、対象ユーザー、パス重複、rawのバイト数とSHA-256、分割partの連続性を検証します。

「バックアップを復元」では検証済みJSONだけを同じユーザーコードへ復元します。既存documentを一括削除せず、同じパスをmerge更新します。データ層を最大450 writeずつ保存し、すべて成功した後にmanifestを最後に切り替えます。

Firebaseを接続する場合は.env.exampleを.env.localへコピーし、Firebase Consoleで登録したWebアプリの設定と対象ユーザーコードを入力します。

cp .env.example .env.local

Google認証をFirebase Consoleで有効にし、Authenticationの承認済みドメインへローカル開発用のlocalhostと、デプロイ先の<account>.github.ioを登録してください。管理者として利用するAuthentication UIDと同じIDで、Firestoreにadmins/{uid}ドキュメントをFirebase Consoleから作成します。管理者ドキュメントをアプリ自身が新規作成する機能はありません。

設定項目:

• VITE_PLAYER_USER_CODE: 保存対象のSF6ユーザーコード
• VITE_DEPLOYMENT_VISIBILITY: privateまたはpublic
• VITE_CONNECTOR_ORIGINS: Battlegraphを配信するoriginをカンマ区切りで指定（パス不可）
• VITE_FIREBASE_API_KEY
• VITE_FIREBASE_AUTH_DOMAIN
• VITE_FIREBASE_PROJECT_ID
• VITE_FIREBASE_APP_ID

Firebase Web設定はブラウザへ配信される公開設定です。サービスアカウント鍵や秘密鍵は使用しないでください。

npm run buildはWebアプリに加えて、Buckler上で自動実行するdist/extensionと配布用dist/sf6-battlegraph-connector-v<version>.zipを生成します。ZIP名と展開後の単一フォルダ名は同じです。導入手順はChrome connectorを参照してください。

masterへのpush時にGitHub Actionsがテスト、Firestore Security Rulesテスト、型検査、本番ビルドを行います。Pagesへのデプロイを有効にする場合は、GitHub上でリポジトリの Settings → Pages → Build and deployment → Source を GitHub Actions に設定し、Settings → Secrets and variables → Actions → Variables にENABLE_PAGES_DEPLOY=trueを追加してください。

ENABLE_PAGES_DEPLOYが未設定の間は検証だけを実行し、Pages jobはスキップします。privateリポジトリでPagesを利用できない期間もCIを成功状態に保てます。

Pagesを有効にする前に、同じRepository Variables画面へ以下も設定します。これらはFirebase Webクライアントへ配信される公開設定であり、Secretsへ入れる必要はありません。

VITE_PLAYER_USER_CODE
VITE_DEPLOYMENT_VISIBILITY
VITE_FIREBASE_API_KEY
VITE_FIREBASE_AUTH_DOMAIN
VITE_FIREBASE_PROJECT_ID
VITE_FIREBASE_APP_ID
VITE_CONNECTOR_ORIGINS

ENABLE_PAGES_DEPLOY=trueなのに必須変数が不足している場合、workflowはFirebase未接続のartifactを公開せず、検証jobを失敗させます。

Pull Requestでは検証だけを行い、Pagesへのデプロイは行いません。Actions画面から手動実行することもできます。

公開時はVITE_CONNECTOR_ORIGINS=https://<account>.github.ioを設定し、リポジトリをpublicへ変更してからPagesのSourceをGitHub Actionsへ切り替え、最後にENABLE_PAGES_DEPLOY=trueを設定する。この順序なら、private期間中に公開用artifactを誤ってデプロイしない。

GitHub FreeでPagesを無料利用する場合、リポジトリをpublicにする必要があります。privateのままPagesを利用できるかはGitHubの契約プランに依存します。

• ランク、カジュアル、ルーム、バトルハブを含む全対戦モードを保存する
• Buckler の取得レスポンスを欠損なく保存する
• 1試合単位の履歴を欠損なく保存する
• 日付、使用キャラクター、モードで絞り込む
• 日本語と英語を切り替えて利用できる
• LP / MR 推移、勝率、キャラクター別戦績などをブラウザで集計する
• GitHub Pages と Firebase の無料枠で個人運用できるようにする
• リポジトリを公開した際に、各利用者がcloneしてセルフホストできるようにする

Buckler's Boot Camp
  └─ Chrome connector
       ├─ 現在の Next.js buildId を取得
       ├─ 全モード合算履歴の全ページを取得
       └─ bundleをBattlegraphへ直接送信
                    │
                    ▼
GitHub Pages
  └─ React SPA
       ├─ Firebase Authentication
       ├─ origin検証とbundle検証
       ├─ 試合データの正規化
       ├─ Firestore への同期
       └─ JavaScript による集計とグラフ表示
                    │
                    ▼
Cloud Firestore
  ├─ raw snapshots
  ├─ normalized matches
  ├─ query chunks
  └─ manifests

現在の技術構成は次のとおりです。

• React
• TypeScript
• Vite
• Firebase Authentication
• Cloud Firestore
• Vitest
• GitHub Pages
• GitHub Actions

GitHub Pages は静的ホスティングであるため、Buckler の取得処理をサーバーとして配置しません。Battlegraphから開いたログイン済みBucklerページ上でコレクターを実行し、取得bundleをファイルを介さず起点の画面へ返します。Buckler の Cookie や CAPCOM ID の認証情報はアプリ、Firestore、GitHub Secretsへ保存しません。

詳細は以下を参照してください。

• Architecture
• Chrome connector
• Collector export format
• Data model
• Decisions and validation
• Release procedure
• Repository instructions for Codex
• Contributing and coding conventions

デプロイごとに次の2モードを選択できます。

• private: 管理者だけが読み書きできる
• public: 誰でも読み取れ、管理者だけが書き込める

Buckler の raw レスポンスには Cookie やアクセストークンを含めません。raw データも保存対象かつ公開可能なデータとして扱いますが、通常画面では通信量と Firestore の読み取り数を抑えるため読み込みません。

認証情報、Firebase サービスアカウント鍵、Buckler Cookie、個人用エクスポートはリポジトリへコミットしません。

Buckler は Next.js の JSON エンドポイントを使用しています。URL に含まれる buildId はデプロイごとに変わる可能性があるため固定せず、Buckler ページの __NEXT_DATA__.buildId から取得します。

Bucklerの総合履歴は全対戦モードを合算した直近100試合を返すものとして扱い、コレクターは総合履歴の全ページだけを取得します。取得元はallですが、各試合のモードはレスポンス内のbattle type IDと名称からランク、カジュアル、ルーム、バトルハブへ正規化します。未知の種別はunknownとして完全データとrawへ保持します。

Firestore に多数の事前集計を作るのではなく、軽量な試合データを複数試合単位の queryChunks にまとめ、ブラウザの JavaScript で集計します。

1試合1ドキュメントを全件読む方式と比べてFirestoreの読み取り数を抑えながら、集計軸を後から柔軟に追加できます。通常画面はquery chunkだけを読み、完全な試合とraw responseはバックアップ、再解析、障害調査のために保存します。

MIT