0xDocs 0x.limo

Docs / JavaScript SDK

@0xlimo/platform

Partly live

A 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:

ImportRuns inFor
@0xlimo/platformbrowser or Node 18+createPlatform(): sign-in, me, lobbies, leaderboards, stats and achievements, cloud saves, plays. Also siteApi() and findAppid().
@0xlimo/platform/launchera page inside the 0x launchercreateLauncher(): talks to the launcher over postMessage. Covers subscriptions and play tickets. The game never sees the player's token.
@0xlimo/platform/serveryour 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.

bash
npm install @0xlimo/platform --@0xlimo:registry=https://0x.limo/npm/

#Quick start

js
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 under x1.session:<baseUrl>. Pass storage: null to keep it in memory only.
  • A token that expires within 30 s is refreshed before a call. A 401 is 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

js
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-encoded

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

js
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:

codemeaning
no_launchernot running inside the 0x launcher (no parent frame)
timeoutno answer within timeoutMs (10 s by default; 3 s for hello)
closedlauncher.close() was called while the request was pending
anything elsethe launcher's own error code, with detail

#On your server: @0xlimo/platform/server

js
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);
  • checkTicket posts to /v1/subscriptions/check. With appid, it treats a ticket for another game as invalid (recommended).
  • hasEntitlement returns checkTicket(...).entitled === true.
  • serverEntitlement calls GET /v1/gameservers/entitlement/<steamid>/<key>.
  • The timeout is 5 s by default (timeoutMs).
  • A non-2xx answer throws EntitlementError with status and body.
  • Entitlement keys come from subscription plans, so these calls depend on subscriptions being on.

#Errors

ErrorThrown byFields
X1ErrorcreatePlatform calls and findAppidstatus (HTTP), body (the parsed JSON, usually {"error": "..."}), path
Error("x1: sign in first …")any call before auth.guest() / auth.password()
LauncherError@0xlimo/platform/launchercode, detail
EntitlementError@0xlimo/platform/serverstatus, body

The API's status codes, including 429 with Retry-After, are listed in the REST API section.