GlobalDataStore

GlobalDataStore : Instance

Overview

데이터를 저장하고 불러오기 위한 기능을 제공합니다.

Properties

Methods

GetAsync

지정한 키에 저장된 값과 해당 항목의 정보를 담은 DataStoreKeyInfo를 반환합니다.

키가 존재하지 않을 경우 두 값은 모두 nil로 반환됩니다.

Parameters

string InKey	데이터가 저장된 키입니다.
DataStoreGetOptions InOptions	현재 지원되지 않습니다.

Return

Tuple	지정한 키의 값과 함께, 버전·생성 시각 등의 정보를 포함한 DataStoreKeyInfo 객체를 반환합니다.

Code Samples

local DataStoreService = game:GetService("DataStoreService") 
local GoldStore = DataStoreService:GetDataStore("PlayerGold") 

local success, errorMessageOrLoadValue, keyInfo = pcall(function()
    return GoldStore:GetAsync(player.UserId)
end)

IncrementAsync

특정 키에 저장된 값을 지정한 정수만큼 증가 또는 감소시키는 기능을 제공합니다. 이때 기존 값과 변경에 사용되는 값은 모두 정수여야 정상적으로 처리됩니다.

또한 IncrementAsync는 SetAsync와 달리 내부적으로 원자적 연산을 수행하므로, 여러 사용자가 동시에 동일한 값을 갱신하더라도 충돌 없이 안전하게 누적됩니다. 이러한 특성 덕분에 코인, 경험치, 점수처럼 단순히 누적되어야 하는 숫자 데이터를 다룰 때 가장 간편하고 효율적인 선택입니다.

Parameters

string InKey	값을 갱신할 키입니다.
number InDelta	기존 값에 추가할 정수 값을 의미하며, 이 숫자만큼 현재 저장된 값이 증가합니다.
array InUserIds	(선택 사항) 데이터를 변경한 주체나 해당 변경과 관련된 사용자 ID들을 기록하기 위한 메타데이터입니다.
DataStoreIncrementOptions InOptions	(선택 사항) 부가적인 정보나 메타데이터를 기록하기 위한 객체입니다.

Return

Value	최종적으로 저장된 값입니다.

Code Samples

local DataStoreService = game:GetService("DataStoreService") 
local GoldStore = DataStoreService:GetDataStore("PlayerGold") 

local success, errorMessageOrLoadValue = pcall(function()
    return GoldStore:IncrementAsync(player.UserId, 1)
end)

RemoveAsync

특정 키를 삭제된 상태로 전환합니다.

삭제가 완료된 이후에는 GetAsync로 해당 키를 조회하더라도 nil만 반환됩니다.

Parameters

string InKey	삭제할 키입니다.

Return

void

Code Samples

local DataStoreService = game:GetService("DataStoreService") 
local GoldStore = DataStoreService:GetDataStore("PlayerGold") 

local success, errorMessage = pcall(function()
    GoldStore:RemoveAsync(player.UserId)
end)

SetAsync

특정 키에 저장된 값을 지정한 값으로 덮어씌웁니다.

SetAsync는 개별 키를 빠르게 갱신할 때 유용하지만, 여러 서버가 동시에 동일한 키를 변경하려는 상황에서는 값이 서로 덮어써지며 의도치않은 값으로 저장될 수 있습니다.

따라서 여러 사용자가 동시에 데이터를 읽고 쓸 때 경쟁 상태(race condition)를 방지해야 하는 경우에는 IncrementAsync나 UpdateAsync와 같이 원자적 처리를 지원하는 메서드를 사용하는 것이 더 안전합니다.

Parameters

string InKey	값을 갱신할 키입니다.
Value InValue	변경할 값입니다.
array InUserIds	(선택 사항) 데이터를 변경한 주체나 해당 변경과 관련된 사용자 ID들을 기록하기 위한 메타데이터입니다.
DataStoreSetOptions InOptions	(선택 사항) 부가적인 정보나 메타데이터를 기록하기 위한 객체입니다.

Return

Value	최종적으로 저장된 값입니다.

Code Samples

local DataStoreService = game:GetService("DataStoreService") 
local GoldStore = DataStoreService:GetDataStore("PlayerGold") 

local success, errorMessageOrLoadValue = pcall(function()
    GoldStore:SetAsync(player.UserId, 100) 
end)

UpdateAsync

특정 키를 읽어온 뒤, 콜백 함수가 결정한 새 값으로 데이터를 갱신하는 방식으로 동작합니다. 콜백에서 nil을 반환하면 작업은 취소되며 기존 데이터는 그대로 유지됩니다.

만약 동시에 여러 요청이 들어와 데이터 충돌이 발생하면, UpdateAsync는 자동으로 최신 값을 다시 불러와 콜백을 재실행하여 충돌을 해결합니다. 이 과정은 데이터가 안전하게 갱신될 때까지 반복됩니다.

콜백 함수의 반환값은 Tuple이 아니라 단일 Table 형태여야 하며, 이 테이블 안에 새 값, UserIds, 메타데이터를 순서대로 포함해 반환해야 합니다.

Parameters

string InKey	값을 갱신할 키입니다.
Value InTransformFunction	현재 저장된 값과 해당 버전 정보를 담은 DataStoreKeyInfo를 인자로 받아, 갱신할 값과 필요 시 함께 저장할 UserIds 및 메타데이터를 하나의 테이블로 반환하는 콜백 함수입니다. UpdateAsync는 이 콜백이 반환한 테이블 내용을 바탕으로 데이터를 갱신합니다.

Return

Tuple	지정한 키의 값과 함께, 버전·생성 시각 등의 정보를 포함한 DataStoreKeyInfo 객체를 반환합니다.

Code Samples

local DataStoreService = game:GetService("DataStoreService") 
local GoldStore = DataStoreService:GetDataStore("PlayerGold") 

local success, errorMessageOrLoadValue, keyInfo = pcall(function()
    return GoldStore:UpdateAsync(player.UserId, function(currentGold, keyInfo)
        local newGold = (currentGold or 0) + 10		
        return { newGold, keyInfo:GetUserIds(), keyInfo:GetMetadata() }
    end)
end)

Events

See also

Saving & Loading Data