플레이어 데이터 및 구매 시스템 구현 | 설명서

배경

Roblox는 DataStoreService를 통해 데이터 스토어와 인터페이스할 수 있는 API 세트를 제공합니다. 이 API의 가장 일반적인 사용 사례는 _플레이어 데이터_를 저장하고, 로드하며, 복제하는 것입니다. 즉, 플레이어의 진행 상황, 구매 및 기타 세션 특성과 관련된 데이터로, 개별 게임 세션 간에 유지됩니다.

대부분의 Roblox 게임은 이러한 API를 사용하여 플레이어 데이터 시스템의 어떤 형태를 구현합니다. 이러한 구현은 접근 방식이 다르지만 일반적으로 동일한 문제를 해결하고자 합니다.

일반적인 문제

아래는 플레이어 데이터 시스템이 해결하고자 하는 가장 일반적인 문제들입니다:

메모리 내 접근: DataStoreService 요청은 비동기적으로 작동하는 웹 요청을 하고, 비율 제한에 좌우됩니다. 이는 세션 시작 시 초기 로드에는 적합하지만, 게임 진행 중 높은 빈도의 읽기 및 쓰기 작업에는 적합하지 않습니다. 대부분의 개발자가 구현하는 플레이어 데이터 시스템은 이러한 데이터를 Roblox 서버의 메모리 내에 저장하여 DataStoreService 요청을 다음과 같은 시나리오로 제한합니다:
- 세션 시작 시 초기 읽기
- 세션 종료 시 최종 쓰기
- 최종 쓰기가 실패하는 상황을 완화하기 위해 주기적인 쓰기
- 구매 처리 중 데이터 저장 보장을 위한 쓰기
효율적인 저장: 플레이어의 세션 데이터를 단일 테이블에 저장하면 여러 값을 원자적으로 업데이트할 수 있고, 더 적은 요청으로 동일한 양의 데이터를 처리할 수 있습니다. 또한 값 간 비동기화의 위험을 제거하고 롤백을 더 용이하게 만듭니다.

일부 개발자는 대형 데이터 구조를 압축하기 위해 커스텀 직렬화를 구현하기도 합니다(일반적으로 게임 내 사용자 생성 콘텐츠를 저장하기 위해).
복제: 클라이언트는 플레이어의 데이터에 정기적으로 접근해야 합니다(예: UI를 업데이트하기 위해). 플레이어 데이터를 클라이언트에 복제하는 일반적인 접근 방식은 각 데이터 구성 요소에 대한 맞춤형 복제 시스템을 만들지 않고도 이 정보를 전송할 수 있게 해줍니다. 개발자는 종종 클라이언트에 복제할 데이터와 복제하지 않을 데이터를 선택할 수 있는 옵션을 원합니다.
오류 처리: 데이터 스토어에 접근할 수 없는 경우 대부분의 솔루션은 재시도 메커니즘과 '기본' 데이터로의 백업을 구현합니다. 백업 데이터가 나중에 '실제' 데이터를 덮어쓰지 않도록 특별히 주의해야 하며, 이를 플레이어에게 적절히 전달해야 합니다.
재시도: 데이터 스토어에 접근할 수 없을 때 대부분의 솔루션은 재시도 메커니즘과 기본 데이터로의 백업을 구현합니다. 백업 데이터가 나중에 "실제" 데이터를 덮어쓰지 않도록 특별히 주의하고, 플레이어에게 상황을 적절히 전달합니다.
세션 잠금: 단일 플레이어의 데이터가 여러 서버에서 메모리 내에 로드되면 구식 정보를 저장하는 서버에서 문제가 발생할 수 있습니다. 이는 데이터 손실과 일반적인 아이템 중복 루프홀로 이어질 수 있습니다.
원자적 구매 처리: 아이템이 분실되거나 여러 번 수여되지 않도록 구매를 확인하고, 수여하며, 기록을 원자적으로 처리합니다.

샘플 코드

이 코드는 참조 목적으로만 제공되며 인기 게임에서 오랜 기간 동안 검증되지 않았습니다. 다양한 문제를 해결하기 위한 접근 방식을 검토하고 이를 귀하의 플레이어 데이터 시스템에 적용할 수 있도록 존재합니다. 철저한 테스트 없이 이 코드를 그대로 게임에서 사용하지 마십시오.

Roblox는 플레이어 데이터 시스템을 설계하고 구축하는 데 도움이 되는 참조 코드를 제공합니다. 이 페이지의 나머지 부분에서는 배경, 구현 세부정보 및 일반 주의 사항을 다룹니다.

모델을 Studio에 가져온 후, 다음과 같은 폴더 구조를 확인할 수 있습니다:

아키텍처

이 상위 수준의 다이어그램은 샘플의 주요 시스템과 이들이 게임의 나머지 코드와 어떻게 인터페이스하는지를 보여줍니다.

재시도

Class: DataStoreWrapper

배경

DataStoreService가 내부에서 웹 요청을 수행하므로 그 요청이 성공할 것이라는 보장은 없습니다. 이렇게 되면 DataStore 메서드가 오류를 발생시켜 이를 처리할 수 있게 됩니다.

다음과 같이 데이터 스토어 실패를 처리하려고 하면 일반적인 "함정"이 발생할 수 있습니다:


local function retrySetAsync(dataStore, key, value)
	for _ = 1, MAX_ATTEMPTS do
		local success, result = pcall(dataStore.SetAsync, dataStore, key, value)

		if success then
			break
		end

		task.wait(TIME_BETWEEN_ATTEMPTS)
	end
end

이것은 일반적인 함수에 대해 완전히 유효한 재시도 메커니즘이지만, DataStoreService 요청에 적합하지 않습니다. 요청이 이루어지는 순서를 보장하지 않기 때문입니다. 요청 순서를 보존하는 것은 상태와 상호작용하는 DataStoreService 요청에 중요합니다. 다음 시나리오를 고려하십시오:

요청 A가 키 K의 값을 1로 설정하기 위해 이루어집니다.
요청이 실패하므로 2초 후에 재시도가 예약됩니다.
재시도가 발생하기 전에 요청 B가 K의 값을 2로 설정합니다. 그러나 요청 A의 재시도가 이 값을 즉시 덮어쓰고 K를 1로 설정합니다.

비록 UpdateAsync가 키의 최신 버전에서 작동하지만, UpdateAsync 요청은 잘못된 전이 상태를 피하기 위해 여전히 순서에 따라 처리되어야 합니다(예: 구매가 코인을 차감하기 전에 코인 추가가 처리되어 음수의 코인이 나타나는 경우).

우리의 플레이어 데이터 시스템은 키당 순서대로 처리되는 재시도 처리 메커니즘을 제공하는 새로운 클래스인 DataStoreWrapper를 사용합니다.

접근 방식

DataStoreWrapper는 DataStore 메서드에 해당하는 메서드를 제공합니다: DataStore:GetAsync(), DataStore:SetAsync(), DataStore:UpdateAsync() 및 DataStore:RemoveAsync().

이 메서드들이 호출되면:

요청이 큐에 추가됩니다. 각 키는 요청이 순서대로 처리되는 고유한 큐를 가지고 있습니다. 요청 스레드는 요청이 완료될 때까지 대기합니다.

이 기능은 coroutine 기반 작업 스케줄러이자 비율 제한기인 ThreadQueue 클래스에 기반하고 있습니다. 프로미스를 반환하는 대신, ThreadQueue는 작업이 완료될 때까지 현재 스레드를 대기하게 하고 실패할 경우 오류를 발생시킵니다. 이는 우아한 비동기 Luau 패턴과 더 일치합니다.
요청이 실패하면 구성 가능한 지수적 백오프를 사용하여 재시도합니다. 이러한 재시도는 ThreadQueue에 제출된 콜백의 일부로 형성되므로 이 키에 대한 다음 요청이 시작되기 전에 완료되도록 보장됩니다.
요청이 완료되면 요청 메서드는 success, result 패턴으로 반환됩니다.

DataStoreWrapper는 특정 키의 큐 길이를 가져오고, 오래된 요청을 제거하는 메서드도 노출합니다. 후자는 서버가 종료되고 최근 요청 외에는 처리할 시간이 없을 때 특히 유용합니다.

DataStoreWrapper는 극단적인 시나리오를 제외하고는 모든 데이터 스토어 요청이 완료되도록 허용해야 한다는 원칙을 따릅니다(성공적이든 아니든). 새로운 요청이 발생하면 오래된 요청은 큐에서 제거되지 않고 완료될 수 있도록 합니다. 새로운 요청이 시작되기 전에. 이러한 이유로 이 모듈의 적용 가능성은 특정 플레이어 데이터 도구가 아닌 일반 데이터 스토어 유틸리티이므로 다음과 같습니다:

요청이 큐에서 안전하게 제거되는 직관적인 규칙 집합을 결정하기가 어렵습니다. 다음 큐를 고려하십시오:

Value=0, SetAsync(1), GetAsync(), SetAsync(2)

기대되는 동작은 GetAsync()가 1을 반환하는 것입니다. 그러나 SetAsync() 요청을 가장 최근의 요청에 의해 불필요하게 큐에서 제거하면 0을 반환하게 됩니다.

논리적인 진행은 새로운 쓰기 요청이 추가될 때 가장 최근의 읽기 요청까지 오래된 요청을 정리하는 것입니다. UpdateAsync()는 이 시스템에서 사용되는 가장 일반적인 작업이므로 읽기와 쓰기를 모두 할 수 있으며, 설계 내에서 이를 조정하기 어려워 추가 복잡성을 초래할 수 있습니다.

DataStoreWrapper는 UpdateAsync() 요청이 읽기 및/또는 쓰기가 허용되는지 여부를 지정하도록 요구할 수 있습니다. 그러나 플레이어 데이터 시스템에는 적절히 확인할 수 없으며, 세션 잠금 메커니즘이 다루어지기 때문입니다(자세한 내용은 뒤에서 설명합니다).
큐에서 제거된 경우 어떻게 처리할지에 대한 직관적인 규칙을 결정하는 것은 어렵습니다. DataStoreWrapper 요청이 들어올 때 현재 스레드는 완료될 때까지 대기하게 됩니다. 오랜 요청을 큐에서 제거하면 false, "Removed from queue"를 반환하거나 절대 반환하지 않고 활성 스레드를 버릴 가능성을 결정해야 합니다. 두 접근 방식 모두 단점이 있으며 소비자에게 추가 복잡성을 초래합니다.

궁극적으로, 우리의 관점은 단순한 접근(모든 요청을 처리하는 것)이 여기서 바람직하며, 세션 잠금과 같은 복잡한 문제에 접근할 때 탐색하기 더 명확한 환경을 만든다고 생각합니다. 유일한 예외는 DataModel:BindToClose() 동안으로, 이 경우에는 모든 사용자의 데이터를 제시간에 저장하기 위해 큐를 비우는 것이 필요하며, 개별 함수 호출에서 반환되는 값은 더 이상 진행 중인 문제가 아닙니다. 이를 통해 skipAllQueuesToLastEnqueued 메서드가 노출됩니다. 더 많은 컨텍스트는 플레이어 데이터를 참조하세요.

세션 잠금

Class: SessionLockedDataStoreWrapper

배경

플레이어 데이터는 서버의 메모리에 저장되며 필요한 경우에만 기본 데이터 스토어에서 읽고 씁니다. 웹 요청 없이 즉시 메모리 내 플레이어 데이터를 읽고 업데이트할 수 있으며 DataStoreService 한도를 초과하지 않을 수 있습니다.

이 모델이 의도한 대로 작동하려면 한 서버에서 플레이어 데이터를 한번에 하나만 메모리로 로드할 수 있도록 해야 합니다.

예를 들어, 서버 A가 플레이어 데이터를 로드 하는 경우 서버 B는 서버 A가 마지막 저장을 위한 잠금을 해제할 때까지 그 데이터를 로드할 수 없습니다. 잠금 메커니즘이 없으면, 서버 B는 서버 A가 메모리에서 더 최신 버전을 저장하기 전에 데이터 스토어에서 구식 플레이어 데이터를 로드할 수 있습니다. 그런 다음 서버 A가 서버 B가 구식 데이터를 로드한 후 업데이트된 데이터를 저장하면 서버 B는 다음 저장 과정에서 그 최신 데이터를 덮어쓰게 됩니다.

Roblox는 클라이언트가 한 번에 하나의 서버에만 연결될 수 있도록 하지만, 단일 세션의 데이터가 다음 세션이 시작되기 전에 항상 저장된다고 가정할 수는 없습니다. 플레이어가 서버 A를 떠날 때 발생할 수 있는 다음과 같은 시나리오를 고려하십시오:

서버 A는 플레이어의 데이터를 저장하기 위해 DataStore 요청을 수행하지만 요청이 실패하고 여러 번 재시도가 필요합니다. 재시도 기간 동안 플레이어는 서버 B에 접속합니다.
서버 A는 동일한 키에 대해 너무 많은 UpdateAsync() 호출을 하여 속도가 제한됩니다. 최종 저장 요청이 큐에 배치됩니다. 요청이 큐에 있는 동안 플레이어는 서버 B에 접속합니다.
서버 A에서 PlayerRemoving 이벤트에 연결된 일부 코드가 플레이어의 데이터가 저장되기 전에 대기하게 됩니다. 이 작업이 완료되기 전에 플레이어는 서버 B에 접속합니다.
서버 A의 성능이 저하되어 최종 저장이 서버 B에 접속한 이후로 지연됩니다.

이러한 시나리오들은 드물지만 발생할 수 있으며, 특히 플레이어가 빠르게 다른 서버로 연결되거나 연결 해제할 때 발생합니다(예: 텔레포트 중). 악의적인 사용자들은 특정 행동이 지속되지 않도록 이 행동을 악용하려고 시도할 수도 있으며, 이는 거래가 가능한 게임에서 특히 영향을 미칠 수 있으며 일반적인 아이템 중복 해킹의 원천입니다.

세션 잠금은 플레이어의 DataStore 키가 처음 서버에서 읽힐 때 서버가 동일한 UpdateAsync() 호출 내에서 그 키의 메타데이터에 잠금을 원자적으로 쓰도록 보장함으로써 이 취약점을 해결합니다. 다른 서버가 이 키를 읽거나 쓰려고 할 때 이 잠금 값이 존재하면 서버는 진행하지 않습니다.

접근 방식

SessionLockedDataStoreWrapper는 DataStoreWrapper 클래스의 메타 래퍼입니다. DataStoreWrapper는 큐잉 및 재시도 기능을 제공하며, SessionLockedDataStoreWrapper는 세션 잠금을 보완합니다.

SessionLockedDataStoreWrapper는 모든 DataStore 요청 (구체적으로 GetAsync, SetAsync, 또는 UpdateAsync)을 UpdateAsync를 통해 전달합니다. 이는 키를 원자적으로 읽고 쓸 수 있게 합니다. 읽은 값에 따라 작성 작업을 포기할 수도 있습니다(변환 콜백 내에서 nil 반환).

각 요청의 UpdateAsync에 전달된 변환 함수는 다음 작업을 수행합니다:

키에 안전하게 접근할 수 있는지 확인하고, 안전하지 않은 경우 작업을 포기합니다. "안전하게 접근 가능"하다는 의미는:
- 키의 메타데이터 객체에 마지막으로 업데이트된 시간이 잠금 만료 시간보다 적은 미인식 LockId 값이 포함되지 않았습니다. 이는 다른 서버에서 설정한 잠금을 존중하는 것과 만료된 경우 그 잠금을 무시하는 것을 포함합니다.
- 이 서버가 이미 키의 메타데이터에서 자신의 LockId 값을 설정한 경우, 이 값은 여전히 키의 메타데이터에 있습니다. 이는 다른 서버가 이 서버의 잠금을 인수했거나(만료 또는 강제) 이후에 해제한 경우의 상황을 감안합니다. 또는 표현방법을 변경하면, LockId가 nil일 경우에도 다른 서버가 잠금을 대체하고 제거했을 수 있습니다.
UpdateAsync는 SessionLockedDataStoreWrapper의 소비자가 요청한 DataStore 작업을 수행합니다. 예를 들어, GetAsync()는 function(value) return value end로 변환됩니다.
요청에 따라 UpdateAsync는 키를 잠금 또는 잠금 해제합니다:
1. 키를 잠금으로 설정하는 경우, UpdateAsync는 키의 메타데이터에 LockId를 GUID로 설정합니다. 이 GUID는 서버의 메모리에 저장되어 다음에 키에 접근할 때 확인할 수 있습니다. 서버가 이미 이 키에 잠금을 소유하고 있다면 아무런 변경도 이루어지지 않습니다. 또한, 잠금 만료 시간 내에 잠금을 유지하기 위해 키에 다시 접근하지 않을 경우 경고하는 작업이 예약됩니다.
2. 키를 잠금 해제하는 경우, UpdateAsync는 키의 메타데이터에서 LockId를 제거합니다.

커스텀 재시도 핸들러가 기본 DataStoreWrapper에 전달되어 세션이 잠겨 있을 때 1단계에서 작업이 중단되면 작동이 재시도됩니다.

또한 세션 잠금을 고려하여 플레이어 데이터 시스템이 클라이언트에 세션 잠금에 대한 대체 오류를 보고할 수 있도록 소비자에게 커스텀 오류 메시지가 반환됩니다.

주의 사항

세션 잠금 규칙은 서버가 키에서 작업을 완료할 때 항상 잠금을 해제해야 한다는 원칙에 의존합니다. 이는 항상 PlayerRemoving 또는 BindToClose()의 최종 쓰기 작업의 일환으로 키 잠금을 해제하는 지시를 통해 발생해야 합니다.

그러나 특정 상황에서 잠금을 해제하는 데 실패할 수 있습니다. 예를 들어:

서버가 충돌했거나 DataStoreService가 키에 접근하려는 모든 시도에 대해 작동하지 않는 경우.
논리 오류나 유사한 버그로 인해 잠금을 해제하는 지시가 내려지지 않은 경우.

키에 대한 잠금을 유지하려면 메모리에 로드된 동안 정기적으로 키에 접근해야 합니다. 이는 대부분의 플레이어 데이터 시스템에서 백그라운드에서 실행되는 자동 저장 루프의 일부로 진행되지만, 수동으로 수행해야 하는 경우를 위해 refreshLockAsync 메서드도 노출됩니다.

잠금 만료 시간이 초과되고 잠금이 업데이트되지 않은 경우에는 아무 서버나 잠금을 인수할 수 있습니다. 다른 서버가 잠금을 인수하는 경우 현재 서버가 키를 읽거나 쓸 시도는 실패하며, 새로운 잠금을 설정해야 합니다.

개발자 제품 처리

싱글턴: ReceiptHandler

배경

ProcessReceipt 콜백은 구매를 완료할 시점을 결정하는 중요한 작업을 수행합니다. ProcessReceipt는 매우 특정한 시나리오에서 호출됩니다. 보장 사항 세트에 대한 내용은 MarketplaceService.ProcessReceipt를 참조하십시오.

구매를 "처리하는" 정의는 게임 간에 다를 수 있지만, 우리는 다음 기준을 사용합니다:

구매가 이전에 처리되지 않았습니다.
구매가 현재 세션에 반영됩니다.
구매가 DataStore에 저장되었습니다.

모든 구매, 심지어 1회 소비성 구매도 DataStore에 반영되어야 하며, 이를 통해 사용자의 구매 이력이 세션 데이터에 포함됩니다.

이는 PurchaseGranted를 반환하기 전에 다음 작업을 수행해야 함을 의미합니다:

PurchaseId가 이미 처리된 것으로 기록되지 않았는지 확인합니다.
플레이어의 메모리 데이터에서 구매를 수여합니다.
플레이어의 메모리 데이터에서 PurchaseId를 처리된 것으로 기록합니다.
플레이어의 메모리 데이터를 DataStore에 기록합니다.

세션 잠금은 흐름을 단순화합니다. 이제 다음과 같은 시나리오에 대해 걱정할 필요가 없기 때문입니다:

현재 서버의 메모리 내 플레이어 데이터가 구식일 수 있어, PurchaseId 이력을 확인하기 전에 DataStore에서 최신 값을 가져와야 하는 경우
동일한 구매에 대한 콜백이 다른 서버에서 실행되고. PurchaseId 이력을 읽고 쓰고 구매가 반영된 플레이어 데이터를 원자적으로 저장해야 하므로 경쟁 조건을 방지해야 하는 경우

세션 잠금은 플레이어의 DataStore에 쓰기 시도가 성공할 경우, 그 데이터가 이 서버에서 로드되고 저장되는 동안 다른 서버가 플레이어의 DataStore를 성공적으로 읽거나 썼다는 보장이 없음을 보장합니다. 즉, 이 서버의 메모리 내 플레이어 데이터가 가장 최신 버전입니다. 몇 가지 주의 사항이 있지만, 이 동작에 영향을 미치지 않습니다.

접근 방식

ReceiptProcessor의 주석은 접근 방식을 설명하고 있습니다:

플레이어의 데이터가 현재 이 서버에 로드되어 있으며 오류 없이 로드되었는지 확인합니다.

이 시스템은 세션 잠금을 사용하므로, 이 검사는 메모리 내 데이터가 가장 최신 버전임을 확인합니다.

플레이어의 데이터가 아직 로드되지 않은 경우(플레이어가 게임에 접속할 때 기대되는 상황) 플레이어의 데이터가 로드될 때까지 기다립니다. 시스템은 또한 플레이어가 데이터가 로드되기 전에 게임에서 떠나는 것을 듣고 있는데, 이는 무한정 대기하지 않고 플레이어가 다시 접속할 때 이 서버에서 이 구매에 대한 콜백이 다시 호출되는 것을 차단하지 않기 위해서입니다.
PurchaseId가 플레이어 데이터에서 이미 처리된 것으로 기록되지 않았는지 확인합니다.

세션 잠금 덕분에 시스템이 메모리에 보유한 PurchaseIds 배열은 가장 최신 버전입니다. PurchaseId가 처리된 것으로 기록되고, DataStore에 반영된 값이 있다면 PurchaseGranted를 반환합니다. 처리된 것으로 기록되었지만 DataStore에 반영되지 않는 경우 NotProcessedYet를 반환합니다.
현재 서버에서 플레이어 데이터를 로컬에서 업데이트하여 구매를 “수여”합니다.

ReceiptProcessor는 일반 콜백 접근 방식을 사용하며 각 DeveloperProductId에 대해 다른 콜백을 할당합니다.

이 단계가 완료되는 즉시 플레이어는 현재 세션에서 구매에 대한 접근을 받게 됩니다. 이는 플레이어 데이터가 5단계에서 저장에 실패할 경우, 플레이어가 세션 동안 무료로 구매를 수여받게 됨을 의미합니다.
현재 서버에서 플레이어 데이터를 로컬에서 업데이트하여 PurchaseId를 저장합니다.
플레이어의 메모리 데이터를 DataStore에 저장하기 위한 요청을 제출하며, 요청이 성공하면 PurchaseGranted를 반환합니다. 그렇지 않으면 NotProcessedYet를 반환합니다.

이 저장 요청이 성공하지 않으면 다음 ProcessReceipt 호출에서 플레이어의 메모리 세션 데이터 저장 요청이 성공할 수 있습니다. 다음 ProcessReceipt 호출에서 2단계가 이 상황을 처리하고 PurchaseGranted를 반환합니다.

플레이어의 데이터를 메모리에 로드하며, 로드 실패 시의 경우도 처리합니다.
서버 코드가 플레이어 데이터를 조회하고 변경할 수 있는 인터페이스를 제공합니다.
플레이어 데이터의 변경 사항을 클라이언트에 복제하여 클라이언트 코드가 접근할 수 있도록 합니다.
클라이언트가 오류 대화 상자를 표시할 수 있도록 로드 및/또는 저장 오류를 클라이언트에 복제합니다.
플레이어의 데이터를 주기적으로 저장하며, 플레이어가 떠날 때 및 서버가 종료될 때 저장합니다.

플레이어 데이터 로드

SessionLockedDataStoreWrapper는 데이터 저장소에 getAsync 요청을 합니다.

이 요청이 실패하면 기본 데이터가 사용되며 프로필이 "오류"로 표시되어 나중에 데이터 저장소에 기록되지 않도록 합니다.

대체 옵션은 플레이어를 퇴출시키는 것이지만, 플레이어에게 기본 데이터와 함께 발생한 상황에 대한 명확한 메시지를 제공하는 것이 좋습니다.
로드된 데이터와 오류 상태(있는 경우)를 포함한 초기 페이로드가 PlayerDataClient에 전송됩니다.
플레이어에 대해 waitForDataLoadAsync를 사용하여 대기 중인 모든 스레드가 재개됩니다.

서버 코드에 대한 인터페이스 제공

PlayerDataServer는 같은 환경에서 실행되는 모든 서버 코드가 요구하고 접근할 수 있는 싱글턴입니다.
플레이어 데이터는 키와 값의 사전으로 구성되어 있습니다. 서버에서 이 값을 조작하려면 setValue, getValue, updateValue, removeValue 메서드를 사용할 수 있습니다. 이 메서드는 모두 대기 없이 동기적으로 작동합니다.
hasLoaded 및 waitForDataLoadAsync 메서드는 데이터에 접근하기 전에 데이터가 로드되었는지 확인할 수 있게 해줍니다. 모든 시스템이 시작되기 전에 로딩 화면에서 한 번 이 작업을 수행하는 것을 권장하여 클라이언트에서 데이터와 상호 작용하기 전마다 로드 오류를 검사할 필요가 없도록 합니다.
플레이어의 초기 로드가 실패하여 기본 데이터를 사용하게 되었는지 질의할 수 있는 hasErrored 메서드도 있습니다. 플레이어가 구매를 하도록 허용하기 전에 이 메서드를 확인해야 합니다. 구매는 성공적인 로드 없이는 데이터에 저장될 수 없습니다.
플레이어의 데이터가 변경될 때마다 playerDataUpdated 신호가 player, key, value와 함께 발송됩니다. 개별 시스템이 이를 구독할 수 있습니다.

클라이언트로 변경 사항 복제

PlayerDataServer의 플레이어 데이터에 대한 모든 변경 사항은 PlayerDataClient에 복제됩니다. 키가 setValueAsPrivate를 사용하여 비공식적으로 표시되지 않은 경우에만 가능합니다.
- setValueAsPrivate는 클라이언트로 전송되지 말아야 할 키를 обознач하는 데 사용됩니다.
PlayerDataClient는 키의 값을 가져오는(get) 메서드 및 업데이트되는 경우 신호가 발송되는(updated) 메서드를 포함합니다. 클라이언트가 데이터가 로드 및 복제될 때까지 기다릴 수 있도록 hasLoaded 메서드와 loaded 신호도 함께 제공됩니다.
PlayerDataClient는 같은 환경에서 실행되는 모든 클라이언트 코드가 요구하고 접근할 수 있는 싱글턴입니다.

오류를 클라이언트로 복제

플레이어 데이터 저장 또는 로딩 중 발생한 오류 상태가 PlayerDataClient로 복제됩니다.
getLoadError 및 getSaveError 메서드를 통해 이 정보를 접근할 수 있으며, loaded 및 saved 신호와 함께 사용할 수 있습니다.
두 가지 유형의 오류가 있습니다: DataStoreError(클래스 DataStoreService 요청이 실패함) 및 SessionLocked(세션 잠금 참조: 세션 잠금).
이러한 이벤트를 사용하여 클라이언트 구매 프롬프트를 비활성화하고 경고 대화 상자를 구현할 수 있습니다. 이 이미지는 플레이어 데이터 로드 실패 시 표시할 수 있는 경고의 예시입니다:

플레이어 데이터 저장

플레이어가 게임을 떠날 때 시스템은 다음 단계를 수행합니다:
1. 플레이어의 데이터를 데이터 저장소에 저장하기에 안전한지 확인합니다. 안전하지 않은 경우에는 플레이어의 데이터가 로드되지 않았거나 여전히 로드 중에 있습니다.
2. SessionLockedDataStoreWrapper를 통해 현재 메모리 내 데이터 값을 데이터 저장소에 쓰고 완료된 후 세션 잠금을 해제하도록 요청을 합니다.
3. 서버 메모리에서 플레이어의 데이터(및 메타데이터 및 오류 상태와 같은 기타 변수)를 지웁니다.
주기적인 루프에서 서버는 각 플레이어의 데이터를 데이터 저장소에 저장합니다(저장이 안전한 경우). 이 환영받는 중복성은 서버 충돌 시 손실을 완화하고, 세션 잠금을 유지하는 데도 필요합니다.
서버 종료 요청이 수신되면, 다음과 같은 작업이 BindToClose 콜백에서 발생합니다:
1. 서버의 각 플레이어 데이터를 저장하기 위한 요청이 이루어지며, 이는 플레이어가 서버를 떠날 때 일반적으로 진행되는 프로세스를 따릅니다. 이러한 요청은 병렬로 진행되며, BindToClose 콜백은 완료될 때까지 30초의 시간이 주어집니다.
2. 저장 작업을 신속하게 처리하기 위해 각 키의 큐에서 모든 다른 요청이 기본 DataStoreWrapper에서 지워집니다(재시도 참조: 재시도).
3. 콜백은 모든 요청이 완료될 때까지 반환하지 않습니다.