Data Access Functions

Get()

Get(key) → any

Gets a top-level data value. Automatically waits for data to load with built-in caching for performance.

Parameters: key: string
Returns: any - The value, or nil if not found

Example

local PlayerState = require(ReplicatedStorage.Libraries.PlayerState.PlayerStateClient)

local coins = PlayerState.Get("Coins")
local level = PlayerState.Get("Level")
print("Player has", coins, "coins and is level", level)

Note

Automatically waits for server data to sync with built-in caching for performance

---

GetPath()

GetPath(path) → any

Gets a nested data value using dot notation. Automatically waits for data to load with optimized nested value caching.

Parameters: path: ValuePath
Returns: any - The value, or nil if not found

Example

local likes = PlayerState.GetPath("Plot.Likes")
local musicEnabled = PlayerState.GetPath("Settings.MusicEnabled")
local highScore = PlayerState.GetPath("Stats.HighScore")

print("Plot has", likes, "likes")
print("Music is", musicEnabled and "enabled" or "disabled")

Note

Handles nested data structures safely with optimized caching

---

GetAll()

GetAll() → PlayerData?

Gets all player data. Automatically waits for data to load.

Parameters: None
Returns: PlayerData? - Complete data table, or nil if not loaded

Example

local allData = PlayerState.GetAll()
if allData then
    print("Complete player data:", allData)

    -- Iterate through top-level keys
    for key, value in pairs(allData) do
        print(key, "=", value)
    end
end

Note

Returns a reference to the actual data (do not modify!)

Read-Only Data

Don't modify the returned data! It's read-only on the client.

---

GetFromDict()

GetFromDict(dictPath, key) → any

Gets a value from a dictionary using a key with automatic type conversion and caching.

Parameters: dictPath: ValuePath, key: string | number
Returns: any - The value, or nil if not found

Example

local PlayerState = require(ReplicatedStorage.Libraries.PlayerState.PlayerStateClient)

-- Get building data
local houseData = PlayerState.GetFromDict("Plot.Buildings", "House")
if houseData then
    print("House level:", houseData.Level)
    print("House material:", houseData.Material)
end

-- Get with numeric key (automatically converted to string)
local equippedItem = PlayerState.GetFromDict("Inventory.Equipped", 1)

-- Get setting value
local quality = PlayerState.GetFromDict("Settings", "GraphicsQuality")
print("Graphics quality:", quality or "Default")

Note

Automatically converts number keys to strings for consistency

---

Clone()

Clone(value, deep?) → any

Shallow-clones a table with table.clone, or deep-clones with Utils.DeepClone when deep is true. Non-table values are returned unchanged.

Parameters: value: any, deep: boolean?
Returns: any

---

GetOfflineData

GetOfflineData(userId) → PlayerData?

Requests a read-only snapshot of another player’s persisted profile data via the built-in offline RemoteFunction. Does not wait for your Replica (only that the Invoke succeeds).

Parameters: userId: number
Returns: PlayerData? — deserialized data from the server, or nil on failure / invalid id

Trust and scope

Only call this when your game design allows clients to request other users’ stored profiles. The server decides what is returned; handle missing users and failures gracefully.

Replica vs offline snapshot

This is separate from Get / GetAll, which reflect your live Replica. Offline reads can be slower (network round-trip) and should not replace normal UI reads for the local player.

Example

local PlayerState = require(ReplicatedStorage.Libraries.PlayerState.PlayerStateClient)

local snapshot = PlayerState.GetOfflineData(123456789)
if snapshot then
    print("Their Coins:", snapshot.Coins)
end