ProfileManager

ProfileManager is a small Roblox DataStore wrapper for player-style profile data. It gives you session locking, auto-save, automatic template reconciliation, user id association, mock stores for Studio testing, and a Wally package layout.

It is inspired by the workflow of ProfileStore, but this is its own implementation and intentionally keeps the surface area focused.

Install

Add the package to your game's wally.toml after publishing it under your Wally scope:

[dependencies]
ProfileManager = "therb/profile-manager@0.1.0"

Then install packages:

wally install

Basic Usage

local Players = game:GetService("Players")
local ServerScriptService = game:GetService("ServerScriptService")

local ProfileManager = require(ServerScriptService.Packages.ProfileManager)

local TEMPLATE = {
	Coins = 0,
	Inventory = {},
	Settings = {
		Music = true,
	},
}

local PlayerStore = ProfileManager.New("PlayerData", TEMPLATE)
local Profiles = {}

Players.PlayerAdded:Connect(function(player)
	local profile = PlayerStore:StartSessionAsync("Player_" .. player.UserId, {
		Cancel = function()
			return player.Parent ~= Players
		end,
	})

	if profile == nil then
		player:Kick("Your data could not be loaded. Please rejoin.")
		return
	end

	profile:AddUserId(player.UserId)

	profile.OnSessionEnd:Connect(function()
		Profiles[player] = nil
		player:Kick("Your data session ended. Please rejoin.")
	end)

	Profiles[player] = profile
end)

Players.PlayerRemoving:Connect(function(player)
	local profile = Profiles[player]
	if profile ~= nil then
		Profiles[player] = nil
		profile:EndSession()
	end
end)

API

ProfileManager.New(storeName, template?, options?)

Creates a profile store backed by DataStoreService:GetDataStore(storeName).

Options:

• AutoSaveInterval: seconds between auto-saves. Defaults to 60.
• LockTimeout: seconds before a stale lock can be claimed. Defaults to 180.
• LoadRetryDelay: seconds between load attempts while another server owns the lock. Defaults to 2.
• LoadTimeout: maximum seconds to wait for a session by default. Defaults to 30.
• SaveRetries: DataStore retry attempts for saving/removing. Defaults to 3.
• RetryDelay: base retry delay for failed DataStore calls. Defaults to 2.
• DataStoreScope: optional DataStore scope.
• DisableAutoSave: set to true to require manual saves.

store:StartSessionAsync(key, params?)

Loads a profile and claims its session lock. Returns a Profile or nil when loading is cancelled, times out, or cannot acquire the lock.

Params:

• Cancel: optional function checked between retries.
• Steal: force-claims the lock. Use only for debugging or recovery tooling.
• Timeout: overrides the store load timeout for this call.

Alias: store:LoadProfileAsync(key, params?).

store:GetAsync(key)

Reads a profile without claiming a session. The returned profile will not auto-save and should be treated as read-only unless you know exactly what you are doing.

store:RemoveAsync(key)

Removes the key from the DataStore. This fails if the same store currently has an active session for that key.

store.Mock

Uses the same API against in-memory storage that disappears when the server shuts down.

local Store = ProfileManager.New("PlayerData", TEMPLATE)

if game:GetService("RunService"):IsStudio() then
	Store = Store.Mock
end

Profile API

• profile.Data: your mutable profile data table.
• profile.LastSavedData: deep copy of the last successfully saved data.
• profile.MetaData: created/updated timestamps, save count, session count, and meta tags.
• profile.UserIds: user ids associated with this profile.
• profile.RobloxMetaData: table saved as Roblox DataStore metadata.
• profile:IsActive(): returns whether this server still owns the session.
• profile:Reconcile(): manually fills missing fields from the template. Profiles are also reconciled automatically when loaded.
• profile:Save(): saves immediately while active.
• profile:EndSession(): final save, clears the session lock, and stops auto-save.
• profile:Release(): alias for EndSession.
• profile:AddUserId(userId) / profile:RemoveUserId(userId).
• profile:SetMetaTag(name, value) / profile:GetMetaTag(name).
• profile.OnSave, profile.OnAfterSave, profile.OnLastSave, profile.OnSessionEnd: simple signal objects.

Notes

ProfileManager uses a simple stale-lock model instead of ProfileStore's full MessagingService-assisted handoff. Keep LockTimeout comfortably higher than AutoSaveInterval, and always call profile:EndSession() when a player leaves.