ビルド依存関係

Studio がビルド時にダウンロード、検証、キャッシュする外部バイナリの宣言方法と、常に通用するオフライン経路

contributes.buildDependencies は、そのライセンスがゲームに同梱することは認めていても、公開のプラグインレジストリがミラーすることは認めていない再配布可能物のために存在します。バイト列がどこから来るか、そのダイジェストが何かを宣言すれば、Studio は作者のビルド中にそれを取得し、検証し、内容ごとにキャッシュし、あなたのsidecarに渡します。

これが不要な場合

プラグインがバイナリを手に入れる方法は 3 通りあり、真ん中のものだけが Studio の仕事です。

経路	誰が担当するか
バイナリを自分のプラグインパッケージに同梱する	あなた自身――sidecar の `include` に列挙するだけです。
外部 URL を宣言し、ビルド時にダウンロードする	Studio――本ページの内容です。
作者にダウンロードしてもらい、そのファイルを指し示す	あなた自身――自分の studio エントリーと `app.privileged.fs` を使って。

自分でそのバイナリを再配布してよいなら、パッケージに入れてください。この仕組みは、それができない場合のためのものです。

宣言する

{
  "contributes": {
    "buildDependencies": [
      {
        "id": "yourname.plugin.sdk",
        "description": "Vendor SDK redistributable binaries",
        "targets": {
          "windows-x64": {
            "url": "https://example.com/sdk_1.6.2.zip",
            "sha256": "a1b2…64 hex chars",
            "archive": "zip",
            "files": {
              "sdk/redistributable_bin/win64/sdk.dll": "bin/windows-x64/sdk.dll"
            }
          },
          "linux-x64": {
            "url": "https://example.com/libsdk.so",
            "sha256": "c3d4…64 hex chars",
            "archive": "none",
            "fileName": "bin/linux-x64/libsdk.so"
          }
        }
      }
    ]
  }
}

フィールド	備考
`id`	あなたのプラグイン id を前置します。`dep:<id>/…` 形式の include が指すのはこれです。
`description`	インストール時とビルドログで作者に表示されます。そのバイナリが何であるかを述べてください。
`targets`	`<platform>-<arch>` をキーとし、sidecar が使うのと同じデスクトップ向けキーです。

各ターゲットについて:

フィールド	必須	備考
`url`	はい	`https` でなければなりません。
`sha256`	はい	ダイジェストがなければダウンロードは行われません。これはキャッシュキーも兼ねます。
`archive`	はい	`"zip"` または `"none"`。
`files`	`"zip"` の場合に必要	アーカイブ内のパス → 生成される依存関係ディレクトリ内のパス。
`fileName`	`"none"` の場合に必要	ダウンロードされたファイルが、生成される依存関係ディレクトリ内で持つ名前。

dep:<dependencyId>/<path> の形をした sidecar の include エントリは、この依存関係が生成した成果物を取り込みます。ファイルは dep:<id>/ の接頭辞を取り除いた include パスの位置に配置されるため、実行ファイルが期待する場所にレイアウトしてください――Windows では DLL は .exe の隣で探索されるため、sidecar の entry と同じディレクトリにマッピングします。

"include": [
  "bin/windows-x64/bridge.exe",
  "dep:yourname.plugin.sdk/bin/windows-x64/sdk.dll"
]

dep: エントリはその依存関係自身の sha256 によってすでにカバーされているため、sidecar のダイジェストマップに重ねて記載する必要はありません。宣言されていない依存関係 id を参照することはマニフェストエラーです。

キャッシュと、作者に見えるもの

キャッシュキーは URL ではなく内容のダイジェストなので、URL を同一のバイト列を指すように変更しても再ダウンロードは決して発生しません。キャッシュがヒットすればネットワークにはまったく触れません。検証に失敗した場合、そのキャッシュキーの下には何も残らないため、汚染されたダウンロードが次回のビルドで正常なものと取り違えられることは決してありません。

インストール時、派生された buildDependency 権限は、依存関係 id と、そのバイナリが取得される予定のホスト名を作者に示します。外部バイナリを他人のゲームにダウンロードすることは、こっそり通り過ぎてよいことではありません。

オフライン経路

作者のビルドマシンにネットワークがないかもしれませんし、あなたの url が失われるかもしれません。いつでも通れる道があります。ビルドは、ファイルを置くべき正確なパスを報告します。

ある依存関係がキャッシュにもなく到達もできない場合、ビルドのプリフライトは build-dependency-unavailable で失敗し、ビルドキャッシュ配下の source ファイルパスを示します。ダウンロードしたファイルをそこに――そのダイジェスト自身のディレクトリの下に、拡張子なしで――保存し、再度ビルドしてください。そこに置かれたものは宣言された sha256 と照合して検証されるため、誤ったファイルは公開されるのではなく大きな音を立てて失敗します。

依存関係がログインの背後にある場合――パートナーポータルや、規約への同意が必要な SDK など――手動の経路はフォールバックではなく唯一の経路であり、あなたのプラグインの README は、それを回避策としてではなく通常の手順として説明すべきです。

Studio が意図的に行わないこと

バージョン解決、依存関係グラフ、ミラーへのフォールバックは行いません。
ライセンス同意のフローは行いません。
インストール時のダウンロードは行いません――ビルド依存関係はゲームがビルドされるときに取得され、プラグインがインストールされるときには取得されません。

これが不要な場合

宣言する

sidecar からファイルにアクセスする

キャッシュと、作者に見えるもの

オフライン経路

Studio が意図的に行わないこと

このページの目次