虚幻引擎数据注册表 | 虚幻引擎 5.7 文档

Programming Language

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

数据注册表是一种高效的全局储存空间，用于存储带有USTRUCT标签的数据结构。数据注册表支持同步和异步数据访问，以及用户定义的缓存行为。数据注册表主要用于常见的只读数据。

由于数据注册表包含在插件中，因此需要一些设置才能使用它。数据注册表快速入门详细介绍了设置流程以及一些基本概念。针对基于特定会话的数据，例如剧情进度或角色的当前状态，请使用引擎的"保存游戏（Save Game）"系统。

你可以将数据注册表设置成为从不同源头加载或生成数据，还可以通过资产扫描和手动注册来填充。数据注册表类似于复合数据表（Composite Data Tables），但除了标准的表格数据行之外，还可以存储曲线数据。此外，它使用一个间接层，而不是手动将多个表复合在一起。

数据源

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.

标识符

数据注册表插件使用独有的标识符来查找数据注册表以及其中包含的单个数据项。这些标识符本质上都是基于字符串的名称，不过FDataRegistryType（用于数据注册表资产）和FDataRegistryId（用于数据注册表中的单个数据项）结构却属于封装器，能提供实用的编辑器内部功能。 FDataRegistryType用于辨识数据注册表资产，而FDataRegistryId用于辨识数据注册表和其中的特定数据项。如果你需要查找数据注册表资产或从中检索单个数据项，可以使用这些标识符类型。

每个数据注册表资产都必须在注册表类型（Registry Type）字段中具有唯一名称。如果两个数据注册表资产在此字段中具有相同的名称，系统将仅识别和填充其中一个。类似地，如果多个数据项共用同一个标识数值（名称或Gameplay标签），那么注册表会读取所有项，但检索操作将仅访问数据注册表资产加载的第一个数据项。如需了解数据项的加载顺序，请参阅数据源小节。

使用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.

如果编辑某个数据注册表资产，在通过数据项标识符引用该资产的其他资产中，你的更改可能不会立即生效。如果发生这种情况，可能是因为数据项标识符在其下拉列表中包含废弃的数据行。在引用数据注册表（而不是数据注册表资产自身）的资产中点击编译（Compile）按钮，即可使用最新的数据项信息更新界面。

由于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.

与游戏功能集成

数据注册表插件可以添加来自游戏功能插件的数据注册表和单个数据注册表来源。如需相关流程的详细信息，请参阅游戏功能和模块化Gameplay页面。