Skip to main content

PlayerDataService

PlayerDataService handles creation and management of PlayerProfiles (ProfileService), and exposes methods for interfacing with PlayerData. PlayerDataService also has native support for migrations, and data replication.

Example:

function TestService:RoamInit()

	local migrations: { Types.DataMigrator } = {}
		{
			FromVersion = 1,
			ToVersion = 2,
			Migrate = function(player: Player, data: Types.ProfileTemplate)
				data.Server.Experience = 0

				return data
			end
		}
	}

	PlayerDataService:SetConfig({
		ProfileStoreName = "PlayerData";
		ProfileTemplate = {
			Server = {
				SecretValue = true
			},
			Shared = {
				Money = 0;
				Inventory = {};
				Coins = 100
			},
			Version = 1
		};
		Migrator = migrations
	})

end

Functions​

SetConfig​

</>
PlayerDataService:SetConfig(config: Types.PlayerDataHandlerConfig) → ()

Sets the configuration of the PlayerDataService

PromisePlayerData​

</>
PlayerDataService:PromisePlayerData(
player: Player,
key: string
) → Types.Promise--Promise<any>

Provides a method to allow other server-side consumers to know when a player's data has loaded.

Returns a promise which:

  • Resolves when the player's data is ready to be consumed.
  • Rejects if the player leaves before the data is ready to be consumed.

GetPlayerData​

</>
PlayerDataService:GetPlayerData(
player: Player,
key: string
) → any?

Returns a value from a players data

SetPlayerData​

</>
PlayerDataService:SetPlayerData(
player: Player,
key: string,
value: any
) → ()

Set's a value in a players data to a specific value. Automatically replicates the data to the player

UpdatePlayerData​

</>
PlayerDataService:UpdatePlayerData(
player: Player,
key: string,
mutator: (any) → any
) → ()

Updates a value in a players data with the value returned by the mutator callback. Automatically replicates the data to the player

ResetPlayerData​

</>
PlayerDataService:ResetPlayerData(
player: Player,
shouldKick: boolean?
) → ()

Resets the player's data to the template data

AddPlayerDataHook​

</>
PlayerDataService:AddPlayerDataHook(
key: string,
callback: (
Player,
any
) → ()
) → ()

Adds a hook to be called when a player's data is updated

ObservePlayerData​

</>
PlayerDataService:ObservePlayerData(
player: Player,
key: string
) → ()

Returns an Rx Observable that fires when a specific piece of a players' data changes -- TODO: Rename this to GetPlayerDataRxObservable

SavePlayerData​

</>
PlayerDataService:SavePlayerData(player: Player) → ()

Forces a save for a players data

GetPlayerProfile​

</>
PlayerDataService:GetPlayerProfile(player: Player) → ()

Gets the player profile

Show raw api
{
    "functions": [
        {
            "name": "SetConfig",
            "desc": "Sets the configuration of the PlayerDataService",
            "params": [
                {
                    "name": "config",
                    "desc": "",
                    "lua_type": "Types.PlayerDataHandlerConfig"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 75,
                "path": "src/playerdata/src/Server/PlayerDataService.lua"
            }
        },
        {
            "name": "PromisePlayerData",
            "desc": "Provides a method to allow other server-side consumers to know when a player's data has loaded.\n\nReturns a promise which:\n* Resolves when the player's data is ready to be consumed.\n* Rejects if the player leaves before the data is ready to be consumed.",
            "params": [
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                },
                {
                    "name": "key",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Types.Promise -- Promise<any>\n"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 325,
                "path": "src/playerdata/src/Server/PlayerDataService.lua"
            }
        },
        {
            "name": "GetPlayerData",
            "desc": "Returns a value from a players data",
            "params": [
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                },
                {
                    "name": "key",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "any?\n"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 357,
                "path": "src/playerdata/src/Server/PlayerDataService.lua"
            }
        },
        {
            "name": "SetPlayerData",
            "desc": "Set's a value in a players data to a specific value. Automatically replicates the data to the player",
            "params": [
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                },
                {
                    "name": "key",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 365,
                "path": "src/playerdata/src/Server/PlayerDataService.lua"
            }
        },
        {
            "name": "UpdatePlayerData",
            "desc": "Updates a value in a players data with the value returned by the mutator callback.\nAutomatically replicates the data to the player",
            "params": [
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                },
                {
                    "name": "key",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "mutator",
                    "desc": "",
                    "lua_type": "(any) -> any"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 401,
                "path": "src/playerdata/src/Server/PlayerDataService.lua"
            }
        },
        {
            "name": "ResetPlayerData",
            "desc": "Resets the player's data to the template data",
            "params": [
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                },
                {
                    "name": "shouldKick",
                    "desc": "",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 426,
                "path": "src/playerdata/src/Server/PlayerDataService.lua"
            }
        },
        {
            "name": "AddPlayerDataHook",
            "desc": "Adds a hook to be called when a player's data is updated",
            "params": [
                {
                    "name": "key",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "callback",
                    "desc": "",
                    "lua_type": "(Player, any) -> ()"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 441,
                "path": "src/playerdata/src/Server/PlayerDataService.lua"
            }
        },
        {
            "name": "ObservePlayerData",
            "desc": "Returns an Rx Observable that fires when a specific piece of a players' data changes\n-- TODO: Rename this to GetPlayerDataRxObservable",
            "params": [
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                },
                {
                    "name": "key",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 451,
                "path": "src/playerdata/src/Server/PlayerDataService.lua"
            }
        },
        {
            "name": "SavePlayerData",
            "desc": "Forces a save for a players data",
            "params": [
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 467,
                "path": "src/playerdata/src/Server/PlayerDataService.lua"
            }
        },
        {
            "name": "GetPlayerProfile",
            "desc": "Gets the player profile",
            "params": [
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 481,
                "path": "src/playerdata/src/Server/PlayerDataService.lua"
            }
        },
        {
            "name": "_replicateSharedDataToPlayer",
            "desc": "Replicates all of a player's shared data to the player",
            "params": [
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                }
            ],
            "returns": [],
            "function_type": "method",
            "private": true,
            "source": {
                "line": 496,
                "path": "src/playerdata/src/Server/PlayerDataService.lua"
            }
        },
        {
            "name": "_replicateDataToPlayer",
            "desc": "Replicates data to a player",
            "params": [
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                },
                {
                    "name": "key",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [],
            "function_type": "method",
            "private": true,
            "source": {
                "line": 516,
                "path": "src/playerdata/src/Server/PlayerDataService.lua"
            }
        },
        {
            "name": "_lookupMigrator",
            "desc": "Looks up a migrator function for a specific version",
            "params": [
                {
                    "name": "fromVersion",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "toVersion",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Types.DataMigrator?\n"
                }
            ],
            "function_type": "method",
            "private": true,
            "source": {
                "line": 533,
                "path": "src/playerdata/src/Server/PlayerDataService.lua"
            }
        },
        {
            "name": "_reconcile",
            "desc": "Reconciles player data",
            "params": [
                {
                    "name": "data",
                    "desc": "",
                    "lua_type": "Types.PlayerData"
                }
            ],
            "returns": [],
            "function_type": "method",
            "private": true,
            "source": {
                "line": 546,
                "path": "src/playerdata/src/Server/PlayerDataService.lua"
            }
        },
        {
            "name": "_flattenPlayerData",
            "desc": "Flattens a profile template into a depth=1 array, used for migrations and for converting new\nplayer data into the profile template",
            "params": [
                {
                    "name": "playerData",
                    "desc": "",
                    "lua_type": "Types.ProfileTemplate"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Types.PlayerData\n"
                }
            ],
            "function_type": "method",
            "private": true,
            "source": {
                "line": 578,
                "path": "src/playerdata/src/Server/PlayerDataService.lua"
            }
        },
        {
            "name": "_expandPlayerData",
            "desc": "Expands flattened userdata to match the profile template. Used for migrations",
            "params": [
                {
                    "name": "playerData",
                    "desc": "",
                    "lua_type": "Types.PlayerData"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Types.ProfileTemplate\n"
                }
            ],
            "function_type": "method",
            "private": true,
            "source": {
                "line": 603,
                "path": "src/playerdata/src/Server/PlayerDataService.lua"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "PlayerDataService",
    "desc": "PlayerDataService handles creation and management of PlayerProfiles (ProfileService), and exposes methods for\ninterfacing with PlayerData. PlayerDataService also has native support for migrations, and data replication.\n\nExample:\n```lua\nfunction TestService:RoamInit()\n\n\tlocal migrations: { Types.DataMigrator } = {}\n\t\t{\n\t\t\tFromVersion = 1,\n\t\t\tToVersion = 2,\n\t\t\tMigrate = function(player: Player, data: Types.ProfileTemplate)\n\t\t\t\tdata.Server.Experience = 0\n\n\t\t\t\treturn data\n\t\t\tend\n\t\t}\n\t}\n\n\tPlayerDataService:SetConfig({\n\t\tProfileStoreName = \"PlayerData\";\n\t\tProfileTemplate = {\n\t\t\tServer = {\n\t\t\t\tSecretValue = true\n\t\t\t},\n\t\t\tShared = {\n\t\t\t\tMoney = 0;\n\t\t\t\tInventory = {};\n\t\t\t\tCoins = 100\n\t\t\t},\n\t\t\tVersion = 1\n\t\t};\n\t\tMigrator = migrations\n\t})\n\nend\n```",
    "source": {
        "line": 44,
        "path": "src/playerdata/src/Server/PlayerDataService.lua"
    }
}