PlatformService is the Blockout Roblox Template's connection to the developer API. The Template is the Blockout SDK: every game built on it gets the platform by switching platform on, with no separate package to install. The service reads market data through one cache every server of the game shares, sends player feedback from the Template's Feedback window, reads the key's own game's analytics and feedback, and feeds the admin panel's staff Platform tab. It sends every request, and reads its secret, through server/Roblox/Http, the one module the Template allows to make HTTP requests. It is a folder module, src/core/server/Services/PlatformService/, and is off by default.
The files of the platform service
- src/
- core/
- server/
- Services/
- PlatformService/
- init.luauthe public calls, the platform switch and init()
- Connection.luauthe key as a Secret, every request through Http (retries, backoff, Retry-After), JSON, the last error
- Reads.luauthe cache every server shares (through MemoryStore) and every read
- Writes.luauplayer feedback and its limits, transfers, studio bans
- Status.luaustatus(), the Platform and Feedback tabs, the platform command
- PlatformService/
- Roblox/
- Http.luauthe one door to outbound HTTP and secrets: budgets, retries, counts
- MemoryStore.luauthe one MemoryStoreService caller
- Config/
- Platform.luaubase URL, secret name, tries and backoff, freshness per route, stale answers, the lease (server only; a game's own values in Overrides/)
- Services/
- shared/
- Rules/
- Platform/
- init.luaure-exports every name of its parts, required as Rules/Platform
- Requests.luaueach route's request and its checks, canonical queries, cache keys
- Responses.luaueach answer's shape, status to reason, retries, Retry-After, the ETag
- Summaries.luauthe own game's analytics, breakdowns, themes and key usage for the tabs
- Cache.luauthe shared entry: claim, cooldown, the lease
- Platform/
- Config/
- Features.luauthe platform switch, off by default
- Feedback.luauthe five categories and their labels, the 2,000-character limit, the per-player limits
- Rules/
- client/
- UI/
- Screens/
- FeedbackWindow.luauthe Feedback window, opened from its button in Roblox's top bar
- Screens/
- UI/
- admin/
- AdminPanel/
- Tabs/
- Platform.luauthe staff Platform tab
- Feedback.luauthe staff Feedback tab
- Tabs/
- AdminPanel/
- server/
- core/
- tests/
- core/
- server/
- Services/
- PlatformService.spec.luauthe service over HttpService, secret and MemoryStore doubles
- PlatformService.feedback.spec.luaufeedback and its limits
- PlatformService.ownGame.spec.luauthe own-game reads, the tabs, the admin output
- Config/
- Platform.spec.luauthe config's limits
- Services/
- shared/
- Rules/
- Platform/
- Requests.spec.luau,Responses.spec.luau, Cache.spec.luau — every rule, without Roblox
- Platform.ownGame.spec.luauthe own-game requests and summaries
- Platform/
- Rules/
- server/
- lib/
- platform.luauloads the service's files as the place lays them out
- core/
The decision behind it is a line in the Template's ARCHITECTURE.md Decisions (one service calls the platform, through a read cache every server shares); the system note is docs/systems/Platform.md in the Template. How the layers fit together: Inside the Template's platform service.
Switching the platform feature on
Set the feature switch in the game's src/core/shared/Config/Overrides/Features.luau:
return { platform = true }While it is off (the default) there is no service, no Feedback window, no Feedback button in the top bar and no platform command, and every PlatformService call answers switched_off.
Setting up the BlockoutApiKey secret
Create the game's key
On the game's Developer tab in the panel, choose Create key and copy it. See Getting a game's API key.
Add it to Studio's Local Secrets
In Studio, File, Experience Settings, Security: under Local Secrets, add
BlockoutApiKeywith the key as the value andstudio.blockoutgames.comas the domain. Local secrets stay on that computer.Add it in the Creator Dashboard
For live servers: Creator Dashboard, the experience, Secrets, Create Secret: name
BlockoutApiKey, the key as the value, domainstudio.blockoutgames.com(not*).Allow HTTP Requests
File, Experience Settings, Security: turn on Allow HTTP Requests, then publish.
Check it
Join as staff and run the
platformcommand: it should sayKey: configured (secret BlockoutApiKey)and name the game.
The secret's name is Config/Platform.secretName. The key is never put in source, config, a place file or a chat. See Keeping a game's key secret.
What happens when the secret is missing
The server prints one warning, from Http: [Http] The secret "BlockoutApiKey" is not set, so the Blockout platform (reads and feedback) is off in this server., followed by where to set it, and every call answers unavailable. The game plays normally. The secret is read once, in the service's init(). When the key is rotated on the platform, update the secret: new servers pick it up, and running servers keep the old key and answer unauthorized until they close.
Calling the platform service from game code
Every call returns a Result and yields (HTTP, MemoryStore, retries), so call it from a service's start() or a task.spawn thread, never from init().
local PlatformService = require(script.Parent.PlatformService)task.spawn(function() local top = PlatformService.games({ sort = "growth_24h", limit = 10, genre = "Simulator" }) if not top.ok then warn(`[Trends] {top.reason}`) -- switched_off, unavailable, bad_query, unauthorized, busy, ... return end for _, game in top.value.value.items do print(game.name, game.ccu) -- unknown values are nil, never 0 endend)From a service in a place folder (src/main/server/Services/), require it as require(script.Parent.Parent.Parent.Services.PlatformService).
The Result and Read every platform call returns
A call answers { ok = true, value = … } or { ok = false, reason = "…", detail = "…" }. A read's value is a Read:
Read
valueany- The platform's answer, checked against the route's shape.
stalebooleantruewhen the platform could not be read and an older answer (at moststaleSeconds, 3,600 s, old) was served.storedAtnumber- When that answer was fetched, as
os.time()seconds.
So a game list is result.value.value.items. A null from the platform is nil in Luau, never 0. Every answer is checked before it is cached or returned: a field of the wrong type, or a required one missing, is bad_answer and never reaches game code. Fields the platform adds later pass through.
The platform service calls
PlatformService.key()
GET /key: the game the key belongs to and its limit, { game = { id, name }, limits = { perMinute } }. Use it to check the key on start. See GET /developer/v1/key.
PlatformService.games(query)
GET /games: a page, { items, total, limit, offset }, of GameSummary items. The query takes q, sort (one of Rules/Platform.sorts), dir (asc or desc), genre, tier, minCcu, maxCcu, maxAgeDays, limit (1 to 100), offset and ids: a list of 1 to 100 universe ids. With ids the platform answers only those games, up to 100 without a limit, whatever their tier unless tier is given; an id it does not track is simply absent. See GET /developer/v1/games.
PlatformService.game(id)
GET /games/:id: one tracked game in full, the summary plus description, maxPlayers, observedPeakCcu, observedPeakAt, avgCcu24h and every other detail field. A game the platform does not track answers not_found. See GET /developer/v1/games/:id.
PlatformService.history(id, range)
GET /games/:id/history: { range, bucketSeconds, points }, points oldest first. range is 6h, 24h, 7d, 30d or all, and is required. See GET /developer/v1/games/:id/history.
PlatformService.genres()
GET /genres: a list of { genre, games, ccu }. See GET /developer/v1/genres.
PlatformService.market(range)
GET /market, with an optional range (24h, 7d or 30d; the platform's default is 7d). The decoded overview is returned unchecked beyond being an object. See GET /developer/v1/market.
PlatformService.sendFeedback(player, category, text)
POST /feedback: answers the receipt, { id, receivedAt }. The server fills in playerId (the player's UserId), placeId (game.PlaceId) and serverVersion (Config/Game.version), with one idempotency key from HttpService:GenerateGUID for every retry, so the platform stores it once. Feedback is never cached. This call is not rate limited: the Feedback window's remote is. Game code that calls it directly must limit players itself. See POST /developer/v1/feedback.
PlatformService.analytics(range)
GET /game/analytics: the key's own game's owned analytics over 30d (the
default) or 90d, the same answer the panel's metrics for that game give: range, analytics
(status, detail, lastAttemptAt, lastSuccessAt), series (one per metric and breakdown,
points oldest first by UTC day, value nil when unknown, never 0) and unavailable.
analytics.status is not-configured, pending, ok, unauthorized, forbidden or error.
There is no id: the key names the game. See The key's own
game.
PlatformService.feedbackList(query)
GET /game/feedback: the key's own game's feedback, newest first: items
(each with id, category, status, text, playerId, placeId, serverVersion, receivedAt,
triagedAt, triagedBy), total, counts by category and status, and hasMore. The query takes
status (new, seen, planned, done, ignored), category, player (a user id: only what
that player sent) and limit (1 to 50; the platform's default is 50). A query with player is kept
on the asking server only, never in the shared MemoryStore cache. The text is written by players: show it to anyone only through Roblox's
text filtering, as the Platform tab does.
PlatformService.limiteds(query)
GET /items/limiteds: Roblox's limited items with their recent average price (rap) and Rolimon's value, demand, trend and projected, hyped and rare flags, stored by the platform every five minutes; nothing asks Roblox. The query takes ids (up to 100, sent sorted so a set in any order is one cache entry), q (words in the name), sort (value, rap or name), dir, limit (1 to 500) and offset. Fresh for five minutes in the shared cache. For a case opening game: read on the server, decide what an item is worth with the value read there, and draw it with rbxthumb://type=Asset&id=<id>&w=150&h=150.
PlatformService.sendTransfer(player, toUniverse, data)
POST /game/transfers: a player's progress, the fields the game chooses (a table with text keys, at most 15 KB as JSON), for another studio game to claim once within 30 days. The target must be in Config/Platform.transferTo; a player may call once every transferCooldownSeconds (30), a server's players together transferPerServerMinute (5), and every server of the game together transferPerGameMinute (30, counted in MemoryStore); a call refused for its data spends no turn. Call it when the player asks to move, never on join. Sending again before the claim replaces the data; after it, the platform refuses (refused, 409). A transfer is a copy: once it answers ok, take the sent fields out of this game's save (or lock them), or the player keeps both.
PlatformService.claimTransfer(player, fromUniverse)
POST /game/transfers/claim: the progress a game in Config/Platform.transferFrom sent for this player, once; not_found when nothing waits (never sent, claimed already, or over 30 days old). The claim key is kept in the server, per player and source game, until the answer is final, so asking again after a lost answer gets the same transfer back. The answer must be this player's, from that game. Another game's server wrote the data: check each field, clamp it, and set or grant once rather than add, then save.
PlatformService.studioBan(request)
POST /game/bans: the studioban admin command's call, a ban in every studio game whose group key happens to allow writing bans (optional: the platform never asks for that permission, and every other game is skipped with the reason). The request is built and checked by Rules/Platform.studioBanRequest before the player is banned in the calling game, so a ban the platform would refuse is never half done. A key may make 20 an hour.
PlatformService.breakdowns(range)
GET /game/breakdowns: the key's own game's daily breakdowns over 30d (the default) or 90d, as
the panel shows them: daily users by platform, country, age group and acquisition source, revenue
and day 1 retention by platform, each with its slices and points by day, and the read's state.
PlatformService.feedbackThemes()
GET /game/feedback/themes: its feedback grouped into themes (by category until text themes are
found) over twelve weeks, each with its statuses and its count per week.
PlatformService.keyUsage()
GET /key/usage: the key's own requests over the last 24 hours and 7 days, by route and outcome,
as the game's Developer tab shows them; usage is null when the platform cannot count just now.
PlatformService.status()
What the platform command shows: whether the key is configured (never the key), the reason it is unavailable, cache hits, misses (and how many of them a 304 answered), stale answers, the shared cache's error and the last error.
The reasons a platform call can fail
- switched_off
Features.platformis off.- unavailable
The secret is missing in this server.
- bad_query
A parameter the API would refuse: an unknown name, a value out of range, more than 100 ids. Nothing is sent.
- unauthorized
401or403: the key is wrong, revoked, or its game left the catalog. Not retried.- not_found
404: the platform does not track that game. Not retried.- rate_limited
A
429with noRetry-Afteror one asking to wait longer than 30 seconds, or still429after every try.- platform_down
A
5xxafter every try.- unreachable
No answer after every try (HTTP off, no network); the detail is Roblox's error.
- refused
Any other
4xx, such as a bad body. Not retried.- bad_answer
Not JSON, or not the route's shape.
- busy
Another server held the entry's lease for all of
waitSecondsand no older answer exists.
A query is checked before anything is sent. One check differs from the API: the Template accepts maxAgeDays = 0, which the API refuses (its minimum is 1), so the call ends as refused. Use 1 or more.
The key's own game
Both routes read the game the key belongs to; there is no id to pass, and no other game's data can be read with the key. They count against the key like every other read, and the Template caches them like the market reads: analytics for 10 minutes, each feedback query for 60 seconds. The platform does not read-cache them itself, so every request the Template does send gets the current answer.
GET https://studio.blockoutgames.com/developer/v1/game/analytics?range=30dGET https://studio.blockoutgames.com/developer/v1/game/feedback?status=new&limit=10Authorization: Bearer bk_live_<the game's key>/game/analytics answers range, analytics, series and unavailable, as described under PlatformService.analytics. /game/feedback answers a page of the game's feedback, as the crew sees it on the Feedback tab.
The staff Platform tab
With platform on, the Template's admin panel has a Platform tab for staff only (a tester, or a player without the admin suite, gets nothing). It shows:
the key's state, the game it belongs to and its limit a minute;
players in the game now (
gameswith the key's own game's id);a 30 days / 90 days switch, which asks again for the other range;
daily users, day 1 and day 7 retention, revenue over the range and revenue per daily user, each with a sparkline of its days, and the analytics status;
every metric of the analytics answer in groups: Players, Retention, Money (with revenue by source), Acquisition, Performance and Safety, and Other for a metric the groups do not name. Each card shows the latest day's value (revenue and ad revenue: the range's total), its day and a sparkline; the platform's reason for a metric it lists as unavailable; and "no data", never 0, for one with no known value;
who plays: each breakdown's largest slices on its latest day, as bars;
the key's requests over 24 hours and 7 days, the limited and failed ones, and its busiest routes;
the cache's counts, the shared cache's state and the last error.
It loads when the tab opens, on Refresh and when the range changes, never on a timer, and every read goes through the shared cache: the tab asks five queries (key, games, analytics and breakdowns for the range, and keyUsage), so it costs a few requests a minute at most however many staff press Refresh, and each range is its own cached query. The default range, the headline metrics and the groups are panelRange, panelMetrics and panelGroups (with panelOther) in Config/Platform.luau; the tab asks with admin.requestPlatform(range), "30d" or "90d". Feedback has its own tab.
The staff Feedback tab
With platform on, the admin panel also has a Feedback tab for staff only. It shows the game's newest 50 pieces of feedback (panelFeedback), narrowed by two dropdowns, a status and a category (all by default). Each piece is a card:
the sender's Roblox headshot, display name and @username, and how long ago they sent it. The names come from Roblox's engine (
UserService:GetUserInfosByUserIdsAsync), asked once per player for the server's life, never from the platform; the headshot is arbxthumb://image the engine loads;their words, filtered by Roblox from the sender for the staff member reading them, and withheld as "(could not be filtered)" when the filter fails or there is no sender, never shown raw;
the category and the status.
Above the cards: how much feedback there is by category and by status, the themes with their latest weekly counts, and where to triage it, the game's Feedback tab on the website. The tab is read only: statuses are set on the website. It asks admin.requestFeedback(status, category): three cached queries (key, feedbackList with the filters, feedbackThemes), on open, on Refresh and when a filter changes.
How the shared MemoryStore cache works
The key allows 120 requests a minute for every server of the game together, so reads go through one cache all servers share: a MemoryStore hash map named BlockoutPlatform (Config/Platform.cacheMapName), one entry per route and canonical query. Parameters are sorted by name and encoded, so { sort, limit } and { limit, sort } share an entry; a key longer than 120 characters is hashed, with the full key kept in the entry and compared.
This server's copy. A copy younger than the route's freshness is answered at once, with no MemoryStore call.
Claim. Otherwise one atomic
UpdateAsyncdecides: a fresh shared answer is copied here and answered; a lease another server holds means wait; otherwise this server takes the lease (10 seconds) and fetches.Wait. A server that already has an older answer serves it at once, flagged stale. Without one, it answers
platform_downat once if the lease is an outage's, and otherwise looks again every 0.5 seconds for up to 3 seconds, then answersbusy. A lease whose holder died lapses after 10 seconds.Fetch. While the request is in flight the fetch renews its own lease every half lease. The answer is checked, stored in the map with the time and its
ETag, kept here and returned. A map entry expires after twice its route's freshness, at least 600 seconds (sharedMinSeconds) and at most 3,600 (staleSeconds). A failed fetch holds the entry so nobody asks the platform for it again meanwhile: an outage for 30 seconds (outageSeconds), serving the older answer flagged stale if there is one; a refusal for 30 seconds (refusalSeconds), which every server answers meanwhile.Revalidate. A fetch over an older answer that came with an
ETagsends it asIf-None-Match, whichever server fetched that answer. A304downloads no body: the older answer is kept, its freshness starts again for every server, and it counts as "not modified". The platform sends anETagon every read, the market's and the key's own game's alike, so every refetch revalidates.
If MemoryStore fails (throttled, or Studio without a published place), the same steps run on this server's own table, so the game keeps working with one fetch per server per interval, and platform shows the MemoryStore error. Every request and MemoryStore call is counted for the staff budgets command.
How fresh the platform service's answers are
| Route | Fresh for (Config/Platform.freshSeconds) |
|---|---|
key | 1,800 seconds |
games | 60 seconds |
game | 60 seconds |
history | 300 seconds |
genres | 300 seconds |
market | 300 seconds |
limiteds | 300 seconds |
analytics | 600 seconds |
breakdowns | 600 seconds |
feedbackList | 60 seconds |
feedbackThemes | 300 seconds |
keyUsage | 300 seconds |
With these, each distinct query costs at most one request a minute (games, game, feedbackList), one every five minutes (history, genres, market, limiteds, feedbackThemes, keyUsage), one every ten (analytics, breakdowns) or one every thirty (key: the game a key belongs to never changes), whatever the number of servers. An answer older than its freshness is fetched again on the next call; one up to 3,600 seconds old (staleSeconds) is served, flagged stale, while the platform cannot be reached. A game's own players figure (ccu) is as of its lastSnapshotAt, which depends on its tier.
Answers over 30,000 bytes are cached per server only
A MemoryStore item holds 32 KB, so an answer longer than 30,000 bytes (Config/Platform.sharedMaxBytes) is kept on the server that fetched it only, and every other server fetches its own. A GameSummary is roughly 800 bytes of JSON, so a page of 100 games is too big to share. With many servers, an unshared query can cost one request a minute per server and run the key out of its 120.
Keep each games call to about 35 to 40 ids and split a longer list into several fixed calls. Pass each list in the same order every time: the Template does not sort ids, so { 1, 2 } and { 2, 1 } are two cache entries, even though the platform answers both the same.
How the platform service retries
Each request is tried up to 3 times (attempts). No answer and a 5xx wait 1 second, then 2 (baseDelaySeconds 1, maxDelaySeconds 8). A 429 waits at least its Retry-After seconds, or gives up as rate_limited when it gives no Retry-After or asks for more than 30 (maxRetryAfterSeconds). No other status is retried. A Retry-After given as an HTTP date is read as absent, and the backoff applies.
How long a read can take in the worst case
Three tries with waits of 1 and 2 seconds after a 5xx or no answer, plus each try's own time
(RequestAsync waits for an answer). A 429 can make each of the two waits as long as 30
seconds, so a call can yield for about a minute before it answers rate_limited. A server waiting
on another's lease gives up after 3 seconds. This is why platform calls belong in start() or a
task.spawn thread, never in code a player is waiting on.
The feedback window and how often a player may send
With the platform on, Roblox's top bar has a Feedback button beside Settings that opens the Feedback window (it is not a menu window; Settings, Feedback and the menu's windows close each other):
The player picks a category (Bug, Idea, Balance, Praise, Other; Idea is sent as
suggestion), types, and presses Send. The counter shows characters out of 2,000 and turns red over. Nothing is sent without a category, for an empty box or over the limit.The remote
feedback.requestSubmitchecks the category and that the text is valid UTF-8 of at most 8,000 bytes. Anything else comes from a modified client and is dropped and reported to the anti-cheat.The server trims the text and counts it in characters (1 to 2,000). Then the player's limits: one every 30 seconds (
shortSeconds) and 10 an hour (hourly), kept per user id for the server's life. Over a limit the player reads "You sent feedback a moment ago. Wait a little and try again." One send per player is in flight at a time, a server's players together send at most 10 a minute (feedbackPerServerMinute), and every server of the game together at most 30 (feedbackPerGameMinute, one MemoryStore count a minute, so at least 60 of the key's 120 requests a minute stay for reads however many servers run; when MemoryStore cannot answer, a server falls back to its own limit).The server sends it with
PlatformService.sendFeedback. The client never sends the player id, the place or the version.The player reads "Thanks! Your feedback was sent.", and
feedback_sentis logged to analytics with the category only. On any failure they read "Your feedback could not be sent right now. Try again later.", and staff see the reason withplatform.
The crew reads the feedback on the game's Feedback tab in the panel, and staff in game on the admin panel's Feedback tab.
The window reads nothing back: it shows no list of the player's own sends, so opening it costs no request; only Send does.
How the per-player limits count
Each limit is a token bucket per user id: one token refilled every 30 seconds, and ten tokens
refilled at ten an hour. A token is spent only once the platform took the feedback (202) or
refused what the player wrote (a 4xx): an outage or a key problem keeps the player's budget. The
buckets live for the server's life, so leaving and rejoining the same server does not refill them;
another server starts the player afresh. Without the secret the window answers "Feedback is not
available right now." and nothing is counted.
The staff platform command
platform (category Server, staff role and up; on the admin console, the ; key) shows the connection without the key:
Key: configured (secret BlockoutApiKey)
Game: Rising Tycoon (1001), 120 requests a minute
Cache: 12 hits, 3 misses (2 not modified), 0 stale answers
Shared cache: working
Last error: noneIt asks GET /key through the cache, and also reports the analytics read (Analytics (30d): ok, 28 series) and the feedback read, or why they could not be read. Without the secret the first line reads Key: missing (…).
Troubleshooting the platform service
| Symptom | Cause and fix |
|---|---|
[Http] The secret "BlockoutApiKey" is not set | No secret in this experience (live) or no local secret (Studio), or a different name |
unreachable with "Http requests are not enabled" | Allow HTTP Requests is off for the experience |
unauthorized | The key was rotated or revoked, or the game left the catalog; update the secret |
rate_limited | Something else uses the same key, or the game asks for many distinct queries; ask fewer, or longer freshSeconds |
Shared cache: shows an error | MemoryStore throttled or unavailable (an unpublished place in Studio); each server caches on its own meanwhile |
| Feedback "could not be sent" | platform shows the reason; nothing is kept until a send succeeds |
Analytics status not-configured or forbidden | The platform has no Open Cloud key for the game's group, or it lacks universe.analytics:read; fixed on the platform |
Related: Building a market game, Errors, limits and polling.
Updated