언리얼 엔진의 데이터 레지스트리 | 언리얼 엔진 5.7 문서

Programming Language

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

데이터 레지스트리(Data Registry)는 USTRUCT 태그가 지정된 데이터 구조를 위한 효율적인 글로벌 스토리지 공간입니다. 데이터 레지스트리는 동기식 및 비동기식 데이터 액세스와 사용자 정의 캐싱 행동을 지원합니다. 또한 데이터 레지스트리는 일반 읽기 전용 데이터로 작동하도록 설계되었습니다.

데이터 레지스트리는 플러그인의 일부입니다. 데이터 레지스트리 퀵스타트(Data Registries Quickstart)에서 프로세스를 살펴보고 기본 개념을 익힐 수 있습니다. 스토리 진행 상황이나 캐릭터의 현재 스테이트와 같은 특정 세션 기반 데이터는 엔진의 세이브 게임(Save Game) 시스템을 사용합니다.

데이터 레지스트리를 환경설정하여 다양한 소스로부터 데이터를 로드하거나 생성할 수 있으며, 에셋 스캔과 수동 등록으로 데이터 레지스트리를 채울 수도 있습니다. 데이터 레지스트리는 컴포짓 데이터 테이블(Composite Data Table)과 비슷하지만 표준 테이블 행뿐 아니라 커브 데이터도 저장할 수 있으며, 다수의 테이블을 수동으로 합성하는 대신 인디렉션 레이어를 사용합니다.

데이터 소스

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.

Identifiers

데이터 레지스트리 플러그인은 자체적인 식별자 타입을 사용하여 데이터 레지스트리와 여기에 포함된 개별 데이터 항목을 식별하거나 검색합니다. 이러한 식별자는 문자열 기반 이름이지만, FDataRegistryType(데이터 레지스트리 에셋의 경우) 및 FDataRegistryId(데이터 레지스트리 내 개별 항목의 경우) 구조는 래퍼(wrapper) 역할을 하며 유용한 에디터 내 함수 기능을 제공합니다. FDataRegistryType은 데이터 레지스트리 에셋을 식별하고, FDataRegistryId는 데이터 레지스트리와 그 안에 있는 특정 데이터 항목을 식별합니다. 데이터 레지스트리 에셋을 찾거나 에셋에서 개별 데이터 항목을 얻어야 할 때 이러한 식별자 타입을 사용합니다.

각 데이터 레지스트리 에셋은 Registry Type 필드에 고유한 이름이 있어야 합니다. 두 데이터 레지스트리 에셋의 이 필드 이름이 동일할 경우, 시스템은 그중 하나만 인식하고 채웁니다. 마찬가지로 여러 데이터 항목에 동일한 식별 값(이름 또는 게임플레이 태그)이 있는 경우, 레지스트리는 모든 항목을 읽지만 얻기 작업은 데이터 레지스트리 에셋이 로드한 것 중 첫 번째 항목에만 액세스합니다. 데이터 항목이 로드되는 순서에 대해 알아보려면 데이터 소스 섹션을 참조하세요.

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) 버튼을 클릭하여 현재 데이터 항목 정보로 인터페이스를 업데이트합니다.

왼쪽은 게임플레이 태그를 사용하는 ID 포맷이 적용된 데이터 레지스트리 에셋의 항목을 선택한 것입니다.

FDataRegistryId에는 RegistryType이라는 FDataRegistryType 멤버가 있으므로 별도의 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.

게임 피처와 통합

데이터 레지스트리 플러그인은 게임 피처 플러그인으로부터 데이터 레지스트리와 개별 데이터 레지스트리 소스를 모두 추가할 수 있습니다. 이 프로세스의 작동 방식에 대해 자세히 알아보려면 게임 피처 및 모듈형 게임플레이 페이지를 참조하세요.