Unity プラグインの導入方法

Playable!Mobile（P!M）は、ゲーム側に組み込んだ Playable!Mobile Unity Plugin と通信して動作します。プラグインが入っていないゲームへは接続できません。ここでは、その組み込み手順を上から順に説明します。

  • 対象：ゲームの開発担当者
  • 所要時間の目安：15〜30 分
  • 必要なもの：Unity プロジェクトの編集権限

この作業は、ゲームの Unity プロジェクトを編集できる方が行います。テスト実施者（QA 担当）だけでは完了できません。P!M 側の導入・接続手順は、配布フォルダの documentation に同梱している「ユーザー向けマニュアル」をご覧ください。

プラグインは、ゲーム開発・テスト用です。製品として出荷するビルドには含めない設定にしてください（「3. ビルドで有効にする」を参照）。

導入の流れは、配布物からプラグインを取得 → Packages へ配置 → ビルド設定で有効化 → P!M から接続確認、の 4 段階です。

1. 最初に確認する

プラグインの入手先

プラグインは、P!M の配布フォルダに同梱されています。EXE と同じ階層の unity-plugin フォルダです。

Playable!Mobile-v<version>\
├─ Playable Mobile General Agent.exe
├─ unity-plugin\
│  └─ PlayableMobilePlugin\       ← このフォルダをそのまま使います
│     ├─ package.json
│     ├─ com.aiqveone.playable-mobile.asmdef
│     ├─ link.xml / LICENSE.md
│     ├─ Core\ / Net\ / Commands\ / Interaction\ / Observation\   （C# ソース）
│     └─ （各ファイルの .meta）
├─ excel-templates\
└─ documentation\                  ← マニュアル一式

フォルダは完成形です。C# ソース、package.json、アセンブリ定義（.asmdef）、.meta まで同梱しているので、中身を組み替えたりファイルを作成したりする必要はありません。Resources の設定アセットだけは任意で、ポートを変えたい場合に「4. ポートと入力方式を合わせる」で作成します。

プラグインの仕様

項目 内容
パッケージ名／版 com.aiqveone.playable-mobile ／ v3.0.0（表示名 Playable!Mobile Unity Plugin）
Unity バージョン 2020.3.48f1 以上（動作確認済み：2022.3.4f1／6000.5.4f1）
対応 UI 主対象は uGUI（Unity UI） です。加えて、Collider／Collider2D を持つオブジェクトと SpriteRenderer も画面情報として取得できます（操作の効き方は下記「操作の届き方」を参照）。UI Toolkit 製の画面は取得・操作とも対象外です。
操作の届き方 uGUI の部品へはイベントを直接配送するため確実に反応します。uGUI 以外（Collider・Sprite）へのタップと、なぞり操作（多点経路ドラッグ。PathDrag）は画面座標への合成タッチとして送るため、ゲーム側がその入力を読んでいれば反応します。合成タッチには Input System の有効化（Active Input Handling が Input System Package (New) または Both）が必要で、Input Manager (Old) のみの構成では uGUI 以外は反応しません。2 点間のドラッグ・スワイプは uGUI の部品にのみ届きます。
役割 ゲーム側が TCP サーバになり、P!M 側がクライアントとして接続します（既定ポート 8001）。

必要な依存パッケージ

次のパッケージが同じ Unity プロジェクトに入っている必要があります。未導入の場合は Package Manager から追加してください。

パッケージ 要件 用途
com.unity.ugui 1.0.0 以上 uGUI 要素の取得と操作
com.unity.nuget.newtonsoft-json 3.0.2 以上 P!M とやり取りする JSON の解析
com.unity.textmeshpro 1.0.0 以上 TextMeshPro のテキスト取得・入力

プラグインを組み込むのはテスト用のブランチまたはプロジェクトにすることを推奨します。製品ビルドへ意図せず混ざることを防げます。

2. プラグインを配置する

配置方法は 2 つあります。方法 A が P!M 側で接続確認した構成です。特に理由がなければ方法 A を使ってください。

方法 A：Packages フォルダへ直接置く（推奨）

Unity プロジェクトの Packages 直下へ置いたフォルダは、Unity が自動でパッケージとして認識します。manifest.json の編集は不要です。

  1. Unity Editor を閉じます。
  2. 配布物の unity-plugin\PlayableMobilePlugin フォルダを、フォルダごと対象 Unity プロジェクトの Packages 直下へコピーします。フォルダ名は変えても構いませんが、中のファイル構成は変えないでください。
  3. Unity でプロジェクトを開きます。コンパイルが終わるまで待ちます。
  4. Window > Package Manager を開き、ウィンドウ左上のドロップダウンを In Project に切り替えます。一覧に Playable!Mobile Unity Plugin が表示され、選択すると右側にバージョン 3.0.0 が出ることを確認します。

完成後のフォルダ構成は次のとおりです。

<Unityプロジェクト>\
└─ Packages\
   ├─ manifest.json          ← 方法 A では編集しません
   └─ PlayableMobilePlugin\
      ├─ package.json
      ├─ com.aiqveone.playable-mobile.asmdef
      ├─ link.xml
      ├─ LICENSE.md
      ├─ AssemblyInfo.cs
      ├─ Core\
      ├─ Net\
      ├─ Commands\
      ├─ Interaction\
      └─ Observation\

アセンブリ定義（.asmdef）は同梱済みです。 参照（uGUI、TextMeshPro、Newtonsoft.Json、Input System）はあらかじめ設定してあります。Input System パッケージが入っていないプロジェクトでは、その参照は無視されるだけでエラーにはなりません。手で作り直す必要はなく、作り直すと参照漏れの原因になります。

方法 B：プロジェクト外へ置いて参照する

複数の Unity プロジェクトで同じプラグインを共有したい場合は、ローカルパッケージとして参照できます。

  1. 配布物の unity-plugin\PlayableMobilePlugin フォルダを、Unity プロジェクトの外側（例：<Unityプロジェクト>\..\LocalPackages\PlayableMobilePlugin）へフォルダごとコピーします。
  2. Packages\manifest.json の dependencies へ、そのフォルダを指す 1 行を追加します。相対パスは Packages フォルダから見た位置で書きます。
{
  "dependencies": {
    "com.aiqveone.playable-mobile": "file:../../LocalPackages/PlayableMobilePlugin",
    "com.unity.ugui": "1.0.0",
    "com.unity.nuget.newtonsoft-json": "3.0.2",
    "com.unity.textmeshpro": "1.0.0"
  }
}

方法 B でフォルダを Packages の内側に置くと、方法 A の自動認識と参照が二重になります。方法 B を使う場合は必ずプロジェクト外へ置いてください。

3. ビルドで有効にする

プラグインは、ビルドの種類によって自動で有効・無効が切り替わります。

実行のしかた プラグインの状態 必要な作業
Unity Editor での再生（Play Mode） 常に有効 なし
Development Build（Build Settings で Development Build を ON） 常に有効 なし
上記以外のビルド（通常の Release Build） 既定では無効 下記の ENABLE_PLAYABLE_MOBILE を定義します

Release Build で使う場合

  1. Edit > Project Settings > Player を開きます。
  2. 上部のアイコンから対象プラットフォーム（Windows／Android／iOS）のタブを選びます。
  3. Other Settings を展開し、Script Compilation 区分の Scripting Define Symbols で欄の下にある + を押して ENABLE_PLAYABLE_MOBILE を入力します。
  4. 欄の右下の Apply を押し、再コンパイル後にビルドします。

製品として配信・出荷するビルドに ENABLE_PLAYABLE_MOBILE を定義したまま出さないでください。 定義されたビルドは、外部から操作を受け付ける TCP サーバをゲーム内で起動します。テスト用ビルドと出荷用ビルドの設定を分けて管理してください。

プラグインが自動で行うこと

  • シーン読み込み前に自動で起動し、Playable!Mobile という常駐オブジェクトを 1 つ作成します。ゲーム側のシーンやプレハブへの追加作業は不要です。
  • Application.runInBackground を有効にします。P!M を操作してゲームが非アクティブになっても描画が止まらず、スクリーンショットを取得できるようにするためです。
  • 起動時に Console へ [Playable!Mobile] Start Playable!Mobile (TCP Server Mode) を出力します。

4. ポートと入力方式を合わせる

TCP ポート

ゲーム側と P!M 側で同じポート番号を使う必要があります。既定は 8001 で、通常は変更不要です。

変更する場合は設定アセットの Port を書き換えます。この値は Unity Editor でも実機ビルドでも使われます。起動引数とディープリンクは、その場かぎりで上書きしたいときの手段です。

実行環境 ポートの変え方
共通（基本） 設定アセット Resources\PlayableMobileSetting の Core > Port を Inspector で変更します（アセットが無い場合は既定値 8001）。
Unity Editor 起動引数もディープリンクも読み込みません。設定アセットの値だけが使われます。
Windows（スタンドアロン） 起動引数に -TCPPort=<番号> を付けると設定アセットの値を上書きします。
Android／iOS ディープリンクの引数として -TCPPort=<番号> を渡すと設定アセットの値を上書きします（区切りは ? と +）。P!M からの接続はディープリンク起動ではないため、通常は設定アセットの値が使われます。

設定アセットを作る（ポートを変える場合のみ）

設定アセットが無くても既定値（ポート 8001）で動作します。ポートを変更したい場合だけ作成してください。アセットの項目は Core > Port と ErrorLog > MaxEntries（P!M へ返す Console ログの保持件数・既定 100）の 2 つだけです。

  1. Project ウィンドウで、配置したパッケージフォルダ（Packages\PlayableMobilePlugin）の直下に Resources フォルダを作成します。プロジェクトの Assets 配下の Resources フォルダでも読み込めます。
  2. 作成した Resources フォルダを右クリックし、Create > Playable! Mobile > Setting を選びます（メニュー名は Unity 上の表記どおりスペース入りです）。
  3. アセット名が PlayableMobileSetting であることを確認します（この名前で読み込むため変更しないでください）。
  4. アセットを選ぶと、Inspector に Core と ErrorLog の 2 つの区分が表示されます。Core > Port を、P!M 側の「接続・録画」タブで指定するポートと同じ番号にします。

フォルダ名 Resources とアセット名 PlayableMobileSetting は変更できません。どちらかが違うと設定は読み込まれず、警告も出ないまま既定値の 8001 で動作します。

なぞり操作（多点経路ドラッグ）を使う場合

スワイプやフリックの経路を複数点で指定する操作（P!M のステップ名は「なぞり操作」、種別は PathDrag）と、uGUI 以外のオブジェクト（Collider・Sprite）へのタップは、Unity の Input System を経由した合成入力として届けます。これらを使う場合は、Input System を有効にしてください。

  1. Input System パッケージが未導入の場合は、Window > Package Manager（Unity Registry）から Input System を追加します。
  2. Edit > Project Settings > Player を開き、Other Settings を展開します。
  3. Configuration 区分にある Active Input Handling のドロップダウンを Input System Package (New) または Both にします。
  4. Unity の再起動を求められたら再起動します。

同梱のアセンブリ定義は Unity.InputSystem をあらかじめ参照しているため、参照の追加作業はありません。

Input Manager (Old) のみの設定でも、uGUI に対するタップ・ドラッグ・テキスト入力などの基本操作は利用できます。 なぞり操作だけが使えません。uGUI 以外（Collider・Sprite）へのタップは合成タッチで届けるため、この構成では反応しません。Input System を有効にした場合、非アクティブ時でも合成入力が届くよう、プラグインが入力設定を自動調整します。

5. 組み込めたか確認する

  1. Unity でゲームのシーンを開き、▶（Play）で再生します。
  2. Console に [Playable!Mobile] Start Playable!Mobile (TCP Server Mode) が出力されることを確認します。
  3. P!M を起動し、「検証」ページ左列の「接続・録画」タブでプラットフォームを「Win / Unity Editor」、ポートを 8001 にします。
  4. 「接続」を押します。状態が緑の「接続済み」になり、ゲーム画面が表示されれば組み込み完了です。

P!M の接続・録画タブ（Win / Unity Editor・ポート 8001・接続）

確認する場所 組み込めている状態
Package Manager（In Project） Playable!Mobile Unity Plugin が表示され、エラーが出ていない。
Unity のコンパイル Console にコンパイルエラーが無い。
再生時の Console 起動ログ [Playable!Mobile] Start Playable!Mobile (TCP Server Mode) が出る。
P!M 側 接続状態が緑になり、ゲーム画面のプレビューが更新される。

実機（Android／iOS）で使う場合も、まず Unity Editor での接続確認を済ませてから実機へ進むと、原因の切り分けが簡単になります。実機側の準備は、同梱の「ユーザー向けマニュアル」の「デバイス接続」章と、iOS の場合は「iOS 接続セットアップ」をご覧ください。

6. うまくいかないとき

症状 確認すること
Package Manager にプラグインが表示されない package.json がパッケージフォルダの直下にあるか確認します。方法 B の場合は manifest.json の相対パスが Packages フォルダ基準になっているか確認します。
再生しても Console に起動ログが出ない 配布フォルダの中身をそのままコピーしたか（com.aiqveone.playable-mobile.asmdef が含まれているか）を確認します。Release Build の場合は ENABLE_PLAYABLE_MOBILE の定義を確認します。赤いエラー [Playable!Mobile] TCP server failed to start on port … が出ている場合は、そのポートを別のアプリ（前回のゲームプロセスの残り、同じポートを使う他のツールなど）が使っています。空くのを待つか、設定アセットでポートを変えてください。
Newtonsoft.Json が見つからないとコンパイルエラーになる com.unity.nuget.newtonsoft-json を導入し、アセンブリ定義の Override References を ON にして Newtonsoft.Json.dll を参照に追加します。
UnityEngine.InputSystem が見つからないとコンパイルエラーになる 同梱のアセンブリ定義を差し替えた・作り直した場合に発生します。配布フォルダの com.aiqveone.playable-mobile.asmdef を元に戻してください（Unity.InputSystem を参照済みです）。
起動ログは出るが P!M から接続できない ゲーム側と P!M 側のポート番号が同じか確認します。Windows のファイアウォールで許可されているかも確認します。ポートを別のアプリに取られている場合は、起動ログの代わりに TCP server failed to start on port … のエラーが出ます。
画面の要素が取得できない 対象が uGUI・Collider／Collider2D・SpriteRenderer のいずれかで作られているか確認します。UI Toolkit 製の画面は対象外です。
uGUI 以外のオブジェクトへのタップが効かない 画面情報としては取得できていても、操作は合成タッチとして届くため、ゲーム側がその入力を読んでいないと反応しません。Active Input Handling が Input System Package (New) または Both になっているかを確認し、対象オブジェクトが画面座標のタッチ／クリックを拾う実装になっているかを確認してください。
なぞり操作（多点経路ドラッグ）だけ失敗する Active Input Handling が Input System Package (New) または Both になっているか確認します。Input Manager (Old) のみの構成では、この操作だけが「PathDragPos requires the New Input System」というエラーで失敗します。
プレビューが固まる・スクリーンショットが取得できない ゲームが非アクティブのときに描画が止まっていないか確認します。ゲーム側のコードで Application.runInBackground を無効化していないかを確認してください。
This site uses Just the Docs, a documentation theme for Jekyll.