@0xlimo/platform
Partly liveA typed client for the 0x API (sign-in, lobbies, leaderboards, stats, cloud saves, plays), plus the launcher bridge and server-side entitlement checks.
The 0x backend speaks Steamworks semantics over HTTP. @0xlimo/platform is a thin client for it:
each call is one fetch with a bearer token. A rotating refresh token is kept in storage,
which is localStorage by default in a browser. The package has three entry points:
| Import | Runs in | For |
|---|---|---|
@0xlimo/platform | browser or Node 18+ | createPlatform(): sign-in, me, lobbies, leaderboards, stats and achievements, cloud saves, plays. Also siteApi() and findAppid(). |
@0xlimo/platform/launcher | a page inside the 0x launcher | createLauncher(): talks to the launcher over postMessage. Covers subscriptions and play tickets. The game never sees the player's token. |
@0xlimo/platform/server | your game server (Node 18+) | checkTicket(), hasEntitlement() and serverEntitlement(): who a player is, and what they hold. |
Registry version: 0.1.1. Typings ship with the package. The generated API reference lists every type and function.
npm install @0xlimo/platform --@0xlimo:registry=https://0x.limo/npm/#Quick start
import { createPlatform, siteApi, findAppid } from "@0xlimo/platform";
const baseUrl = await siteApi(); // the hosting service's API, else https://api.0x.limo
const appid = await findAppid({ baseUrl, id: "my-game" }); // null until the listing is approved
const x1 = createPlatform({ baseUrl, appid });
if (!x1.session) await x1.auth.guest(); // a guest account: plays at once
const me = await x1.me();
await x1.leaderboards.upload("high-score", 4200); // keep_best
const top = await x1.leaderboards.entries("high-score", { start: 1, end: 10 });
await x1.stats.set({ stats: { runs: 12 }, achievements: { FIRST_WIN: true } });
await x1.cloud.write("save/slot1.json", JSON.stringify({ level: 3 }));
const stop = await x1.plays.auto(); // counts the play; not needed inside the launcher#Concepts
#Sessions
auth.guest()(POST /v1/oauth/guest) creates a guest account.auth.password(username, password)uses the OAuth2 password grant (POST /v1/oauth/token).- The session is
{accessToken, refreshToken, expiresAt, steamid, persona, guest}. It is stored underx1.session:<baseUrl>. Passstorage: nullto keep it in memory only. - A token that expires within 30 s is refreshed before a call. A
401is retried once after a refresh. auth.signOut()revokes the refresh token (POST /v1/oauth/revoke).auth.onChange(fn)is called on every change and returns an unsubscribe function.
#App id
Calls under /v1/apps/<appid>/… (lobbies, leaderboards by name, stats, cloud) need appid in
createPlatform. Without it they throw x1: createPlatform({appid}) is needed for this call.
findAppid({baseUrl, id}) looks the app id up by the id in your 0x.config.json, in the
public catalog (GET /v1/catalog). The app id is fixed when the listing is first approved, so a
build does not need the number written into it.
#Hosted sites
siteApi() reads ./x1.json (api, written by the hosting builder). It falls back to
https://api.0x.limo, so the same build works on any 0x service.
#Everything else
x1.request(method, path, {body, binary}) calls any other /v1 endpoint as the signed-in user,
with the same refresh rules. See the REST API for the endpoints.
#Lobbies
const lobby = await x1.lobbies.create({ maxMembers: 8, type: 2 }); // 0 private, 1 friends, 2 public
await x1.lobbies.setData(lobby.id, { map: "dunes", mode: "ctf" });
const { lobbies } = await x1.lobbies.search([{ kind: "string", key: "mode", value: "ctf", cmp: 0 }]);
await x1.lobbies.join(lobbies[0].id);
await x1.lobbies.chat(lobby.id, "gl hf"); // sent hex-encodedFilter kinds are string, numerical, near, slots, count and compatible, as in
ISteamMatchmaking. cmp is the ELobbyComparison value, and 0 means equal. A search
returns only public (type: 2), joinable lobbies of your app, at most 50 by default.
#Inside the launcher: @0xlimo/platform/launcher
A game opened from the 0x launcher (https://0x.limo/play/<game>) runs in an iframe.
createLauncher() sends {x1: "req", id, type, …} to window.parent. It accepts answers only
from the parent, and only from https://0x.limo or the page's own origin (change this with
launcherOrigins).
import { createLauncher } from "@0xlimo/platform/launcher";
const launcher = createLauncher();
if (launcher.embedded) {
const hello = await launcher.hello(); // {launcher: "0x1", version, appid, signedIn}
const ticket = await launcher.playTicket(); // short-lived; send it to your game server
launcher.on("subscription.changed", () => refreshPerks());
}Subscriptions are switched off on 0x.limo
launcher.subscriptions.status(), .has(key) and .subscribe(plan, period) are built and
deployed, but SG_SUBSCRIPTIONS is off, so the backend answers
{"error": "subscriptions are off"}. has() returns false when anything fails, so a game
that checks it keeps working.
subscribe() opens the launcher's confirm dialog and has no timeout, because it waits for the
player. It resolves with {outcome, status}. outcome is one of subscribed,
already_subscribed, canceled, signed_out, insufficient_funds or failed.
Errors are LauncherError with a code:
| code | meaning |
|---|---|
no_launcher | not running inside the 0x launcher (no parent frame) |
timeout | no answer within timeoutMs (10 s by default; 3 s for hello) |
closed | launcher.close() was called while the request was pending |
| anything else | the launcher's own error code, with detail |
#On your server: @0xlimo/platform/server
import { checkTicket } from "@0xlimo/platform/server";
// ticket: from launcher.playTicket() on the page, sent over your own connection
const t = await checkTicket({ api: "https://api.0x.limo", ticket, appid: 4000123, entitlement: "vip" });
if (!t.valid) return reject();
console.log(t.steamid, t.entitlements, t.entitled);import { serverEntitlement } from "@0xlimo/platform/server";
// session: the token from POST /v1/gameservers/logon (ISteamGameServer); your own app only
const r = await serverEntitlement({ api: "https://api.0x.limo", session, steamid, entitlement: "vip" });
if (r.entitled) grantPerks(steamid);checkTicketposts to/v1/subscriptions/check. Withappid, it treats a ticket for another game as invalid (recommended).hasEntitlementreturnscheckTicket(...).entitled === true.serverEntitlementcallsGET /v1/gameservers/entitlement/<steamid>/<key>.- The timeout is 5 s by default (
timeoutMs). - A non-2xx answer throws
EntitlementErrorwithstatusandbody. - Entitlement keys come from subscription plans, so these calls depend on subscriptions being on.
#Errors
| Error | Thrown by | Fields |
|---|---|---|
X1Error | createPlatform calls and findAppid | status (HTTP), body (the parsed JSON, usually {"error": "..."}), path |
Error("x1: sign in first …") | any call before auth.guest() / auth.password() | |
LauncherError | @0xlimo/platform/launcher | code, detail |
EntitlementError | @0xlimo/platform/server | status, body |
The API's status codes, including 429 with Retry-After, are listed in the
REST API section.
