Veri depoları

DataStoreService, bir oyuncunun envanterindeki öğeler veya yetenek puanları gibi oturumlar arasında kalıcı olması gereken verileri depolamanıza olanak tanır. Veri depoları oyun başına tutarlıdır, bu nedenle bir oyundaki herhangi bir yer aynı verilere erişebilir ve bunları değiştirebilir; bu, farklı sunuculardaki yerleri de içerir.

Eğer veri depolarınıza ince izin kontrolü eklemek ve bunlara Studio veya Roblox sunucuları dışından erişmek istiyorsanız, veri depoları için Açık Bulut API’lerini kullanabilirsiniz.

Creator Hub aracılığıyla bir oyundaki tüm veri depolarını görüntülemek ve izlemek için Veri Depoları Yöneticisini kullanın.

Güncellemeniz veya sık erişmeniz gereken geçici veriler için hafıza depolarını kullanın.

Studio erişimini etkinleştir

Varsayılan olarak, Studio'da test edilen oyunlar veri depolarına erişemez, bu nedenle önce bunları etkinleştirmeniz gerekir. Studio'da veri depolarına erişim canlı oyunlar için tehlikeli olabilir, çünkü Studio, istemci uygulamasıyla aynı veri depolarına erişir. Üretim verilerini üst üste yazmamak için, bu ayarı canlı oyunlar için etkinleştirmeyin. Bunun yerine, oyunun ayrı bir test sürümü için etkinleştirin.

Bir yayınlanmış oyunda Studio erişimini etkinleştirmek için:

1. Studio'nun Dosya ⟩ Deneyim Ayarları penceresini açın.
2. Güvenlik sekmesine gidin.
3. API Hizmetlerine Studio Erişimini Etkinleştir geçiş düğmesini etkinleştirin.
4. Kaydet butonuna tıklayın.

Veri depolarına erişim

Bir oyunda bir veri deposuna erişmek için:

1. DataStoreService'i bir sunucu tarafı Script'e ekleyin.
2. GetDataStore() fonksiyonunu kullanın ve kullanmak istediğiniz veri deposunun adını belirtin. Eğer veri deposu mevcut değilse, Studio, oyun verilerinizi ilk kez kaydettiğinizde bir tane oluşturacaktır.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

Veri oluşturma

Bir veri deposu esasen, Luau tablosuna benzer bir sözlüktür. Her bir değeri indekslemek için benzersiz bir anahtar kullanılır; bu, bir kullanıcının benzersiz Player.UserId'sı veya bir oyun promosyonu için adlandırılmış bir dize olabilir.

Yeni bir giriş oluşturmak için, SetAsync() çağrısını anahtar adı ve bir değerle yapın.

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

Veriyi güncelleme

Bir veri deposundaki depolanan herhangi bir değeri değiştirmek için UpdateAsync() çağrısını anahtar adını ve girişi nasıl güncellemek istediğinizi tanımlayan bir geri çağırma işlevini ile yapın. Bu geri çağırma mevcut değeri alır ve tanımladığınız mantığa dayalı olarak yeni bir değer döndürür. Eğer geri çağırma nil dönerse, yazma işlemi iptal edilir ve değer güncellenmez.

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("Büyük Harf ile İsim:", updatedName)
end

Set vs güncelle

Belirli bir anahtarı hızla güncellemek için set kullanın. SetAsync() fonksiyonu:

• Aynı anahtarı aynı anda ayarlamaya çalışan iki sunucunun veri tutarlılığını bozabilir.
• Sadece yazma limitine karşı sayılır.

Birden çok sunucu denemelerini yönetmek için update kullanın. UpdateAsync() fonksiyonu:

• Değişiklik yapmadan önce son güncelleme yapan sunucudan mevcut anahtar değerini okur.
• Yazmadan önce okuduğundan daha yavaştır.
• Hem okuma hem de yazma limitine karşı sayılır.

Veriyi okuma

Bir veri deposu girişinin değerini okumak için GetAsync() çağrısını anahtar adı ile yapın.

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

Veriyi artırma

Bir veri deposundaki bir tamsayıyı artırmak için, IncrementAsync() çağrısını anahtar adı ve değerin ne kadar değişeceğini belirten bir sayı ile yapın. IncrementAsync() çağrısı, UpdateAsync() çağrısını yapmadan tamsayıyı artırmanızı sağlayan bir rahatlık fonksiyonudur.

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

Veriyi kaldırma

Bir girişi kaldırmak ve anahtarla ilişkilendirilmiş değeri döndürmek için, RemoveAsync() çağrısını yapın.

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

Metadata

Anahtarlarla ilişkili iki tür meta veri vardır:

• Servis tanımlı: En son güncelleme zamanı ve oluşturulma zamanı gibi varsayılan salt okunur meta veriler. Her nesne, servis tarafından tanımlanmış meta verilere sahiptir.
• Kullanıcı tanımlı: Etiketleme ve kategorilendirme için özel meta veriler. DataStoreSetOptions nesnesi ve SetMetadata() fonksiyonu kullanılarak tanımlanır.

Meta verileri yönetmek için, SetAsync(), UpdateAsync(), GetAsync(), IncrementAsync() ve RemoveAsync() fonksiyonlarını genişletin.

• SetAsync() isteğe bağlı üçüncü ve dördüncü argümanları kabul eder:

  • UserIds tablosu. Bu, içerik telif hakkı ve fikri mülkiyet izleme ve kaldırma konusunda yardımcı olabilir.

  • Özel meta verileri tanımlayabileceğiniz bir DataStoreSetOptions nesnesi; SetMetadata() fonksiyonunu kullanarak tanımlanır.

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

• GetAsync(), IncrementAsync() ve RemoveAsync() ikinci bir değeri DataStoreKeyInfo nesnesinde döndürür. Bu ikinci değer, hem servis tarafından tanımlanan özellikleri hem de kullanıcı tarafından tanımlanan meta verileri almak için fonksiyonları içerir.

  • GetUserIds() fonksiyonu, SetAsync() ile geçirdiğiniz UserIds’nin tablosunu getirir.
  • GetMetadata() fonksiyonu, SetMetadata() aracılığıyla SetAsync() ile geçirdiğiniz kullanıcı tanımlı meta verileri getirir.
  • Version özelliği, anahtarın sürümünü getirir.
  • CreatedTime özelliği, anahtarın oluşturulma zamanını epoch'tan itibaren geçen milisaniye cinsinden getirir.
  • UpdatedTime özelliği, anahtarın son güncellendiği zamanı epoch'tan itibaren geçen milisaniye cinsinden getirir.

  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() geri çağırma işlevi, mevcut anahtar durumunu tanımlayan ek bir parametre alır DataStoreKeyInfo nesnesinde. Bu, değiştirilen değeri, UserIds ile ilişkili anahtarları ve anahtarın meta verisini döndürür.

  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

Meta veri tanımlarken limitler için, meta veri limitlerine bakın.

Sıralı veri depoları

Varsayılan olarak, veri depoları içeriğini sıralamaz. Kalıcı liderlik istatistikleri gibi verileri sıralı bir şekilde almak istiyorsanız, GetOrderedDataStore() çağrısını GetDataStore() yerine yapın.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

Sıralı veri depoları, varsayılan veri depolarıyla aynı temel işlevleri destekler, ayrıca benzersiz GetSortedAsync() fonksiyonunu destekler. Bu, belirli bir sıralama düzenine, sayfa boyutuna ve minimum/maksimum değerlere göre birden çok sıralanmış anahtar alır.

Aşağıdaki örnek, karakter verilerini her biri azalan sırada üç girişi olan sayfalara sıralar, ardından sayfaları döngüye alır ve her bir karakterin adını ve yaşını çıktılar.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- Sıralı veri deposunu doldur
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

-- Verileri azalan sırayla üçer giriş içeren sayfalara sıralar
local success, pages = pcall(function()
	return characterAgeStore:GetSortedAsync(false, 3)
end)
if success then
	while true do
		-- Mevcut (ilk) sayfayı al
		local entries = pages:GetCurrentPage()
		-- Sayfadaki tüm anahtar-değer çiftleri üzerinden geçer
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Son sayfanın erişilip erişilmediğini kontrol et
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Bir sonraki sayfaya geç
			pages:AdvanceToNextPageAsync()
		end
	end
end