Server API

Server-side PlayerState API for data management and persistence.

Initialization Functions

Init()

Init(player, existingData?)

Initializes PlayerState for a player. Must be called when a player joins.

Parameters:

• player: Player - The player to initialize
• existingData?: PlayerData - Optional existing data (not currently supported)

Returns: boolean - Success status

---

Basic Data Functions

Set()

Set(player, key, value) → boolean

Sets a top-level data value with enhanced validation.

Parameters: player: Player, key: string, value: any
Returns: boolean - Success status (false if leaderstats modification attempted)

---

Get()

Get(player, key) → any

Gets a top-level data value with validation.

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

---

Path-based Functions

SetPath()

SetPath(player, path, value) → boolean

Sets a nested data value using dot notation with enhanced validation.

Parameters: player: Player, path: ValuePath, value: any
Returns: boolean - Success status

---

GetPath()

GetPath(player, path) → any

Gets a nested data value using dot notation with optimized performance.

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

---

Numeric Operation Functions

Increment()

Increment(player, key, amount?) → boolean

Increments a numeric value with validation. Works with both top-level keys and nested paths.

Parameters: player: Player, key: string, amount: number? (defaults to 1)
Returns: boolean - Success status

---

Decrement()

Decrement(player, key, amount?) → boolean

Decrements a numeric value with validation. Works with both top-level keys and nested paths.

Parameters: player: Player, key: string, amount: number? (defaults to 1)
Returns: boolean - Success status

---

Batch Operation Functions

SetValues()

SetValues(player, values) → boolean

Sets multiple top-level values at once with leaderstats protection.

Parameters: player: Player, values: {[string]: any}
Returns: boolean - Success status

---

BatchSetValues()

BatchSetValues(player, operations) → boolean

Queues multiple path-based operations for optimized batch processing.

Parameters: player: Player, operations: {BatchOperation}
Returns: boolean - Success status

---

FlushBatch()

FlushBatch(player) → boolean

Immediately processes all queued batch operations for a player.

Parameters: player: Player
Returns: boolean - Success status

---

Array Operation Functions

AddToArray()

AddToArray(player, arrayPath, item) → boolean

Adds an item to the end of an array with validation.

Parameters: player: Player, arrayPath: ArrayPath, item: any
Returns: boolean - Success status

---

RemoveFromArray()

RemoveFromArray(player, arrayPath, index) → boolean

Removes an item from an array by index with bounds checking.

Parameters: player: Player, arrayPath: ArrayPath, index: number (1-based)
Returns: boolean - Success status

---

UpdateArrayItem()

UpdateArrayItem(player, arrayPath, index, newItem) → boolean

Updates an item in an array by index with validation.

Parameters: player: Player, arrayPath: ArrayPath, index: number (1-based), newItem: any
Returns: boolean - Success status

---

Dictionary Operation Functions

SetInDict()

SetInDict(player, dictPath, key, value) → boolean

Sets a value in a dictionary/table with efficient nested path updates and automatic dictionary creation.

Parameters: player: Player, dictPath: DictPath, key: string, value: any
Returns: boolean - Success status

---

GetFromDict()

GetFromDict(player, dictPath, key) → any

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

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

---

RemoveFromDict()

RemoveFromDict(player, dictPath, key) → boolean

Removes a key from a dictionary using efficient nested path updates.

Parameters: player: Player, dictPath: DictPath, key: string
Returns: boolean - Success status

---

Cache Management Functions

ClearPathCache()

ClearPathCache() → void

Clears the global path parsing cache for memory management.

Parameters: None
Returns: Nothing

---

Events

BeforeSave()

BeforeSave:Connect(listener)

Fired before player data is saved, allowing for final data modifications.

Parameters: listener: (player: Player, data: PlayerData) -> ()
Returns: Connection - Event connection for disconnecting

---

ProfileLoaded()

ProfileLoaded:Connect(listener)

Fired when a player's profile data has been loaded and is ready for use.

Parameters: listener: (player: Player, data: PlayerData) -> ()
Returns: Connection - Event connection for disconnecting

---

ProfileUnloaded()

ProfileUnloaded:Connect(listener)

Fired when a player's profile session ends and data is being unloaded.

Parameters: listener: (player: Player, data: PlayerData) -> ()
Returns: Connection - Event connection for disconnecting

---

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

---

GetReplica()

GetReplica(player) → ReplicaInstance?

Gets the raw Replica instance for advanced operations.

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

---

GetProfile()

GetProfile(player) → ProfileStoreProfile?

Gets the raw ProfileStore profile for advanced operations.

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

---

GetOfflineData()

GetOfflineData(userId) → PlayerData?

Retrieves player data for offline users from ProfileStore.

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

---

SetOfflineData()

SetOfflineData(userId, path, value) → boolean

Sets data for offline users in ProfileStore.

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

---

SaveData()

SaveData(player) → boolean

Forces data save validation check.

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

---

WipePlayerData()

WipePlayerData(player) → boolean

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

Parameters: player: Player
Returns: boolean - Success status

---

WipeOfflinePlayerData()

WipeOfflinePlayerData(userId) → boolean

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

Parameters: userId: number
Returns: boolean - Success status

---

Global Leaderboard

GetLeaderboard()

GetLeaderboard(statName, topCount) → {LeaderboardEntry}

Retrieves the top players for a specific leaderboard statistic.

Parameters: statName: string, topCount: number
Returns: {LeaderboardEntry} - Array of leaderboard entries sorted by score (highest first), or empty array if configuration issues

---

GetPlayerRank()

GetPlayerRank(player, statName) → number?

Gets a player's current rank on a specific leaderboard.

Parameters: player: Player, statName: string
Returns: number? - Player's rank (1-based), or nil if not ranked, invalid player, or configuration issues

---

UpdateLeaderboard()

UpdateLeaderboard(player, statName, score) → boolean

Manually updates a player's leaderboard entry for a specific statistic.

Parameters: player: Player, statName: string, score: number
Returns: boolean - Success status, or false if configuration or validation issues