📄 ゲームマニフェスト仕様書

本ドキュメントは、ひつまぶし（OmoshiroGamePortal） にゲームを掲載・連携するクリエイター向けに、各ゲームの技術特性を宣言するための 「ゲームマニフェスト（manifest.json）」 の公式仕様を定義します。

1. 概要と目的

ポータルサイトでは、日常のクイック対戦（シンプルプレイ）に加えて、「大会モード（1on1トーナメント、1on1総当たり、総合順位グランプリ）」 を提供しています。各ゲームがルートURL直下に manifest.json を公開することで、ポータル側は：

参加人数や選択された大会フォーマットに応じた 「安全に遊べるゲームの自動フィルタリング」 を行います。
チーム戦ゲームを検出し、ロビー画面でのチームスロット配置や teamId の自動注入を行います。
対戦結果（勝者や順位）を共通エンジンで取得し、ブラケット進行や総合順位ポイント集計を行います。
作者（creator）を、カタログ登録の初期値に使います。作者ごとのプレイ実績は、カタログに登録された作者で集計します。

初めての方は Getting Started から読むことをおすすめします。SDK本体のAPIは Hitsumabushi SDK 技術仕様書を参照してください。

💡 カタログ台帳との違い:
manifest.json はクリエイターがゲーム側に配置する技術マニフェストです。ポータル一覧画面での表示テキストやバッジ・テーマカラー・公開状態（active/draft）などのポータル側メタデータは、運営側が管理するゲームカタログ（Cloud Firestore games コレクション）にて管理・設定されます。外部クリエイターがポータルへゲームを掲載する際は、ポータル運営者にゲームURL（および manifest.json）を提出いただくフローとなります。

2. マニフェストの配置とディレクトリ構成

各ゲームのルートディレクトリ（公開URL直下）に静的ファイルとして配置してください。

URL: https://<game-domain>/manifest.json
CORS要件: ポータルからの fetch() を許可するため、Access-Control-Allow-Origin: * を設定してください。

リポジトリ内の置き場所

my-games/
├── package.json         ← 開発用。提出物には含まれない
├── .claude/             ← 同上
└── games/
    ├── my-first-game/
    │   ├── index.html
    │   ├── manifest.json
    │   ├── guide.md
    │   └── game.test.js
    └── my-second-game/
        └── ...

1リポジトリに何ゲーム置いても構いません。 ゲームが1個か複数かは、games/ の下のディレクトリが1個かN個かの違いでしかありません。

CLIは games/*/manifest.json を探して対象を決めます。1個しか無ければ何も指定する必要はなく、複数あるときだけ --game <gameId> で選びます（verify は指定が無ければ全ゲームを検査します）。

ディレクトリ名は manifest.json の gameId と一致させてください。ディレクトリ名がそのまま公開URLになる一方、ポータルのカタログは gameId で引くため、ずれると「デプロイはできているのにカタログから辿れない」状態になります（verify が検査します）。

カード画像（`thumbnail.png`）

ポータルのゲーム一覧とロビーのカードには、manifest.json と同じディレクトリ（games/<gameId>/）の thumbnail.png が表示されます。

形式: PNG。ファイル名は thumbnail.png 固定で、ほかの形式・ファイル名は読まれません。
縦横比: 16:9（推奨 640×360）。カードは 16:9 の枠で表示され、はみ出した部分は切り取られます。
ファイルサイズ: 500KB 以下。
無い場合: カードにはゲームのテーマカラーを使った代わりのアイコンが表示されます。ゲームは動きますが、一覧で見分けにくくなります。

3. マニフェスト JSON スキーマ

📐 型・必須・列挙値・デフォルトの正本は JSON Schema です。 https://milightpartner.jp/schemas/game-manifest-1.json 本書はその意味と運用ルールを説明するものです。フィールドの型や取り得る値について本書とSchemaが食い違う場合は、Schemaを正とします。

記述例（そのままコピーして使えます）

{
  "$schema": "https://milightpartner.jp/schemas/game-manifest-1.json",
  "gameId": "neon-target-rush",
  "title": "ネオン・ターゲットラッシュ",
  "version": "1.0.0",
  "players": {
    "min": 2,
    "max": 4,
    "type": "variable",
    "allowCpuFill": true
  },
  "teamBattle": {
    "supported": true,
    "mode": "two_teams"
  },
  "resultModel": {
    "type": "single_winner",
    "allowTie": false
  }
}

各フィールドの意味は §4 を参照してください。個人戦専用のゲームは teamBattle を省略できます。

3.1 エディタで検証する（推奨）

1行目の "$schema" を書いておくと、VS Code等のエディタが入力補完と検証を行います（追加の設定・パッケージは不要）。フィールド名のタイポ、列挙値の誤り、人数の範囲外、version の形式不正などが、ポータルに提出する前にその場で分かります。

npmパッケージからローカル参照する場合は、インストール済みの実体を指定できます。

{
  "$schema": "./node_modules/@milightpartner/hitsumabushi-sdk/schemas/manifest.schema.json"
}

CIで検証したい場合は、任意のJSON Schemaバリデータ（ajv等）に同じファイルを渡してください。

4. プロパティ定義

4.1 `players`（プレイ人数仕様）

フィールド	型	必須	説明
`min`	number	Yes	最小総プレイヤー人数（1〜8）
`max`	number	Yes	最大総プレイヤー人数（1〜8）
`type`	string	Yes	`"fixed"`（固定人数）または `"variable"`（可変人数）
`allowCpuFill`	boolean	No	ゲームがBot（CPU）思考ロジックをサポートしているか（デフォルト: `false`）。`true` の場合、ホストが空きスロットにCPUを追加可能。

CPU思考ロジックの原則: allowCpuFill: true の場合、CPU思考ロジックは試合進行役（P1）のブラウザ内で実行してください（クリエイターは if (Hitsumabushi.isGameMaster()) の1行分岐で制御）。進行役切断時はノーゲーム扱いとなるため、他プレイヤーへの引き継ぎ処理は不要です。

4.2 `teamBattle`（チーム戦仕様）

個人戦専用ゲームの場合は省略、または null を指定してください。

フィールド	型	必須	説明
`supported`	boolean	Yes	チーム戦をサポートしているか（`true`）
`mode`	string	Yes	チーム戦の形態：`"two_teams"` / `"pairs"` / `"both"` / `"other"`

チーム戦と参加人数のルール（ポータル共通）

奇数人数（3, 5, 7人）: 個人戦のみ選択可能（CPU追加で偶数繰り上がり時はチーム戦可能）。
偶数人数（2, 4, 6, 8人）:
- 4人: 個人戦 / 2人×2チーム (2v2)
- 6人: 個人戦 / 2人×3チーム (2v2v2) / 3人×2チーム (3v3)
- 8人: 個人戦 / 2人×4チーム (2v2v2v2) / 4人×2チーム (4v4)
公式チームID仕様: team_a / team_b / team_c / team_d
- ※試合に出る teamId の組み合わせは決まっていません（2チームの試合でも team_a と team_b とは限りません）。ゲームでのチームの分け方は API リファレンス §3 INIT_GAME を見てください。

4.3 `resultModel`（試合結果の型）

フィールド	型	必須	説明
`type`	string	Yes	`"single_winner"` / `"ranked"` / `"score"` / `"other"`
`allowTie`	boolean	No	同点・引き分けを許容するか（デフォルト: `false`）

"single_winner": 1名（または1チーム）の勝者を返すゲーム。
"ranked": 1位〜N位の順位配列を返すゲーム（4人対戦ボードゲームなど）。
"score": 各自の獲得スコアを返すゲーム。
"other": 勝敗や順位が存在しないゲーム（協力プレイ・コミュニケーション系など）。
- ※大会モードでは自動的に選択肢から除外されますが、シンプルプレイ（単発ルーム）では通常通りプレイ可能です。
allowTie: true を宣言するゲームは、引き分けの報告に Hitsumabushi.sendGameOver({ isTie: true, winnerPlayerId: null, ... }) を使用してください（SDK技術仕様書の sendGameOver 参照）。

4.4 実績（achievements）— 現状マニフェストでは宣言しません

🚧 実績を宣言するフィールドは、現在のマニフェストスキーマには存在しません。追加しないでください（ポータルは未知のフィールドを無視します。またJSON Schemaは未知のフィールドを検証エラーとして報告します）。

SDKには Hitsumabushi.unlockAchievement(achievementId) というAPIが存在しますが、ポータル側に受け口が実装されていないため、現状このAPIは何も行いません。したがって実績ID・表示名・アイコンをポータルへ登録する手段も現状ありません。

実績機能を実装する段階になった時点で、本仕様書に achievements フィールドを追加します（それまでは未サポート）。詳細は SDK技術仕様書の unlockAchievement を参照してください。

4.5 `creator`（作者）

フィールド	型	必須	説明
`creator`	string	No（コミュニティ枠の新規ゲームでは必須）	作者のGitHubユーザー名。

作者を表す値です。どの掲載経路でも書いてください。

ポータル: カタログにゲームを登録するときの作者の初期値に使います。作者ごとのプレイ実績（試合数・プレイ時間・遊んだ人の数）は、カタログに登録された作者で集計します。大会の適合判定やカタログの表示には使いません（表示名は manifest.json には書きません）。
コミュニティ枠: 新規ゲームでは必須です。PR作成者との照合など、書いてよい値の規約は hitsumabushi-community-games の CONTRIBUTING.md が正本です。チーム名（例: milightpartner）で書く方法は、同リポジトリの README.md の「チームでの投稿 (creators.json)」にあります。

旧名の creatorGithub は廃止しました（#618）。書くとスキーマ違反になります。

4.6 各フィールドを誰が読むか

フィールド	読む側
`$schema`	エディタ（補完・検証）
`gameId`	ポータル（manifest のキャッシュ）、`verify`、コミュニティのPR検証
`title`	ポータルのカタログ登録（新しいゲームの名前の初期値）
`version`	スキーマ検証のみ（ポータルは読みません）
`players.min` / `players.max`	ロビー、大会の適合判定、カタログ登録（人数表記の初期値）
`players.type`	ロビー（チームスロットの配置）
`players.allowCpuFill`	ロビー（CPU追加）、大会の適合判定
`teamBattle`	ロビー（チーム編成）、大会の適合判定
`resultModel.type`	大会の適合判定、結果表示
`resultModel.allowTie`	`verify`（引き分けの検査）
`creator`	ポータルのカタログ登録（作者の初期値。計測はカタログの作者を使う）、コミュニティのPR検証、`verify`

5. 既存のゲームから `manifest.json` を起こす

すでに動くゲームがあり、そこからマニフェストを作る場合の手掛かりです。

🤖 AIに解析させる場合の判断基準

人数判定 (players):

プレイヤー管理ロジック（配列長、p1/p2、config.players の参照）から min / max を特定する。

min === max なら "type": "fixed"、幅があれば "type": "variable"。

コード内にCPU/Bot思考ロジックや allowCpuFill らしき処理がない場合は、安全のため一旦 allowCpuFill: false とする。

結果型判定 (resultModel):

Hitsumabushi.sendGameOver() の引数を調べる：

winnerPlayerId を渡している ➔ "single_winner"

rankings（順位配列）を渡している ➔ "ranked"

scores（得点）のみで勝者指定なし ➔ "score"

sendGameOver 自体がない／協力・作業ゲー ➔ "other"

引き分け処理（isTie, winnerPlayerId: null, draw）の有無から allowTie を判定。

チーム戦判定 (teamBattle):

teamId やチームスコアを扱っていれば "supported": true とし、チーム構成から mode（two_teams / pairs / both / other）を判定。個人戦なら省略または null。

gameId & title:

<title> タグ、定数名、ファイル名などから推測。特定困難な場合は仮の名前を入れ、確認を促す。

creator:

コードからは絶対に分かりません。 勝手に埋めず、作者のGitHubユーザー名をユーザーに確認してください。

生成した manifest.json には必ず "$schema" を含め、エディタで検証してください（§3.1）。

6. 大会フォーマットとの適合関係

大会の試合の種目に出せるのは、ポータルが作る試合の席の形で遊べて、勝敗か順位を返すゲームだけです。ポータルはこれをマニフェストだけから決めます（マニフェストが無い、または取れないゲームは候補に出しません）。本節がこの規則の正本です。

6.1 ポータルが作る試合の席の形

N は大会の参加者の数（ソロは人数、ペアはペアの数）です。

	トーナメント・総当たり	総合順位（グランプリ）
ソロ	個人戦・2人	個人戦・N 人
ペア	2チーム × 2人	N チーム × 2人、または個人戦・2N 人

ペアで個人戦のゲームを遊ぶときも、ペアの全員が席に座ります。1on1 のゲームを各ペアの代表者が操作し、相方が相談する形は未実装です（#744）。

6.2 ゲームがその形で遊べる条件

席の形	条件（マニフェスト）
個人戦・k 人	`players.min ≤ k ≤ players.max`、かつチーム戦専用でない
c チーム × s 人	`teamBattle.supported` が `true`、かつ `players` と `teamBattle.mode` から c チーム × s 人が組める（§4.2 の分割ルール）
共通	`resultModel.type` が `"other"` でない

チーム戦専用とは、teamBattle.supported が true で mode が "other" でなく、players.min が4以上で players.type が "fixed" のゲームです。ロビーも同じ定義で、このゲームをチーム戦で始めます。teamBattle.supported は「チーム戦もできる」という意味なので、それだけでは個人戦の候補から外れません。
CPU で補う: ソロのグランプリだけは、N が players.min に届かなくても、allowCpuFill: true なら候補に出ます。ポータルは足りない席に CPU を座らせて min 人にし、CPU が取った順位点は捨てます。トーナメント・総当たり（1対1の形式）と、ペアのグランプリでは CPU を足しません。
チームの数と人数（teamCount / teamSize）は、クリエイターが宣言するフィールドではありません。ポータルが players.min〜max と teamBattle.mode から導きます（実装: packages/hitsumabushi-sdk/src/teamComposition.ts）。

例

ゲーム	ソロのトーナメント	ソロのグランプリ（3人）	ペアのトーナメント	ペアのグランプリ（2ペア）
2人・個人戦	○	×（3人が座れない）	×	×
2〜4人・個人戦	○	○	×	○（個人戦・4人）
4人固定・`allowCpuFill`	×	○（CPU 1人）	×	○（個人戦・4人）
4人固定・チーム戦専用（`two_teams`）	×	×	○	○（2チーム × 2人）

7. クリエイター向け：スタンドアロン起動とポータル起動の両立方法

ゲームアプリを自前WebサイトやGitHub Pages等で単体（スタンドアロン）公開する場合でも、コードを1行フォールバックさせるだけで、ポータル連携と完全両立できます。

Hitsumabushi.init({
  onStartMatch: (config) => {
    // ① ポータルから teamId が渡されていればそれを使う！（ポータル起動時）
    const myPlayer = config.players?.find(p => p.id === config.localPlayerId);
    if (myPlayer?.teamId) {
      setMyTeam(myPlayer.teamId);
      startGameDirectly();
      return;
    }

    // ② 単体起動時や、チーム未指定時はゲーム自前のUIを表示！
    showLocalTeamSelectUI();
  }
});