Hi Creators,
Friend leaderboards are one of your most requested social features, but today they’re expensive to run at scale because you have to fan out DataStore reads across a user’s entire friend list.
We’re releasing the beta for our new GetFriendsWhoPlayed API that gives you a way to fetch only friends who have actually played your game. Now, you can build fast, reliable friends leaderboards with far fewer reads. We will expand access over time as we validate performance and reliability.
What is the GetFriendsWhoPlayed API?
The GetFriendsWhoPlayed API lets you query friends who have played this universe ever.
Instead of pulling a full friend list and hitting DataStore for everyone, you can now narrow down to the friends who matter and then look up scores only for them. This reduces DataStore load, lowers the chance of rate limits, and makes it more practical to run friends leaderboards at scale.
Implementing a Friends Leaderboard
The beta introduces a new method on Player:
local DataStoreService = game:GetService("DataStoreService")
local GlobalScores = DataStoreService:GetOrderedDataStore("GlobalScores")
local function getFriendLeaderboard(player)
local friendScores = {}
-- 1. Fetch friends who played recently
local friendIds = player:GetFriendsWhoPlayedAsync()
-- 2. Fetch score of each of the friends who played
for _, friendId in friendIds do
local success, score = pcall(function()
return GlobalScores:GetAsync(tostring(friendId))
end)
if success and score then
table.insert(friendScores, {
UserId = friendId,
Score = score,
})
end
end
return friendScores
end
API shape (beta)
- Player:GetFriendsWhoPlayedAsync() → Array of userIds (Type: Number)
- Returns a list of friends’ user IDs who have played the same games.
See documentation here.
Other Use Cases Beyond Leaderboards
Although the main goal is powering friends leaderboards, this API is meant to be broadly useful for any feature that needs “friends who actually play this game,” such as:
- “Friends who play this game” sections in menus
- Social surfaces that highlight active friends
What’s Next
In the future, we’re planning to provide out-of-the-box support for friend and global leaderboards on Roblox platform surfaces, designed to drive stronger competition and deeper player engagement.
Please share any feedback with us below. Thank you!
FAQs
Does this replace OrderedDataStore or my existing leaderboard system?
- No. This API does not store scores or rank players. It helps you figure out which friends to look up; you still own storage, ranking, and display.
Can I use this to build global leaderboards?
- Not directly. This API is focused on friends who played this universe. Global leaderboards will come later this year
Can I use this outside of leaderboards?
- Yes. Any feature that benefits from “friends who actually play this game” can use this API.
How should I think about rate limits?
- Treat “ever played” calls as infrequent bootstraps and rely on “since timestamp” calls for ongoing refreshes. Design your system to cache results and avoid refreshing on every frame or every UI open.
What happens if the API is temporarily unavailable?
- You should handle failures gracefully (e.g., show cached or partial data, hide the friends tab) and avoid blocking core gameplay on a single API call.
