Veri depoları

DataStoreService, bir oyuncunun envanterindeki eşyalar veya yetenek puanları gibi oturumlar arasında kalıcı olması gereken verileri depolamanıza olanak tanır. Veri depoları, her oyun için tutarlıdır, bu nedenle bir oyundaki herhangi bir yer, farklı sunuculardaki yerler de dahil olmak üzere aynı verilere erişebilir ve bunları değiştirebilir.

Veri depolarınıza ayrıntılı izin kontrolü eklemek ve bunlara Studio veya Roblox sunucuları dışında 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öneticisi kullanın.

Geçici veriler için, sık sık güncellemeniz veya erişmeniz gereken veriler için bellek 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şmek, canlı oyunlar için tehlikeli olabilir çünkü Studio, istemci uygulamasıyla aynı veri depolarına erişir. Üretim verilerini üzerine 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 bölümüne gidin.
3. API Hizmetlerine Studio Erişimini Etkinleştir anahtarını etkinleştirin.
4. Kaydet butonuna tıklayın.

Veri depolarına erişim

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

1. DataStoreService'i bir sunucu tarafı Script'e ekleyin.
2. Kullanmak istediğiniz veri deposunun adını belirterek GetDataStore() fonksiyonunu kullanın. Eğer veri deposu yoksa, Studio, oyun verilerinizi ilk kez kaydettiğinizde bir tane oluşturur.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

Veri oluşturma

Bir veri deposu esasen bir sözlük gibidir, Luau tablosuna benzer. Her değeri indeksleyen benzersiz bir anahtar, bir kullanıcının benzersiz Player.UserId'si veya bir oyun promosyonu için adlandırılmış bir dize gibi.

Yeni bir giriş oluşturmak için, anahtar adını ve bir değeri belirterek SetAsync() fonksiyonunu çağırı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 herhangi bir depolanan değeri değiştirmek için, girişin anahtar adını ve girişi nasıl güncellemek istediğinizi tanımlayan bir geri çağırma fonksiyonu ile UpdateAsync() fonksiyonunu çağırın. Bu geri çağırma, mevcut değeri alır ve tanımladığınız mantığa göre 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 Harfli İsim:", updatedName)
end

Set vs update

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

• İki sunucu aynı anahtarı aynı anda ayarlamaya çalışırsa veri tutarsızlığına neden olabilir
• Sadece yazma limitine karşı sayılır

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

• Değişiklik yapmadan önce en son güncellenen sunucudan mevcut anahtar değerini okur
• Yazmadan önce okuduğu için 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, girişin anahtar adını belirterek GetAsync() fonksiyonunu çağırı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, girişin anahtar adını ve değeri ne kadar değiştireceğinizi belirterek IncrementAsync() fonksiyonunu çağırın. IncrementAsync() fonksiyonu, UpdateAsync() fonksiyonunu çağırmaktan ve tamsayıyı manuel olarak artırmaktan kaçınmanıza olanak tanıyan bir kolaylı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şkili değeri döndürmek için RemoveAsync() fonksiyonunu çağırı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

Meta veriler

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

• Hizmet tanımlı: En son güncelleme zamanı ve oluşturma zamanı gibi varsayılan salt okunur meta veriler. Her nesne, hizmet tanımlı 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 takibi ve kaldırma konusunda yardımcı olabilir.

  • Özel meta verileri tanımlayabileceğiniz bir DataStoreSetOptions nesnesi, SetMetadata() fonksiyonu ile.

    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(), ve RemoveAsync() fonksiyonları, DataStoreKeyInfo nesnesinde ikinci bir değer döndürür. Bu ikinci değer, hem hizmet tanımlı özellikleri hem de kullanıcı tanımlı meta verileri almak için fonksiyonları içerir.

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

  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() fonksiyonunun geri çağırma fonksiyonu, mevcut anahtar durumunu tanımlayan DataStoreKeyInfo nesnesinde ek bir parametre alır. Değiştirilen değeri, UserIds ile ilişkili anahtarları ve anahtarın meta verilerini 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ımları için limitler hakkında bilgi için meta veri limitleri bölümüne bakın.

Sıralı veri depoları

Varsayılan olarak, veri depoları içeriklerini sıralamaz. Kalıcı liderlik istatistikleri gibi verileri sıralı bir şekilde almak istiyorsanız, GetOrderedDataStore() fonksiyonunu GetDataStore() yerine çağırı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 da destekler. Bu, belirli bir sıralama düzenine, sayfa boyutuna ve minimum/maksimum değerlere göre birden fazla sıralı anahtar alır.

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

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- Sıralı veri deposunu doldurur
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ırada üç girişten oluşan sayfalara sıralar
local success, pages = pcall(function()
	return characterAgeStore:GetSortedAsync(false, 3)
end)
if success then
	while true do
		-- Mevcut (ilk) sayfayı alır
		local entries = pages:GetCurrentPage()
		-- Sayfadaki tüm anahtar-değer çiftlerini döngüye alır
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Son sayfanın ulaşılıp ulaşılmadığını kontrol eder
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Bir sonraki sayfaya geçer
			pages:AdvanceToNextPageAsync()
		end
	end
end

Birden fazla girişi okuma

Tek bir istekte birden fazla sıralı veri deposu girişini okumak için, bir dizi anahtar ile BatchGetAsync() fonksiyonunu çağırın. Bu, girişleri birer birer okumak için GetAsync() fonksiyonunun toplu karşılığıdır.

BatchGetAsync() her bir istenen anahtarı bir value alanına sahip bir tabloya eşleyen bir sözlük döndürür. Mevcut olmayan anahtarlar sözlükten çıkarılır, bu nedenle bir anahtarın mevcut olduğunu doğrulayın ve ardından değerini okuyun.

İstediğiniz her anahtar bir okuma isteği olarak sayılır, bu nedenle N anahtar için tek bir çağrı, sıralı veri deposu okuma limitine karşı N isteği olarak sayılır.

Aşağıdaki örnek, tek bir istekte üç oyuncu puanını okur, ardından anahtarları döngüye alır ve mevcut her puanı çıktılar.

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 .. " kaydedilmiş bir girişi yok")
		end
	end
end