This example builds the core of a market game on the Blockout Roblox Template: a board that shows how many people are playing each of a list of Roblox games right now, refreshed every minute, for every player in every server. It uses only PlatformService.games({ ids = … }), the Template's SharedState and Charm, so it costs the game's key one request a minute per 40 games, whatever the number of servers.
What the market game example needs first
The platform switched on and the
BlockoutApiKeysecret set, as on The Template's platform service.The universe ids of the games to show (a game's universe id, not its place id; the panel's game page address
/games/<id>carries it). Every one must be tracked by the platform: an untracked id is simply absent from the answer. A studio owner starts tracking a game by opening its page in the panel (/games/<universe id>).
How the market game reads players every minute
A server service,
PlayersBoardService, splits the list into fixed groups of 40 ids.Every 60 seconds it calls
PlatformService.games({ ids = group })for each group. The platform service answers from its shared MemoryStore cache, so only one server of the game asks the platform per group per minute; every other server reads that answer.It writes each game's players into a
SharedStateatom, which the Template syncs to every client.A client controller shows the atom on a board.
The example adds two files to the Template and changes one:
- src/
- core/
- shared/
- SharedState.luaugains the marketPlayers atom
- shared/
- main/
- server/
- Services/
- PlayersBoardService.luaunew: the groups and the loop
- Services/
- client/
- Controllers/
- PlayersBoardController.luaunew: the board on each client
- Controllers/
- server/
- core/
The board itself is a ScreenGui named PlayersBoard with a TextLabel named Text, in StarterGui.
Step 1: add the board to SharedState
Add one atom to src/core/shared/SharedState.luau. Keys are universe ids as text, as every public map in SharedState is.
-- In the SharedState table:marketPlayers = Charm.atom({} :: { [string]: { name: string?, ccu: number?, growth1h: number?, lastSnapshotAt: string?, stale: boolean },}),Step 2: the PlayersBoardService server service
--!strictlocal ReplicatedStorage = game:GetService("ReplicatedStorage")local SharedState = require(ReplicatedStorage.Shared.SharedState)local PlatformService = require(script.Parent.Parent.Parent.Services.PlatformService)-- The games on the board, by universe id (not place id). Keep the order fixed: it is part-- of the cache key. These ids are placeholders: put your own.local BOARD: { number } = { 1001, 1002, 1003 }-- About 40 summaries stay under the 30,000 bytes the shared cache holds per answer.local GROUP_SIZE = 40local EVERY_SECONDS = 60local PlayersBoardService = {}-- Skipped by the Loader while Config/Features.platform is off.PlayersBoardService.feature = "platform"local groups: { { number } } = {}for index = 1, #BOARD, GROUP_SIZE do table.insert(groups, table.move(BOARD, index, math.min(index + GROUP_SIZE - 1, #BOARD), 1, {}))endlocal function refresh() -- Start from the last board, so a group that fails keeps its last numbers. local board = table.clone(SharedState.marketPlayers()) for _, ids in groups do local result = PlatformService.games({ ids = ids }) if not result.ok then warn(`[PlayersBoard] {result.reason}: {result.detail or ""}`) continue end for _, item in result.value.value.items do board[tostring(item.id)] = { name = item.name, ccu = item.ccu, -- nil when unknown, never 0 growth1h = item.growth1h, -- 0.5 is +50% in the last hour lastSnapshotAt = item.lastSnapshotAt, stale = result.value.stale, } end end SharedState.marketPlayers(board)endfunction PlayersBoardService.start() while true do refresh() task.wait(EVERY_SECONDS) endendreturn PlayersBoardServicestart() runs in its own thread, so the loop and the yielding calls are safe there. Never call the platform service from init().
Step 3: show the board on every client
A client controller reads the atom with Charm.effect, which runs again whenever the server writes a new board. This one fills a TextLabel; a Fusion screen would read the same atom with UI/Util/fromCharm.
--!strictlocal Players = game:GetService("Players")local ReplicatedStorage = game:GetService("ReplicatedStorage")local Charm = require(ReplicatedStorage.Packages.Charm)local SharedState = require(ReplicatedStorage.Shared.SharedState)local PlayersBoardController = {}function PlayersBoardController.start() local label = Players.LocalPlayer:WaitForChild("PlayerGui"):WaitForChild("PlayersBoard"):WaitForChild("Text") :: TextLabel Charm.effect(function() local lines: { string } = {} for _, row in SharedState.marketPlayers() do local players = if row.ccu then tostring(row.ccu) else "-" local change = if row.growth1h then string.format("%+.0f%%", row.growth1h * 100) else "" table.insert(lines, `{row.name or "?"} {players} {change}`) end label.Text = table.concat(lines, "\n") end)endreturn PlayersBoardControllerHow many requests a minute the market game uses
One
gamesrequest per group of 40 ids per minute for the whole game: 120 games is 3 requests a minute out of the key's 120, however many servers run.Each server spends one MemoryStore update per group per minute to read the shared answer.
A group over 30,000 bytes (about 35 to 40 games or more) is cached per server only, and then costs one request a minute per server. That is why the list is split.
How fresh the market game's numbers are
A game's
ccuis the players at its last reading,lastSnapshotAt. The collector reads a game every 5 minutes to once a week by its tier: a busy or surging game is read every 5 or 15 minutes, a small one hourly or daily. ShowlastSnapshotAtor hide games read long ago.The platform service keeps each answer for 60 seconds, so the board can trail the platform by up to a minute. Asking more often than once a minute gains nothing.
While the platform cannot be reached, the last answer (up to an hour old) is served with
stale = true; show it as such.
Ideas built on the same read
Rank by movement: sort the items by
growth1h, or askPlatformService.games({ ids = ids, sort = "growth_1h" }).Charts:
PlatformService.history(id, "24h")gives a game's players in 5-minute buckets; it is fresh for 5 minutes in the cache. See GET /developer/v1/games/:id/history.Discovering games:
PlatformService.games({ sort = "breakout", limit = 20 })lists the games breaking out now. See GET /developer/v1/games.
Related: Errors, limits and polling, Reading market data.
Updated