데이터 저장소

DataStoreService는 플레이어의 인벤토리 아이템이나 스킬 포인트와 같이 세션 간에 지속해야 하는 데이터를 저장할 수 있게 해줍니다. 데이터 저장소는 게임마다 일관되므로 게임의 모든 장소가 같은 데이터에 접근하고 변경할 수 있으며, 다른 서버에 있는 장소도 포함됩니다.

데이터 저장소에 세분화된 권한 제어를 추가하고 Studio 또는 Roblox 서버 외부에서 접근하려면 데이터 저장소를 위한 Open Cloud API를 사용할 수 있습니다.

Creator Hub를 통해 게임의 모든 데이터 저장소를 보고 모니터링하려면 데이터 저장소 관리자를 사용하세요.

업데이트하거나 자주 접근해야 하는 임시 데이터에는 메모리 저장소를 사용하세요.

스튜디오 접근 활성화

기본적으로 스튜디오에서 테스트된 게임은 데이터 저장소에 접근할 수 없으므로 먼저 활성화해야 합니다. Studio에서 데이터 저장소에 접근하는 것은 클라이언트 애플리케이션과 같은 데이터 저장소에 접근하기 때문에 라이브 게임에 위험할 수 있습니다. 프로덕션 데이터를 덮어쓰지 않으려면 라이브 게임에 대해 이 설정을 활성화하지 마세요. 대신 게임의 별도 테스트 버전에 대해 활성화하세요.

발행된 게임에서 스튜디오 접근을 활성화하려면:

1. Studio의 파일 ⟩ 경험 설정 창을 엽니다.
2. 보안으로 이동합니다.
3. API 서비스에 대한 스튜디오 접근 활성화 토글을 활성화합니다.
4. 저장을 클릭합니다.

데이터 저장소 접근

게임 내에서 데이터 저장소에 접근하려면:

1. 서버 사이드 Script에 DataStoreService를 추가합니다.
2. GetDataStore() 함수를 사용하고 사용하려는 데이터 저장소의 이름을 지정합니다. 데이터 저장소가 존재하지 않으면 Studio는 게임 데이터를 처음 저장할 때 하나를 생성합니다.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

데이터 생성

데이터 저장소는 본질적으로 Luau 테이블과 유사한 사전입니다. 각 값은 고유한 키에 인덱싱되며, 사용자의 고유한 Player.UserId 또는 게임 프로모션을 위한 명명된 문자열이 될 수 있습니다.

새 항목을 생성하려면 SetAsync()를 호출하면서 키 이름과 값을 전달하세요.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local success, errorMessage = pcall(function()
	gameStore:SetAsync("User_1234", 50)
end)
if not success then
	print(errorMessage)
end

데이터 업데이트

저장된 데이터 저장소의 값이 변경되면, UpdateAsync()를 호출하면서 항목의 키 이름과 업데이트 방법을 정의하는 콜백 함수를 전달합니다. 이 콜백은 현재 값을 받아서 정의한 로직에 기반하여 새로운 값을 반환합니다. 콜백이 nil을 반환하면 쓰기 작업이 취소되고 값이 업데이트되지 않습니다.

local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local function makeNameUpper(currentName)
	local nameUpper = string.upper(currentName)
	return nameUpper
end

local success, updatedName = pcall(function()
	return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
end)
if success then
	print("대문자 이름:", updatedName)
end

설정 대 업데이트

특정 키를 빠르게 업데이트 하려면 설정을 사용하세요. SetAsync() 함수는:

• 두 서버가 동시에 같은 키를 설정하려고 하면 데이터 일관성 문제를 일으킬 수 있습니다.
• 쓰기 제한에만 적용됩니다.

멀티 서버 시도를 처리할 때는 업데이트를 사용하세요. UpdateAsync() 함수는:

• 변경을 하기 전에 마지막으로 업데이트된 서버에서 현재 키 값을 읽습니다.
• 쓰기 전에 읽기 때문에 느립니다.
• 읽기와 쓰기 제한 모두에 적용됩니다.

데이터 읽기

데이터 저장소 항목의 값을 읽으려면, 항목의 키 이름으로 GetAsync()를 호출합니다.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local success, currentGame = pcall(function()
	return gameStore:GetAsync("User_1234")
end)
if success then
	print(currentGame)
end

데이터 증가

데이터 저장소에서 정수를 증가시키려면, 항목의 키 이름과 변경하려는 수량으로 IncrementAsync()를 호출합니다. IncrementAsync()는 수동으로 정수를 증가시키기 위해 UpdateAsync()를 호출하는 것을 피할 수 있도록 해주는 편리한 함수입니다.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local success, newGame = pcall(function()
	return gameStore:IncrementAsync("Player_1234", 1)
end)
if success then
	print(newGame)
end

데이터 제거

항목을 제거하고 키와 연관된 값을 반환하려면 RemoveAsync()를 호출합니다.

local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local success, removedValue = pcall(function()
	return nicknameStore:RemoveAsync("User_1234")
end)
if success then
	print(removedValue)
end

메타데이터

키에 연결된 두 가지 유형의 메타데이터가 있습니다:

• 서비스 정의: 가장 최근 업데이트 시간 및 생성 시간과 같은 기본 읽기 전용 메타데이터. 모든 객체는 서비스 정의 메타데이터를 가집니다.
• 사용자 정의: 태그 및 분류를 위한 사용자 정의 메타데이터. DataStoreSetOptions 객체를 사용하고 SetMetadata() 함수를 통해 정의됩니다.

메타데이터를 관리하려면 SetAsync(), UpdateAsync(), GetAsync(), IncrementAsync(), 및 RemoveAsync() 함수를 확장합니다.

• SetAsync()는 선택적인 세 번째 및 네 번째 인자를 수락합니다:

  • 콘텐츠 저작권 및 지적 재산권 추적 및 제거에 도움이 될 수 있는 UserIds의 테이블입니다.

  • 사용자 정의 메타데이터를 정의할 수 있는 DataStoreSetOptions 객체, 여기서 SetMetadata() 함수를 사용하여 사용자 정의 메타데이터를 정의할 수 있습니다.

    local DataStoreService = game:GetService("DataStoreService")
    
    local gameStore = DataStoreService:GetDataStore("PlayerGame")
    
    local setOptions = Instance.new("DataStoreSetOptions")
    setOptions:SetMetadata({["GameElement"] = "Fire"})
    
    local success, errorMessage = pcall(function()
        gameStore:SetAsync("User_1234", 50, {1234}, setOptions)
    end)
    if not success then
        print(errorMessage)
    end

• GetAsync(), IncrementAsync(), 및 RemoveAsync()는 DataStoreKeyInfo 객체에서 두 번째 값을 반환합니다. 이 두 번째 값은 서비스 정의 속성 및 사용자 정의 메타데이터를 가져오는 함수가 포함되어 있습니다.

  • GetUserIds() 함수는 SetAsync()에 전달한 UserIds의 테이블을 가져옵니다.
  • GetMetadata() 함수는 SetMetadata()를 통해 SetAsync()에 전달한 사용자 정의 메타데이터를 가져옵니다.
  • Version 속성은 키의 버전을 가져옵니다.
  • CreatedTime 속성은 키가 생성된 시간을 epoch 이후 밀리초로 포맷하여 가져옵니다.
  • UpdatedTime 속성은 키가 마지막으로 업데이트된 시간을 epoch 이후 밀리초로 포맷하여 가져옵니다.

  local DataStoreService = game:GetService("DataStoreService")
  
  local gameStore = DataStoreService:GetDataStore("PlayerGame")
  
  local success, currentGame, keyInfo = pcall(function()
      return gameStore:GetAsync("User_1234")
  end)
  if success then
      print(currentGame)
      print(keyInfo.Version)
      print(keyInfo.CreatedTime)
      print(keyInfo.UpdatedTime)
      print(keyInfo:GetUserIds())
      print(keyInfo:GetMetadata())
  end

• UpdateAsync()의 콜백 함수는 현재 키 상태를 설명하는 DataStoreKeyInfo 객체에 추가 매개변수를 받습니다. 수정된 값, UserIds와 연결된 키 및 키의 메타데이터를 반환합니다.

  local DataStoreService = game:GetService("DataStoreService")
  
  local nicknameStore = DataStoreService:GetDataStore("Nicknames")
  
  local function makeNameUpper(currentName, keyInfo)
      local nameUpper = string.upper(currentName)
      local userIDs = keyInfo:GetUserIds()
      local metadata = keyInfo:GetMetadata()
      return nameUpper, userIDs, metadata
  end
  
  local success, updatedName, keyInfo = pcall(function()
      return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
  end)
  if success then
      print(updatedName)
      print(keyInfo.Version)
      print(keyInfo.CreatedTime)
      print(keyInfo.UpdatedTime)
      print(keyInfo:GetUserIds())
      print(keyInfo:GetMetadata())
  end

메타데이터 정의 시의 제한 사항은 메타데이터 제한을 참조하세요.

정렬된 데이터 저장소

기본적으로 데이터 저장소는 콘텐츠를 정렬하지 않습니다. 지속적인 리더보드 통계와 같이 데이터를 정렬된 방식으로 얻어야 하는 경우, GetOrderedDataStore()를 호출하세요.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

정렬된 데이터 저장소는 기본 데이터 저장소에서 지원하는 동일한 기본 함수를 지원하며, 고유한 GetSortedAsync() 함수도 포함됩니다. 이 함수는 특정 정렬 순서, 페이지 크기 및 최소/최대 값에 기반하여 여러 정렬된 키를 검색합니다.

다음 예제는 캐릭터 데이터를 내림차순 정렬하여 각 페이지에 세 개의 항목을 구성한 뒤, 페이지를 반복하면서 각 캐릭터의 이름과 나이를 출력합니다.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- 정렬된 데이터 저장소를 채웁니다.
local characters = {
	Mars = 19,
	Janus = 20,
	Diana = 18,
	Venus = 25,
	Neptune = 62
}
for char, age in characters do
	local success, errorMessage = pcall(function()
		characterAgeStore:SetAsync(char, age)
	end)
	if not success then
		print(errorMessage)
	end
end

-- 내림차순으로 세 개의 항목이 포함된 페이지로 데이터를 정렬합니다.
local success, pages = pcall(function()
	return characterAgeStore:GetSortedAsync(false, 3)
end)
if success then
	while true do
		-- 현재(첫 번째) 페이지를 가져옵니다.
		local entries = pages:GetCurrentPage()
		-- 페이지의 모든 키-값 쌍을 반복합니다.
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- 마지막 페이지에 도달했는지 확인합니다.
		if pages.IsFinished then
			break
		else
			print("----------")
			-- 다음 페이지로 진행합니다.
			pages:AdvanceToNextPageAsync()
		end
	end
end