プラグインをインストールする
ストアまたはフォルダからプラグインをインストールし、その権限を承認し、有効化・無効化・更新・削除する
プラグインはランチャーの Plugins(プラグイン)で管理します。そこには Installed(インストール済み)と Store(ストア)という 2 つのリストがあります。ストアからインストールすることも、ディスク上の任意のフォルダからインストールすることもできます。
ストアから
ストアには、あるレジストリインデックスに載っているプラグインが一覧表示されます。既定では公式の NarraLeaf/Plugins インデックスが使われます。これは、ビルドできるかどうかだけでなく、動作と権限も審査されたプラグインを収録する、精選されたリポジトリです。設定の Registry URL(レジストリ URL)で別の場所を指すこともできます。空にしておくと公式のものが使われます。
Install(インストール)を選ぶとリリースがダウンロードされ、インストールされ、そのまま権限プロンプトに進みます。プラグインが宣言する Studio のバージョン範囲があなたのビルドを含まない場合、後になってインストールが失敗するのではなく、ボタンは表示されず、行に必要なバージョンが記載されます。
Studio がレジストリに到達できない場合、Store のリストはその旨を表示し、再試行を提案します。それ以外は何も影響を受けません――Installed リストと、すでにインストール済みのものはすべて、オフラインでも問題なく動作し続けます。
フォルダから
プラグインとは、manifest.json とビルド済みのエントリーファイルを含むフォルダです。リリースの zip から来たものでも、あなた自身の dist/ から直接持ってきたものでも、そのようなフォルダはどれでもインストールできます。
プラグインを入手する
プラグインのリリース(.zip)をダウンロードして展開します。最終的に、トップレベルに manifest.json を含むフォルダができるはずです。
hello-1.0.0/
manifest.json
main.js
runtime.jsフォルダからインストールする
Plugins で Install from folder(フォルダからインストール)を選び、そのフォルダを選択します。Studio はマニフェストを検証し、プラグインを自身のストレージにコピーします。
権限を承認する
Studio は、プラグインが要求する内容を正確に列挙したプロンプトを表示します。内容を確認し、承認するか拒否してください。何も要求しないプラグインはプロンプトなしでインストールされます。
プロンプトに列挙されるもの
このプロンプトは、プラグイン作者が書いた自己申告文ではありません――その大部分はプラグインの宣言から計算されたものであり、プラグインができることを過小に述べることはあり得ません。
| 項目 | 由来 |
|---|---|
| あるパスへのファイルシステムアクセス | 作者が書いた filesystem 権限。エディターのみに影響します。 |
bash.execute のような API 能力 | 作者が書いた api 権限。エディターのみです。 |
| ゲーム側の能力――ストレージ、ストーリー変数、セーブデータ、画面上のオーバーレイ、同梱アセット、ゲームの言語 | プラグインが contributes.runtimeCapabilities に宣言した各項目。 |
| あなたが構築するゲームに同梱されるネイティブプログラム | 宣言された各 sidecar と、それがバイナリを提供するプラットフォーム、そのフィンガープリント。 |
| ビルド時にダウンロードされるバイナリ | 宣言された各ビルド依存関係と、その取得元のホスト名。 |
後半の 3 種類は派生しています。Studio がそれらを contributes から計算し、手で書こうとするマニフェストは拒否します。これにより、「プロンプトが述べたこと」が「プラグインが実際に到達できること」から乖離するのを防いでいます――ある能力はただ 1 か所でしか宣言されず、プラグインの API サーフェスはまさにその宣言から構築されるからです。宣言されていない能力は、プロンプトに出ないだけでなく、プラグインの API オブジェクトそのものに存在しません。
承認する前にもう一度見ておく価値がある項目が 2 つあります。
- セーブデータの上書き。
saves.writeを持つプラグインは、セーブスロットを上書きしたり読み込んだりでき、読み込みは現在進行中のプレイを置き換えます。クイックセーブ系のプラグインには正当な理由でこれが必要ですが、ほとんどのプラグインには不要です。 - 同梱されたネイティブプログラム。 これは、あなたが出荷するゲームの中に入って、プレイヤーのマシンに届くコードです。Studio はインストール時とパッケージング時の両方でそのフィンガープリントを検証するため、改ざんされたパッケージは静かに出荷されるのではなく失敗します――ただし、それを含めるかどうかはあなた次第です。
拒否すると、プラグインはインストールされたままですが、認可はされません。無効のままとなり、リストには Needs authorization(認証が必要)と表示されます。Authorize(承認)を選ぶと、プロンプトが再び表示されます。
プラグインはサンドボックス化されていません。一度インストールされ有効化されると、プラグインは Studio と同じアクセス権で実行され、そのゲーム側コードはあなたのプレイヤーのマシン上で実行されます。信頼できる提供元からプラグインをインストールし、承認する前に権限プロンプトを読んでください。
更新
ストアのインデックスにより新しいバージョンがある場合、そのプラグインをストアからインストールしたかどうかにかかわらず、Installed リストはそのプラグインを Update available(更新が利用可能)と表示します。更新すると、そのバージョンがダウンロードされ、その場でインストールされます。あなたの Studio ビルドが古すぎて対応できない更新も告知はされますが、ボタンとしてではなく事実として示されるだけです。
権限の付与はプラグインのバージョンごとに、あなたが実際に承認した権限セットとともに記録されます。すでに承認した範囲を超えて何も要求しない新しいバージョンは、その付与を引き継ぎます。能力を追加するバージョンは派生する権限セットを広げるため、Studio は何が変わったかを示して再度確認を求めます。
プラグインのメジャーバージョンは、それを使うプロジェクトとの互換性契約です。メジャーバージョンをまたいで更新すると、旧メジャーバージョンに対して作られたプロジェクトではそれが非互換と判定され、スキップされます――プロジェクトの依存関係を参照してください。
有効化・無効化・アンインストール
- Enable / disable(有効化 / 無効化)――無効化されたプラグインはインストールされたままですが読み込まれません。そのエディター側の貢献項目とゲーム側コードの両方が停止します。切り替えは、次にワークスペースまたはゲームが読み込まれるときに反映されます。
- Uninstall(アンインストール)――プラグインのファイルを削除します。
言語パックを提供するプラグインは、有効な間、その言語を設定 → 言語に追加します。無効化またはアンインストールすると、それらの言語は取り除かれます。あなたが使っていた言語をそのプラグインが提供していた場合、Studio は英語にフォールバックし、そのプラグインを再度有効化すればあなたの選択が戻ります。
何か問題が起きたとき
プラグインのマニフェストが無効であったり、そのエントリーファイルが見つからなかったり、読み込み中にエラーを投げたりすると、Studio は Plugins のリストでそれをエラー状態としてマークし、そこにメッセージを表示します。読み込みに失敗したプラグインが Studio の起動を妨げることは決してなく、1 つの壊れたプラグインが他のプラグインを止めることもありません。
プロジェクトが使用するブループリントノードやウィジェットに利用可能な提供元がない場合――プラグインが見つからない、無効化されている、あるいはそれをもはや宣言しないバージョンである場合――何もしないノードを含むゲームを出荷するのではなく、Preview とエクスポートは、そのプラグインと型を名指しした診断メッセージとともに失敗します。
あるプロジェクトでだけプラグインがスキップされ、他の場所では問題なく動くこともあります。それはバージョンの非互換性であり、Dependencies パネルがそれを名指しします。プロジェクトの依存関係を参照してください。