8. トラブルシューティングと FAQ

よくある質問を、新規ユーザーがぶつかりがちな順に並べています。ここに載っていない問題は、サービスリファレンスを確認してください — すべてのサービスに「Gotchas」セクションつきの専用ページがあります（同じページがプロジェクト内の Documentation/Modules/ にも同梱されています） — または、お問い合わせください（8.9 節）。

8.1 「パッケージをインポートしたのに、シーンに何も現れない」

それは仕様です。このフレームワークはコードであって、シーンオブジェクトではありません — 配置するプレハブも、設定するマネージャーもありません。Play を押した瞬間に自分で起動します。動作を確かめるには:

• Welcome ウィンドウを開きます: Tools > Common Game System > Welcome（Window > Common Game System > Welcome の下にもあります）。インポート後に一度だけ自動で開き、どちらのメニュー項目からもいつでも呼び戻せます。
• そのウィンドウ上部の Open Demo Scene をクリックして Play を押します。Motion Lab デモが、トゥイーン、タイマー、ポーズに影響されないクロックシステムを、セットアップなしでその場で見せてくれます。
• あるいは、どのシーンでもいいので Play を押し、Console に bootstrap complete (v2.1.0, 23 services) という行が出ているか確認してください。

8.2 「新しい Input System のためにエディタが再起動を求めてきた」

「はい」と答えてください。Unity は、プロジェクトが初めて Input System パッケージを有効化するときにこのプロンプトを表示します — 入力バックエンドは再起動時にしか切り替えられないためです。再起動でプロジェクトとパッケージが影響を受けることはありません。再起動後も Welcome ウィンドウは上記の 2 つのメニューから開けますし、すべては中断したところから続きます。

8.3 「デモやサンプルがマウスとキーボードを無視する」（コンソールで Enter を打っても何も起きない）

プロジェクトがまだ「旧」入力バックエンドで動いています。Input System パッケージをインストールしてもバックエンドは切り替わらず、新規プロジェクトでは "Input Manager (Old)" のままです — そのため、デモシーン、UI サンプル、コマンドコンソールは、何のエラーも出さずに入力を一切受け取れなくなります。

修正はワンクリックです: この状態のとき、Welcome ウィンドウには Enable the new Input System (restarts the editor) ボタンつきの黄色い警告が表示されます。クリックして、エディタを再起動させてから、もう一度 Play を押してください。手動で行う場合は: Edit > Project Settings > Player > Other Settings > Active Input Handling → "Input System Package (New)" または "Both" を選び、エディタを再起動します。

再起動は必須であって、任意ではありません: 設定を変更した後でも、実行中のエディタセッションは旧バックエンドのままである可能性があります。入力がまだ死んでいるように見えるなら、他のデバッグを始める前にエディタを再起動してください。

8.4 「デモシーンが見つからない」

Motion Lab デモは、ボタンとスライダーのために Unity 組み込みの uGUI パッケージ（com.unity.ugui）を必要とします。このパッケージがプロジェクトから削除されていると、デモのスクリプトは自らコンパイル対象から外れるため、シーンは実行できません。Package Manager から uGUI を再インストールすればデモは戻ってきます。どちらの場合でもフレームワーク本体は影響を受けません — uGUI がなくてもすべてのサービスが起動して動作します（第 7.2 章を参照）。

8.5 「エディタではセーブできるのに、IL2CPP ビルドではセーブが消える」

セーブ用のクラスがビルドからストリップされています。IL2CPP は未使用に見えるクラスを除去しますが、シリアライズのためだけに存在するクラスは、まさに未使用に見えてしまいます。Assets/ 配下に、セーブデータクラスを列挙した link.xml ファイルを追加してください — コピー＆ペーストできるファイルつきの完全なレシピは第 6.3 章にあります。カスタム設定グループにも同じ修正が有効です。

8.6 「2,600 以上の自動テストはどこにありますか?」

意図的に隠してあります。2,600 以上の自動テストのスイートは、Unity がインポートしないフォルダの中に同梱されており、プロジェクトのコンパイル時間を増やすことも散らかすこともありません。自分で実行するには: Welcome ウィンドウを開き、フッターの Import framework tests をクリックしてください。テストは Unity の Test Runner（Window > General > Test Runner）に現れます。これは完全に任意です — スイートはリリース前にすでに全件パスしています。完全な手順は第 3.4 章を参照してください。

8.7 「URP、HDRP、ビルトインレンダラーで動きますか?」

はい、3 つすべてで動きます。このフレームワークは何も描画せず、シェーダーもマテリアルもレンダーパイプラインのコードも一切含みません。提供するのはロジックです: セーブ、時間管理、イベント、入力ルーティング、オーディオミキシングなどのサービスです。ゲームを何が描画していようとフレームワークからは見えないので、パイプラインのアップグレードがフレームワークに触れることはありません。

8.8 「コンソールに Unknown action map 'ui.panel' と出る」

UI パネルスタックがメニュー用の入力マップを有効化しようとしましたが、あなたの入力アセットにそれらが定義されていません。.inputactions アセットに、正確に ui.panel と ui.modal という名前（小文字、ドットつき）のアクションマップを 2 つ追加し、第 6.2 章の手順どおりにアセットを接続してください。

8.9 ヘルプを利用する

• メール: yoop80075@gmail.com — Unity のバージョンと、あれば bootstrap complete で始まる Console の行を添えてください。
• このマニュアル: パッケージ内の Documentation/CGS-Manual.pdf として同梱され、オンラインでは Getting Started から読めます。
• サービスリファレンス: サービスごとに平易な言葉で書かれた 1 ページ — オンラインではドキュメント索引、プロジェクト内では Documentation/Modules/ 配下（例えば Modules/SaveLoad.md） — それぞれに完全な API、動作するサンプル、既知の注意点を掲載しています。
• 変更履歴: パッケージルートの CHANGELOG.md に各バージョンの変更点が記載されています。
• クイックリンク: Welcome ウィンドウのリンク列（Manual、Documentation、Changelog、Module Reference）から上記のすべてを直接開けます。