データストア

DataStoreServiceを使用すると、プレイヤーのインベントリ内のアイテムやスキルポイントのように、セッション間で永続化する必要があるデータを保存できます。データストアはゲームごとに一貫性があるため、ゲーム内のどの場所でも同じデータにアクセスして変更できます。異なるサーバー上の場所も含まれます。

データストアに対して詳細な権限管理を追加し、StudioやRobloxサーバーの外部からアクセスしたい場合は、データストア用のオープンクラウドAPIを使用できます。

Creator Hubを通じてゲーム内のすべてのデータストアを表示および監視するには、データストアマネージャーを使用してください。

頻繁に更新またはアクセスする必要がある一時的なデータには、メモリストアを使用してください。

Studioアクセスを有効にする

デフォルトでは、Studioでテストされたゲームはデータストアにアクセスできないため、最初にそれを有効にする必要があります。Studioでデータストアにアクセスすることは、クライアントアプリケーションと同じデータストアにアクセスするため、ライブゲームにとって危険です。プロダクションデータを上書きしないように、ライブゲームにはこの設定を有効にしないでください。代わりに、ゲームの別のテストバージョンに対して有効にしてください。

公開されたゲームでStudioアクセスを有効にするには：

1. Studioのファイル ⟩ エクスペリエンス設定ウィンドウを開きます。
2. セキュリティに移動します。
3. APIサービスへのStudioアクセスを有効にするトグルを有効にします。
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()関数は：

• 2つのサーバーが同時に同じキーを設定しようとすると、データの不整合を引き起こす可能性があります。
• 書き込み制限にのみカウントされます。

マルチサーバーの試行を処理するには更新を使用します。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

メタデータ

キーに関連付けられたメタデータには2種類あります：

• サービス定義: 最も最近の更新時刻や作成時刻などのデフォルトの読み取り専用メタデータ。すべてのオブジェクトにはサービス定義のメタデータがあります。
• ユーザー定義: タグ付けや分類のためのカスタムメタデータ。DataStoreSetOptionsオブジェクトとSetMetadata()関数を使用して定義します。

メタデータを管理するには、SetAsync()、UpdateAsync()、GetAsync()、IncrementAsync()、およびRemoveAsync()関数を拡張します。

• SetAsync()は、オプションの第3引数と第4引数を受け入れます：

  • 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オブジェクト内の2番目の値を返します。この2番目の値には、サービス定義のプロパティとユーザー定義のメタデータを取得するための関数が含まれています。

  • GetUserIds()関数は、SetAsync()に渡したUserIdsのテーブルを取得します。
  • GetMetadata()関数は、SetMetadata()を通じてSetAsync()に渡したユーザー定義のメタデータを取得します。
  • Versionプロパティは、キーのバージョンを取得します。
  • CreatedTimeプロパティは、キーが作成された時刻を取得し、エポックからのミリ秒数としてフォーマットされます。
  • UpdatedTimeプロパティは、キーが最後に更新された時刻を取得し、エポックからのミリ秒数としてフォーマットされます。

  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()関数をサポートします。これにより、特定のソート順、ページサイズ、最小/最大値に基づいて複数のソートされたキーを取得できます。

次の例では、キャラクターデータを3つのエントリを持つページにソートし、各ページをループして各キャラクターの名前と年齢を出力します。

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

-- データを降順に3つのエントリのページにソート
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

複数のエントリを読み取る

単一のリクエストで複数の順序付きデータストアエントリを読み取るには、キーの配列を指定してBatchGetAsync()を呼び出します。これは、GetAsync()でエントリを1つずつ読み取るためのバッチ対応です。

BatchGetAsync()は、要求された各キーをvalueフィールドを持つテーブルにマッピングする辞書を返します。存在しないキーは辞書から省略されるため、値を読み取る前にキーが存在することを確認してください。

要求する各キーは1つの読み取りリクエストとしてカウントされるため、N個のキーに対する単一の呼び出しは、順序付きデータストアの読み取り制限に対してNリクエストとしてカウントされます。

次の例では、単一のリクエストで3つのプレイヤースコアを読み取り、キーをループして存在する各スコアを出力します。

local DataStoreService = game:GetService("DataStoreService")

local playerScores = DataStoreService:GetOrderedDataStore("PlayerScores")
local keys = {"Player_123", "Player_456", "Player_789"}

local success, results = pcall(function()
	return playerScores:BatchGetAsync(keys)
end)
if success then
	for _, key in keys do
		local entry = results[key]
		if entry then
			print(key .. " : " .. tostring(entry.value))
		else
			print(key .. "には保存されたエントリがありません")
		end
	end
end