Skip to main content

PlayerData

Provides an interface for managing player data using ProfileService and ReplicaService.

Functions​

GetPlayerDataReplica​

</>
PlayerData:GetPlayerDataReplica(
player: Player--

The player whose data Replica is being requested.

) → Replica?--

The Replica object associated with the given player, or nil if the player has left.

Returns the Replica object associated with the given player. Modifying tables/arrays should be done through the Replica instead of GetValue/SetValue in order to make sure they replicate properly. The Replica API can be found at: https://madstudioroblox.github.io/ReplicaService/api/#replica

NOTE: Can return nil if the player has left the game, otherwise it will yield until the replica is available.

GetValue​

</>
PlayerData:GetValue(
player: Player,--

The player whose data is being accessed.

keyPath: string | {string}--

The path to the value being accessed, either as a dot-separated string or an array of strings.

) → any?--

The value at the given keyPath, or nil if it doesn't exist.

Returns the value at the given keyPath. Keys can be passed in any of the following ways: 

PlayerData:GetValue(player, "Tokens")
PlayerData:GetValue(player, "Powerups.ExtraLives")
PlayerData:GetValue(player, { "Powerups", "ExtraLives" })

SetValue​

</>
PlayerData:SetValue(
player: Player,--

The player whose data is being modified.

keyPath: string | {string},--

The path to the value being modified, either as a dot-separated string or an array of strings.

newValue: any--

The new value to set at the given keyPath.

) → ()

Sets the value at the given keyPath to the given newValue. Keys can be passed in any of the following ways: 

PlayerData:SetValue(player, "Tokens", 0)
PlayerData:SetValue(player, "Powerups.ExtraLives", 1)
PlayerData:SetValue(player, { "Powerups", "ExtraLives" }, 1)

IncrementNumValue​

</>
PlayerData:IncrementNumValue(
player: Player,--

The player whose data is being modified.

keyPath: string | {string},--

The path to the value being modified, either as a dot-separated string or an array of strings.

increment: number--

The amount to increment the value by. Must be a non-zero number.

) → number?--

The new value after incrementing, or nil if the increment was invalid.

Increments the value at the given keyPath by the given increment. The current stored value must be a number or nil. If the current value is nil, it is first initialized to 0, then incremented. The increment must be a non-zero number. Keys can be passed in any of the following ways: 

PlayerData:IncrementNumValue(player, "Tokens", 1)
PlayerData:IncrementNumValue(player, "Powerups.ExtraLives", 1)
PlayerData:IncrementNumValue(player, { "Powerups", "ExtraLives" }, 1)

Observe​

</>
PlayerData:Observe(
player: Player,--

The player whose data is being observed.

keyPath: string | {string},--

The path to the value being observed, either as a dot-separated string or an array of strings.

callback: (
newValue: any,
oldValue: any
) → ()--

The function to call when the value changes. Will also be called immediately with the current value.

) → RBXScriptConnection?--

The connection object for the change listener, or nil if the player has left.

Immediately processes the callback on the current value at the given keyPath and listens for changes. Keys can be passed in any of the following ways: 

PlayerData:Observe(player, "Tokens", callback)
PlayerData:Observe(player, "Powerups.ExtraLives", callback)
PlayerData:Observe(player, { "Powerups", "ExtraLives" }, callback)

SetValueCallback​

</>
PlayerData:SetValueCallback(
player: Player,
keyPath: string | {string},
callback: (
newValue: any,
oldValue: any
) → (),
runImmediately: boolean?
) → RBXScriptConnection?

Sets a callback function to be run when the value in path is changed. If runImmediately is true, the callback will also be run immediately with the current value. Keys can be passed in any of the following ways: 

PlayerData:SetValueCallback(player, "Tokens", callback, true)
PlayerData:SetValueCallback(player, "Powerups.ExtraLives", callback, true)
PlayerData:SetValueCallback(player, { "Powerups", "ExtraLives" }, callback, true)

CreateProfileHold​

</>
PlayerData:CreateProfileHold(
player: Player--

The player whose profile hold is being created.

) → string?--

A unique hold ID that can be used to release the hold, or nil if the player's profile doesn't exist.

Creates a hold on the player's profile, preventing it from being released until the hold is released. This can be used to prevent the player's data from being unloaded while asynchronous operations are still pending. Returns a unique hold ID that can be used to release the hold.

ReleaseProfileHold​

</>
PlayerData:ReleaseProfileHold(
holdId: string--

The unique hold ID that was returned by CreateProfileHold.

) → ()

Releases a hold on the player's profile with the given hold ID. If the hold ID is invalid or doesn't exist, this function does nothing.

Show raw api
{
    "functions": [
        {
            "name": "GetPlayerDataReplica",
            "desc": "Returns the `Replica` object associated with the given player. Modifying\ntables/arrays should be done through the Replica instead of\n`GetValue`/`SetValue` in order to make sure they replicate properly. The\nReplica API can be found at:\nhttps://madstudioroblox.github.io/ReplicaService/api/#replica\n\nNOTE: Can return `nil` if the player has left the game, otherwise it will\nyield until the replica is available.",
            "params": [
                {
                    "name": "player",
                    "desc": "The player whose data Replica is being requested.",
                    "lua_type": "Player"
                }
            ],
            "returns": [
                {
                    "desc": "The Replica object associated with the given player, or nil if the player has left.",
                    "lua_type": "Replica?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 134,
                "path": "src/server/core/tasks/PlayerData/PlayerData.luau"
            }
        },
        {
            "name": "GetValue",
            "desc": "Returns the value at the given `keyPath`. Keys can be passed in any of the\nfollowing ways:\n```lua\nPlayerData:GetValue(player, \"Tokens\")\nPlayerData:GetValue(player, \"Powerups.ExtraLives\")\nPlayerData:GetValue(player, { \"Powerups\", \"ExtraLives\" })\n```",
            "params": [
                {
                    "name": "player",
                    "desc": "The player whose data is being accessed.",
                    "lua_type": "Player"
                },
                {
                    "name": "keyPath",
                    "desc": "The path to the value being accessed, either as a dot-separated string or an array of strings.",
                    "lua_type": "string | { string }"
                }
            ],
            "returns": [
                {
                    "desc": "The value at the given `keyPath`, or nil if it doesn't exist.",
                    "lua_type": "any?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 171,
                "path": "src/server/core/tasks/PlayerData/PlayerData.luau"
            }
        },
        {
            "name": "SetValue",
            "desc": "Sets the value at the given `keyPath` to the given `newValue`. Keys can be\npassed in any of the following ways:\n```lua\nPlayerData:SetValue(player, \"Tokens\", 0)\nPlayerData:SetValue(player, \"Powerups.ExtraLives\", 1)\nPlayerData:SetValue(player, { \"Powerups\", \"ExtraLives\" }, 1)\n```",
            "params": [
                {
                    "name": "player",
                    "desc": "The player whose data is being modified.",
                    "lua_type": "Player"
                },
                {
                    "name": "keyPath",
                    "desc": "The path to the value being modified, either as a dot-separated string or an array of strings.",
                    "lua_type": "string | { string }"
                },
                {
                    "name": "newValue",
                    "desc": "The new value to set at the given `keyPath`.",
                    "lua_type": "any"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 212,
                "path": "src/server/core/tasks/PlayerData/PlayerData.luau"
            }
        },
        {
            "name": "IncrementNumValue",
            "desc": "Increments the value at the given `keyPath` by the given `increment`. The\ncurrent stored value must be a number or nil. If the current value is nil,\nit is first initialized to 0, then incremented. The increment must be a\nnon-zero number. Keys can be passed in any of the following ways:\n```lua\nPlayerData:IncrementNumValue(player, \"Tokens\", 1)\nPlayerData:IncrementNumValue(player, \"Powerups.ExtraLives\", 1)\nPlayerData:IncrementNumValue(player, { \"Powerups\", \"ExtraLives\" }, 1)\n```",
            "params": [
                {
                    "name": "player",
                    "desc": "The player whose data is being modified.",
                    "lua_type": "Player"
                },
                {
                    "name": "keyPath",
                    "desc": "The path to the value being modified, either as a dot-separated string or an array of strings.",
                    "lua_type": "string | { string }"
                },
                {
                    "name": "increment",
                    "desc": "The amount to increment the value by. Must be a non-zero number.",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "The new value after incrementing, or nil if the increment was invalid.",
                    "lua_type": "number?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 240,
                "path": "src/server/core/tasks/PlayerData/PlayerData.luau"
            }
        },
        {
            "name": "Observe",
            "desc": "Immediately processes the callback on the current value at the given `keyPath`\nand listens for changes. Keys can be passed in any of the following ways:\n```lua\nPlayerData:Observe(player, \"Tokens\", callback)\nPlayerData:Observe(player, \"Powerups.ExtraLives\", callback)\nPlayerData:Observe(player, { \"Powerups\", \"ExtraLives\" }, callback)\n```",
            "params": [
                {
                    "name": "player",
                    "desc": "The player whose data is being observed.",
                    "lua_type": "Player"
                },
                {
                    "name": "keyPath",
                    "desc": "The path to the value being observed, either as a dot-separated string or an array of strings.",
                    "lua_type": "string | { string }"
                },
                {
                    "name": "callback",
                    "desc": "The function to call when the value changes. Will also be called immediately with the current value.",
                    "lua_type": "(newValue: any, oldValue: any) -> ()"
                }
            ],
            "returns": [
                {
                    "desc": "The connection object for the change listener, or nil if the player has left.",
                    "lua_type": "RBXScriptConnection?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 268,
                "path": "src/server/core/tasks/PlayerData/PlayerData.luau"
            }
        },
        {
            "name": "SetValueCallback",
            "desc": "Sets a callback function to be run when the value in path is changed. If\n`runImmediately` is true, the callback will also be run immediately with the\ncurrent value. Keys can be passed in any of the following ways:\n```lua\nPlayerData:SetValueCallback(player, \"Tokens\", callback, true)\nPlayerData:SetValueCallback(player, \"Powerups.ExtraLives\", callback, true)\nPlayerData:SetValueCallback(player, { \"Powerups\", \"ExtraLives\" }, callback, true)\n```",
            "params": [
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                },
                {
                    "name": "keyPath",
                    "desc": "",
                    "lua_type": "string | { string }"
                },
                {
                    "name": "callback",
                    "desc": "",
                    "lua_type": "(newValue: any, oldValue: any) -> ()"
                },
                {
                    "name": "runImmediately",
                    "desc": "",
                    "lua_type": "boolean?\n"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "RBXScriptConnection?\n"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 296,
                "path": "src/server/core/tasks/PlayerData/PlayerData.luau"
            }
        },
        {
            "name": "CreateProfileHold",
            "desc": "Creates a hold on the player's profile, preventing it from being released until\nthe hold is released. This can be used to prevent the player's data from being\nunloaded while asynchronous operations are still pending. Returns a unique\nhold ID that can be used to release the hold.",
            "params": [
                {
                    "name": "player",
                    "desc": "The player whose profile hold is being created.",
                    "lua_type": "Player"
                }
            ],
            "returns": [
                {
                    "desc": "A unique hold ID that can be used to release the hold, or nil if the player's profile doesn't exist.",
                    "lua_type": "string?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 325,
                "path": "src/server/core/tasks/PlayerData/PlayerData.luau"
            }
        },
        {
            "name": "ReleaseProfileHold",
            "desc": "Releases a hold on the player's profile with the given hold ID. If the hold\nID is invalid or doesn't exist, this function does nothing.",
            "params": [
                {
                    "name": "holdId",
                    "desc": "The unique hold ID that was returned by `CreateProfileHold`.",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 347,
                "path": "src/server/core/tasks/PlayerData/PlayerData.luau"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "PlayerData",
    "desc": "Provides an interface for managing player data using ProfileService and\nReplicaService.",
    "source": {
        "line": 25,
        "path": "src/server/core/tasks/PlayerData/PlayerData.luau"
    }
}