プラットフォームの所有者は、SDK をケースごとに組織に配布します。SDK の取得はプロバイダから行う必要がある一方で、それらは組織の共通のファイル ソースの場所に配置が可能です。その後は、Turnkey でこれらのファイルにアクセスすることで、個々のユーザーのデバイスで SDK のダウンロードとインストールができるようになります。
Turnkey 用の SDK ファイルは、次の 3 つの場所でホストできます。
-
組織の Perforce リポジトリ上。
-
ユーザーのローカル マシン上。
-
Google Drive の共有ドライブ上。
次に、Turnkey は一連のチェーンされた XML ファイルを使用して、各プラットフォームで使用可能な SDK を決定します。このプロセスは、「Engine/Build/Turnkey」ディレクトリ下の Unreal Engine (UE) をインストールしたディレクトリ内にある TurnkeyManifest.xml ファイルと TurnkeyStudioSettings.xml ファイルを読み取ることから開始されます。
TurnkeyManifest.xml は利用可能な SDK に関する情報を追加するか、必要な情報を含む他のマニフェスト ファイルを指定します。一方、TurnkeyStudioSettings.xml は Google Drive や署名付き証明書にアクセスするために必要な資格情報など、スタジオ全体の情報を提供します。TurnkeyManifest.xml と TurnkeyStudioSettings.xml の両方をチェーンして、ローカルまたはリモート ディレクトリの他の .xml ファイルを指定することもできます。
組織では、バージョン管理システム内の Unreal Engine ソース ファイルと一緒に、この TurnkeyManifest.xml をすべてのユーザーに配布するのが理想的です。この基本マニフェストが変更されることはありません。しかし、その代わり、これには各プラットフォームの SDK ファイルの側にある他のマニフェストへの参照が含まれます。この設定を使用すると、Unreal Engine のソース ファイルを変更することなく、これらのマニフェストをすばやく編集および更新できるようになります。
マニフェスト ファイルの概要
Turnkey のマニフェストには、次の情報が含まれます。
-
マニフェスト全体を網羅する
TurnkeyManifestタグ。-
AdditionalManifestsタグ- 現在のマニフェストと一緒に含めたい他のマニフェストを指定している個々の
Manifestエントリ。
- 現在のマニフェストと一緒に含めたい他のマニフェストを指定している個々の
-
以下を含む、利用可能な SDK に関する情報が入っている
FileSourceエントリ-
Platform -
Type -
Version -
Name -
Source
-
-
たとえば、次は Win64 と Mac をサポートする有効な TurnkeyManifest の例です。
<?xml version="1.0" encoding="utf-8" ?>
<TurnkeyManifest>
<AdditionalManifests>
<Manifest>$(ThisManifestDir)/MyStudio_TurnkeyManifest.xml</Manifest>
<Manifest>$(UE_STUDIO_TURNKEY_LOCATION)</Manifest>
</AdditionalManifests>
<FileSource>
<Platform>Mac</Platform>
<Type>Full</Type>
<Version>$(ExpVersion)</Version>
<Name>MacOS SDK v$(ExpVersion)</Name>
<Source>fileexpansion:googledrive:/SdkInstallers/Mac/$[ExpVersion]/Installer.zip</Source>
</FileSource>
<FileSource>
<Platform>Win64</Platform>
<Type>Full</Type>
<Version>1.00</Version>
<Name>Win64 SDK V1.00</Name>
<Source>googledrive:/SdkInstallers/Win64/1.00/Installer.zip</Source>
</FileSource>
</TurnkeyManifest>
追加のマニフェストを提供する
AdditionalManifests セクションには、Turnkey のファイルのスキャン時に含めたい他の XML ファイルを指定する個々の Manifest エントリが含まれています。「Engine/Build/Turnkey」ディレクトリにあるベースの TurnkeyManifest.xml が、常にこのプロセスの開始点となります。それ以外の場合は、マニフェストを必要なだけチェーンさせたり、任意の方法で整理したりできます。
このリストにある Manifest エントリは、ソース ファイルのファイル参照に使用している形式のルールに従います。したがって、追加のマニフェストは、リモート リポジトリや Google Drive のフォルダなど、ソース ファイルが配置されている任意の場所に配置できます。ディレクトリ文字列をフォーマットする方法の詳細については、「形式のルール」セクションを参照してください。
FileSource エントリ
FileSource エントリは、入力方法に応じて、組織で使用できる特定の SDK またはグループ化された SDK エントリをリストします。以下では、FileSource エントリ内の各パラメータのルールを説明します。
Platform
この SDK でサポートされているプラットフォームの名前です。Turnkey はこの情報を使用して、特定のプラットフォームに適したバージョン管理ルールを自動的に決定します。
プラットフォーム名は、Unreal Engine のビルトインのプラットフォーム名のいずれかと一致している必要があります。たとえば、「Windows」ではなく「Win64」、「iPhone」ではなく「IOS」を使用する必要があります。
Type
Type フィールドは、完全版 SDK のインストールをリストするのか、フラッシュ キットなどの最小版 SDK のインストールをリストするのかを示します。有効な SDK タイプは次のとおりです。
| タイプ | 説明 |
|---|---|
| Full | 開発者向けの完全版 SDK をインストールします。 |
| AutoSDK | Unreal Engine が必要に応じて SDK のインストールを構成できるパッケージです。Full SDK と AutoSDK の両方が存在する場合、Turnkey は AutoSDK を優先します。 |
| Flash | 開発キットをフラッシュするためのコンポーネントを備えている最小版をインストールします。 |
AutoSDK の詳細については、Unreal Engine の「AutoSDK リファレンス」を参照してください。
Version
Version フィールドには、SDK のバージョン番号が入ります。プラットフォームごとに想定されるバージョンの形式が異なるため、この情報を正確にリストすることが重要となります。
$[ExpVersion] などのキャプチャ変数を使用して「Source」セクションのバージョン番号をキャプチャし、このセクションに $[ExpVersion] を置換変数としてリストすることができます。 詳細については、「ファイル拡張とキャプチャ変数」のセクションを参照してください。
Turnkey が SDK をスキャンするときは、バージョン番号も整数に変換されます。そして、Turnkey はプラットフォームごとに異なるルールを使用します。Full SDK と Flash SDK が異なるバージョン管理フォーマットを使用している場合は、それらも考慮されます。Turnkey が SDK の複数の有効なバージョンを比較する際は、リストされているバージョンの中で変換された整数値のうち最も高いものが優先されます。
各プラットフォームで想定されるバージョン番号の形式については、「Turnkey コマンドライン」の Help コマンドで確認してください。
Name
Name フィールドには、SDK 用の表示名が人間が読める形で入ります。これは純粋に表示目的でのみ使用されます。また、必要に応じて好きな名前を設定できます。
Name フィールドには、FileSource の他の場所で使用したキャプチャ変数に対応する置換変数を入れることもできます。たとえば、バージョン番号を表すために `$[ExpVersion] を使用した場合、名前フィールドは $(ExpVersion) を使用して、キャプチャ変数が見つけた値を置き換えることができます。 キャプチャ変数と置き換え変数の詳細については、「ファイル展開とキャプチャ変数」セクションを参照してください。
Source
Source フィールドには、SDK の場所を説明する文字列が入ります。この文字列は、ファイル パスの読み取り方法を Turnkey に指示する一連のプレフィックスと、ファイル パス自体の 2 つの部分に分かれています。
たとえば、次のソース エントリは、ローカル ファイル システムで (file: プレフィックスを使用して) Win64 SDK を検索し、Install.zip という 7zip ファイルを想定しています。
<Source>file:X:\SdkInstallers\Win64\1.10\Install.zip</Source>
fileexpansion: プレフィックスを使用すると、キャプチャ変数 を有効にして、ファイル プロバイダからのデータを使用して多くの SDK を反復処理できます。たとえば、次のソース エントリは、Version フィールドで指定されたバージョン番号を使用します。
<Source>fileexpansion:file:X:\SdkInstallers\Win64\$[ExpVersion]\Install.zip</Source>
特定のファイル パスを 1 つだけ調べるのではなく、この形式に一致するすべてのファイル パスを調べます。
Source パラメータでは、オプションの CopyOverride 指定子を使用して、Perforce リポジトリの使用時に Turnkey が展開するディレクトリを制限することもできます。この指定子を使用する FileSource ブロックについては、以下の「例」を参照してください。
ソース文字列で使用できるプレフィックスとキャプチャ変数の完全なリストについては、以下の「[文字列形式のリファレンス](#文字列形式のリファレンス」を参照してください。
その他のパラメータ
上記のパラメータが最も一般的に使用されますが、特殊なケースで使用できるパラメータも他にいくつか用意されています。
AllowedFlashDeviceTypes
AllowedFlashDeviceTypes 値は、Flash タイプの SDK にのみ使用されます。これらは、対象のプラットフォームにのみ意味のある値を持つ文字列となります。使用できる値は、特定のプラットフォームの情報の下にリストされている Turnkey コマンド ラインの Help セクションでわかります。Turnkey は、デバイス情報を受信すると、デバイス タイプとインストールされているソフトウェア バージョンを取得します。次に、これらを使用して最新かどうかを判断し、インストール元の Flash FileSource を選択します。
例
以下は、Perforce リポジトリで AutoSDK ファイルを検索する FileSource エントリの例です。この例では、SDK バージョンごと、プラットフォームごとに 1 つの FileSource に展開する Setup.bat ファイルと Setup.sh ファイルを検索します。また、ユーザーがこれらの SDK のいずれかを明示的に選択しない限り、Turnkey が再帰的に展開するのを制限するために CopyOverride を使用します。これにより、Turnkey が不必要に多くの Perforce ファイルを展開してしまうのを防ぎます。これは、ディレクトリではなくファイルに対してのみ機能する、Perforce に固有の動作となります。
<FileSource>
<Platform>listexpansion:ExpPlatform=$(AutoSDKPlatforms)</Platform>
<Version>$(ExpVersion)</Version>
<Name>$(ExpPlatform) AutoSdk version $(ExpVersion)</Name>
<Type>AutoSdk</Type>
<Source CopyOverride="perforce://depot/CarefullyRedist/Host$(HOST_PLATFORM_NAME)/$(ExpPlatform)/$(Version)/...">
fileexpansion:perforce://depot/CarefullyRedist/Host$(HOST_PLATFORM_NAME)/$(ExpPlatform)/$[ExpVersion]/Setup.*
</Source>
</FileSource>
文字列形式のリファレンス
Turnkey マニフェスト内の文字列は、いくつかのプレフィックスを使用して、指定されたファイル パスの読み取り方法を決定します。使用するプレフィックスに応じて、読み取り時に追加情報に展開されるカスタム変数をファイル パスに組み込むことができます。これにより、特定のファイルのファイル パスを明示的にリストするのではなく、ファイル パスへの使用を想定した形式を指定できるようになり、Turnkey がその形式に一致するすべてのファイルを検出します。
コピー プロバイダ
Copy provider プレフィックスは、その後に続くファイル パスを解析するときに Turnkey が検索する場所の種類を決定します。Turnkey は 3 種類の場所を認識します。そして、これらの場所を判別するプレフィックスには、それらが想定しているファイル パスの種類に関するルールが存在します。
| プレフィックス | 説明 | ファイルパスの例 |
|---|---|---|
file: |
Turnkey で SDK インストーラのローカル ファイル システムを調べます。 このプレフィックスが想定しているのは、ファイルが置かれているドライブを含む標準のファイル パスです。これには、共有ネットワーク ドライブを含めることができます。 MacOS では、SMB 共有をマウントするために追加の |
|
perforce: |
Turnkey で、Perforce ストリームに接続して、SDK インストーラを見つけます。 このプレフィックスが想定しているのは、標準の Perforce ファイル仕様です。これには、常に特定のファイル コンポーネントが含まれており、ファイル拡張子が付いている必要があります。Turnkey が Perforce クライアントの場所を見つけられるようにするために、初回使用時は clientspec を提供するように求められる場合もあります。 |
|
googledrive: |
Turnkey で Google Drive に接続して、SDK インストーラを見つけます。 ファイル パスの最初のコンポーネントは、検索する共有ドライブの名前を表し、パスの後続のすべてのコンポーネントは、そのドライブ上のサブフォルダの名前となります。 |
googledrive:/SdkInstallers/$[ExpPlatform]/$[ExpVersion].Install.zip |
ローカルのファイルを使用する場合、ユーザーのマシンに直接配置された SDK インストーラを使用できるため、追加のセットアップは最小限で済みます。ただし、このセットアップでは、ローカル フォルダとその中にある SDK インストーラの位置を各ユーザーが一致させないといけないため、追加でのメンテナンスの手間が最もかかります。ユーザーのマシン上にあるローカル ドライブではなく、共有ネットワーク ドライブを使用することもできます。しかし、その場合、共有ドライブによっては速度が低下することがあります。
Google Drive を使用する場合、Google Drive API を使用するアカウントを設定し、エンジン ファイルと一緒に OAuth 2.0 認証情報をユーザーに提供する必要があるため、追加で設定することが最も多くなります。しかし、この方法の場合、一度設定が完了してしまえば組織の管理者が行う必要のあるメンテナンスの手間は少なくなります。詳細については、「Unreal Turnkey 用の Google Drive の設定」に関するガイドを参照してください。
Perforce ストリームを使用すると、組織が SDK ファイルを保持するための中心の場所が作成されるため、これら 2 つの方法の間でバランスを取ることができます。しかし、この場合、組織は Perforce ストリームを設定し、それにアクセスするための資格情報をユーザーに提供する必要があります。
他のソース管理オプションのサポートを Turnkey に追加する必要がある場合は、エンジンのソース コードに変更を加えた新しいタイプのコピー プロバイダを追加できます。例については、GoogleCopyProvider 、 PerforceCopyProvider、および NullCopyProvider を参照してください。
ファイル展開とキャプチャ変数
fileexpansion: プレフィックスを使用すると、特定の SDK へのパスではなく、一般的な形式に一致するパスを Turnkey で検索できます。これにより、ダウンロードする必要のない SDK のサーバー呼び出しの数が減ったり、すべてのエントリを個別に書き込む必要がなくなったり、幅広い SDK を追跡できるようになったりします。たとえば、新しいインストーラをサーバーにアップロードできるようになります。そして、そのディレクトリ構造が FileSource エントリにリストされている期待される形式に適合している限り、マニフェストを変更することなくファイル展開でそれを検出するといったことが可能になります。
fileexpansion: プレフィックスを使用する場合、ファイル展開はコピー プロバイダからの情報に依存するため、その後に file: や googledrive: などのコピー プロバイダ プレフィックスを付ける必要があります。
パスに fileexpansion: を追加した後は、パスの一部を キャプチャ変数 で置き換えられるようになります。これらの変数は、$[xyz] という形式を使用します。xyz は、定義した任意の文字列に置き換えられます。Turnkey がマニフェストを読み取るとき、ユーザーとファイル プロバイダからの情報でこれらを展開します。
例として、次のソース文字列を使用する場合、
fileexpansion:file:X:\Installers\$[ExpPlatform]\$[ExpVersion]\Install.bat
Turnkey は、$[ExpPlatform] と $[ExpVersion] キャプチャ変数をワイルドカード値 (* 文字) に変換します。次に、Turnkey はそれらを fileexpansion: プレフィックスの後に使用されるコピー プロバイダ (この場合はローカル ファイル システム) に渡します。そして、プロバイダは使用可能なファイルとフォルダを繰り返し処理し、提供された形式に一致する結果のリストと、各キャプチャ変数に対してキャプチャされた値を返します。
X:\Installers\Win64\1.00\Install.bat [ $(ExpPlatform) = Win64, $(ExpVersion=1.00)]
X:\Installers\Win64\2.00\Install.bat [ $(ExpPlatform) = Win64, $(ExpVersion=2.00)]
X:\Installers\Android\10.1a\Install.bat [ $(ExpPlatform) = Android, $(ExpVersion=10.1a)]
Turnkey は、これらのエントリごとに SDK インストーラのダウンロード ソースとして検出できる FileSource オブジェクトを C# で作成します。キャプチャ変数によって展開されたファイル パスの部分は、FileSource オブジェクトが他のフィールドで参照できる $(xyz) スタイルの置換変数に変換されます。たとえば、ソースパスで $[ExpVersion] を使用する場合、Version フィールドでは $(ExpVersion) も使用できます。
キャプチャ変数は、ファイル名、ディレクトリ、または名前の一部を含む、ファイル パスの任意の部分を表すことができます。
fileexpansion:file:X:\Installers\$[ExpPlatform]\Installer_$[ExpVersion].zip
たとえば、上記のエントリでは、インストーラがプラットフォームのフォルダに存在しており、「Installer_1.00.zip」や「Installer_2.00.zip」といった名前の .zip ファイルにインストーラが含まれていることを想定しています。
リストの展開
listexpansion: プレフィックスは、サーバーにクエリを実行する必要のない値のリストを持つ変数を定義します。listexpansion で変数を定義すると、FileSource の他のエントリでその変数を使用できるようになります。
たとえば、次のテキストはプラットフォームの下で listexpansion を定義し、次に Name 下にあるそのリストを参照します。
<Platform>
listexpansion:ExpPlatform=Windows,Android,IOS
</Platform>
<Name>$(ExpPlatform) Installer</Name>
Turnkey がこれを読み取ると、Windows、Android、iOS 用に個別の FileSource オブジェクトを作成し、それぞれを適切な形で $(ExpPlatform) に置き換えます。listexpansion によって提供されるリストを使用するため、この機能はサーバーにクエリを実行するのに Turnkey を必要としません。SDK を備えたプラットフォームのリストがリストの展開から生成される場合、これにより Turnkey の初期起動を高速化できることがあります。
また、リスト項目を直接リストするのではなく、XML 変数を使用してリスト項目を保存することもできます。
<SavedSetting hostplatform="Win64">
<Variable>AllowedPlatforms</Variable>
<Value>Windows,Android</Value>
</SavedSetting>
...
<Platform>listexpansion:ExpPlatform=$(AllowedPlatforms)</Platform>
ビルトイン変数
Turnkey は、ユーザー定義のキャプチャおよび置換変数とともにファイル パスを定義するためのいくつかのビルトイン変数をサポートしています。
| 変数 | 説明 |
|---|---|
$(ThisManifestDir) |
現在処理中の この変数により、マニフェストに対する各ディレクトリの位置が一貫している限り、ディレクトリ構造全体を再配置できます。 |
$(EngineDir) |
Unreal Engine がインストールされているルート フォルダです。ソースコントロールにチェックインされているファイルを使用している場合、このフォルダを参照点にすると便利です。 |
$(HOST_PLATFORM_NAME) |
ホスト プラットフォームの名前です。これは通常、Win64、Mac、または Linux となります。 |
$(UE_STUDIO_TURNKEY_LOCATION) |
スタジオ全体の Turnkey ディレクトリの場所に設定できる環境変数です。 |