The Template's platform service

PlatformService, the Blockout SDK inside the Roblox Template: switching it on, the secret, every call, the shared cache, the Platform tab and the platform command.

Get started

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
        • 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/)
      • 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
        • Config/
          • Features.luauthe platform switch, off by default
          • Feedback.luauthe five categories and their labels, the 2,000-character limit, the per-player limits
      • client/
        • UI/
          • Screens/
            • FeedbackWindow.luauthe Feedback window, opened from its button in Roblox's top bar
      • admin/
        • AdminPanel/
          • Tabs/
            • Platform.luauthe staff Platform tab
            • Feedback.luauthe staff Feedback tab
  • 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
      • 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
    • lib/
      • platform.luauloads the service's files as the place lays them out

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:

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

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

  2. Add it to Studio's Local Secrets

    In Studio, File, Experience Settings, Security: under Local Secrets, add BlockoutApiKey with the key as the value and studio.blockoutgames.com as the domain. Local secrets stay on that computer.

  3. Add it in the Creator Dashboard

    For live servers: Creator Dashboard, the experience, Secrets, Create Secret: name BlockoutApiKey, the key as the value, domain studio.blockoutgames.com (not *).

  4. Allow HTTP Requests

    File, Experience Settings, Security: turn on Allow HTTP Requests, then publish.

  5. Check it

    Join as staff and run the platform command: it should say Key: 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.

Whether the platform service runs in a server. When a server starts, the Loader skips PlatformService if Config/Features.platform is off, and every call answers switched_off. Otherwise the service's init reads the BlockoutApiKey secret once. If the secret is missing, it warns once and every call answers unavailable. If the secret is there, the header is built from it, the feedback remote and the platform command are registered, and calls go to the platform through the shared MemoryStore cache.

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

A server service
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.
staleboolean
true when the platform could not be read and an older answer (at most staleSeconds, 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.platform is 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

401 or 403: 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 429 with no Retry-After or one asking to wait longer than 30 seconds, or still 429 after every try.

platform_down

A 5xx after 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 waitSeconds and 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.

HTTP
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 (games with 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 a rbxthumb:// 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.

  1. This server's copy. A copy younger than the route's freshness is answered at once, with no MemoryStore call.

  2. Claim. Otherwise one atomic UpdateAsync decides: 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.

  3. Wait. A server that already has an older answer serves it at once, flagged stale. Without one, it answers platform_down at once if the lease is an outage's, and otherwise looks again every 0.5 seconds for up to 3 seconds, then answers busy. A lease whose holder died lapses after 10 seconds.

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

  5. Revalidate. A fetch over an older answer that came with an ETag sends it as If-None-Match, whichever server fetched that answer. A 304 downloads no body: the older answer is kept, its freshness starts again for every server, and it counts as "not modified". The platform sends an ETag on 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

RouteFresh for (Config/Platform.freshSeconds)
key1,800 seconds
games60 seconds
game60 seconds
history300 seconds
genres300 seconds
market300 seconds
limiteds300 seconds
analytics600 seconds
breakdowns600 seconds
feedbackList60 seconds
feedbackThemes300 seconds
keyUsage300 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):

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

  2. The remote feedback.requestSubmit checks 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.

  3. 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).

  4. The server sends it with PlatformService.sendFeedback. The client never sends the player id, the place or the version.

  5. The player reads "Thanks! Your feedback was sent.", and feedback_sent is 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 with platform.

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.

Feedback from the window to the platform. The player's client sends the category and the text on the feedback.requestSubmit remote; the remote guard drops anything malformed. The server checks the text's length in characters and the player's limits, then posts the feedback to the platform with the player id, place and version filled in and one idempotency key for every retry. The platform answers 202 with a receipt, and the server tells the player it was sent and logs feedback_sent with the category only.
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:

text
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: none

It 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

SymptomCause and fix
[Http] The secret "BlockoutApiKey" is not setNo 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
unauthorizedThe key was rotated or revoked, or the game left the catalog; update the secret
rate_limitedSomething else uses the same key, or the game asks for many distinct queries; ask fewer, or longer freshSeconds
Shared cache: shows an errorMemoryStore 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 forbiddenThe 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