Utility Functions

GetAll()

GetAll(player) → PlayerData?

Gets all player data with validation.

Parameters: player: Player
Returns: PlayerData? - Complete data table, or nil if not found

Example

local allData = PlayerState.GetAll(player)
if allData then
    print("Player has", allData.Coins, "coins")
    -- Safely iterate through data
    for key, value in pairs(allData) do
        print(`{key}: {value}`)
    end
end

Note

Returns reference to actual data (be careful with modifications)

---

GetReplica()

GetReplica(player) → ReplicaInstance?

Gets the raw Replica instance for advanced operations.

Parameters: player: Player
Returns: ReplicaInstance? - Replica instance, or nil if not found

Example

local replica = PlayerState.GetReplica(player)
if replica then
    -- Advanced Replica operations
    replica:OnChange(function(action, path, ...)
        print(`Data changed: {action} at {table.concat(path, ".")}`)
    end)

    -- Check replica status
    print("Replica is active:", replica:IsActive())
end

Note

Enhanced validation ensures replica is active

---

GetProfile()

GetProfile(player) → ProfileStoreProfile?

Gets the raw ProfileStore profile for advanced operations.

Parameters: player: Player
Returns: ProfileStoreProfile? - Profile instance, or nil if not found

Example

local profile = PlayerState.GetProfile(player)
if profile then
    -- Advanced ProfileStore operations
    print("Profile is active:", profile:IsActive())

    -- Access profile metadata
    print("Profile tags:", profile.Tags)
end

Note

Enhanced validation ensures profile is active

---

IsPlayerDataReady

IsPlayerDataReady(player) → boolean

Returns whether this player has an active profile and Replica after Init (without blocking/waiting).

Parameters: player: Player
Returns: boolean — true when profile and replica are valid for that player

Use this for cheap readiness checks from server scripts. Operations such as GetPath / SetPath already wait internally where appropriate; this API matches the explicit check used inside PlayerState.

Example

if PlayerState.IsPlayerDataReady(player) then
    PlayerState.SetPath(player, "Stats.LastSeenServer", os.time())
end

---

Clone()

Clone(value, deep?) → any

Clones a value, with optional deep cloning for tables. Useful for safely copying data without modifying the original.

Parameters: value: any, deep: boolean? (defaults to false)
Returns: any - Cloned value (tables are cloned, other types returned as-is)

Example

-- Shallow clone (default)
local originalTable = {coins = 100, items = {sword = true}}
local clonedTable = PlayerState.Clone(originalTable)
clonedTable.coins = 200 -- Only modifies clone
clonedTable.items.sword = false -- Modifies original too (shallow clone)

-- Deep clone (nested tables are also cloned)
local deepCloned = PlayerState.Clone(originalTable, true)
deepCloned.coins = 300 -- Only modifies clone
deepCloned.items.sword = false -- Only modifies clone (deep clone)

-- Clone non-table values (returns as-is)
local number = PlayerState.Clone(100) -- Returns 100
local string = PlayerState.Clone("test") -- Returns "test"

Note

• Non-table values are returned unchanged
• Shallow clone (default) uses table.clone() for performance
• Deep clone recursively clones all nested tables
• Use deep clone when you need to modify nested structures safely

---

GetOfflineData()

GetOfflineData(userId) → PlayerData?

Retrieves player data for offline users from ProfileStore. Automatically checks if the player is currently in the server first for better performance.

Parameters: userId: number
Returns: PlayerData? - Player data, or nil if not found or invalid

Example

local offlineData = PlayerState.GetOfflineData(123456789)
if offlineData then
    print("Offline player has", offlineData.Coins, "coins")
    print("Level:", offlineData.Level)
else
    print("No offline data found for user")
end

Note

• Automatically checks if player is in server first (uses live data if available)
• Falls back to ProfileStore for offline players
• More efficient than previous implementation

---

SetOfflineData()

SetOfflineData(userId, path, value) → boolean

Sets data for offline users in ProfileStore. Automatically checks if the player is currently in the server first and uses live data operations when available.

Parameters: userId: number, path: string, value: any
Returns: boolean - Success status

Example

-- Set top-level data
local success = PlayerState.SetOfflineData(123456789, "Coins", 5000)
if success then
    print("Offline coins updated successfully")
end

-- Set nested data using paths
PlayerState.SetOfflineData(123456789, "Plot.Likes", 100)
PlayerState.SetOfflineData(123456789, "Settings.MusicEnabled", false)

Note

• Automatically checks if player is in server first (uses live PlayerState functions if available)
• Falls back to ProfileStore messaging for offline players with active sessions
• Creates new session if player is completely offline
• More efficient handling of online vs offline players

Session Paths Blocked

SetOfflineData blocks runtime-only paths such as session.*. Writes to those paths will warn or fail. Session data is never persisted; use SetPath when the player is in-game.

Server-only paths

Paths under ServerOnlyRoots (for example Server.*) are persistent and can be updated with SetOfflineData. See Server-only data.

---

SaveData()

SaveData(player) → boolean

Forces data save validation check.

Parameters: player: Player
Returns: boolean - Profile active status

Example

-- Check if save will succeed before critical operation
local canSave = PlayerState.SaveData(player)
if canSave then
    -- Proceed with critical operation
    PlayerState.Set(player, "ImportantData", value)
else
    warn("Cannot save data - profile inactive")
end

Note

Returns profile active status for validation

---

WipePlayerData()

WipePlayerData(player) → boolean

Wipes all player data and resets it to the template values.

Parameters: player: Player
Returns: boolean - Success status

Example

-- Reset player data to template values
local success = PlayerState.WipePlayerData(player)
if success then
    print(`{player.Name}'s data has been reset`)
else
    warn(`Failed to reset {player.Name}'s data`)
end

Note

Resets all data to CONFIG.Profile.Template values and kicks player

---

WipeOfflinePlayerData()

WipeOfflinePlayerData(userId) → boolean

Wipes data for offline players and resets it to template values.

Parameters: userId: number
Returns: boolean - Success status

Example

-- Reset offline player data
local success = PlayerState.WipeOfflinePlayerData(123456789)
if success then
    print("Offline player data reset successfully")
else
    warn("Failed to reset offline player data")
end

Note

Works with offline players not currently in the game