データストア

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

データストアに対して詳細なアクセス制御を追加したり、Studio や Roblox サーバーの外部からアクセスしたりしたい場合は、データストア用の Open Cloud 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")

データを作成する

データストアは基本的に辞書であり、Lua のテーブルに似ています。ユニークな キー がデータストア内の各値にインデックスを付け、ユーザーのユニークな 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

セットと更新

特定のキーを迅速に更新するには set を使用します。 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

メタデータ

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

以下の例では、キャラクターデータを昇順にソートし、ページごとに３件ずつ表示し、その後、各キャラクターの名前と年齢を出力します。

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