プロジェクトの依存関係
プロジェクトが使用するプラグインをどう記録するか、あるプラグインが欠落または非互換のときに何が起こるか、そしてビルドしたゲームにどのプラグインが同梱されるか
プロジェクトは、そのドキュメントが実際に使用しているプラグインを記録します。この表は .nlproj マニフェストの中にあり、プロジェクトをスキャンして導出されるもので、手で書かれることは決してありません。これは 2 つの問いに答えます。あるマシンがこのプロジェクトを開くために何をインストールする必要があるか、そしてそこから構築するゲームにどのプラグインが入るべきか、です。
ワークスペースのサイドバーにある Project → Dependencies(プロジェクト → 依存関係)から開きます。
ハードとソフト
| 種類 | 記録されるとき | プラグインがなくなると |
|---|---|---|
| ハード | プロジェクトがそのプラグインが所有する型――ブループリントノード型やウィジェット型――を参照している。 | ドキュメントが壊れます。Studio が対処します。 |
| ソフト | プラグインがプロジェクトのストレージに書き込んだだけ。 | 何も壊れません。情報提供のみです。 |
プラグインは両方であることもあります。ハード依存でありながらストアも保持しているプラグインは、それでもハードとして扱われます。
この表がいつ書かれるか
- 開くとき、Studio はどのプラグインも読み込む前に永続化された表を解決します。そのため、あるプラグインの
setupが何かを登録できるようになる前に、何をスキップすべきかがすでにわかっています。 - エクスポートするとき、プロジェクトは再スキャンされ、表が書き直されます。これにより、エクスポートされたパッケージは自分が必要とするものを正確に記録します。
- オンデマンドで、Dependencies パネルの Rescan(再スキャン)から。
パネルを開くだけでは現在の状態が解決されるだけで、マニフェストへの書き込みは行われません。
スキャンは、読み込まれていて型を貢献しているプラグインについてのみエントリーを再導出します。存在しない、または無効化されているプラグインのエントリーはそのまま保持されます――それを落としてしまうと、そのプラグインを持たないマシンでプロジェクトを開いた瞬間に、その要件が静かに消し去られてしまいます。
状態
| 状態 | 意味 |
|---|---|
| Ready | 互換性のあるバージョンでインストールされています。 |
| Outdated | メジャーバージョンは同じですが、プロジェクトが作られた時点のものより古いバージョンです。読み込みは行われます。 |
| Missing | このマシンにインストールされていません。 |
| Incompatible | プロジェクトが作られた時点とは異なるメジャーバージョンでインストールされています。 |
| Disabled | Missing または Incompatible なハード依存です。このプロジェクトではそのプラグインがスキップされます。 |
互換性はメジャーバージョンのみで判定されます。2.4.0 は 2.1.0 を基準に作られたプロジェクトを満たしますが、3.0.0 は満たしません。解析できないバージョンは非互換として扱われます。
スキップされるとはどういうことか
Missing または Incompatible なハード依存は、そのプラグインをこのプロジェクトについてのみ抑制します。Studio はそのエントリーを import することすら一切行わないため、setup は実行されず、そのノード、ウィジェット、アクションも登録されません――間違ったメジャーバージョンによって登録されたノード型が、もはや理解できなくなったドキュメントを書き換えてしまう可能性があるためです。プラグイン名を挙げた警告が表示され、プロジェクトは通常どおり開きます。
抑制はプロジェクト単位です。プラグインは他のあらゆる場所ではインストール済み・有効のままです。
ソフト依存は何も抑制しません。
ビルドしたゲームに同梱されるもの
パッケージングはインストール済みの一覧ではなく、この表に従います。
- ハード依存だけが同梱されます。 runtime エントリーを持つ有効なプラグインでも、このプロジェクトが使用していなければパックから外れます。
- 提供元のない使用中の型はビルドを失敗させます。 プロジェクトが使用するノードやウィジェットについて、
contributesでそれを宣言している同梱プラグインが存在しない場合、そのノードがプレイヤーのマシン上で何もしないゲームを出荷するのではなく、Preview とエクスポートは、そのプラグインと型を名指ししたメッセージとともに停止します。 - 表がまったく存在しないプロジェクト――一度もスキャンされず、一度もエクスポートされていないもの――は、有効なすべての runtime プラグインを同梱するというフォールバックになります。一度スキャンまたはエクスポートすれば、選択は正確になります。
バージョン番号は契約です
プラグイン作者にとって、ここがあなたのユーザーに直接影響する部分です。
- メジャーバージョンの引き上げは、旧メジャーバージョンを基準に作られたすべてのプロジェクトを壊します。 それらのプロジェクトはあなたのプラグインを Incompatible と判定し、スキップします。壊す意図があるときにメジャーバージョンを上げてください。「このリリースは重要だ」という合図として使わないでください。
- 型 id は安定させてください。 プロジェクトはノード型とウィジェット型を文字列で保存します。名前の変更は、どんなバージョン番号でも表現できない破壊的変更です――新しい型を追加し、古い型はそのまま登録し続けてください。
- 組み込みのプラグインは Studio とバージョンが連動します。 Studio の更新そのものが、あるプロジェクトを Incompatible に変えることがあります。この仕組み全体は、まさにそのケースのために作られています。