Unreal Engine のデータレジストリ | Unreal Engine 5.7 ドキュメンテーション

Programming Language

Select an option from the dropdown to see content relevant to it.

データレジストリ は、USTRUCT タグの付いたデータ構造体用の、効率的なグローバルストレージスペースです。データレジストリは、同期および非同期のデータアクセスと、ユーザー定義のキャッシュ動作をサポートします。データレジストリは、一般的な読み取り専用データを使用するよう設計されています。

データレジストリはプラグインの一部です。データレジストリのクイックスタートでは、そのプロセスが説明されるため、基本概念のいくつかを理解することができます。ストーリーの進展やキャラクターの現在の状態など、特定のセッションベースのデータについては、エンジンのゲーム保存システムを使用します。

データレジストリは、アセットスキャンによる検索と手動による登録で、幅広いソースからデータをロードまたは生成するように設定できます。データレジストリは、複合データテーブルと似ているものの、標準的なテーブル行に加えて、カーブデータを保存でき、複数のテーブルを手動で合成するのではなく、間接レイヤーを使用します。

データソース

Data Registries gather data items from two types of sources, Data Registry Sources and Meta Data Registry Sources. These sources are not the actual data items, instead the Data Registry uses them to find or generate data items. The order in which data sources appear within a Data Registry matters, if a specific data item is not found in one source, then the Data Registry will look in the sources that appear after it in the list.

This creates the potential for override and fallback behavior, and enables context-specific sources to override generic ones. The Data Registry plugin includes built-in Data Registry Sources and Meta Data Registry Sources that wrap Data Tables (UDataTable) and Curve Tables (UCurveTable).

データレジストリソース

The Data Registry directly owns a set of Data Registry Source objects that you can create and configure in an array within the Data Registry Asset. These objects represent interfaces to specific data sources where the Data Registry can find information, such as an individual data table or a web database. You can create child classes of UDataRegistrySource if you want to handle other types of data, or implement different indirection rules to map identifiers to data items.

Any child class you create will appear in the dropdown list when you add new data sources to a Data Registry Asset.

メタデータレジストリソース

Meta Data Registry Sources create and own other data sources at runtime. Rather than explicitly list all data sources, Meta Data Registry Sources use generic rules, such as scanning a set of user-named paths, to locate Assets that contain data items. They can also listen for manual registration of specific Assets. Because Meta Data Registry Sources are dynamically generated, data sources (and the data items within those sources) that they discover load into the Data Registry at runtime. Similar to Data Registry Sources, you can create your own child classes to handle other data types, create different scanning rules, and so on. To do this, override the UMetaDataRegistrySource class.

Any child classes you create will appear in the dropdown list as options when you add new Data Sources to a Data Registry Asset.

識別子

Data Registry プラグインは独自の識別子を使用し、データレジストリおよびそこに含まれる個別のデータ項目を識別し、検索します。これらの識別子は、文字列ベースの名前ですが、FDataRegistryType (データレジストリアセット用) および FDataRegistryId (データレジストリ内の個別項目用) 構造体は、ラッパーとして機能し、便利なエディタ内機能を提供します。 FDataRegistryType はデータレジストリアセットを識別しますが、FDataRegistryId はデータレジストリとその内部の個別データ項目を識別します。データレジストリアセットを見つける、またはそこから個別のデータ項目を取り出す必要があるとき、これらの識別子型を使用できます。

各データレジストリアセットには、[レジストリ型] フィールドに一意の名前が必要です。 2 つのデータレジストリアセットに、このフィールドで同じ名前がある場合、システムは一方だけを認識して取り込みます。同様に、複数のデータ項目が同じ識別値 (名前またはゲームプレイタグ) を共有している場合、レジストリはすべての項目を読み取りますが、取り出し処理は、データレジストリアセットがロードした最初の対象だけにアクセスします。データ項目をロードする順序に関する情報については、データソースのセクションを参照してください。

C++ を使用するデベロッパーは、子データレジストリクラスを作成し、ResolveDataRegistryId 関数でオーバーライドすることにより、この動作を変更できます。

データレジストリアセット識別子

While setting up a Data Registry Asset, developers must set the Registry Type field to a unique name value. This is the identifier for the Data Registry. After setting this value, FDataRegistryType fields across the editor will immediately add the new Data Registry name to their dropdown list. This prevents user error resulting from spelling mistakes when referencing the Data Registry in other Assets, and makes the selection process quicker and easier.

データ項目の識別子

Identifying an individual data item, such as a row within a data table, requires specifying the Data Registry Asset and the data item itself. The FDataRegistryId type contains both identifiers. Its Data Registry Type field will appear as a dropdown list, from which you can select any known Data Registry by its identifying name. After selecting a Data Registry's name from that dropdown list, the Data Registry ID field will change to accommodate the Data Registry.

If the Data Registry's ID Format uses a Gameplay Tag, the user interface will display a filtered list containing that Gameplay Tag and all of its children. If the Data Registry's ID Format did not use a Gameplay Tag, the user interface will display a dropdown list of all known rows that the Data Registry Asset contains.

データレジストリアセットを編集する場合、データ項目の識別子を使用して、参照する他のアセットで変更がすぐに有効にならないことがあります。これが起きる場合、データ項目の識別子のドロップダウンリストに古い行が含まれることがあります。データレジストリ (データレジストリアセット自体ではなく) を参照するアセットの [コンパイル] ボタンをクリックして、インターフェースをその時点のデータ項目情報で更新します。

左側で、Gameplay Tag を使用する ID フォーマットで、データレジストリアセットに対する項目を選択します。

FDataRegistryId には FDataRegistryType メンバー (RegistryType と呼ばれる) があるため、個別の FDataRegistryType 識別子を必要とせずに、行を含むデータレジストリアセットを見つけることができます。

Dynamic Identifier Resolution

By default, the system looks up data items by searching for the value of the ItemName field of the FDataRegistryId you supply. If this is not the ideal behavior for your project, you can create your own UDataRegistry subclass and override the MapIdToResolvedName function to include additional FDataRegistryResolverScope structs in the local scope. By overriding the ResolveIdToName function within your FDataRegistryResolverScope subclasses, you can remap the incoming row names, even using dynamic or player-specific information. After resolving an ID, the system produces an FDataRegistryLookup which is guaranteed to be unique (within the system) and is used as the caching unique ID.

クイック関数リファレンス

次の関数は、データレジストリを開始するときに役に立ちます。これは完全なリファレンスではありませんが、これらの関数は、プロジェクトでデータレジストリをセットアップした後に、データにアクセスする必要がある場合の基本になります。

Function	Description
`UDataRegistrySubsystem::Get`	Returns a pointer to the `UDataRegistrySubsystem` instance. The only static function in the list, this function acts as the entry point to the subsystem.
`UDataRegistrySubsystem::GetRegistryForType`	Takes a name or `FDataRegistryType` (either standalone or from `FDataRegistryId::RegistryType`) and returns a `UDataRegistry` pointer to the matching Data Registry, if it exists.
`UDataRegistrySubsystem::RegisterSpecificAsset`	Searches for a Data Registry by `FDataRegistryType`, and adds a specific Asset to it. If you do not provide a valid `FDataRegistryType`, the subsystem will attempt to add the Asset to all Data Registries in the subsystem. Returns `true` if at least one Data Registry accepted the Asset.
`UDataRegistry::GetCachedItem`	Searches the Data Registry for the data item that corresponds to the `FDataRegistryId` you provide. If the item is not in the cache at the time of the function call, the function will return null. Otherwise, the function returns a const pointer to whichever struct type the Data Registry stores.
`UDataRegistry::GetAllCachedItems`	Populates a map with a pointer to the engine's `UScriptStruct` data (as a `const uint8*`) for each cached item in the Data Registry, using the item's `FDataRegistryId` as the key. Also provides the `UScriptStruct` itself through a separate output parameter. This is often useful for iterating over the cache as a debugging tool, such as using the `UScriptStruct::ExportText` function to log the contents of each cached item.
`UDataRegistry::EvaluateCachedCurve`	Finds the curve that corresponds to the `FDataRegistryId` you provide, and evaluates it for a given input value. This function will fail if the requested curve is not in the cache at the time of the call. The function's return value is of type `FDataRegistryCacheGetResult`, which provides information about the cached status of the curve you requested, and most importantly whether or not the curve was found. The curve's output value, of type `float`, comes through an output parameter.
`UDataRegistry::AcquireItem`	Similar to `GetCachedItem`, but finds the data item even if it is not cached at the time of the call. This function is asynchronous; it will run your callback function, of type `FDataRegistryItemAcquiredCallback`, when the search is complete. The function's return value is a `bool` that indicates success at scheduling the callback; a `false` return value means that there has been an error and your callback function will not run. A return value of `true` means that your callback function will run, but does not guarantee that the data item exists.

Caching struct pointers that you retrieve from a Data Registry can be unsafe. While some data items are always available, others load dynamically and the Data Registry can unload them without warning. If you are potentially dealing with data that can be unloaded, the recommended practice is to use the data immediately after retrieving it, or cache your own copy rather than keeping the pointer from the Data Registry.

ゲーム機能との統合

Data Registry プラグインは、データレジストリと Game Feature プラグインから個別のデータレジストリソースの両方を追加できます。このプロセスの仕組みの詳細は、「ゲーム機能およびモジュール式ゲームプレイ」のページを参照してください。