Building a market game

A worked example for a Template game - reading the live players of a list of Roblox games every minute with PlatformService.games and showing them to every player.

Building on the platform

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 BlockoutApiKey secret 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

  1. A server service, PlayersBoardService, splits the list into fixed groups of 40 ids.

  2. 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.

  3. It writes each game's players into a SharedState atom, which the Template syncs to every client.

  4. A client controller shows the atom on a board.

One minute of the market board. Every 60 seconds PlayersBoardService on each server calls PlatformService.games with a group of 40 ids. On the first server to ask, the shared MemoryStore cache has no fresh answer, so that server takes the lease, fetches GET /games?ids from the platform and stores the answer. Every other server finds the fresh answer in MemoryStore and spends no request. Each server writes the players into its SharedState atom, which is synced to its players' clients.

The example adds two files to the Template and changes one:

  • src/
    • core/
      • shared/
        • SharedState.luaugains the marketPlayers atom
    • main/
      • server/
        • Services/
          • PlayersBoardService.luaunew: the groups and the loop
      • client/
        • Controllers/
          • PlayersBoardController.luaunew: the board on each client

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.

src/core/shared/SharedState.luau
-- In the SharedState table:marketPlayers = Charm.atom({} :: {	[string]: { name: string?, ccu: number?, growth1h: number?, lastSnapshotAt: string?, stale: boolean },}),

Step 2: the PlayersBoardService server service

src/main/server/Services/PlayersBoardService.luau
--!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 PlayersBoardService

start() 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.

src/main/client/Controllers/PlayersBoardController.luau
--!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 PlayersBoardController

How many requests a minute the market game uses

  • One games request 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 ccu is 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. Show lastSnapshotAt or 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 ask PlatformService.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