Orion Leaderboards

Orion Leaderboards are a custom-built iteration on OrderedDataStores. These leaderboards allow for realtime updates to player positions, fetching of specific player rankings, and more.

info

Orion Leaderboards are not a Database for player scores. Rather they act as a "model" for viewing this data. Player scores should be stored normally in Roblox DataStores and frequently written to the Orion Leaderboards package to keep it up to date.

Quick Start

Provision a new auth token

Ensure you've registered your development place as an environment

1. Head over to Orion Mission Control
2. Select your experience via the game selector on the top of the window
3. Navigate to the Auth page
4. Create a new token
   1. Give it a helpful name
   2. Set it's expiration
   3. Select the environment(s) the token will be used in
   4. Select leaderboards:write and leaderboards:read
   5. Copy the token once created and keep it somewhere safe!

Add the token as a secret to your Roblox place

1. Head over to the creator dashboard and navigate to the group and experience
2. Under Configure, select the Secrets menu
3. Create a new secret
   1. Set its name to orion_leaderboard_auth_token
   2. Set its value to the auth token you fetched in Step 1

info

Group owners are the only users that can add / edit secrets to an experience. Please reach out to Patrick or Brandon to provision the secret.

Setup the token in your Roblox place

1. Create a .leaderboard_auth_token.txt file at the root of your project
2. Add .leaderboard_auth_token.txt to your .gitignore
3. Edit the default.project.json and ensure there's an entry for ServerStorage
4. Add the .leaderboard_auth_token.txt underneath ServerStorage

"ServerStorage": {
    "$className": "ServerStorage",

    "LeaderboardAuthToken": {
        "$path": ".leaderboard-auth-token.txt"
    }
}

info

This is an important step: we are no longer committing auth tokens to our codebase. Ensure you delete these files when publishing to production!

Setup the leaderboards in your codebase

1. Create a LeaderboardService or adjacently named Service
2. In the RoamInit method, construct a new OrionLeaderboard class
3. Set the ApiUrl to https://leaderboards.supersocialinc.com
4. Add the following code (or similar) to your LeaderboardService, above the constructor

-- import server storage somewhere

local authTokenObject = ServerStorage:FindFirstChild("LeaderboardAuthToken")
local authTokenValue = authTokenObject and authTokenObject.Value

...

4. Set the AuthToken parameter to authTokenValue
5. Adjust any other parameters (see [OrionLeaderboard] for other configuration options)

Here's a complete example of the constructor of the leaderboard

local ServerStorage = game:GetService("ServerStorage")

local OrionLeaderboard = Import("OrionLeaderboard")

local authTokenObject = ServerStorage:FindFirstChild("LeaderboardAuthToken")
local authTokenValue = authTokenObject and authTokenObject.Value

local leaderboard = OrionLeaderboard.new({
    ApiUrl = "https://api.supersocialinc.com/leaderboards",
    AuthToken = authTokenValue,
    CacheTTL = 120
})

danger

The raw AuthToken should not be committed to the repo and should not make it to production. AuthToken is an optional parameter that should only be passed in to supplement the Secret when not available (like in Studio).

Understanding Leaderboard scoping

The leaderboard package automatically sends the UniverseId alongside requests to the backend. The backend then uses this to determine where to read and write data from. This "scopes" data per experience, just like DataStores.

Example Usage

Here's an example LeaderboardService that showcases some of the functionality of the Leaderboard package

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ServerStorage = game:GetService("ServerStorage")

local Import = require(ReplicatedStorage.Orion.Import)
local OrionLeaderboard = Import("OrionLeaderboard")

local LeaderboardService = {}

--[=[
    Returns a players score for the TopCoins board
]=]
function LeaderboardService:GetPlayerCoinsScore(player: Player)
    return self._leaderboard:GetPlayerScore("TopCoins", player)
end

--[=[
    Sets the players score on the TopCoins board
]=]
function LeaderboardService:SetPlayerCoinsScore(player: Player, coins: number)
    return self._leaderboard:SetPlayerScore("TopCoins", player, coins)
end

--[=[
    Returns top 10 players on the TopCoins board
]=]
function LeaderboardService:GetTopCoinsRankings()
    return self._leaderboard:GetRankings("TopCoins", 1, 10)
end

--[=[
    Returns the "special" user for the TopCoins board, in this case, the 10,000th user
]=]
function LeaderboardService:GetCoinsSpecialUser()
    return self._leaderboard:GetRankings("TopCoins", 10_000, 1)
end

--[=[
    Returns a stack ranked list of a users friends on the TopCoins leaderboard
]=]
function LeaderboardService:GetUserFriendsCoinRanking(player: Player, friendIds: {number})
    return self._leaderboard:GetRankingOfPlayers("TopCoins", `{player.UserId}_friends`, friendIds)
end

function LeaderboardService:RoamInit()
    local authTokenObject = ServerStorage:FindFirstChild("LeaderboardAuthToken")
    local authTokenValue = authTokenObject.Value

    self._leaderboard = OrionLeaderboard.new({
        ApiUrl = "https://leaderboards.supersocialinc.com",
        AuthToken = authTokenValue
    })
end

return LeaderboardService