Unreal Engine で派生データキャッシュを使用する | Unreal Engine 5.4 ドキュメンテーション

Unreal Engine (UE) アセットの多くは使用する前に追加の 派生データ を必要とします。

たとえば、マテリアルをレンダリングする前に、シェーダーでマテリアルを作るとします。その場合、Unreal Editor を実行しているプラットフォーム用にシェーダーをコンパイルする必要があります。

派生データはサイズが大きく、開発中に再生成が必要な場合があるため、ソースコントロールにチェックインされません。その代わりに 派生データキャッシュ (DDC) に保持されます。

このドキュメントでは次の項目について説明します。

DDC の構成についての概要。
UE がサポートする DDC のタイプ。
DDC の設定、使用、配布方法の手順。
以下についてのよくある質問 (FAQ)。
- 一般的な DDC の用途。
- ファイルシステムから Unreal Zen Storage (ZenServer) への切り替え。

DDC の構成方法

プロジェクトとシステムの構成方法によって、高速から低速にわたる階層の中に複数の DDC キャッシュが存在する可能性があります。派生データを評価する際、システムは次のことを実行して、データにアクセスできる速さを決定します。

アセットが派生データを必要とする場合、システムはまず最速のキャッシュをチェックし、次に速いキャッシュをチェックする動作を、データを見つけるまで繰り返します。
データが見つかると、最速のローカルキャッシュにコピーされるため、次回のアクセスが高速になります。
データが見つからない場合は、アセット用に新しい派生データが生成されて非同期でキャッシュにコピーされるため、その後は自分やチームがデータを利用できるようになります。

DDC に格納されているコンテンツは使い捨てですが、.uasset ファイルに格納されているデータを使用していつでも再生成できます。これらの派生フォーマットを外部に保存すると、ソースアセットファイルを変更しなくても、UE で使用されるフォーマットを簡単に追加または変更できます。

DDC のタイプ

UE には DDC で使用可能な複数のストレージタイプがあり、それぞれ異なる DDC ロケーションで使用できます。以下は、永続的なストレージタイプです。

ファイルシステム
- 読み取り / 書き込み可能。
- ローカルディスクや LAN での使用に最適。
- データは、ローカルマシンまたはプライベートローカルネットワーク上でファイル共有しているルートフォルダ内にファイルとして保存されます。未使用データのクリーンアップやガベージコレクションも含め、ファイルの読み取り、書き込み、削除の操作は、Unreal Editor が直接処理します。
PAK
- 読み取り専用です。
- ローカルディスクや LAN での使用に最適。
- データは、ディスク上に単一アーカイブファイルとして保存される。通常、.ddp 拡張子が付く。アーカイブは通常読み取り専用です。Unreal Editor と別のプロセスが定期的にアーカイブの内容を書き込みます。
S3
- 読み取り専用です。
- クラウド用途に最適。
- クラウドホストの Simple Storage Service (S3) バケットから取得した単一のアーカイブファイルとしてデータを保存します。Unreal Editor と別のプロセスが定期的にアーカイブの内容を書き込みます。

S3 DDC ストレージタイプの使用は推奨ではなくなりました。Unreal Cloud DDC Client に移行してください。

Unreal Zen Store Client
- 読み取り / 書き込み可能。
- ローカルディスクや LAN での使用に最適。
- ローカルマシンまたはプライベートローカルネットワークでホストされている Unreal Zen Store サーバーにデータを保存し、ディスクの永続化を処理します。認証されていないサービスであるため、ローカル接続か信頼できるネットワークや VPN 内でのみ使用してください。Unreal Editor は、HTTP 経由でサーバーに非同期リクエストを行います。サーバーは未使用データのクリーンアップとガベージコレクションを管理します。
Unreal Cloud DDC Client
- 読み取り / 書き込み可能。
- クラウド用途に最適。
- データは Unreal Cloud DDC Server に保存されます。このサーバーはクラウドストレージ (AWS、Azure など) での永続化とリージョン間でのレプリケートを処理します。認証サービスと適切なセキュリティポリシーを組み合わせれば、この認証サービスをパブリックインターネット上に展開することが可能です。未使用データのクリーンアップとガベージコレクションは、Unreal Editor の代わりにサーバーが処理します。

UE 5.3 およびそれ以前では、デフォルトで ファイルシステム DDC をローカル DDC として使用し、プロジェクトの派生データを表します。たとえば、ローカル DDC は UE のインストールディレクトリの DerivedDataCache フォルダにあります。

UE 5.4 のデフォルトでは、Unreal Zen Store DDC をローカル DDC として使用し、デフォルトで「AppSettingsDir/Zen/Data」に保存します。レガシーファイルシステムタイプのローカル DDC は、削除専用モードに設定され、8 日間のクリーンアップ期間後にデータを削除するように設定されています。ただし、DDC Pak または 共有 DDC を使用するようにプロジェクトを設定することもできます。

DDC Pak

Epic Games Store から UE をダウンロードすると DDC Pak (.ddp) が付属しています。DDC Pak にはすべての UE コンテンツの派生データが含まれているため、シェーダーをコンパイルせずに開始でき、また、派生データを使用するのに他の UE アセットを必要とすることもありません。同じ理由から、DDC Pak にはサンプルもいくつか付属しています。

DDC Pak には以下が含まれています。

エンジン <YourEngineDir>/DerivedDataCache/Compressed.ddp
プロジェクト <YourProjectDir>/DerivedDataCache/Compressed.ddp

共有 DDC

共有 DDC はネットワークまたはマップされたドライブを介して利用可能です。共有ドライブの例: \epicgames.net\root\DDC-Global-GameTitle

一元化されたオフィスや本社といった共通の場所にいるチームは、共有 DDC をセットアップすることが強く奨励されます。共有 DDC の最も一般的な設置方法は、すべてのチームメンバーとビルドマシンによって読み取り/書き込み可能な 1 つのネットワークドライブ上で、ファイルシステムタイプの DDC ストレージを使用することです。これにより、チーム全体で必要な DDC データの作成負荷が相殺されます。たとえば、アーティストが 1 つのシェーダーを編集すると、その DDC データは即座に共有 DDC に書き込まれます。

実験的機能: ローカルの Zen Storage Server

ファイルシステムタイプの DDC を共通ネットワークドライブで使用する以外には、お使いのローカルネットワークのマシンで Unreal Zen Storage Server インスタンスをホストし、それを共有 DDC として使用する方法があります。Windows マシンでホストする場合は Windows サービスとしてサーバーをインストールして以下のコマンドラインを使用します。

コマンドライン

zenserver.exe –install

zenserver プロセスは、–config [path_to_config_file] 引数を使用したコンフィギュレーションファイルを介しても実行可能です。コンフィギュレーションファイルは以下の動作を制御します。

デフォルトデータディレクトリ。
ガベージコレクションパラメータ。
ネットワーク構成。

こちらから、EpicGames GitHub リポジトリ内で構成の例を見つけることができます。リポジトリへのアクセスを必要とする場合は、UE on GitHub ページの指示に従ってください。

クラウド DDC

ローカルネットワークまたは VPN に縛られずに DDC データを共有できるよう、チーム用のクラウド DDC をセットアップすることは、ある共通の場所以外にもチームメンバーが配置されている状況において多大なメリットがあります。

クラウド DDC であれば、DDC データが部分的に書き込まれると同時にそれをアーカイブに追加することができます。これは、一般的に必要とされるデータを含む、固定の読み取り専用アーカイブを特定の間隔で作成および公開する PAK または S3 DDC とは対照的です。

こちらから、EpicGames GitHub リポジトリ内の指示を活用しながらクラウド DDC サービスのセットアップを実行できます。リポジトリへのアクセスを必要とする場合は、UE on GitHub ページの指示に従ってください。

共有 DDC の使用方法

共有 DDC は特定の場所のすべてのユーザーに対してアクセス可能であるべきです。この方法では、1 つのアセットの派生データのフォーマットを構築する必要があるのは常に 1 人だけであり、構築後、すべての他のユーザーがその派生データを自動的に利用できます。

アセットの処理時にユーザーのシステムでストールが発生した場合であっても結果は DDC に格納されており、他のユーザーに共有されています。小規模なチームであっても、この方法でアセットの処理作業を共有することで、処理に要するチーム全体での時間は大幅に減少します。

DDC 全体をインターネット上でコピーしたり、DDC のバックアップを作成したり、リモートバックアップから DDC を復元したりすることはお勧めしていません。これは、DDC に保存されているデータ量を転送するには、それらをローカルでゼロから生成するよりも時間がかかるためです。大きいプロジェクトでビルド済みの DDC データを配布する場合は、DDC Pak を生成する必要があります。

共有 DDC のセットアップ方法

UE インストール一式の BaseEngine.ini はすでにセットアップされているため、Unreal Editor でファイルシステムタイプの共有 DDC を使用できます。

以下の推奨順に挙げた 3 つの方法から 1 つを選んで共有 DDC を有効にしてください。

プロジェクトの DefaultEngine.ini にオーバーライドを追加し、チームの有効な場所のパスを設定する。次に例を示します。

DefaultEngine.ini

[DerivedDataBackendGraph] Shared=(Type=FileSystem, ReadOnly=false, Clean=false, Flush=false, DeleteUnused=true, UnusedFileAge=10, FoldersToClean=10, MaxFileChecksPerSec=1, ConsiderSlowAt=70, PromptIfMissing=false, Path=\YourCompanyServer\DDC, EnvPathOverride=UE-SharedDataCachePath, EditorOverrideSetting=SharedDerivedDataCache)

使用したいフォルダのファイルパスにマッピングする以下の環境変数を作成する。
- Windows: UE-SharedDataCachePath=[path to folder]
- Mac/Linux: UE_SharedDataCahcePath=[path to folder]
[Editor Preferences (エディタの環境設定)] を開いて General > Global > Derived Data Cache の順に進み、Global Shared DDC Path (グローバル共有 DDC パス) を設定する。

共有 DDC を無効にする方法

リモートロケーションで働くデベロッパーは、DDC のデータアクセスとデータ生成の間の遅延によるパフォーマンスの低下を実感する可能性があります。

共有 DCC を一時的に無効にするには、以下のいずれかの操作をします。

ファイルシステム DDC または Unreal Zen Storage DDC では、お使いの DefaultEngine.ini の DeactivateAt 構成パラメータを使用し、パフォーマンスが低下するとそのレイヤーが自身を無効化するよう、DDC ストレージレイヤーにしきい値 (ミリ秒) を設定することができます。
コマンドラインで -ddc=noshared を渡します。
ローカルのハードドライブに次の環境変数を設定します。
- Windows: UE-SharedDataCachePath=None
- Mac/Linux: UE_SharedDataCachePath=None

クラウド DDC の使用方法

チームメンバーがさまざまな場所で作業する場合、クラウド DDC により、メンバーの DDC データを効率的に共有できる状況を確保できます。

クラウド DDC を使用する際は、クラウドサービスプロバイダでサービスをセットアップする必要があります。詳細はクラウド DDC セットアップガイドを参照してください。サービスを設置したら、以下のように DDC クライアントを設定します。

クラウド DDC のセットアップ方法

UE インストール一式の BaseEngine.ini はすでにセットアップされているため、Unreal Editor でクラウド DDC を使用することができます。

プロジェクトの DefaultEngine.ini で以下のオーバーライドを追加し、クラウド DDC を有効にすることができます。

DefaultEngine.ini

[StorageServers (ストレージサーバー)]
Cloud=(Host="https://cloud-ddc.example.com",Namespace="myproject.sddc", OAuthProviderIdentifier=MyOrg-MyService, OAuthProvider="https://domain.oauthprovider.com/oauthuripath",OAuthClientId="ClientIdString")

このオーバーライドには以下を含みます。

有効なホストへのパス。
名前空間。
チームの認証情報。

ID プロバイダ用の対話型ログインをセットアップする方法については、OIDC トークンページを参照してください。

クラウド DDC の自動ジョブ用の非対話型ログイン

認証フローの一環として、クラウド DDC には通常、周期的な対話型ログインステップが入っています。

ビルドファームなどの自動ジョブでは、Unreal Editor に渡されるトークンを使用して対話型ログインのプロセスをバイパスすることができます。お使いの認証サービス (静的/周期的) が、このトークンを生成することができます。

トークンは、実行される自動ジョブのうち最長のものを網羅できる、十分な有効時間枠を持たなければなりません。トークンはビルドシステムのログから作成され、自動ジョブを実行するマシンの、(ディスクではなく) メモリでのみ保持されるべき、秘密のものです。

このようなトークンをいったん取得すると、UE-CloudDataCacheAccessToken という構成済みの環境変数を介して Unreal Editor に渡すことができます。

クラウド DDC の派生データをビルドする方法

アセットをインポートするユーザーは、UE でそのアセットを使用およびテストする可能性が最も高いユーザーであるため、その派生データを構築するのはインポートするユーザーです。

しかし、場合によっては新アセットの処理が必要になることがあります。これは必要に応じて自動的に発生し、高速のハードウェアで実行する場合に大きな影響を与えることはありませんが、時折ストールが発生する可能性があります。

UE のインストール一式フォルダで次のコマンドを実行すると、DDC をいつでもフィルすることができます。

コマンドライン

Engine\Binaries\Win64\UnrealEditor.exe ProjectName -run=DerivedDataCache -fill

Epic Games は、DDC が常に準備万端であるために毎晩これを実行していますが、一般的な自動キャッシュ機能で十分なのでこれは不要です。

DDC のパッケージ化および配布の方法

クックされたビルドは DDC を必要としないか、または使用しないため、クック処理はゲームのパッケージ化に推奨される方法です。しかし、必要であれば DDC を配布するためにパッケージ化することができます。

DDC のパッケージング：

UE インストール一式の Engine/Binaries/Win64 ディレクトリから UnrealEditor.exe を実行し、以下に示す引数を渡します。 UnrealEditor.exe ProjectName -run=DerivedDataCache -fill -DDC=CreatePak
これにより DDC.ddpファイルが Project\DerivedDataCache ディレクトリ内に作成されます。
UE は、この .ddp ファイルを自動検知して使用します。

DDC を設定する方法

以下の .ini files の [DerivedDataBackendGraph (派生データのバックエンドグラフ)] セクションにある DDC 設定項目を設定できます。

プロジェクト設定: <YourProjectDirectory>/Config/DefaultEngine.ini
デフォルトのエンジン: <YourUEDirectory>/Config/BaseEngine.ini

Unreal Zen Store タイプの DDC と Unreal クラウドタイプの DDC は、ServerID パラメータを使用して、.ini ファイルの [StorageServers (ストレージサーバー)] セクションに格納されている共有サーバーの構成を参照することができます。これにより、複数の DDC グラフのセクションを使用しなくても、(ホスト名や名前空間などの) パラメータの集合を一度に指定することができます。

DDC 構成の各オプションに関する詳細は BaseEngine.ini の [DerivedDataBackendGraph] セクション下のコメントを参照してください。

UE のコンフィグファイルに関する詳細は、[Configuration Files (コンフィギュレーションファイル)] (programming-and-scripting\unreal-architecture\configuration-files) を参照してください。

よくある質問 (FAQ)

全般

Q：複数の DDC 設定を使用できますか？

はい。DefaultEngine.ini で新しい [YourDDCSettings] エントリを作成し、それから -ddc=YourDDCSettings の Unreal Editor を実行してください。

Epic では、これを次の 3 つの理由で行っています。

グローバルな DDC ではなく、独自の DDC を使いたいと考えるオフィス内チームも存在します。
DDC Pak の作成時に、[CreateInstalledEnginePak] のように、.pak ファイルの中に入るものを制御するオプションのうちから、1 つを使います。
在宅勤務の場合、インターネット接続の速度が遅かったり、VPN の問題が発生したりするなど、必ずしも共有 DDC の恩恵を受けられるとは限りません。

BaseEngine.ini には、NoShared といった DDC エントリがデフォルトでいくつか含まれているため、前出の在宅勤務のユースケースで使用することができます (-ddc=NoShared)。

Q: ディスク容量が足りない場合、ローカル DDC を他の場所に移動できますか。

はい。プロジェクトの [Editor Preferences (エディタの環境設定)] で調整してください。また、UE-LocalDataCachePath という環境変数を選択したパスに設定することもできます。例: UE-LocalDataCachePath=D:\DDC

コマンドプロンプトで setx UE-LocalDataCachePath D:\DDC と入力します。
Unreal Editor と、それを起動するアプリケーション (Epic Launcher、UGS、Visual Studio など) を再起動します。

これは、主とするドライブの容量が限られている場合や、複数のブランチで作業している場合に、データの重複を回避する目的で使用することができます。

Q: ネットワーク接続が遅い場合、共有 DDC をオフにできますか。

はい。以下の 3 つのオプションがあります。

(推奨されるオプションであり、自動です) DefaultEngine.ini を開き、パラメータ DeactivateAt=40 を共有 DDC 構成に追加します。共有 DDC へのレイテンシが 40 ミリ秒を超えると、共有 DDC はセルフで無効化します。40 の値は、ユースケースにより適した値に置き換え可能です。この方法は、ファイルシステムタイプまたは Unreal Zen ストアタイプの共有 DDC で利用できます。
DDC の環境変数を None に設定すると、DDC を無効化します。この場合、UE-SharedDataCachePath=None を設定します。
-ddc=noshared で Unreal Editor を起動します。

Q：共有 DDC パスを変更できますか？

はい。すでに触れた UE-SharedDataCachePath を設定するとパスを変更できます。

ただし、UE-SharedDataCachePath を決してローカルパスに設定しないでください。これを行うと、ローカルキャッシュと共有キャッシュの両方がマシンに存在することになり、ディスクスペースが 2 倍になり、ゲインはゼロになります。

実験的機能: Unreal Zen Storage タイプの DDC をお使いの場合、環境変数 UE-ZenSharedDataCacheHost=hostname を使って (パスではなく) ホストを変更することができます (Mac の環境変数は UE_ZenSharedDataCacheHost=hostname)。

Q：DDC の問題をどのように診断できますか？

Unreal Editor が DDC データを正しく読み込んでいないと感じる場合、LogDerivedDataCache のログファイルを調べます。

ログファイル

LogDerivedDataCache: Display: Max Cache Size: 512 MB
LogDerivedDataCache: FDerivedDataBackendGraph:  Pak pak cache file ../../../EngineTest/DerivedDataCache/DDC.ddp **not** found, will **not** **use** a pak cache.
LogDerivedDataCache: Unable to find inner node Pak **for** hierarchical cache Hierarchy.
LogDerivedDataCache: FDerivedDataBackendGraph:  EnginePak pak cache file ../../../Engine/DerivedDataCache/DDC.ddp **not** found, will **not** **use** a pak cache.
LogDerivedDataCache: Unable to find inner node EnginePak **for** hierarchical cache Hierarchy.
LogDerivedDataCache: Found environment variable UE-LocalDataCachePath=D:\DDC
LogDerivedDataCache: Using Local data cache path D:\DDC: Writable
LogDerivedDataCache: Using Shared data cache path \\epicgames.net\root\DDC-Global-UE:Writable

この例では以下が表示されます。

プロジェクトまたは Engine Pak のキャッシュが存在しません。このビルドは Perforce からコンパイルされたものであるためです。
このローカルデータキャッシュパスは書き込み可能です。D:\DDC にマップされます。
Epic の書き込み可能な共有キャッシュを使っています。

詳細なロギングをオンにするには、-logcmds="LogDerivedDataCache Verbose" で実行します。

Q：DDC Pak はどのように作成するのですか？

プロジェクトに特化した DDC を作成する場合、UnrealEditor.exe ProjectName -run=DerivedDataCache -fill -DDC=CreatePak を実行します。

このコマンドが、プロジェクト内のすべてのコンテンツの DDC を作成します。別の方法としては、オートメーションやユーザーセッションの実行中に -DDC=CreatePak を指定することで、よりターゲットを絞ったコンテンツのセットを生成できます。

Engine DDC を作成する場合は、UnrealEditor.exe -run=DerivedDataCache -fill -DDC=CreatePak を実行します。

ファイルシステムのローカル DDC から Unreal Zen Storage のローカル DDC への移行

Q: Unreal Zen Storage (ZenServer) とは何ですか。

ZenServer としても知られる Unreal Zen Storage は、Epic が作成した、Unreal Editor の外部で複数種類のデータを管理するプログラムです。これは、ローカル DDC データを管理するために使用できます。

Unreal Editor に合わせて自動的に開いたり閉じたりしますが、閉じても実行し続けるように設定可能です。

Q: ローカル DDC から Unreal Zen Storage ローカル DDC に移行するとどうなりますか。

単なるファイルフォルダから変化し、ローカル DDC は Unreal Zen Storage を使ってコンピュータ上のキャッシュデータを管理するようになります。これは Windows、Mac、Linux 環境で完了しています。

Q: これはコンピュータのディスク容量を消費しますか。

はい。この変更により、古いローカル DDC ファイルのフォルダは保持され、新しい Unreal Zen Storage ローカル DDC でそれらを使用できる設計になっています。このためデータが重複する可能性がありますが、古いローカル DDC フォルダは 8 日後に未使用のデータを削除します。

Q: Unreal Editor で DDC 構成を変更する必要がありますか。

いいえ。Unreal Zen Storage は既存の構成設定を使用するため、DDC の構成に関するガイダンスに変更はありません。

Q: Unreal Zen Storage はローカル DDC データをどこに保存しますか。

Unreal Zen Storage は、ローカル DDC データに、UE ワークスペースのルートディレクトリ外で設定されたパスと、以下のいずれかがあれば、既存のローカル DDC 構成を尊重します。

Unreal Editor の DDC 設定で設定されたグローバルローカル DDC パス。
環境変数を介したローカル DDC パスのオーバーライド。
コマンドライン引数を介したローカル DDC パスのオーバーライド。

当てはまる場合、Unreal Zen Storage は指定されたパスの Zen のサブフォルダにデータを保存します。

当てはまらない場合、Unreal Zen Storage は、以前のファイルシステム DCC で使用したパスとは異なる、デフォルトのパスを使用します。Windows でのデフォルトのパス: C:\ProgramData\Epic\Zen\Data\。

一般的な、ユーザーのシステムドライブが他のドライブよりも高速である状況でのユースケースをサポートするため、デフォルトはシステムドライブに設定されています。別の場所を使用する場合は、前出の構成オプションのいずれかを使用して代替のパスを指定することができます。

Q: Unreal Zen Storage を実行すると、ツーリングを使用して同期する際のアビリティに支障をきたしますか。

いいえ。お使いのツーリングは ZenServer の実行可能ファイルを同期するものの、その同期された場所からは実行されません。代わりに、実行可能ファイルはインストール先 (Windows の場合は C:\ProgramData\Epic\Zen\Install\) にコピーされてから実行されます。

Unreal Editor は、新しいバージョンの ZenServer がワークスペースに同期されると自動検出し、その新しい実行可能ファイルをインストール先にコピーしてから起動します。

ZenServer は後方互換性があるよう設計されているため、ZenServer のバージョンが異なる複数のワークスペースを持つ場合、Unreal Editor はその中の最新バージョンのみを使用します。