Data Access Functions

Get()

Get(key) → any

Gets a top-level data value. Automatically waits for data to load, then reads the live replicated data directly.

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. Reads are live (no value cache), so you always get the latest value, even inside your own Replica listeners.

---

GetPath()

GetPath(path) → any

Gets a nested data value using dot notation. Automatically waits for data to load and always returns the latest value. Array indices work as path segments, e.g. GetPath("Items.1").

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; returns nil if any part of the path is missing

---

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. Reads the live data directly.

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.

What the client gets

• No server-only data and no session data, only data clients could normally see.
• Requests are rate limited per player, and offline results are cached briefly, so repeated calls may return the same snapshot.
• NaN, infinite and fractional user ids are rejected (returns nil) without spending DataStore requests.

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