Eğitim · Oyuncu verisi

Roblox Studio'da DataStore ile oyuncu verisi nasıl kaydedilir

Bir sunucu scripti kaydetmedikçe Roblox oturumlar arasında oyuncu hakkında hiçbir şey hatırlamaz. Bu rehberde her oyuncunun verisini DataStoreService üzerinden yükleyen, bellekte tutan ve kaydeden bir PlayerData modülü kuruyorsun, sonra testi, limitleri ve kaydedilmiş verinin nasıl kaybolduğunu inceliyorsun.

Güncellendi: 20 Kasım 202615 dk okumaYazan:

Kısaca

DataStoreService'i bir sunucu Script'inden kullan: oyuncu girdiğinde verisini GetAsync ile yükle, oynarken bir tabloda tut ve bir zamanlayıcıyla, çıkışta (PlayerRemoving) ve sunucu kapanırken (game:BindToClose) UpdateAsync ile kaydet. Her çağrıyı pcall içine sar ve başarısız olanları birkaç kez yeniden dene.

  • Studio'da test etmek için place'i yayınla ve ayrı bir test oyununda File > Experience Settings > Security > Enable Studio Access to API Services'ı aç: Studio canlı sunucularla aynı veriyi kullanır.
  • Bir oyuncunun verisi yüklenmediyse o oyuncuyu asla kaydetme. Varsayılan değerleri kaydetmek gerçek ilerlemesinin üzerine yazar.
  • Oyuncu başına tek bir tabloyu User_12345 gibi tek bir anahtar altında tut ve her değişiklikte değil, bir zamanlayıcıyla kaydet.
  • Takas ya da ücretli eşyalar için iki sunucunun aynı oyuncuyu kaydedememesi adına oturum kilidi (session locking) ekle.
Bu sayfada
  1. Studio erişimi
  2. DataStore nasıl çalışır
  3. GetAsync ve UpdateAsync
  4. 1. PlayerData modülü
  5. Modül nasıl çalışır
  6. 2. Veriyle çalışmak
  7. 3. Uyarı
  8. 4. Studio'da test
  9. Veri neden kaybolur
  10. Oturum kilidi
  11. Limitler
  12. Sürümler ve yedekler
  13. Common errors
  14. With RoCode
  15. Sık sorulan sorular
  16. Kaynaklar ve ek okumalar

Başlamadan önce: test kopyasında Studio erişimini aç

Studio'da çalışan bir oyun, sen izin verene kadar data store'lara erişemez. Bu iznin Roblox dokümantasyonunun uyardığı bir tuzağı var: Studio o zaman canlı oyunla aynı data store'ları okur ve yazar, yani Studio'da paralarını sıfırlayan bir test canlı oyunda da sıfırlar, test kodundaki bir hata da gerçek oyuncuların anahtarlarını bozabilir.

  1. Bir test kopyası yap. Place'i bir dosyaya kaydet, kopyayı aç, File > Publish to Roblox As'i seç ve Create new game'e tıkla. Onu canlı oyunun içine bir place olarak ekleme: aynı oyunun tüm place'leri aynı data store'ları paylaşır.
  2. Test kopyasında File > Experience Settings'i aç ve Security'ye geç.
  3. Enable Studio Access to API Services'ı aç ve Save'e tıkla.

Data store çağrıları sadece sunucu Script'lerinde çalışır; deneyen bir LocalScript hata alır, bu yüzden client'lar kaydedilmiş veriye yazamaz. Bir butonun onu değiştirmesi gerektiğinde client bir RemoteEvent ile sunucudan ister, kararı da sunucu verir (RemoteEvents rehberine bak, İngilizce).

Data store'lar oyuncu verisini nasıl saklar

ÇizimRehberin 4. adımındaki test hızlandırılmış hâliyle: Play, Stop oturumu data store'a kaydeder, ikinci Play onu yükler, bu yüzden Output 200 gösterir.

Bir data store, Roblox sunucularında adı olan bir anahtar ve değer kümesidir; oyununun tüm sunucuları ve tüm place'leri onu paylaşır. DataStoreService:GetDataStore("PlayerData") böyle bir store döndürür.

Roblox'un önerileri şu kurala iner: oyuncu verisi için tek store, oyuncu başına tek anahtar, her anahtarda tek tablo. Anahtarı oyuncunun UserId'sinden kur, örneğin User_12345, değiştirebileceği adından asla. Sabit User_{UserId} kalıbı, ayarlarsan Roblox'un unutulma hakkı için otomatik işleminin oyuncunun verisini bulmasını da sağlar.

Bir data store'a neler kaydedilebilir
TürKaydedilir mi?Notlar
Sayılar, string'ler, boolean'lar, buffer'larEvetString'ler geçerli UTF-8 olmalı. inf ya da nan saklama.
TablolarEvetİçindeki her şey de kaydedilebiliyorsa. Sayısal anahtarları 1'den başlamayan (bu yüzden uzunluğu 0 olan) bir tablo, bu anahtarlar string olarak geri gelir.
Instance, Vector3, CFrame, Color3HayırKaydetme hata verir ya da nil yazar. Eşyanın adını ya da konumu üç sayı olarak kaydet.

Her istek başarısız olabilen, zaman alan ve dakikalık bütçeden harcayan bir web çağrısıdır. Bu yüzden güvenilir kayıt sistemleri veriyi oyuncu girdiğinde bir kez okur, o oynarken bir sunucu tablosunda tutar ve zaman zaman geri yazar.

GetAsync, SetAsync mı UpdateAsync mi: hangisini seçmeli

Data store'un temel metotları
MetotNe yaparNe için
GetAsync(key)Değeri okur. Sonuç bu sunucuda 4 saniye önbelleğe alınır.Oyuncu verisini yükleme
SetAsync(key, value)Değeri okumadan üzerine yazar. Bir yazma.Yeni bir anahtar ya da eskisine bağlı olmayan bir değer
UpdateAsync(key, callback)Son değeri okur, senin fonksiyonuna verir ve onun döndürdüğünü yazar. Bir okuma ve bir yazma.Oyuncu verisini kaydetme ve birden fazla sunucunun yazabileceği her anahtar
IncrementAsync(key, delta)Kaydedilmiş bir tam sayıya bir tam sayı ekler.Sayaçlar
RemoveAsync(key)Anahtarı siler ve eski değeri döndürür. Önceki sürümler hâlâ listelenip okunabilir.Oyuncu verisini silme

SetAsync körlemesine yazar: iki sunucu aynı anahtarı neredeyse aynı anda kaydederse, içinde ne olursa olsun son yazma kazanır. UpdateAsync önce mevcut değeri okur ve arada başka bir sunucu yazarsa Roblox fonksiyonunu yeni değerle tekrar çalıştırır. Roblox, yazma mevcut değere bağlı olduğunda ya da anahtarı birden fazla sunucu yazabildiğinde her zaman onu öneriyor, oyuncu verisi de tam olarak böyle. Fonksiyonun üç kuralı var:

  • Yield etmemeli: içinde task.wait() ya da başka data store çağrısı olmamalı.
  • Birden fazla kez çalışabilir, bu yüzden sadece yeni değeri hesaplamalı, asla eşya vermemeli ya da event tetiklememeli.
  • nil döndürmek yazmayı iptal eder. Modül bunu, oyunun daha yeni bir sürümünün kaydettiği verinin üzerine yazmamak için kullanır.

Adım 1: PlayerData modülünü oluştur

Bu ModuleScript data store ile konuşan tek koddur. Oyuncu girdiğinde verisini yükler, bellekte tutar, her 180 saniyede, çıkışta ve sunucu kapanırken kaydeder ve verisi yüklenmeyenleri kaydetmeyi reddeder.

  1. Explorer'da fareyle ServerScriptService üzerine gel, +'ya tıkla ve bir ModuleScript ekle. Adını PlayerData yap ve içeriğini aşağıdaki kodla değiştir.
  2. Bir ModuleScript sadece bir script onu require ettiğinde çalışır. ServerScriptService'e Main adında ve şu satırı içeren bir Script ekle: local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Diğer sunucu scriptleri de onu aynı şekilde require eder.
  3. DEFAULTS'u ve Data tipini oyununa göre değiştir; her alan bir sayı, string, boolean ya da tablo olarak kalsın.
1-3. adımlardan sonra Explorer
ServerScriptService
    PlayerData ModuleScript new
    Main Script new
StarterPlayer
    StarterPlayerScripts
        DataWarning LocalScript new
ModuleScript konum: ServerScriptService adı: PlayerData
-- PlayerData: oyuncu girdiğinde verisini yükler, bellekte tutar
-- ve zamanlayıcıyla, çıkışta ve sunucu kapanırken kaydeder.
-- Diğer sunucu scriptleri onu PlayerData.Get(player) ile okur ve değiştirir.

local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")
local RunService = game:GetService("RunService")

local STORE_NAME = "PlayerData"
local SCHEMA_VERSION = 2 -- verinin şekli değişince artır ve migrate()'e bir adım ekle
local AUTOSAVE_SECONDS = 180
-- Studio'da başarısız bir çağrı hemen vazgeçer, böylece store erişimi olmayan bir test hızlı geçer
local MAX_ATTEMPTS = if RunService:IsStudio() then 1 else 4
local FIRST_RETRY_SECONDS = 1 -- her başarısızlıktan sonra ikiye katlanır: 1, 2, 4

export type Data = {
	SchemaVersion: number,
	Coins: number,
	Level: number,
	Inventory: { string },
}

-- Tamamen yeni bir oyuncunun başladığı değerler
local DEFAULTS: { [string]: any } = {
	Coins = 0,
	Level = 1,
	Inventory = {},
}

type Session = {
	key: string,
	userId: number,
	data: Data,
	canSave: boolean, -- yükleme başarısız olduysa false: varsayılan veri gerçek ilerlemenin yerini almamalı
}

-- Aşağıdaki her pcall'un içinde çağrılır, böylece henüz yayınlanmamış bir place
-- (store erişimi olmadan) oyuncuları yine de varsayılan veriyle yükler
local function store(): DataStore
	return DataStoreService:GetDataStore(STORE_NAME)
end
local sessions: { [Player]: Session } = {}
local pendingSaves: { [string]: number } = {} -- hâlâ süren kayıtlar, anahtara göre
local loadedEvent = Instance.new("BindableEvent")

local PlayerData = {}

-- Oyuncunun verisi hazır olduğunda oyuncuyla tetiklenir. Tabloyu PlayerData.Get(player) ile al:
-- bir BindableEvent ile gönderilen tablo kopya olarak gelir ve onu değiştirmek hiçbir şeyi değiştirmez.
PlayerData.Loaded = loadedEvent.Event

local function deepCopy(value: any): any
	if type(value) ~= "table" then
		return value
	end
	local copy = {}
	for key, item in value do
		copy[key] = deepCopy(item)
	end
	return copy
end

local function defaultData(): Data
	local data = deepCopy(DEFAULTS) -- taze bir kopya, böylece oyuncular asla tek bir Inventory tablosunu paylaşmaz
	data.SchemaVersion = SCHEMA_VERSION
	return data
end

-- Kaydedilmiş veriyi mevcut şemaya getirir. Güvenle kullanılamıyorsa nil döndürür.
local function migrate(saved: any): Data?
	if type(saved) ~= "table" then
		return nil
	end
	local version = tonumber(saved.SchemaVersion) or 1
	if version > SCHEMA_VERSION then
		return nil -- oyunun daha yeni bir sürümü kaydetmiş: burada yükleme ve üzerine yazma
	end

	-- Her şema değişikliği için bir adım, eskiden yeniye
	if version < 2 then
		-- Örnek: 1. sürümde para birimi Gold idi. Sadece Coins yoksa kopyala,
		-- böylece Coins'i olan ama SchemaVersion'ı olmayan eski veri değerini korur.
		if saved.Coins == nil then
			saved.Coins = saved.Gold
		end
		saved.Gold = nil
	end

	-- Oyuncunun son kaydından sonra eklenen alanları ekle ve yanlış tipteki değerleri değiştir
	for field, default in DEFAULTS do
		if type(saved[field]) ~= type(default) then
			saved[field] = deepCopy(default)
		end
	end
	saved.SchemaVersion = SCHEMA_VERSION
	return saved
end

-- Bir store çağrısını pcall içinde çalıştırır. Başarısız olursa bekler ve tekrar dener, her seferinde
-- bekleme süresini ikiye katlayıp biraz rastgelelik ekler, böylece sunucular hepsi birden yeniden denemez.
local function withRetries(label: string, call: () -> any): (boolean, any)
	for attempt = 1, MAX_ATTEMPTS do
		local ok, result = pcall(call)
		if ok then
			return true, result
		end
		warn(`{label} failed (attempt {attempt} of {MAX_ATTEMPTS}): {result}`)
		if attempt < MAX_ATTEMPTS then
			local waitTime = FIRST_RETRY_SECONDS * 2 ^ (attempt - 1)
			task.wait(waitTime + math.random() * waitTime / 2)
		end
	end
	return false, nil
end

local function save(session: Session): boolean
	if not session.canSave then
		return false
	end
	local key = session.key
	pendingSaves[key] = (pendingSaves[key] or 0) + 1

	local newerSchema = false
	local ok = withRetries(`Save {key}`, function()
		return store():UpdateAsync(key, function(current: any)
			if type(current) == "table" and (tonumber(current.SchemaVersion) or 1) > SCHEMA_VERSION then
				newerSchema = true
				return nil -- nil döndürmek yazmayı iptal eder
			end
			-- Mevcut tablonun tamamını oyuncunun UserId etiketiyle yaz
			return session.data, { session.userId }
		end)
	end)

	local left = (pendingSaves[key] or 1) - 1
	if left > 0 then
		pendingSaves[key] = left
	else
		pendingSaves[key] = nil
	end
	if newerSchema then
		session.canSave = false
		warn(`{key} was saved by a newer version of the game, so this server stopped saving it`)
	end
	return ok and not newerSchema
end

local function startAutosave(player: Player, session: Session)
	task.spawn(function()
		-- Aralığın rastgele bir anında başla, böylece sunucular hepsi birden kaydetmez
		task.wait(math.random() * AUTOSAVE_SECONDS)
		while sessions[player] == session do
			save(session)
			task.wait(AUTOSAVE_SECONDS)
		end
	end)
end

local function load(player: Player)
	local key = "User_" .. player.UserId

	-- Oyuncu bu sunucudan az önce çıkıp geri döndüyse önce son kaydın bitmesini bekle
	while pendingSaves[key] do
		task.wait()
	end

	local ok, saved = withRetries(`Load {key}`, function()
		return store():GetAsync(key)
	end)
	if player.Parent ~= Players then
		return -- yükleme sırasında çıktı: hiçbir şey değişmedi, kaydedilecek bir şey yok
	end

	local data: Data? = nil
	if ok then
		data = if saved == nil then defaultData() else migrate(saved)
	end

	local session: Session = {
		key = key,
		userId = player.UserId,
		data = data or defaultData(),
		canSave = data ~= nil,
	}
	if not session.canSave then
		warn(`Could not load {key}. {player.Name} is playing on default data that will not be saved.`)
	end

	sessions[player] = session
	player:SetAttribute("DataLoaded", session.canSave) -- bir GUI bunu okuyup oyuncuyu uyarabilir
	startAutosave(player, session)
	loadedEvent:Fire(player)
end

local function endSession(player: Player)
	local session = sessions[player]
	if not session then
		return
	end
	sessions[player] = nil -- otomatik kayıt döngüsünü durdurur, ikinci bir çağrı da hiçbir şey yapmaz
	save(session)
end

-- Oyuncunun canlı veri tablosu ya da yüklenene kadar nil. Onu sadece sunucu scriptlerinden değiştir.
function PlayerData.Get(player: Player): Data?
	local session = sessions[player]
	return if session then session.data else nil
end

-- Oyuncunun verisi yüklendiğinde ve kaydedilecekse true. Her satıştan önce kontrol et.
function PlayerData.CanSave(player: Player): boolean
	local session = sessions[player]
	return session ~= nil and session.canSave
end

-- Zamanlayıcıyı beklemeden şimdi kaydeder, satın alma gibi önemli anlar için.
-- Yield eder ve kayıt geçtiğinde true döndürür.
function PlayerData.SaveNow(player: Player): boolean
	local session = sessions[player]
	return session ~= nil and save(session)
end

Players.PlayerAdded:Connect(load)
Players.PlayerRemoving:Connect(endSession)
for _, player in Players:GetPlayers() do
	task.spawn(load, player) -- bu modül ilk require edilmeden önce giren oyuncular
end

game:BindToClose(function()
	-- Sunucu bu fonksiyonlara 30 saniye verir, bu yüzden herkesi aynı anda kaydet
	for player in sessions do
		task.spawn(endSession, player)
	end
	-- Sonra PlayerRemoving'de başlayanlar dahil hâlâ süren tüm kayıtları bekle
	while next(pendingSaves) do
		task.wait()
	end
end)

return PlayerData

Oyun yayına girdikten sonra STORE_NAME'i ve User_ anahtar kalıbını değiştirme. Herhangi birini değiştirmek modülü boş anahtarlara yönlendirir ve her oyuncu varsayılan değerlerle baştan başlar.

Modül veriyi nasıl korur

Varsayılan değerler ve şema sürümü

Yeni bir oyuncu DEFAULTS'un taze bir kopyasını alır. Bunun kopya olması şart: tüm oyuncular tek bir Inventory tablosunu paylaşsaydı, birine eklenen eşya herkeste görünürdü.

Kaydedilen her tablo bir SchemaVersion taşır. Bir alan eklemek yeni sürüm gerektirmez, çünkü migrate eksik alanları varsayılan değerlerden doldurur. Yeniden adlandırma ya da yeniden yapılandırma gerektirir: SCHEMA_VERSION'ı artır ve Gold'u Coins olarak yeniden adlandıran örnekteki gibi bir adım ekle (yeni bir oyunda onu sil ve 1'den başla). Sürümü sunucununkinden yüksek olan veri, hâlâ dağıtılan daha yeni bir sürümden gelmiştir, bu yüzden eski sunucular ona dokunmaz.

Başarısız yükleme asla kaydedilmez

Bu kural tamamen silinmeye karşı korur. Tüm yükleme denemeleri başarısız olursa oyuncu varsayılan veriyle oynar, ama canSave false olur, böylece bu değerler gerçek ilerlemesinin üzerine asla yazmaz. Modül ayrıca DataLoaded attribute'unu false yapar, 3. adım da oyuncuya haber vermek için bunu kullanır. Roblox'un referans örneği başarısız yüklemeleri aynı şekilde ele alıyor ve kick yerine bunu öneriyor; kick etmeyi tercih edersen, modülün uyarı yazdırdığı yerde mesajla player:Kick() çağır.

Artan beklemeli yeniden denemeler

withRetries her çağrıyı pcall içine sarar. Bir başarısızlıktan sonra 1, sonra 2, sonra 4 saniye bekler, her seferinde bu sürenin yarısına kadar rastgele ekleme yapar ve dört denemeden sonra durur (Studio'da bir denemeden sonra, böylece store erişimi olmayan bir place hemen başlar). Rastgelelik bir arızadan sonra çok sayıda sunucunun yeniden denemelerini dağıtır, sınır da beklemeyi yaklaşık 10 saniye içinde, sunucunun kapanmak için aldığı 30 saniyenin içinde tutar. Her kayıt canlı tablonun tamamını UpdateAsync ile yazdığı için geç biten bir yeniden deneme eski veriyi geri getiremez.

Modül ne zaman kaydeder

Ne zamanNeden
Oyuncu sunucudayken her 180 saniyedeBir çökmede kaybı sınırlar. İlk kayıt aralığın rastgele bir anına denk gelir, böylece sunucular hepsi birden kaydetmez. Roblox'un referans örneği de 180 saniye kullanıyor.
Oyuncu çıktığında (PlayerRemoving)Normal son kayıt. Oturum önce silinir, böylece otomatik kayıt durur.
Sunucu kapanırken (game:BindToClose)Hâlâ sunucuda olan herkes birden kaydedilir ve fonksiyon süren her kaydı bekler. Roblox ona 30 saniye verir.
İstek üzerine, PlayerData.SaveNow(player) ileSatın alma gibi kaybedilmemesi gereken bir şeyden sonra.

Bir oyuncu son kaydı hâlâ sürerken aynı sunucuya tekrar girerse, yeni yükleme o kaydın bitmesini bekler, bu yüzden eski değeri okuyamaz.

Adım 2: veriyi diğer scriptlerden oku ve değiştir

Modülü require eden tüm sunucu scriptleri aynı tablolarla çalışır:

ÇağrıNe yapar
PlayerData.Get(player)Oyuncunun canlı veri tablosu ya da yüklenene kadar nil. Alanları doğrudan değiştir, örneğin data.Coins += 10, sonraki kayıt bunu alır.
PlayerData.LoadedOyuncunun verisi hazır olduğunda, başarısız bir yüklemeden sonra da, oyuncuyla tetiklenir. Sadece oyuncuyu gönderir, çünkü bir BindableEvent ile gönderilen tablo kopya olarak gelir.
PlayerData.CanSave(player)Yükleme başarısız olduysa false. Her satıştan önce kontrol et: kaydedilemeyen bir satın alma oyuncu çıkınca kaybolur.
PlayerData.SaveNow(player)Hemen kaydeder ve başarılı olursa true döndürür. Yield eder.

Kaydedilmiş verinin yaşadığı tek yer modüldür, leaderstats ise sadece bir görüntü: onu leaderboard rehberindeki (İngilizce) gibi kur, Loaded işleyicisinde PlayerData.Get(player)'dan doldur ve bir değer değişince ikisini de güncelle. Kaydedilmiş değerleri asla leaderstats'tan geri okuma ve ikinci bir scriptin aynı anahtarı kaydetmesine asla izin verme.

Oyuncular girdikten sonra modülü require eden bir script onlar için Loaded'ı kaçırır. İşleyiciyi bağla, sonra ayrıca Players:GetPlayers() üzerinde döngü kur ve PlayerData.Get(player)'ın zaten tablo döndürdüğü herkesi işle.

Eski bir kayıt scriptini, örneğin leaderboard rehberindekini, mi değiştiriyorsun? Onun değerleri kendi store'unda ve anahtarında kalır, bu yüzden bu modül herkesi varsayılan değerlerle başlatır. Yayına almadan önce ya STORE_NAME'i ve User_ önekini eskilerine yönlendir (migrate, SchemaVersion'ı olmayan veriyi sürüm 1 sayar ve eksik alanları doldurur), ya da eski değerleri taşı, sonra eski scripti sil.

Client'lar bu veriyi asla doğrudan değiştirmez. Bir mağaza butonu bir RemoteEvent tetikler; sunucu CanSave'i kontrol eder, fiyatı oyuncunun Coins'iyle karşılaştırır, tabloyu değiştirir ve SaveNow'ı çağırır. Mağaza GUI rehberi (İngilizce) böyle bir satın almayı sunucu tarafında kuruyor.

Alan eklemenin hazır bir örneği clicker simülatör rehberinde (İngilizce) var: PowerLevel ve Rebirths'ü DEFAULTS'a ve Data tipine ekliyor, sonra onları PlayerData.Get'in döndürdüğü tabloda değiştiriyor. migrate yeni alanları eski kayıtları olan oyunculara verir.

Adım 3: oyuncuya verisinin yüklenmediğini söyle

Verisi yüklenmeyen bir oyuncu, boşuna oynamak yerine yeniden girmek için bu oturumun kaydedilmeyeceğini bilmeli. Bu LocalScript DataLoaded attribute'unu izler ve false olduğunda bir banner gösterir.

LocalScript konum: StarterPlayerScripts adı: DataWarning
local Players = game:GetService("Players")

local player = Players.LocalPlayer
local shown = false

local function showWarning()
	if shown or player:GetAttribute("DataLoaded") ~= false then
		return
	end
	shown = true

	local gui = Instance.new("ScreenGui")
	gui.Name = "DataWarning"
	gui.ResetOnSpawn = false

	local label = Instance.new("TextLabel")
	label.AnchorPoint = Vector2.new(0.5, 0)
	label.Position = UDim2.new(0.5, 0, 0, 12)
	label.Size = UDim2.new(0.8, 0, 0, 48)
	label.BackgroundColor3 = Color3.fromRGB(110, 28, 28)
	label.TextColor3 = Color3.new(1, 1, 1)
	label.TextScaled = true
	label.Text = "Your saved progress could not be loaded. Nothing you do in this server will be saved, so rejoin later."
	label.Parent = gui

	gui.Parent = player:WaitForChild("PlayerGui")
end

-- Sunucu DataLoaded'ı bu oyuncunun verisini yüklemeyi denedikten sonra bir kez ayarlar
player:GetAttributeChangedSignal("DataLoaded"):Connect(showWarning)
showWarning()

Adım 4: kaydetmeyi Studio'da test et

Bunu Studio erişimi açık test kopyasında yap.

  1. Kendine kaydedecek bir şey ver. Main'deki require satırının altına şunu ekle: PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end)
  2. Play'e bas. Output penceresi (Window menüsünde ya da Script sekmesinde) adını ve 100'ü gösterir (ilk çalıştırmada), Could not load uyarısı olmadan.
  3. Stop'a bas. Testi bitirmek sunucuyu kapatır ve modül seni kapanmadan önce kaydeder.
  4. Tekrar Play'e bas. Output 200 göstermeli, geçen seferden 100 fazla. Yine aynı sayıyı gösteriyorsa kayıt geçmemiştir: üstündeki uyarıları oku.
  5. Hata yolunu test et. Studio erişimini kapat ve Play'e bas. Birkaç saniyelik yeniden denemeden sonra Output Could not load User_... ve 100 gösterir, 3. adımdaki banner da çıkar. Testi durdur, erişimi tekrar aç ve Play'e bas: Output 300 gösterir, kaydedilmiş 200'ün artı 100, çünkü başarısız oturum verinin üzerine hiç yazmadı.
  6. Test satırını Main'den sil.

Oyuncu verisi neden kaybolur

Bir kayıt sisteminin ilerlemeyi kaybetmesinin olağan yolları bunlar. Modül ilk dört satırı ve şema satırını kodda kapatıyor; diğerleri neyi ve nasıl sakladığına bağlı, sonuncusu için de oturum kilidi gerekiyor.

Ne oluyorSonuçNasıl önlenir
Yükleme başarısız oldu ama script yine de kaydediyorVarsayılan değerler gerçek ilerlemenin üzerine yazar: tamamen silinmeYüklemesi başarısız olan oyuncuyu asla kaydetmemek
Sadece PlayerRemoving'de kaydetmekSunucu çökmesi ya da kapanması kaydı atlarOtomatik kayıt artı kendi kayıtlarını bekleyen BindToClose
pcall yok ya da yeniden deneme yokTek bir başarısız istek scripti durdurur ya da kaydı kaybederZamana yayılmış birkaç yeniden denemeyle pcall
Her değişiklikte kaydetmekİstekler kuyruğa girer; kuyrukta 30 olunca yenileri atılırVeriyi bellekte tutmak ve zamanlayıcıyla kaydetmek
Store'un saklayamadığı bir şeyi kaydetmekKaydetme hata verir ya da değer nil olarak geri gelirSayıları, string'leri, boolean'ları ve bunlardan oluşan tabloları kaydetmek
Migration olmadan verinin şeklini değiştirmekEski kayıtlar yanlış alanlara yüklenirŞema sürümü ve migration adımı
İki script aynı anahtarı kaydediyorHer kayıt diğerinin alanlarının üzerine yazarAnahtarın sahibi tek bir modül
İki sunucu aynı oyuncuyu tutuyorEski verili sunucu en son kaydeder ve yeni ilerlemenin üzerine yazarOturum kilidi

Oturum kilidi, "lock lost" ve ProfileStore

Bir oyuncu aynı anda tek bir sunucuya bağlıdır, ama eski sunucunun son kaydı o yeni bir sunucuya girerken hâlâ sürüyor olabilir: yavaş bir yeniden deneme, bir teleport ya da hızlı bir yeniden giriş. Yeni sunucu veriyi önce yüklerse elinde eski veri olur ve en son kaydeden sunucu kazanır. Roblox dokümantasyonu, takas olan oyunlarda bu boşluğun eşya kopyalamanın sık bir nedeni olduğunu belirtiyor.

Oturum kilidi bu boşluğu kapatır. Bir sunucu oyuncunun anahtarını yüklediğinde, aynı UpdateAsync çağrısında kendi kilit ID'sini anahtarın metadata'sına yazar. Kendisinin koymadığı ve süresi dolmamış bir kilit bulan herhangi bir sunucu bu anahtarı yüklemez ve kaydetmez. Sahibi kilidi her otomatik kayıtta yeniler ve son kayıtta kaldırır; yenilemeyi bırakırsa kilidin süresi dolar ve başka bir sunucu onu alabilir.

"Lock lost" ne demek

Oturum kilitli bir sistemde, kilidin süresi dolduğu ya da kilit ele geçirildiği için oyuncunun anahtarının sahibi artık başka bir sunucuysa, sunucu kilidi kaybetmiştir. Onun kopyası eskimiş olabilir, bu yüzden o oyuncuyu kaydetmeyi bırakmalı; olağan tepki: oyuncuyu yeniden bağlanması için bir mesajla kick etmek. "Lock lost"u oyuncu olarak gördüysen, bu o oyunun kendi kayıt sisteminin mesajıdır ve onu sadece oyunun geliştiricileri açıklayabilir.

Sana gerekli mi?

Bu rehberdeki modül oturumları kilitlemez. Kilit olmadan gerçek en kötü durum şu: nadir bir yarışta oyuncu, eski sunucuda son başarılı kayıttan sonra kazandığını kaybeder. Kopyalama ya da kayıp oyunculara gerçek bir şeye mal olduğunda kilit ekle: takas, developer product'lar, nadir eşyalar ya da sık teleportlar.

SeçenekNe oBilmen gereken
Bu rehberdeki modülYükleme, bellekte önbellek, yeniden denemeler, otomatik kayıt, kapanışta kayıt ve şema sürümleri, kilit olmadanTamamını okuyup değiştirecek kadar kısa
Roblox'un oyuncu verisi ve satın almalar örneğiRoblox'tan oturum kilitli, her anahtar için sıralı yeniden denemeli ve satın alma fişlerini işleyen referans kodRoblox, popüler bir oyunda zamanla sınanmadığını ve kapsamlı test olmadan olduğu gibi kullanılmaması gerektiğini söylüyor
ProfileStoreOturum kilidi ve otomatik kayıt etrafında kurulmuş, ProfileService'in halefi, ücretsiz ve açık kaynaklı bir topluluk modülüRoblox'tan değil. Mevcut bir oyunu ona geçirmek zaten kaydedilmiş verinin taşınmasını gerektirir

Herhangi bir üçüncü taraf modül için Roblox, sahibinin kim olduğunu, bakımının yapılıp yapılmadığını ve onsuz verine nasıl ulaşacağını kontrol etmeyi öneriyor. Aynı dokümantasyon DataStore2'yi yeni oyunların kullanmaması gereken eskimiş bir kütüphane olarak anıyor.

Data store limitleri

Bunlar Roblox dokümantasyonundaki 30 Eylül 2026 itibarıyla geçerli limitler. Roblox onları gözden geçiriyor, bu yüzden tam bir sayıya güvenmeden önce hata kodları ve limitler sayfasını (İngilizce) kontrol et.

Her sunucu için varsayılan istek limitleri, dakika başına
İstek türüNormal store'larSıralı store'lar
Okuma: GetAsync, UpdateAsync içindeki okuma60 + 40 × oyuncu60 + 40 × oyuncu
Yazma: SetAsync, IncrementAsync, UpdateAsync içindeki yazma60 + 40 × oyuncu30 + 5 × oyuncu
Listeleme: ListKeysAsync ya da sıralı store'lar için GetSortedAsync5 + 2 × oyuncu5 + 2 × oyuncu
Silme: RemoveAsync60 + 40 × oyuncu30 + 5 × oyuncu

20 oyuncuyla bir sunucu dakikada 860 normal yazma yapabilir; bu modülün otomatik kaydı bunlardan yaklaşık 7'sini harcar, artı çıkan her oyuncu için bir tane. Bütçeyi, toplanan her coin'de kaydetmek tüketir. İkinci bir bütçe tüm oyun için geçerli ve Open Cloud ile paylaşılıyor: dakikada 300 okuma artı çevrimiçi her oyuncu için 40 ve 300 yazma artı oyuncu başına 20.

Boyut ve bant genişliği limitleri
LimitDeğer
Store adı, anahtar adı, scopeHer biri 50 karakter
Tek bir anahtardaki değerJSON olarak 4 194 304 karakter
Tüm sunuculardan tek bir anahtarı okumaDakikada 25 MB
Tüm sunuculardan tek bir anahtara yazmaDakikada 4 MB, her istek bir sonraki KB'ye yukarı yuvarlanır
Bekleyen isteklerKuyruk başına 30; bunun üstünde istekler 301-306 hatalarıyla düşer
Tüm oyunun depolama alanı500 MB artı tüm zamanlardaki her kullanıcı için 1 MB

Oyuncu verisinin boyutunu #HttpService:JSONEncode(data) ile ölç, canlı bir sunucunun kalan bütçesini de DataStoreService:GetRequestBudgetForRequestType(Enum.DataStoreRequestType.StandardWrite) ile gör. 4 saniyelik önbelleğin yanıtladığı GetAsync çağrıları sayılmaz. Studio'daki Run modunun kendine ait, muhtemelen daha düşük limitleri var, bu yüzden istek limitlerini test etmek için Roblox Team Create'i öneriyor.

Sürümler ve yedekler

Normal data store'lar geçmişi senin için tutar. Bir anahtara UTC'ye göre her saatteki ilk yazma bir sürüm olarak saklanır, o saatteki sonraki yazmalar da birbirinin üzerine yazar. Eski bir sürüm, daha yeni bir yazma onun yerini aldıktan 30 gün sonra sona erer; en sonuncusu asla sona ermez. Sıralı store'lar sürüm tutmaz.

Tek bir oyuncuyu geri almak için Data Stores Manager'ı aç (Creations, oyunun, Configure > Data Stores Manager), anahtarını seç, daha önceki bir sürümü seç ve Revert'e tıkla; bunun için Edit izni gerekir. Bunu oyuncu çevrimdışıyken yap, yoksa onun oturumunu tutan sunucu kendi kopyasını geri almanın üzerine kaydeder. Bir sunucu scriptinden ListVersionsAsync ve GetVersionAsync eski bir sürümü bulup okur, sen de onu mevcut değer olarak geri yazarsın.

Verinin kaydedilme şeklini değiştiren bir güncellemeyi yayınlamadan önce Roblox, Open Cloud Snapshot Data Stores API ile bir anlık görüntü almayı öneriyor (oyun başına günde bir). Onsuz 3:30 UTC'deki hatalı bir kayıt, o anahtara 3:00'ten beri yazılan her şeyin üzerine yazar, çünkü aynı saatlik sürüme düşer.

Sık yapılan hatalar ve çözümleri

Data store hataları Studio'nun Output penceresinde görünür, modül de her başarısız denemede Roblox'un hata metniyle bir uyarı yazdırır. Script hataları rehberi Output'un genel olarak nasıl okunacağını anlatıyor.

StudioAccessToApisNotAllowed (hata 403)

"Can't write to DataStore from Studio because API access is not enabled." Place'i yayınla, sonra test kopyasında File > Experience Settings > Security'de Enable Studio Access to API Services'ı aç.

DataStore request was added to queue

Sunucu istekleri bütçenin izin verdiğinden hızlı gönderiyor ya da tek bir anahtarı çok sık yazıyor, genellikle her değişiklikte ya da bir döngüde kaydettiği için. Kuyrukta 30 istek olunca yenileri 301-306 hatalarıyla düşer. Veriyi bellekte tut ve zamanlayıcıyla kaydet.

CantStoreValue (hata 104) ya da bir alan nil olarak geri geliyor

Tabloda store'un kaydedemeyeceği bir şey var, örneğin Instance, Vector3 ya da Color3. Bunun yerine adı, ID'yi ya da basit sayıları kaydet ve nesneyi yüklerken yeniden kur.

ValueTooLarge (hata 105)

Tek bir anahtar 4 194 304 karakterden fazla JSON tutuyor. #HttpService:JSONEncode(data) ile ölç, yeniden oluşturulabilecek şeyleri çıkar ya da veriyi birkaç sabit anahtara böl.

Hata yok ama veri kaydedilmiyor

Modülün Could not load uyarısını ara: başarısız bir yüklemeden sonra kaydetmeyi bilerek reddeder. Yoksa değer büyük ihtimalle bir LocalScript'te değiştirildi, bu da sunucuya asla ulaşmaz, ya da aynı anahtarı başka bir script kaydediyor.

Veri her yeniden girişte sıfırlanıyor

Anahtar oturumlar arasında değişiyor (player.Name'den kurulmuş ya da STORE_NAME'i değiştirdin), yükleme başarısız oluyor ve varsayılan değerleri görüyorsun, ya da modülü kimse require etmiyor ve hiç çalışmıyor. Output'u ve Main'in PlayerData'yı require ettiğini kontrol et.

RoCode ile yap

Bunu elle kurmak istemiyorsan RoCode onu açık olan place'inde yapabilir. Roblox'a ait olmayan, Roblox Studio için bir plugin üzerinden çalışan bağımsız bir yapay zeka ajanı: DataStoreService'i her script gibi kullanan Luau yazar ve scriptleri Explorer'ında oluşturur. Data store'larına kendisi asla erişmez, ama plugin 3.9 veya sonrasıyla kısa bir oyun testi için Play'e basabilir, orada scriptlerin her testteki gibi çalışır.

Sen yazarsın

Oyunuma kayıt ekle: Coins, Level ve Inventory'yi otomatik kayıtlı ve sunucu kapanırken kaydeden bir PlayerData modülünde sakla ve Coins'i zaten olan leaderstats'ımda göster.

RoCode yapar
  • İkinci bir kayıt scripti eklemek yerine sende olanı genişletmek için Search Scripts ve Read Script ile mevcut leaderstats'ı ve DataStore kodunu arayabilir. Büyük bir place'te mesajında scriptin ya da klasörün adını ver.
  • Create Script ile ModuleScript'i ve onu require eden Script'i oluşturur ya da Edit Script ile mevcut olanları değiştirir
  • Yazdığı her script için Check Script çalıştırır: Studio içinde kısa bir uyarı listesiyle derleme kontrolü, tip kontrolü ya da test çalıştırması değil
  • Değişiklikleri gruplar hâlinde gönderir ve her grup Studio'da bir geri alma (undo) noktasıdır

Test kopyasında Studio Access to API Services'ı açmak yine sana kalıyor: RoCode bu ayarı değiştiremez. Plugin 3.9 veya sonrasıyla kısa oyun testi hataları okur, plugin 3.9.11 veya sonrasıyla da oyunun çalıştığını kontrol etmek için bir test karakterini yönetebilir, ama sadece kendi kontrol etmeye karar verdiği şeyi kontrol eder, bu yüzden kendin oyna ve Coins, Level ve Inventory'nin kaydedilip yüklendiğinden emin ol. Kayıt senin testinde geçmediyse Check Output, senin başlattığın oyun testindeki Server satırlarını okuyabilir. Kayıt genellikle ana oyun döngüsü zaten çalışırken eklenir; yapay zeka ile Roblox oyununu her seferinde bir sistem olarak yapmak bu sırayı gösteriyor. RoCode Studio'ya nasıl bağlanır.

Sık sorulan sorular

Roblox Studio'da DataStore nasıl açılır?

Place'i yayınla, File > Experience Settings > Security'yi aç, Enable Studio Access to API Services'ı aç ve Save'e tıkla. Bunu ayrı bir test oyununda yap, çünkü Studio o zaman bu oyunun canlı sunucularıyla aynı data store'ları kullanır.

Roblox oyuncu verisini otomatik kaydeder mi?

Hayır. Bir sunucu scripti DataStoreService ile kaydetmedikçe oyuncu hakkında hiçbir şey oturumdan sonra kalmaz, leaderstats da.

Hangisini seçmeli: ProfileStore mu, doğrudan DataStoreService mi?

ProfileStore da data store'lar üzerine kurulu, yani soru oturum kilidinin senin için yazılıp bakımının yapılmasını isteyip istemediğin. Takas, ücretli eşyalar ya da sık teleportlar için kilit buna değer, ister bir kütüphaneden ister Roblox'un referans örneğinden. Daha küçük bir oyun için bunun gibi bir modülü okumak ve değiştirmek daha kolay.

Oyuncu verisi nasıl sıfırlanır ya da silinir?

Data Stores Manager'da anahtarı bul ve bekleme süresi içinde geri alınabilen Mark for Deletion'ı seç ya da bir sunucu scriptinden anahtar için RemoveAsync çağır. Bunu oyuncu çevrimdışıyken yap, yoksa onun sunucusunun sonraki kaydı veriyi geri yazar. Test kopyasında STORE_NAME'i değiştirmek herkesi sıfırdan başlatır; bunu canlı oyunda asla yapma.

Kaynaklar ve ek okumalar

Kod nasıl kontrol edildi: bu sayfadaki her script, Roblox API tanımlarıyla Luau'nun katı tür denetleyicisinden geçiyor (luau-lsp, 20 Kasım 2026). Tür denetimi yanlış yazılmış API'leri ve hatalı türleri yakalar, oyun mantığını değil. Bu yüzden yayınlamadan önce Studio'da test et.

RoCode'u kendi oyununda dene.

Her gün ücretsiz kredi, kart gerekmez. Plugin'i kur, özelliği anlat ve Studio'da ne oluştuğunu kontrol et.