🚀 Getting Started

ひつまぶし（OmoshiroGamePortal）向けのゲームを1本、インストールから公開まで作りきるための手順書です。 上から順に実行してください。仕様の正本は各所からリンクしている仕様書で、本書は手順だけを扱います。

やることは4つです。

1. インストールする
2. AIにゲームのルールを伝える
3. 出来上がったものを確認する
4. 公開する

実装そのものはAIに任せられます。人間がSDKの仕様を読んでコードを書く必要はありません。

1. インストールする

1-1. ディレクトリを作る

mkdir my-game && cd my-game

このディレクトリ名がそのままゲームID（gameId）になり、公開URLになります。 半角英数小文字とハイフンで付けてください。大文字・スペース・アンダースコアは kebab-case に倒されます（My_Game → my-game）。英数字を含まない名前（日本語のみなど）では次の手順で落ちるので、その場合は init に --game <id> を付けて明示します。

1-2. 認証を設定する

⚠️ 現在このパッケージは未公開のため、この手順なしでは install できません。公開後はこの節ごと不要になります。

GitHub の Settings → Developer settings → Personal access tokens で read:packages スコープのPATを発行し、 いま作ったディレクトリの直下に .npmrc を置きます（~/.npmrc への追記でも構いません）。

@milightpartner:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}

発行したトークンを環境変数にセットします。

export GITHUB_PACKAGES_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Organization外のメンバーやリポジトリへの個別の権限付与、GitHub Actions からの利用は インストールガイド にあります。

1-3. リポジトリ一式を作る

1-1 で作ったディレクトリで実行します。

npx -p @milightpartner/hitsumabushi-sdk hitsumabushi init
npm install

こうなります。

├── games/my-game/
│   ├── index.html      ← ゲーム本体の雛形
│   ├── manifest.json   ← プレイ人数・結果の型の宣言
│   ├── guide.md        ← 解説記事（ルール。必須）
│   └── game.test.js    ← 試合が最後まで進むかのテスト
├── package.json        ← dev / verify / test の scripts 入り
└── .claude/skills/hitsumabushi-game-developer/   ← AI開発Skill

ゲームは常に games/<gameId>/ に置き、1リポジトリに複数のゲームを置けます。既にあるファイルは上書きされません。

manifest.json は gameId がディレクトリ名と一致した状態で生成されます（ディレクトリ名が公開URLになる一方、ポータルのカタログは gameId で引くため、この2つは常に一致している必要があります）。中身 — プレイ人数・チーム戦・引き分けの有無 — はこのあとAIが書くので、いま触る必要はありません。

生成された index.html は、SDKを公開URLの <script> タグで読み込みます。URL にはインストールした SDK の版が入っていて（https://milightpartner.jp/sdk/<version>/hitsumabushi-sdk.js）、本番でもその版が読まれます。

• バンドラもビルド工程も要りません。 静的ホストにそのまま置けます
• 開発ハーネス（npm run dev）でも、デプロイした本番でも、同じ記述のまま動きます

⚠️ この行は、版の部分以外を書き換えないでください。 ローカルでしか解決できないパス（開発ハーネスが配信する /__hitsumabushi_dev__/* など）に変えると、本番で404になりゲームが一切反応しなくなります。SDK を更新するときは、版の部分を新しい版に書き換えます（規則は API リファレンス §1）。

1-4. 動くことを確かめる

npm test
npm run verify

この時点で両方通ります。 通らない場合は認証か npm install が失敗しているので、先へ進まずに解決してください。

--game / --template などのオプションは CLI リファレンス にあります。

2. AIにゲームのルールを伝える

リポジトリを Claude Code で開き、作りたいゲームのルールを伝えてください。

3×3の三目並べを作って。先手が○、後手が×。縦横斜めのどれかが揃ったら勝ち、埋まったら引き分け。

これだけです。init が置いた .claude/skills/hitsumabushi-game-developer/ から、AIが通信仕様・manifest.json の書き方・モバイル要件・テストの書き方を自分で参照します。人間がSDKの仕様を説明する必要はありません。

AIが書き換えるのは基本的にこの4つです。

ファイル	中身
games/<gameId>/index.html	ゲーム本体。Hitsumabushi.init() の中身が埋まります
games/<gameId>/manifest.json	プレイ人数・チーム戦・引き分けの有無の宣言
games/<gameId>/game.test.js	試合が最後まで進むかのテスト
games/<gameId>/guide.md	ゲームのルールを伝える解説記事（必須）。コミュニティ枠に提出すると https://guide.milightpartner.jp/<gameId>/ に公開され、quickRules はゲーム画面のルールパネルに出ます

思うように進まないとき、人間が読むものはこれです。

• Hitsumabushi SDK 技術仕様書 — JS API と postMessage 通信プロトコル
• ゲームマニフェスト仕様書 — manifest.json の全プロパティ
• ポータル制約仕様書 — 画面・入力・通信・音声で守ること

3. 出来上がったものを確認する

3-1. 機械で検査する

npm run verify
npm test

verify は manifest.json の適合・モバイルUX・通信制約・起動確認をまとめて検査し、結果を終了コードで返します。ブラウザを開く必要はありません。

終了コード1になるのは fail（本番で壊れる項目）だけです。⚠ warn は実害のない指摘なので終了コードには影響しませんが、内容は確認してください。

⚠️ skip は「問題なし」ではなく「このツールは何も言っていない」という意味です。 何がどこまで機械で確かめられるかは 検証ガイド にあります。

3-2. ブラウザで対戦してみる

npm run dev

表示されたURLを開くと、manifest.json の宣言に沿った人数分の <iframe> が並び、実際のポータルと同じ INIT_GAME の注入と GAME_DATA_RELAY の相互中継が行われます。観戦者の追加・OBSモードの切り替え・リマッチ（onStartMatch の再実行）も確認できます。ポータル本体のクローンも起動も、ゲームカタログへの登録も不要です。

ビルド成果物を配信する場合は npm run dev -- --dir dist です（CLI リファレンス）。

3-3. 人間の目で確認する

verify も同梱テストも、画面の見え方と手触りは見ていません。残りを3段階に分けて確認します。全項目は 検証ガイド §5 にあります（🤖 が付いているものは verify が見ているので、人間が見るのは残りです）。

a. ブラウザのデバイスモードで見る

npm run dev を開いた状態で、DevTools のデバイスモードを狭い画面（iPhone SE など）に切り替えます。§5 の大半はここで足ります。

• タッチターゲットが 44 × 44 px 以上あるか
• 画面の高さ・幅が変わってもレイアウトが破綻しないか
• 狭い画面でボタンをアイコンにした場合も 44px を保っているか
• ランドスケープ専用ゲームなら、ポートレートで回転案内が出るか

b. ポータルの外で開く

index.html を直接開きます。onStartMatch が呼ばれないので、ゲーム自前のUI（ローカル対戦・チーム選択画面など）にフォールバックする必要があります。実装例は ゲームマニフェスト仕様書 の「スタンドアロン起動とポータル起動の両立方法」の節にあります。

c. スマートフォン実機で開く

--host を付けると、同じWi-Fiのスマートフォンから開けるURLが表示されます。

npm run dev -- --host

Hitsumabushi dev harness running at http://localhost:4000/?entry=...
  Network: http://192.168.1.23:4000/?entry=...   ← これをスマホで開く

デバイスモードでは分からないものが3つ残ります。

見るもの	なぜ実機が要るか
BGM・効果音がユーザー操作を契機に鳴るか	iOS Safari の自動再生ポリシーがデスクトップと違う
アドレスバーの伸縮でレイアウトが崩れないか	100vh が実機だけスクロールで変わる
実際に指で押せるか	44px は最低ライン。親指の届く範囲は別の話

4. 公開する

作ったゲームをポータルに載せる経路は2つあります。どちらも開発は同じで、違うのは提出の仕方だけです。

	提出先	誰が
コミュニティ枠	hitsumabushi-community-games にPR	誰でも
認定クリエイター枠	自分でデプロイし、ポータル運営にカタログ登録を依頼	認定を受けたクリエイター

コミュニティ枠へPRを出す

投稿リポジトリは 提出専用で、開発環境ではありません。自分のリポジトリで開発し、成果物だけを持ち込みます。

1. npm run verify を実行し、fail が無いことを確認する
2. manifest.json に "creator": "<あなたのGitHubユーザー名>" を足す（新規ゲームでは必須）
3. カード画像 games/<gameId>/thumbnail.png を置く。640×360（16:9）の PNG で、500KB 以下にする。npm run dev で開いたゲーム画面のスクリーンショットが手軽です
4. hitsumabushi-community-games を Fork し、games/<gameId>/ を丸ごとコピーする（*.test.js は不要）
5. PRを送る

ディレクトリ構成は開発リポジトリと投稿リポジトリで同じ games/<gameId>/ なので、パスの読み替えは要りません。開発用のファイル（package.json / node_modules/ / .claude/）はリポジトリ直下にあり、games/<gameId>/ には元から入らないため、選別の判断も要りません。

投稿PRはCIで自動検証されます。主なルール:

• games/<あなたのgameId>/ 配下以外は変更できない（リポジトリ直下の設定ファイルを触るPRは弾かれます）
• 1つのPRで扱えるのは1ゲームのみ
• gameId はディレクトリ名と一致し、kebab-case であること
• creator はPR作成者と一致し、一度設定したら変更できない（なりすまし防止）
• 開発ハーネス専用パス /__hitsumabushi_dev__/ を参照していないこと

このうち gameId の一致・kebab-case・ハーネス専用パスは npm run verify が先に検出します。 creator とカード画像の有無は ⚠ warn として報告されます（無くてもゲームは動くため fail にはしません）。

規約の正本は投稿リポジトリの CONTRIBUTING.md です。本書と食い違った場合はそちらが優先されます。

---

次のステップ

• 🔌 Hitsumabushi SDK 技術仕様書 — JS API・通信プロトコルの完全リファレンス
• 📄 ゲームマニフェスト仕様書 — manifest.json の全プロパティ定義
• 📱 ポータル制約仕様書 — 画面・入力・通信・音声で守ること
• ✅ 検証ガイド — 何がどこまで機械で確かめられるか
• 🛠 CLI リファレンス — init / dev / verify の全オプション
• 🤖 既存のゲームから manifest.json を起こす — ソースコードから各項目を判定する手掛かり