플레이어 데이터 및 구매 시스템 구현

배경

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

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

일반적인 문제

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

• 메모리 내 접근: DataStoreService 요청은 비동기적으로 작동하는 웹 요청을 생성하며, 속도 제한의 영향을 받습니다. 이는 세션 시작 시 초기 로드에는 적합하지만, 게임 플레이 중의 높은 빈도의 읽기 및 쓰기 작업에는 적합하지 않습니다. 대부분의 개발자의 플레이어 데이터 시스템은 이 데이터를 Roblox 서버의 메모리에 저장하여 DataStoreService 요청을 다음 시나리오로 제한합니다:

  • 세션 시작 시 초기 읽기
  • 세션 종료 시 최종 쓰기
  • 최종 쓰기가 실패할 경우를 완화하기 위한 주기적인 쓰기
  • 구매 처리 중 데이터가 저장되도록 보장하는 쓰기

• 효율적인 저장: 플레이어의 세션 데이터를 단일 테이블에 저장하면 여러 값을 원자적으로 업데이트하고 더 적은 요청으로 동일한 양의 데이터를 처리할 수 있습니다. 또한 값 간의 비동기화 위험을 제거하고 롤백을 더 쉽게 처리할 수 있습니다.

  일부 개발자는 대규모 데이터 구조를 압축하기 위해 사용자 정의 직렬화를 구현하기도 합니다(일반적으로 게임 내 사용자 생성 콘텐츠를 저장하기 위해).

• 복제: 클라이언트는 플레이어 데이터에 정기적으로 접근해야 합니다(예: UI 업데이트를 위해). 플레이어 데이터를 클라이언트에 복제하는 일반적인 접근 방식은 각 데이터 구성 요소에 대해 맞춤형 복제 시스템을 만들 필요 없이 이 정보를 전송할 수 있게 해줍니다. 개발자는 클라이언트에 복제할 데이터와 복제하지 않을 데이터를 선택적으로 결정할 수 있는 옵션을 원합니다.

• 오류 처리: 데이터 저장소에 접근할 수 없을 때, 대부분의 솔루션은 재시도 메커니즘과 '기본' 데이터로의 대체를 구현합니다. 대체 데이터가 나중에 '실제' 데이터를 덮어쓰지 않도록 특별한 주의가 필요하며, 이를 플레이어에게 적절히 전달해야 합니다.

• 재시도: 데이터 저장소에 접근할 수 없을 때, 대부분의 솔루션은 재시도 메커니즘과 기본 데이터로의 대체를 구현합니다. 대체 데이터가 나중에 "실제" 데이터를 덮어쓰지 않도록 특별한 주의가 필요하며, 상황을 플레이어에게 적절히 전달해야 합니다.

• 세션 잠금: 단일 플레이어의 데이터가 여러 서버에 로드되고 메모리에 있을 경우, 한 서버가 오래된 정보를 저장하는 문제가 발생할 수 있습니다. 이는 데이터 손실 및 일반적인 아이템 중복 루프홀로 이어질 수 있습니다.

• 원자적 구매 처리: 아이템이 분실되거나 여러 번 수여되지 않도록 구매를 원자적으로 확인하고 수여하며 기록합니다.

샘플 코드

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

모델을 Studio에 가져온 후, 다음과 같은 폴더 구조를 볼 수 있어야 합니다:

아키텍처

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

재시도

Class: DataStoreWrapper

배경

DataStoreService가 내부적으로 웹 요청을 생성하므로, 그 요청이 성공할 것이라는 보장은 없습니다. 이럴 경우, DataStore 메서드는 오류를 발생시켜 이를 처리할 수 있게 합니다.

데이터 저장소 실패를 처리하려고 할 때 발생할 수 있는 일반적인 "함정"은 다음과 같습니다:

local MAX_ATTEMPTS = 5
local BASE_DELAY = 2
local MAX_DELAY = 32

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

		if success then
			return result
		end

		if attempt < MAX_ATTEMPTS then
			local backoff = math.min(MAX_DELAY, BASE_DELAY * (2 ^ (attempt - 1)))
			local jitter = math.random() * backoff
			task.wait(math.min(MAX_DELAY, backoff + jitter))
		end
	end
end

일시적인 실패를 지수 백오프 및 무작위 지터로 재시도하여 서버가 동시에 재시도하지 않도록 합니다. 지연 및 시도 횟수를 제한합니다.

이 지연 패턴이 있더라도, 이 재시도 메커니즘은 DataStoreService 요청에 적합하지 않습니다. 요청이 이루어지는 순서를 보장하지 않기 때문입니다. 요청의 순서를 유지하는 것은 DataStoreService 요청에 중요합니다. 왜냐하면 이 요청들이 상태와 상호작용하기 때문입니다. 다음 시나리오를 고려해 보십시오:

1. 요청 A가 키 K의 값을 1로 설정하기 위해 이루어집니다.
2. 요청이 실패하므로 재시도가 백오프 지연 후에 실행되도록 예약됩니다.
3. 재시도가 발생하기 전에 요청 B가 K의 값을 2로 설정하지만, 요청 A의 재시도가 즉시 이 값을 덮어쓰고 K를 1로 설정합니다.

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

우리의 플레이어 데이터 시스템은 DataStoreWrapper라는 새로운 클래스를 사용하여, 키별로 순서대로 처리되도록 보장된 재시도를 제공합니다.

접근 방식

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

이 메서드들이 호출될 때:

1. 요청을 큐에 추가합니다. 각 키는 자체 큐를 가지며, 요청은 순서대로 시리즈로 처리됩니다. 요청하는 스레드는 요청이 완료될 때까지 대기합니다.

   이 기능은 코루틴 기반의 작업 스케줄러 및 속도 제한기인 ThreadQueue 클래스에 기반합니다. 약속을 반환하는 대신, ThreadQueue는 작업이 완료될 때까지 현재 스레드를 대기시키고 실패할 경우 오류를 발생시킵니다. 이는 관용적인 비동기 Luau 패턴과 더 일치합니다.

2. 요청이 실패하면, 구성 가능한 지수 백오프를 사용하여 재시도합니다. 이러한 재시도는 ThreadQueue에 제출된 콜백의 일부를 형성하므로, 이 키에 대한 다음 요청이 시작되기 전에 완료될 것이 보장됩니다.

3. 요청이 완료되면, 요청 메서드는 success, result 패턴으로 반환됩니다.

DataStoreWrapper는 또한 주어진 키에 대한 큐 길이를 가져오고 오래된 요청을 지우는 메서드를 노출합니다. 후자의 옵션은 서버가 종료되고 가장 최근의 요청 외에는 처리할 시간이 없을 때 특히 유용합니다.

주의 사항

DataStoreWrapper는 극단적인 시나리오를 제외하고는 모든 데이터 저장소 요청이 완료되도록 허용해야 한다는 원칙을 따릅니다(성공적으로 완료되거나 그렇지 않든). 새로운 요청이 발생할 때, 오래된 요청은 큐에서 제거되지 않고 대신 완료될 수 있도록 허용됩니다. 이러한 접근 방식의 근거는 이 모듈이 특정 플레이어 데이터 도구가 아닌 일반 데이터 저장소 유틸리티로서의 적용 가능성에 뿌리를 두고 있습니다. 그 이유는 다음과 같습니다:

1. 요청을 큐에서 제거할 때 안전한지에 대한 직관적인 규칙을 결정하기 어렵습니다. 다음 큐를 고려해 보십시오:

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

   예상되는 동작은 GetAsync()가 1을 반환하는 것이지만, 가장 최근의 요청으로 인해 SetAsync() 요청을 큐에서 제거하면 0을 반환하게 됩니다.

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

   DataStoreWrapper는 UpdateAsync() 요청이 읽기 및/또는 쓰기가 허용되었는지 지정하도록 요구할 수 있지만, 이는 세션 잠금 메커니즘으로 인해 사전에 결정할 수 없으므로 우리의 플레이어 데이터 시스템에는 적용되지 않습니다(자세한 내용은 나중에 다룹니다).

2. 큐에서 제거된 후, 이를 처리하는 방법에 대한 직관적인 규칙을 결정하기 어렵습니다. DataStoreWrapper 요청이 이루어지면, 현재 스레드는 완료될 때까지 대기합니다. 오래된 요청을 큐에서 제거하면 false, "큐에서 제거됨"을 반환할지 아니면 반환하지 않고 활성 스레드를 폐기할지 결정해야 합니다. 두 접근 방식 모두 단점이 있으며 소비자에게 추가적인 복잡성을 부여합니다.

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

세션 잠금

Class: SessionLockedDataStoreWrapper

배경

플레이어 데이터는 서버의 메모리에 저장되며, 필요할 때만 기본 데이터 저장소에서 읽고 씁니다. 웹 요청 없이 즉시 메모리 내 플레이어 데이터를 읽고 업데이트할 수 있으며, DataStoreService의 한계를 초과하는 것을 피할 수 있습니다.

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

예를 들어, 서버 A가 플레이어 데이터를 로드하면, 서버 B는 서버 A가 최종 저장 중에 잠금을 해제할 때까지 해당 데이터를 로드할 수 없습니다. 잠금 메커니즘이 없으면, 서버 B는 서버 A가 메모리에 있는 최신 버전을 저장할 기회를 갖기 전에 데이터 저장소에서 오래된 플레이어 데이터를 로드할 수 있습니다. 그런 다음 서버 A가 최신 데이터를 저장한 후 서버 B가 오래된 데이터를 로드하면, 서버 B는 다음 저장 시 그 최신 데이터를 덮어쓰게 됩니다.

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

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

이러한 시나리오는 드물어야 하지만 발생할 수 있으며, 특히 플레이어가 한 서버에서 다른 서버로 빠르게 연결을 끊고 연결할 때(예: 텔레포트 중) 발생할 수 있습니다. 일부 악의적인 사용자는 이 동작을 악용하여 지속되지 않는 작업을 완료하려고 시도할 수 있습니다. 이는 플레이어가 거래를 할 수 있는 게임에서 특히 영향을 미칠 수 있으며, 아이템 중복 악용의 일반적인 원인입니다.

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

접근 방식

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

SessionLockedDataStoreWrapper는 모든 DataStore 요청을 UpdateAsync를 통해 전달합니다. 이는 UpdateAsync가 키를 원자적으로 읽고 쓸 수 있도록 허용하기 때문입니다. 또한 읽은 값에 따라 쓰기를 포기할 수도 있습니다.

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

1. 키에 안전하게 접근할 수 있는지 확인하고, 그렇지 않으면 작업을 포기합니다. "안전하게 접근할 수 있다"는 것은:

   • 키의 메타데이터 객체에 인식되지 않는 LockId 값이 포함되어 있지 않으며, 이는 잠금 만료 시간보다 짧은 시간 전에 마지막으로 업데이트된 것입니다. 이는 다른 서버가 설정한 잠금을 존중하고, 만료된 경우 그 잠금을 무시하는 것을 포함합니다.

   • 이 서버가 이전에 키의 메타데이터에 자신의 LockId 값을 설정한 경우, 이 값이 여전히 키의 메타데이터에 존재합니다. 이는 다른 서버가 이 서버의 잠금을 인수(만료 또는 강제로)하고 나중에 이를 해제한 상황을 설명합니다. 다른 서버가 잠금을 대체하고 제거했을 수 있습니다.

2. UpdateAsync는 SessionLockedDataStoreWrapper 소비자가 요청한 DataStore 작업을 수행합니다. 예를 들어, GetAsync()는 function(value) return value end로 변환됩니다.

3. 요청에 전달된 매개변수에 따라 UpdateAsync는 키를 잠그거나 잠금을 해제합니다:

   1. 키를 잠그려면, UpdateAsync는 키의 메타데이터에 LockId를 GUID로 설정합니다. 이 GUID는 서버의 메모리에 저장되어 다음에 키에 접근할 때 확인할 수 있습니다. 서버가 이미 이 키에 대한 잠금을 가지고 있다면, 아무런 변경도 하지 않습니다. 또한 잠금 만료 시간 내에 잠금을 유지하기 위해 다시 접근하지 않으면 경고하는 작업을 예약합니다.

   2. 키를 잠금 해제하려면, UpdateAsync는 키의 메타데이터에서 LockId를 제거합니다.

세션이 잠겨 있을 때 1단계에서 작업이 중단된 경우, 기본 DataStoreWrapper에 사용자 정의 재시도 핸들러가 전달되어 작업이 재시도됩니다.

세션 잠금의 경우, 클라이언트에 대체 오류를 보고할 수 있도록 소비자에게 사용자 정의 오류 메시지도 반환됩니다.

주의 사항

세션 잠금 체계는 서버가 키에 대한 작업을 완료한 후 항상 잠금을 해제해야 한다는 원칙에 의존합니다. 이는 항상 PlayerRemoving 또는 BindToClose()의 최종 쓰기 과정에서 키의 잠금을 해제하는 지침을 통해 이루어져야 합니다.

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

• 서버가 충돌했거나 DataStoreService가 키에 접근하기 위한 모든 시도에서 작동하지 않았습니다.
• 논리 오류나 유사한 버그로 인해 키의 잠금을 해제하라는 지침이 이루어지지 않았습니다.

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

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

개발자 제품 처리

싱글톤: ReceiptHandler

배경

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

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

1. 구매가 이전에 처리되지 않았습니다.

2. 구매가 현재 세션에 반영됩니다.

3. 구매가 DataStore에 저장되었습니다.

   모든 구매는 일회성 소비재라도 DataStore에 반영되어 사용자의 구매 기록이 세션 데이터에 포함되어야 합니다.

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

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

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

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

세션 잠금은 플레이어의 DataStore에 대한 쓰기가 성공하면, 데이터가 로드되고 저장되는 동안 다른 서버가 플레이어의 DataStore를 성공적으로 읽거나 쓰지 않았음을 보장합니다. 간단히 말해, 이 서버의 메모리 내 플레이어 데이터는 사용 가능한 최신 버전입니다. 몇 가지 주의 사항이 있지만, 이 동작에는 영향을 미치지 않습니다.

접근 방식

ReceiptProcessor의 주석은 접근 방식을 설명합니다:

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

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

   플레이어의 데이터가 아직 로드되지 않은 경우(플레이어가 게임에 접속할 때 예상되는 상황), 플레이어의 데이터가 로드될 때까지 대기합니다. 시스템은 또한 플레이어의 데이터가 로드되기 전에 플레이어가 게임을 떠나는 경우를 감지하여, 무한정 대기하지 않고 이 콜백이 다시 호출되는 것을 차단합니다.

2. PurchaseId가 플레이어 데이터에서 이미 처리된 것으로 기록되지 않았는지 확인합니다.

   세션 잠금 덕분에 시스템이 메모리에 보유한 PurchaseIds 배열은 최신 버전입니다. PurchaseId가 처리된 것으로 기록되어 있고 DataStore에 반영된 값에 포함되어 있다면, PurchaseGranted를 반환합니다. 처리된 것으로 기록되어 있지만 DataStore에 반영되지 않았다면, NotProcessedYet를 반환합니다.

3. 현재 서버의 플레이어 데이터를 로컬에서 업데이트하여 구매를 "수여"합니다.

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

   이 단계가 완료되면, 플레이어는 현재 세션에서 구매에 대한 접근 권한을 받습니다. 이는 플레이어의 데이터가 5단계에서 저장되지 않으면, 플레이어가 세션 동안 무료로 구매를 받게 됨을 의미합니다.

4. 플레이어 데이터를 로컬에서 업데이트하여 PurchaseId를 저장합니다.

5. 메모리 내 데이터를 DataStore에 저장하기 위한 요청을 제출하며, 요청이 성공하면 PurchaseGranted를 반환합니다. 그렇지 않으면 NotProcessedYet를 반환합니다.

   이 저장 요청이 성공하지 않더라도, 플레이어의 메모리 내 세션 데이터에 대한 후속 요청은 여전히 성공할 수 있습니다. 다음 ProcessReceipt 호출에서 2단계가 이 상황을 처리하고 PurchaseGranted를 반환합니다.

플레이어 데이터

싱글톤: PlayerData.Server, PlayerData.Client

배경

코드가 플레이어 세션 데이터를 동기적으로 읽고 쓸 수 있는 인터페이스를 제공하는 모듈은 Roblox 게임에서 일반적입니다. 이 섹션에서는 PlayerData.Server와 PlayerData.Client를 다룹니다.

접근 방식

PlayerData.Server와 PlayerData.Client는 다음을 처리합니다:

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

플레이어 데이터 로드

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

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

   대안으로 플레이어를 퇴장시키는 방법도 있지만, 우리는 플레이어가 기본 데이터로 플레이할 수 있도록 하고 발생한 일에 대한 명확한 메시지를 제공하는 것을 권장합니다.

2. 로드된 데이터와 오류 상태(있는 경우)를 포함하는 초기 페이로드가 PlayerDataClient에 전송됩니다.

3. 플레이어에 대해 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. 플레이어가 게임을 떠날 때, 시스템은 다음 단계를 수행합니다:

   1. 플레이어의 데이터를 데이터 저장소에 쓰는 것이 안전한지 확인합니다. 안전하지 않은 시나리오에는 플레이어의 데이터가 로드되지 않거나 여전히 로드 중인 경우가 포함됩니다.
   2. SessionLockedDataStoreWrapper를 통해 현재 메모리 내 데이터 값을 데이터 저장소에 쓰고, 완료되면 세션 잠금을 해제하는 요청을 합니다.
   3. 서버 메모리에서 플레이어의 데이터(및 메타데이터 및 오류 상태와 같은 기타 변수)를 지웁니다.

2. 주기적인 루프에서 서버는 각 플레이어의 데이터를 데이터 저장소에 씁니다(저장할 수 있는 것이 안전한 경우). 이 환영하는 중복성은 서버 충돌 시 손실을 완화하며, 세션 잠금을 유지하는 데도 필요합니다.

   샘플은 AUTO_SAVE_INTERVAL 초(기본값 180) 후에 하나의 공유 루프를 시작한 다음, 모든 로드된 플레이어를 병렬로 저장합니다. 이 루프는 서버나 플레이어를 오프셋하지 않으므로, 비슷한 시점에 시작하는 서버가 함께 플러시할 수 있습니다.

   각 플레이어의 첫 번째 저장을 간격 내의 무작위 기간으로 오프셋하여 실시간 서버가 동시에 쓰지 않도록 합니다:

   local AUTO_SAVE_INTERVAL = 180
   
   local function startAutoSave(player)
   	task.spawn(function()
   		task.wait(math.random() * AUTO_SAVE_INTERVAL)
   
   		while player.Parent do
   			if canSave(player) then
   				savePlayerData(player)
   			end
   			task.wait(AUTO_SAVE_INTERVAL)
   		end
   	end)
   end

3. 서버 종료 요청을 받으면, BindToClose 콜백에서 다음이 발생합니다:

   1. 서버에서 각 플레이어의 데이터를 저장하기 위한 요청이 이루어지며, 이는 플레이어가 서버를 떠날 때 일반적으로 거치는 과정입니다. 이러한 요청은 병렬로 이루어지며, BindToClose 콜백은 완료될 때까지 반환되지 않습니다.
   2. 저장을 신속하게 하기 위해, 각 키의 큐에 있는 모든 다른 요청이 기본 DataStoreWrapper에서 지워집니다(자세한 내용은 재시도 참조).
   3. 콜백은 모든 요청이 완료될 때까지 반환되지 않습니다.