The SDK is published globally as window.Legion.SDK (the platform was formerly called Legion — the package and namespace keep that name; the product is Boxity). It works two ways automatically:

• Embedded — your game runs in an iframe at bloxity.io/g/<your-slug>. Auth, friends and purchases flow through the portal over postMessage (no extra HTTP).
• Standalone — your game runs on your own domain. The same calls fall back to the Boxity REST API (apiUrl of the told environment) and a login popup window.

You write the same code for both — the SDK detects its environment and routes accordingly.

How it works #

What happens when your game boots (the handshake)

Almost every "why doesn't the SDK work?" question comes down to timing — calling something before the data it needs has arrived. Here is the exact boot sequence when your game is embedded on bloxity.io, so you know precisely when each piece of data is ready:

1. The portal opens your game in an iframe t = 0

   A loading overlay is already covering your game. The portal is waiting to hear from your code.

2. The SDK script loads <script> onload

   window.Legion.SDK now exists. Nothing before this point can touch the SDK, so put your integration code after the script tag (or in its onload).

3. You call Legion.SDK.init() you, once

   The SDK immediately posts a handshake request and an auth request to the portal, then returns. init() is synchronous and returns before the portal answers — at this instant getUser() is still null.

4. Your onUserChanged / settings.listen callbacks fire once immediately microtask

   They fire right away with the current (empty) state: onUserChanged with null, each settings.listen with its default value. This is why you subscribe first and let the callback drive everything — it will fire again with real data.

5. The portal answers with the handshake ~1 round-trip

   One reply carries everything at once: the logged-in user (or null for a guest), the access token, the equipped avatar, the resolved gameSlug, the debug flag, and the current settings. The SDK stores it all and fires your callbacks again — onUserChanged (now with the real user), avatar.onAvatarChanged, and every settings.listen — with the real values.

6. Your game finishes its own loading, you call loadingEnd() you, when ready

   The overlay lifts and the player is in. (See Game lifecycle for the loading-screen rules.)

Standalone (your own domain) is simpler: init() reads a saved token from localStorage, drops it if expired, and calls GET /v1/auth/me to refresh the user. No iframe, no postMessage, no portal. onUserChanged fires with null, then again with the restored user once that request returns (or stays null if there's no valid token).

Install & URLs #

The SDK is a single script — no build step, no npm install required for the browser global.

<!-- Production (minified) -->
<script src="https://sdk.bloxity.io/legion-sdk.min.js"></script>

<!-- Pinned v1 (recommended for production stability) -->
<script src="https://sdk.bloxity.io/v1/legion-sdk.min.js"></script>

<!-- Development (unminified + source map, verbose logging) -->
<script src="https://sdk.bloxity.io/legion-sdk.js"></script>

Quick start #

The smallest working integration — log a user in and react to login state:

<script src="https://sdk.bloxity.io/legion-sdk.min.js"></script>
<script>
  // 1. Initialize once. gameSlug is the slug your game is registered under
  //    on bloxity.io (required for Gems purchases; auto-filled when embedded).
  Legion.SDK.init({ gameSlug: 'my-game' });

  // 2. React to login state. Fires immediately with the current user
  //    (or null), then again on every login / logout.
  Legion.SDK.auth.onUserChanged((user) => {
    if (user) {
      console.log('Hello', user.displayName || user.username);
    } else {
      console.log('Not logged in');
    }
  });

  // 3. Open the login UI (auto-picks modal vs popup) from a button.
  document.getElementById('login').onclick = () => Legion.SDK.auth.showAuthPopup();
</script>

Environments: prod, stage, local #

Boxity runs as three environments. The same game build runs in all of them, and the platform tells the game which one it is in. Your game never works it out for itself.

In the browser

Boxity tells a page its environment in two ways. Pages it serves get a window.BLOXITY_ENV object injected before your code runs. Games embedded in a Boxity page also receive it in the portal handshake. The SDK reads both, so after the script loads, ask the SDK:

const { env, apiUrl, playUrl, portalUrl, staticUrl } = Legion.SDK.environment();
// env: 'prod' | 'stage' | 'local'. Production when nothing was told.

// Embedded games learn it from the handshake, which can land after init:
Legion.SDK.onEnvironmentChanged((e) => reconnectTo(e.playUrl));

The SDK uses the same values for its own calls: login, avatar, Gems, Legion.SDK.api, Legion.SDK.net and party tickets. Code that needs a URL before the SDK has loaded reads window.BLOXITY_ENV through one helper with the prod fallback:

// boxityEnv.js - the only place Boxity URLs come from
const PROD = {
  env: 'prod',
  apiUrl: 'https://api.bloxity.io',
  playUrl: 'https://play.bloxity.io',
  portalUrl: 'https://bloxity.io',
  staticUrl: 'https://static.bloxity.io',
};

export function boxityEnv() {
  if (window.Legion?.SDK?.environment) return window.Legion.SDK.environment();
  const told = window.BLOXITY_ENV;
  return told && told.apiUrl ? told : PROD;
}

// e.g. fetch(`${boxityEnv().apiUrl}/v1/avatar/emotes`)

On your game server

Boxity hosting injects these variables into every deploy of your server:

export const boxity = {
  env: process.env.BLOXITY_ENV || 'prod',
  apiUrl: process.env.BLOXITY_API_URL || 'https://api.bloxity.io',
  matchmakerUrl: process.env.BLOXITY_MATCHMAKER_URL || 'https://play.bloxity.io',
  portalUrl: process.env.BLOXITY_PORTAL_URL || 'https://bloxity.io',
  staticUrl: process.env.BLOXITY_STATIC_URL || 'https://static.bloxity.io',
};
// e.g. POST `${boxity.apiUrl}/v1/auth/game-token/verify`

Local development

• Inside the local portal (http://localhost:3000/g/<slug>): nothing to do. The portal sends env: 'local' in the handshake.
• Standalone (your dev server on its own): tell the page itself, before the game's code runs. One line in index.html:

<script>window.BLOXITY_ENV = { env: 'local', apiUrl: 'http://localhost:4000', playUrl: 'http://localhost:2567', portalUrl: 'http://localhost:3000', staticUrl: 'https://static.bloxity.io' };</script>

With Vite, keep that tag out of production builds by injecting it only from the dev server:

// vite.config.js
const LOCAL_ENV = { env: 'local', apiUrl: 'http://localhost:4000', playUrl: 'http://localhost:2567', portalUrl: 'http://localhost:3000', staticUrl: 'https://static.bloxity.io' };

export default {
  plugins: [{
    name: 'boxity-local-env',
    apply: 'serve',
    transformIndexHtml: () => [{ tag: 'script', children: `window.BLOXITY_ENV = ${JSON.stringify(LOCAL_ENV)}`, injectTo: 'head-prepend' }],
  }],
};

Your local server reads the same BLOXITY_* variables from its own .env, e.g. BLOXITY_ENV=local, BLOXITY_API_URL=http://localhost:4000.

Release flow: one build, both platforms

No extra branch. Your branches mean what they always did, and every push goes to both platforms:

• main → deploys the same build to prod and, when your repo has a stage token, to stage as well. The two deploys are independent: a staging failure never blocks or undoes prod.
• dev → your playtest channel on prod (<game>.dev.play.bloxity.io) and, with a stage token, on stage (<game>.dev.play.stage.bloxity.io).
• The Run workflow button deploys any branch to the platform you pick, e.g. to try a change on stage before it reaches players.

Staging is opt-in. Each environment has its own hosting API and its own deploy token: create the prod token on hosting.bloxity.io (secret LEGION_DEPLOY_TOKEN) and, if you want your game on stage, a stage token on hosting.stage.bloxity.io (secret LEGION_DEPLOY_TOKEN_STAGE). A token from one environment never works on the other. Each environment lists only the games deployed to it.

# .github/workflows/deploy.yml
on:
  push:
    branches: [main, dev]
  workflow_dispatch:
    inputs:
      target: { type: choice, options: [staging, prod], default: staging }

jobs:
  targets:
    runs-on: ubuntu-latest
    outputs: { list: ${{ steps.t.outputs.list }} }
    steps:
      - id: t
        env: { HAS_STAGE_TOKEN: ${{ secrets.LEGION_DEPLOY_TOKEN_STAGE != '' }} }
        run: |
          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then echo 'list=["${{ inputs.target }}"]' >> "$GITHUB_OUTPUT"
          elif [ "$HAS_STAGE_TOKEN" != "true" ]; then echo 'list=["prod"]' >> "$GITHUB_OUTPUT"
          else echo 'list=["prod","staging"]' >> "$GITHUB_OUTPUT"; fi

  deploy:
    needs: targets
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false   # staging can never take prod down with it
      matrix: { target: ${{ fromJSON(needs.targets.outputs.list) }} }
    env:
      BLOXITY_API_URL: ${{ matrix.target == 'staging' && 'https://api.stage.bloxity.io' || 'https://api.bloxity.io' }}
      BLOXITY_DEPLOY_TOKEN: ${{ secrets[matrix.target == 'staging' && 'LEGION_DEPLOY_TOKEN_STAGE' || 'LEGION_DEPLOY_TOKEN'] }}
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build   # one build: no environment baked in
      - run: npm run deploy             # your deploy script reads BLOXITY_API_URL + BLOXITY_DEPLOY_TOKEN

Getting your game onto stage

Stage is a separate platform with its own accounts, hosting whitelist and catalog, so a game joins it once:

1. Create an account on https://stage.bloxity.io (your prod account does not exist there) and ask the Boxity team to enable hosting for it on stage.
2. On https://hosting.stage.bloxity.io, create your game with the same game id it has on prod. Copy the deploy token it shows.
3. Add it to your repo as the secret LEGION_DEPLOY_TOKEN_STAGE. Keep LEGION_DEPLOY_TOKEN for prod; never swap them.
4. Push. With the workflow above, the same build now ships to both platforms. Your game is playable at https://<game>.play.stage.bloxity.io right away.
5. Ask the Boxity team to list it on stage. Each environment lists only the games deployed to it, and a game appears on stage.bloxity.io once its card is added there.

Build with the Boxity MCP #

Connect the Boxity MCP server to your coding agent (Claude Code, Codex, Cursor, Gemini CLI) and build Boxity games from it. Nothing to install: the server is hosted at https://mcp.bloxity.io/mcp. The live preview runs on Boxity — you never run the game locally.

Connect

# Claude Code — then run /mcp, pick boxity, choose Authenticate, sign in and click Allow
claude mcp add --transport http --scope user boxity https://mcp.bloxity.io/mcp

Other agents: add the same URL as a remote (HTTP) MCP server and sign in when asked. Agents without OAuth can use a personal token from bloxity.io/create as Authorization: Bearer <token>. Connected agents are listed (and can be disconnected) in Settings → Connected agents.

The loop

1. Start: ask your agent to create_project (a new game from the SDK starter, with every SDK feature already wired) or clone_game (one of your games, or one marked remixable).
2. Code: the agent git clones the returned remote and edits locally.
3. Preview: git push origin HEAD:dev rebuilds the live preview in seconds at bloxity.io/create/<slug> — inside the real Boxity player, with your avatar. Only the dev branch can be pushed; game-server changes take a few minutes.
4. Share: get_share_link gives a link anyone can play before publishing; rotate it any time.
5. Check: audit_sdk checks every SDK feature that fits the game (required to publish); integrate_sdk returns exact, project-specific fixes for anything missing.
6. Publish: publish_game. Accounts with creator access publish at once; everyone else is reviewed by the Boxity team first.

⚡ Integrate in one AI prompt

Copy a prompt below and paste it into your AI coding agent (Claude Code, Cursor, etc.) inside your game's repo. Each prompt is fully self-contained — it tells the agent the entire SDK surface needed to wire up Boxity end-to-end.

HTML5 / JavaScript browser global

Everything below is available on the global Legion.SDK after the script loads. Call Legion.SDK.init() once before using any namespace.

Top-level namespaces

Authentication #

The SDK manages an access token (JWT) and the current user. User objects are never cached — only the token is persisted (localStorage["legion_token"]) and fresh user data is re-fetched on load. The golden rule of auth here: you never poll for the user — you subscribe with onUserChanged and let it drive your UI. It fires once immediately with the current state and again on every login/logout, so a single subscription is your complete auth state machine.

Add login in five steps

1. Initialize once, on load

   Legion.SDK.init({ gameSlug: 'my-game' }).

2. Subscribe to onUserChanged — your single source of truth right after init
   javascriptCopy

   Legion.SDK.auth.onUserChanged((user) => {
     if (user) showLoggedIn(user);   // render name/pfp, load friends + balance
     else     showLoginButton();     // show a "Log in" button
   });

3. Wire your "Log in" button to showAuthPopup() on click

   loginBtn.onclick = () => Legion.SDK.auth.showAuthPopup();. You don't need its return value — the login flow ends by firing onUserChanged, which your step-2 handler already catches.

4. Wire "Log out" to logout() on click

   Legion.SDK.auth.logout() clears the token and fires onUserChanged(null) — again, your handler does the rest.

5. (If you have your own backend) verify the identity server-side when user arrives

   Inside the user branch of step 2, call authenticateWithServer(yourUrl) (see below) and use the session it returns.

Every function in this namespace

Quick reference — the whole namespace in one block:

// Current user object, or null
const user = Legion.SDK.auth.getUser();

// Access token (JWT) for your own backend, or null. Auto-checked for expiry.
const token = Legion.SDK.auth.getToken();

const loggedIn = Legion.SDK.auth.isLoggedIn();

// Show login UI — auto-detects the best method:
//   embedded  -> in-game modal overlay   (showAuthModal)
//   standalone-> 500x600 popup window    (showAuthWindow)
const u = await Legion.SDK.auth.showAuthPopup();

// Force a specific method if you need to:
await Legion.SDK.auth.showAuthModal();   // only works embedded in bloxity.io/g/[slug]
await Legion.SDK.auth.showAuthWindow();  // popup, for standalone domains

Legion.SDK.auth.logout();

// Subscribe to login/logout. Fires immediately with current state. Returns unsubscribe.
const off = Legion.SDK.auth.onUserChanged((user) => { /* ... */ });

Authenticate with your own game server

If your game has its own backend, validate the Boxity identity server-side. The SDK POSTs { token, user } to your endpoint; you verify the JWT and return your own session.

// SDK sends:  POST https://yourgame.com/api/legion-auth
//   Content-Type: application/json
//   { "token": "<bloxity JWT>", "user": { _id, username, ... } }
const session = await Legion.SDK.auth.authenticateWithServer(
  'https://yourgame.com/api/legion-auth'
);
// returns your server's JSON response, or null on failure

Debugging

Legion.SDK.auth.enableDebug();        // verbose console logging (standalone games)
const d = Legion.SDK.auth.diagnose();    // { isLoggedIn, hasToken, tokenLength, tokenPreview,
                                          //   isEmbedded, isStandalone, storedAuth }

User & avatar data #

The LegionUser returned by getUser():

The avatar object (all fields optional). '-1' / null mean nothing equipped / default mesh:

{
  "hatId":   "6602f1...",  // ObjectId hex, or null = no hat
  "backId":  "6612a0...",  // or null = no back item
  "skinId":  "3",         // skin texture id; defaults to "-1"
  "headId":  "...",       // body-part mesh ids; undefined = default mesh
  "armLId":  "...", "armRId": "...",
  "legLId":  "...", "legRId": "...",
  "torsoId": "...",
  "hairId":  "...",       // hair, worn together with a hat; "-1" = none
  "maskId":  "...",       // mask / glasses / face props; "-1" = none
  "neckId":  "...", "chestId": "...",   // accessories; "-1" = none
  "waistId": "...", "handId":  "...",
  "shoesId": "...",                          // worn as a pair on both feet
  "faceId":  "...", "pantsId": "...",   // drawn on the skin; use getSkinTextureUrl()
  "shirtId": "...",                          // drawn on the skin; use getSkinTextureUrl()
  "proportions": {        // body sliders; every value defaults to 1.0
    "height": 1, "shoulderWidth": 1, "armLength": 1, "legOffsetX": 1,
    "torsoScaleX": 1, "neckHeight": 1, "headScale": 1
  }
}

Guests (signed-out players)

Not everyone logs in — but you should never show an anonymous "Player 1". When getUser() is null, Legion.SDK.auth.getGuest() gives the signed-out player a stable, friendly identity: a Boxity-generated name (e.g. "Comet42") and a derived profile picture. The name is minted once and saved to localStorage, so the same browser keeps the same guest name across sessions.

// One line that ALWAYS gives you someone to display:
const player = Legion.SDK.auth.getUser() || Legion.SDK.auth.getGuest();
nameLabel.textContent = player.username;    // "coolplayer42"  or  "Comet42"
avatarImg.src      = player.pfp;         // real PFP or the guest's derived PFP

// Distinguish the two if you need to (e.g. gate a feature behind login):
if (player.isGuest) promptLoginForRankedMode();

Avatar / cosmetics #

A player's Boxity avatar is a set of equipped item IDs — a hat, a back item, a skin texture, and per-body-part meshes — plus body proportions (height, arm length, etc.). Your job as a game is to read those IDs, load the matching meshes/textures from the CDN, and re-load them when the player changes something so their character looks the same in your game as it does on their profile. Everything here is read-mostly; the portal owns buying and (in standalone mode) the SDK can show a customizer.

Show the player's avatar — the recipe

1. Read the equipped IDs after login/handshake

   const eq = Legion.SDK.avatar.getEquipped(); — gives you every slot at once.

2. Turn each ID into a CDN URL, skipping empty slots per slot

   An ID of '-1', '', 'undefined' or null means "nothing equipped — use the default mesh baked into player.glb". Only build a URL for real IDs. Base is {staticUrl}/avatars from Legion.SDK.environment(); the exact patterns are in CDN asset URLs.

   javascriptCopy

   const CDN = Legion.SDK.environment().staticUrl + '/avatars';
   const real = (id) => id && !['-1', 'undefined'].includes(id);
   
   if (real(eq.hatId)) loadMesh(`${CDN}/items/hats/${eq.hatId}.obj`,
                                `${CDN}/textures/hats/${eq.hatId}.png`);
   if (real(eq.hairId)) loadMesh(`${CDN}/items/hats/${eq.hairId}.obj`,   // hair shares the hat folders and anchor
                                 `${CDN}/textures/hats/${eq.hairId}.png`);
   // Skin with any worn face / pants already drawn on it
   loadSkin(Legion.SDK.avatar.getSkinTextureUrl());

   Neck, chest, waist and hand accessories load the same way from /items/{neck|chest|waist|hand}/{id}.obj; where to attach each one is in CDN asset URLs.

3. Subscribe so the character updates live once, at startup

   onAvatarChanged fires whenever the player equips/unequips (in the portal or the in-game customizer); onProportionsChanged fires on body-slider changes. Re-run your load/rescale logic inside them so the change shows up without a reload.

Every function in this namespace

Quick reference — every call in one place:

// All slots at once
const eq = Legion.SDK.avatar.getEquipped();
// { hatId, backId, skinId, headId, armLId, armRId, legLId, legRId, torsoId,
//   hairId, maskId, neckId, chestId, waistId, handId, shoesId, faceId, pantsId, shirtId }

// Individual getters
Legion.SDK.avatar.getHatId();   // string | undefined
Legion.SDK.avatar.getBackId();
Legion.SDK.avatar.getSkinId();  // string (default "-1")
Legion.SDK.avatar.getHeadId();  // + getArmLId/getArmRId/getLegLId/getLegRId/getTorsoId
Legion.SDK.avatar.getHairId();  // string | undefined
Legion.SDK.avatar.getSkinTextureUrl();  // skin + face + pants, ready to load

// Body proportions (all default to 1.0)
const p = Legion.SDK.avatar.getProportions();

// Set body proportions (partial merge, clamped, persists to the avatar). Ranges:
//   height 0.5–1.6 · shoulderWidth 0.5–1.5 · armLength 0.05–3 · legOffsetX -0.7–5
//   torsoScaleX 0.3–2 · neckHeight 0.94–1.2 · headScale 0.3–2.6
await Legion.SDK.avatar.setProportions({ height: 1.3, headScale: 1.6, armLength: 0.8 });
await Legion.SDK.avatar.resetProportions();  // back to defaults

// React to changes made in the portal customizer (or your own setProportions)
Legion.SDK.avatar.onAvatarChanged((eq) => updateCharacter(eq));
Legion.SDK.avatar.onProportionsChanged((p) => rescaleRig(p));

// In-game customizer window. Embedded → portal customizer. Standalone → full
// catalog with in-window Gems buying + top-up. Equips flow back via onAvatarChanged.
Legion.SDK.avatar.showCustomizer();
Legion.SDK.avatar.hideCustomizer();
Legion.SDK.avatar.toggleCustomizer();
Legion.SDK.avatar.isCustomizerOpen();   // boolean

Friends & social #

The social namespace lets your game show the player's Boxity friends (with live presence), let them invite friends into the exact room they're in, and send friend requests. When embedded, all of this routes through the portal over postMessage (no extra HTTP and no token exposed to the page); standalone, it falls back to the REST API.

Quick reference — every call in one place:

// Friends with live presence
const friends = await Legion.SDK.social.getFriends();
friends.forEach(f => {
  console.log(f.username, f.presence.status);  // 'online' | 'in-game' | 'away' | 'offline'
  if (f.presence.currentGame) console.log('Playing', f.presence.gameName);
});

// Invite a friend into YOUR current room. Set the room first!
Legion.SDK.game.updateRoom('lobby-123');
const ok = await Legion.SDK.social.inviteFriend(friends[0]._id);

// A shareable link that drops a friend straight into your room/party.
// Behaviour depends on where the game is running - no config needed either way:
//  - Embedded in the Boxity portal: links INTO the portal, which loads your
//    game and joins the room -> https://bloxity.io/g/my-game?roomId=lobby-123
//  - Standalone (game opened directly on its own host): links back to THIS
//    host's current URL (auto-detected) -> https://my-game.play.bloxity.io?roomId=lobby-123
// Pass { baseUrl } to force the portal-style link even when standalone.
const link = Legion.SDK.social.getInviteFriendsLink();

// Send a friend request
const r = await Legion.SDK.social.sendFriendRequest(userId);
// { success: true, status: 'accepted' | 'pending' }  — or { success:false, error }

A LegionFriend is { _id, username, displayName?, pfp?, avatar?, presence }, where presence is { status, lastSeen?, currentGame?, currentRoom?, currentParty?, gameSlug?, gameName? }.

Synced settings #

Players change settings in the Boxity portal's in-game pause menu (volume, graphics quality, sensitivity…), and the SDK pushes those values into your game. Every value is a string — "80", "High", "true" — so parse as needed. You don't build any settings UI; you just listen for the keys you support and apply them.

Wire up settings in three steps

1. Listen for each key you support right after init

   One listen() per setting. The callback fires immediately with the current value (a default until the portal's real value lands), then again on every change. Registering also un-greys the control in the menu.

2. Apply the value — remember it's a string in the callback

   parseInt(v,10)/100 for volumes, string-compare === 'true' for toggles, a switch for graphics_quality.

3. Call triggerAll() once your systems exist after load

   This re-fires every listener with the current value, guaranteeing your audio, graphics, etc. all start in sync with the player's saved settings even if they were created after the first push arrived.

Quick reference — every call in one place:

// Listen for a key. Fires immediately with the current value, then on change.
// Registering a listener also tells the portal to SHOW that control.
Legion.SDK.settings.listen('master_volume', (v) => {
  audio.volume = parseInt(v, 10) / 100;     // "0".."100"
});
Legion.SDK.settings.listen('graphics_quality', applyQuality);  // "Low"|"Medium"|"High"|"Ultra"

Legion.SDK.settings.get('show_fps');     // "true" | "false"  ('' if unknown)
Legion.SDK.settings.getAll();          // { master_volume: "80", ... }
Legion.SDK.settings.onChanged((all) => {});  // any-change subscription
Legion.SDK.settings.triggerAll();      // re-fire every listener with current values (call on load)
Legion.SDK.settings.refresh();          // ask the portal to re-send (after reconnect)

Standard keys (full table in Reference → Settings keys): master_volume, music_volume, graphics_quality, show_fps, camera_sensitivity, enable_chat, fullscreen, background_transparency.

Game lifecycle & rooms #

The Legion.SDK.game namespace is how your game talks to the portal about what it's doing: when it has finished loading, when a match starts, and which room the player is in. The portal uses these signals to dismiss the loading screen, record analytics, and let friends join the player. Every call here is a one-way postMessage to the portal — they only do something when your game is embedded on bloxity.io (inside the iframe). On your own domain they are harmless no-ops, so it is always safe to call them.

The loading screen & loadingEnd() — read this first

This is the single most-misunderstood part of the SDK, so here is exactly how it works. The moment a player opens your game at bloxity.io/g/<slug>, the portal draws a full-screen loading overlay on top of your game's iframe (spinner + your game art). Your game is already running underneath — the player just can't see it yet. That overlay stays up until it is dismissed. There are two ways it can be dismissed, and which one applies depends on a single checkbox on your game's developer page: "LoadingEnd Support".

1. Portal opens your game and shows the loading overlay automatic

   Nothing for you to do — the overlay is up from the first millisecond, covering the iframe while your assets download and your first frame renders.

2. You report progress with loadingStep() optional, repeat

   Each call updates the small line of text at the bottom of the overlay ("Loading world…", "Connecting…"). Purely cosmetic, but it tells the player something is happening. Call it as many times as you like while loading.

3. You call loadingEnd() exactly once when the game is ready after first frame

   This tells the portal "I'm done — take the overlay down." The overlay disappears and the player sees your game. This is also the moment the portal records that the game successfully loaded (a one-time POST /v1/games/<slug>/loaded analytics ping).

The full truth table — find your row:

Every function in this namespace

Quick reference — every call in one place:

// Loading screen (portal shows your step text)
Legion.SDK.game.loadingStep('Loading world…');
Legion.SDK.game.loadingEnd();          // dismiss the loading screen

// Analytics / state
Legion.SDK.game.gameplayStart();
Legion.SDK.game.gameplayEnd();

// Joinable presence — friends can join this room/party
Legion.SDK.game.updateRoom('match-456');              // in a room
Legion.SDK.game.updateRoom('match-456', 'party-789'); // with a party (squad games)
Legion.SDK.game.updateRoom('');                       // in menu / not joinable

// Friend-join toasts — call from your netcode's player-join handlers
Legion.SDK.game.playerJoined(p.username);  // "X joined you" if they're a friend
Legion.SDK.game.playerInRoom(p.username);  // "you joined X's lobby" for players already there

Open Rooms on your game page

Every Boxity game page can list your game's live rooms under Open Rooms, with player counts and a Join button. It appears on every page layout, and it stays hidden while your game has no rooms. Join opens your game with ?roomId=<id>, the same parameter friend invites use, so read roomId at launch and join that room, falling back to normal matchmaking when it is gone or full.

Player events #

The portal's menu and chat can trigger actions inside your game — resetting the character, relaying a chat message, releasing the mouse. Your game receives these through one subscription, Legion.SDK.player.onEvent, and switches on the event name.

const off = Legion.SDK.player.onEvent((event, data) => {
  switch (event) {
    case 'respawn_request':      respawnPlayer(); break;        // "Reset Character" in menu — no data
    case 'chat_message_sent':    showChat(data); break;       // data = message string
    case 'pointer_lock_changed': setLocked(data); break;      // data = boolean
  }
});

You can also open the portal's pause menu yourself (e.g. from your ESC handler):

document.addEventListener('keydown', (e) => {
  if (e.key === 'Escape') Legion.SDK.portal.showMenu(true);  // true = re-lock pointer on Resume
});

Emotes #

Boxity owns the emote picker. The button in the in-game overlay, the wheel, ownership, prices, purchases and the rendered thumbnails are all rendered by the portal — your game never builds an emote menu. It registers once, then receives a single event: play this emote.

The button only appears over games that have registered, so nothing changes for your players until you opt in, and a player can never be shown a control your game would ignore.

Receiving the emote

The pick arrives through the same player.onEvent subscription every other portal-to-game event uses. data is the emote's catalogue id.

// 1. Opt in, once the SDK is ready. Calling before init() resolves is a
//    silent no-op - Legion.SDK does not exist yet.
await Legion.SDK.init({ gameSlug: 'your-slug' });
Legion.SDK.game.registerFeature('emotes');

// 2. Listen.
Legion.SDK.player.onEvent((event, data) => {
  if (event === 'play_emote') playEmote(data); // data = emote id, a string
});

Playing it

How you implement playEmote(id) depends on your character rig.

If your game has its own emote animations, fetch the catalogue once and map by name. Simple, but an emote added to Boxity later will not appear in your game until you add a mapping.

const { emotes } = await (await fetch(`${Legion.SDK.environment().apiUrl}/v1/avatar/emotes`)).json();
const byId = new Map(emotes.map(e => [e.id, e]));

function playEmote(id) {
  const emote = byId.get(id);
  if (emote) myAnimator.play(myClipFor(emote.name));
}

If your game uses the standard Boxity avatar (player.glb), the clips apply directly and every emote works automatically, including ones added after your game ships. This is the option that scales.

Each emote carries a clip:

{
  "len": 1.4,           // seconds
  "loop": true,
  "tracks": {
    // bone: [[timeSec, xDeg, yDeg, zDeg], ...]
    "ArmR_Offset": [[0, -60, 0, -10], [0.25, -144, 0, -16], [1.4, -60, 0, -10]]
  }
}

• values are degrees, and are deltas over the bind pose, not absolute
• euler order is XYZ, right-multiplied onto the bone's bind quaternion
• ease between keys with smoothstep: s = s * s * (3 - 2 * s)
• clamp outside the key range; loop wraps on time % len
• an unknown bone name is ignored, never an error

function sampleTrack(keys, t) {
  if (t <= keys[0][0]) return keys[0].slice(1);
  const last = keys[keys.length - 1];
  if (t >= last[0]) return last.slice(1);
  for (let i = 0; i < keys.length - 1; i++) {
    const a = keys[i], b = keys[i + 1];
    if (t >= a[0] && t <= b[0]) {
      let s = (t - a[0]) / (b[0] - a[0]);
      s = s * s * (3 - 2 * s);                       // smoothstep
      return [1, 2, 3].map(j => a[j] + (b[j] - a[j]) * s);
    }
  }
  return null;
}

// per frame, per bone
const v = sampleTrack(clip.tracks[bone.name], clipTime);
if (v) {
  bone.quaternion.copy(bindQuaternion[bone.name]);
  bone.quaternion.multiply(new THREE.Quaternion().setFromEuler(
    new THREE.Euler(v[0] * DEG, v[1] * DEG, v[2] * DEG, 'XYZ')));
}

The standard rig

22 bones. These are the only names that do anything:

Rig1
  Spine1 -> Spine2 -> ArmR_Offset -> ArmR1 -> ArmR2
                      ArmL_Offset -> ArmL1 -> ArmL2
                      Neck_Offset -> Neck1
  LegR_Offset -> LegR1 -> LegR2
  LegL_Offset -> LegL1 -> LegL2

Raising an arm is negative X on ArmL_Offset / ArmR_Offset — the shoulder bones. Z there is sideways abduction, not lift, and ArmR1 is upper-arm twist. Getting this wrong swings the arm into the torso instead of up; it is the single most common mistake with this rig. Note also that the legs hang off Rig1, not Spine1, so rotating Spine1 bends the torso over stationary legs.

Joint limits

The meshes are rigid boxes with no deformation. Past these angles they self-intersect or visibly pull apart. You only need this table if you author your own clips — the ones Boxity serves are already inside it.

Multiplayer

Boxity sends play_emote only to the player who picked it. If your game has other players, replicate the emote id and its start time through your own networking and run the same clip on every client. Keep the id an opaque string — they are 24-character catalogue ids and new ones appear without a game release.

Testing

1. Open your game inside Boxity at bloxity.io/g/<your-slug>.
2. The emote button appears in the overlay dock. If it does not, your registerFeature('emotes') is not firing — check it runs on boot.
3. Pick an emote; your character should animate.

To test playback without the UI, run this in the browser console on the Boxity page (not inside the game frame). …e01 is Right Hand Wave, which is free for everyone:

document.querySelector('iframe').contentWindow.postMessage(
  { type: 'legion_play_emote', emoteId: '000000000000000000000e01' }, '*');

Gotchas

• Register as soon as init() resolves. Earlier is a silent no-op (no SDK global yet); later means a late button. If your platform layer wraps the SDK, make sure the wrapper awaits its own init before forwarding the call — optional chaining through a not-yet-loaded SDK fails without a single error.
• Do not check ownership yourself. Boxity only ever sends an id the player is entitled to. Duplicating the check is how the two drift apart.
• Unknown id? Ignore it quietly. Never throw — an emote is cosmetic and must never be able to break a frame.
• The catalogue grows. Do not hardcode ids or assume a count.
• Stop on movement. An emote that keeps playing while the player walks looks broken.

Overhead chat bubbles # embed

Boxity owns in-game chat: the chat button, the message bar, the Enter shortcut and the floating feed are all drawn by the portal over your game. Only your game knows where each character's head is, though, so to show a player's message above their head your game subscribes to chat and draws the bubble itself. Boxity does the rest.

• Every message in the room reaches every player in it, including the sender's own.
• The sender is verified by Boxity, never taken from a browser, so a bubble can safely go over that player's character.
• The text is already filtered. A message with a blocked word is never sent.
• Nothing arrives while the player has chat turned off, or when the game's chat is off in its settings.

Subscribing is the opt-in: the portal only forwards chat to games that called chat.onMessage, so nothing changes until you do.

Matching a message to a character

Key your players by the Boxity id your server verified from their token. If your server sends that id to clients as, say, legion_<id>, strip the prefix. Guests have a Boxity id too when they play through Boxity.

three.js

await Legion.SDK.init({ gameSlug: 'your-slug' });

Legion.SDK.chat.onMessage((message) => {
  const player = message.isLocalPlayer ? localPlayer : playersByBoxityId.get(message.userId);
  if (!player) return; // not on screen in this room
  Legion.SDK.chat.attachBubble(THREE, player.root, Legion.SDK.chat.bubbleText(message));
});

Your own bubble (HTML overlay, canvas, any engine)

If you already draw name tags, put the bubble right above the tag and reuse its screen position.

Legion.SDK.chat.onMessage((message) => {
  const player = findPlayer(message);
  if (!player) return;
  player.showBubble(Legion.SDK.chat.bubbleText(message));        // your UI
  clearTimeout(player.bubbleTimer);
  player.bubbleTimer = setTimeout(() => player.hideBubble(), Legion.SDK.chat.bubbleSeconds * 1000);
});

Unity WebGL

Subscribe in the host page and hand each message to a C# receiver, as the other SendMessage receivers do.

// Host page, after Legion.SDK.init() resolves
Legion.SDK.chat.onMessage((message) => {
  unityInstance.SendMessage('BoxityChat', 'OnChatMessage', JSON.stringify({
    userId: message.userId,
    text: Legion.SDK.chat.bubbleText(message),
    isLocalPlayer: message.isLocalPlayer,
    seconds: Legion.SDK.chat.bubbleSeconds,
  }));
});

// BoxityChat.cs, on a GameObject named "BoxityChat"
[System.Serializable] class ChatLine { public string userId; public string text; public bool isLocalPlayer; public float seconds; }

public class BoxityChat : MonoBehaviour {
  public void OnChatMessage(string json) {
    var line = JsonUtility.FromJson<ChatLine>(json);
    var player = line.isLocalPlayer ? Players.Local : Players.FindByBoxityId(line.userId);
    if (player != null) player.ShowChatBubble(line.text, line.seconds); // a world-space Canvas above the head
  }
}

Testing

Open your game at bloxity.io/g/<slug> in two browsers signed in as different players, join the same room, press Enter and send a message. It should appear over the sender in both windows for 4 seconds, and a second message should replace the first.

Gems purchases (IAP) #

Gems are Boxity's in-game currency (called Bux before the rename). The model is deliberately server-authoritative so games can't be cheated and players can't be charged for nothing: your game only ever passes a sku (a product id) — never a price — and the server looks up the price from your game's IAP catalog, deducts the Gems, and confirms the sale to your backend via a webhook. If anything in that chain fails, the Gems are refunded automatically.

How a purchase actually flows

1. Player clicks buy → you call requestPurchase(sku) client

   The SDK shows a confirm modal populated with the server's product name and price (you don't render it). Nothing is charged yet.

2. Player confirms → Boxity prices & deducts Gems server

   The server re-reads the price from your catalog and atomically deducts it. If the player is short, the flow opens a real-money top-up for the smallest covering package, then continues automatically.

3. Boxity calls your game server's webhook server → your server

   A signed POST with the transaction details (sku, user, amount, your metadata) lands on your fulfillment endpoint. This is the moment you actually grant the item.

4. Your server grants the item and returns 2xx your server, ≤10s

   Add the coins / unlock the skin in your database, then respond 2xx. The grant is only considered final once you do.

5. requestPurchase resolves { success:true, transactionId } client

   Reflect the grant in the game UI. Record the transactionId if you want an audit trail.

Quick reference:

// gameSlug must be set (init or portal handshake) so the API knows which catalog to price from.
Legion.SDK.init({ gameSlug: 'my-game' });

// Show the confirm modal & run the transaction. Just pass the sku.
const res = await Legion.SDK.gems.requestPurchase('coins_500');
if (res.success) grantCoins(500);   // res.transactionId for your records

// Optional metadata (passed through to your webhook) + override webhook URL:
await Legion.SDK.gems.requestPurchase('coins_500', { playerId: 'p_123' });

// Current balance
const gems = await Legion.SDK.gems.getBalance();

Buying Gems & gifting

Implement your game server's webhook

If you sell anything, your backend needs one endpoint. Boxity calls it after deducting Gems; you grant the item and answer 2xx.

1. Expose a POST endpoint once

   e.g. POST https://your-server.com/api/legion-webhook. Register its base URL as your game's default webhook (or pass a per-purchase webhookUrl in requestPurchase's options).

2. Verify the secret header every request

   When LEGION_WEBHOOK_SECRET is configured, reject any request whose x-legion-webhook-secret header doesn't match. Never grant on an unverified call.

3. Deduplicate by transactionId before granting

   Boxity retries on network errors and 502/503/504, so the same transactionId can arrive twice. Grant each one only once.

4. Grant the item, then return 2xx within 10 seconds fast

   Use sku, userId, and your metadata to apply the grant, then respond 2xx. A 4xx fails fast (no retry) and refunds; a slow or 5xx response refunds after retries. See the exact payload.

Portal & raw API #

Two utility namespaces: Legion.SDK.portal for detecting the environment and driving fullscreen, and Legion.SDK.api for making authenticated calls to the told API (environment().apiUrl) when a wrapper doesn't already exist.

Quick reference:

// Environment
Legion.SDK.portal.isInIframe();          // boolean
Legion.SDK.portal.isEmbeddedInLegion();  // embedded on bloxity.io?

// Portal menu & fullscreen (when embedded)
Legion.SDK.portal.showMenu(/* lockCursorOnResume */ false);
Legion.SDK.portal.requestFullscreen();
Legion.SDK.portal.exitFullscreen();

// Authenticated raw requests to the told apiUrl (Bearer token added automatically)
const me  = await Legion.SDK.api.get('/v1/social/me');
const out = await Legion.SDK.api.post('/v1/some/endpoint', { a: 1 });
await Legion.SDK.api.patch('/v1/x', {});
await Legion.SDK.api.delete('/v1/x');

Ads #

Boxity runs every ad itself. When your game is embedded on Boxity, the portal picks the ad network, applies frequency rules and draws the ad over your game - you never load an ad script. Your game does two things: pause during ad breaks, and optionally ask for rewarded ads. Midroll (interstitial) ads are started by the platform, never by the game.

Quick reference:

// Pause for every ad break - platform midrolls included.
Legion.SDK.ads.onBreakStart(() => { game.pause(); audio.mute(); });
Legion.SDK.ads.onBreakEnd(() => { game.resume(); audio.unmute(); });

// Rewarded ad from a button.
reviveButton.hidden = !Legion.SDK.ads.isAvailable();
const r = await Legion.SDK.ads.showRewarded('revive');
if (r.status === 'completed') revivePlayer();

Death screen #

When the player dies, Boxity shows ads along the edges of the game and runs a short countdown. Your game keeps its own death UI and its own Respawn button, in its own style. The button shows the countdown and only works once it reaches 0, so the ads are seen. Boxity decides which ads show, where, and how long the countdown is (at least 4 seconds); your game never picks or places an ad.

Quick reference:

function onLocalPlayerDied() {
  const death = Legion.SDK.deathScreen.show();
  deathUi.open();
  death.onCountdown(n => {
    respawnButton.label = n > 0 ? String(n) : 'RESPAWN';
    respawnButton.enabled = n === 0;
  });
  respawnButton.onClick = () => {
    if (death.respawn()) { deathUi.close(); respawnPlayer(); }
  };
}

// Round over while dead: close it without a respawn.
Legion.SDK.deathScreen.hide();

Multiplayer matchmaker # required for Boxity-hosted multiplayer

Every multiplayer game whose server is hosted on Boxity (Legion) must connect this way. Boxity's matchmaker fills each Colyseus server pod to your room cap, starts another pod when they're full, and shuts empty ones down. Legion.SDK.net.resolveEndpoint() asks the matchmaker which pod the player should join and hands you back a WebSocket endpoint to open. Single-player games, and games whose servers run somewhere other than Boxity, can skip this section.

import { Client } from 'colyseus.js';

// 1. Ask the matchmaker where to connect.
const { endpoint, cold } = await Legion.SDK.net.resolveEndpoint('my-game', {
  userId: Legion.SDK.auth.getUser()?._id,
});
if (cold) showToast('Waking up a server…');   // optional UX for cold starts

// 2. Open the Colyseus connection to that endpoint.
const room = await new Client(endpoint).joinOrCreate('arena', { /* your join opts */ });

Party play # embed

Players on Boxity can form a party of up to 6 friends and pick a game together. Boxity promises them one thing: everyone lands in the same room. If a game cannot keep that promise, Boxity shows the party "This game doesn't support party play yet" instead of launching it, so parties are never split without warning. Support is detected automatically - there is nothing to switch on in a dashboard.

Running your own servers? Use the four calls below. You seat the party yourself using the shared roomKey; Boxity checks every launch, and a game that fails to keep two parties in a row together is switched off for party play for 7 days.

// On boot.
Legion.SDK.party.enable({ maxPartySize: 8 });

// When the player presses Play / the game connects.
const party = await Legion.SDK.party.getLaunch();
const room = party && !party.managed
  ? await joinOrCreatePartyRoom(party.roomKey, party.size)   // your server: one room per roomKey, strangers kept out
  : await joinPublicRoom();
if (party) Legion.SDK.party.joined(room.id);

CrazyGames & Play with friends # embed

Boxity also runs on CrazyGames: the whole site at bloxity.io/?cg=true, and the /mini site. Your game runs there unchanged, but a few CrazyGames features need it to behave in a particular way. Build for them by default and the game is ready on both.

Play with friends (instant join)

A CrazyGames player can press Play with friends. They expect to land in a new private room that friends they invite can join straight away. Boxity shows them a short picker of the games that support it. A game is offered in one of two ways.

Making your own private rooms instead (your own servers, or you want your own behaviour)? Handle ?instantMultiplayer=true and announce it:

// On boot, once private rooms work.
Legion.SDK.game.registerFeature('play_with_friends');

// When connecting.
const instant = new URLSearchParams(location.search).get('instantMultiplayer') === 'true';
const room = instant
  ? await client.create(ROOM_NAME, { ...options, private: true })   // server: setPrivate(true)
  : await client.joinOrCreate(ROOM_NAME, options);
Legion.SDK.game.updateRoom(relayRoomId + '~' + room.roomId);

Invites

A friend who accepts a CrazyGames invite opens the game with ?roomId=, exactly like Boxity's Join button (see rooms). If your game already joins ?roomId= at launch, there is nothing extra to build.

Signing in mid-game

CrazyGames players often sign in after they start. If your game reconnects when onUserChanged reports the new user, rejoin the same room by id (new Client(Legion.SDK.environment().playUrl.replace(/^http/, 'ws') + '/v1/ws/' + relayRoomId).joinById(colyseusRoomId, options)) and fall back to matchmaking only if it is gone. Re-matchmaking would pull the player out of their friends' room.

Guest progress

CrazyGames players start as Boxity guests. When that browser signs in to an account that already existed, the guest's progress should follow. If your game saves progress on its server, verify each player with:

Controls & the CrazyGames build

• On CrazyGames, ESC exits fullscreen and P opens Boxity's pause menu. Never bind P, and show no fullscreen button of your own.
• Optional: set a separate CrazyGames URL for the game in its dashboard entry (for example your URL + ?cg=true). Boxity loads it on CrazyGames. Read ?cg=true from the game's own location to leave out anything you do not want there, and keep one bundle for both.
• Ads, gameplay start/stop and the CrazyGames login are handled by Boxity. Your game does nothing for them.

Unity (WebGL) host bridge

A Unity WebGL game runs inside a host HTML page. That page loads the Legion SDK and bridges it to Unity in both directions. The two reference implementations are Gunblox (full: auth + avatars + Gems) and 2v2 / fps (auth + social).

The two directions of communication

Project setup #

1. Create a WebGL template at Assets/WebGLTemplates/default/ with an index.html (the Unity loader) and a bridge file legion_integration.js.
2. In index.html, load your bridge after the Unity loader and any ad SDK so it can wrap (not overwrite) lifecycle hooks:

// index.html — load the Legion bridge last
const legionScript = document.createElement("script");
legionScript.src = "legion_integration.js?v=2";
document.head.appendChild(legionScript);

3. The bridge injects the SDK and initializes it with your gameSlug:

// legion_integration.js (top)
const s = document.createElement('script');
s.src = 'https://sdk.bloxity.io/v1/legion-sdk.min.js';
s.onload = () => {
  window.Legion.SDK.init({ gameSlug: 'my-game' });   // required for Gems pricing
  /* wire onUserChanged, settings.listen, player.onEvent → SendMessage */
};
document.head.appendChild(s);

Host bridge — window.* functions #

These are the functions Unity (C#) calls via Application.ExternalEval. The bridge awaits SDK init before each one.

jslib externs (C# → JS) #

The Legion-essential externs bridge C# to the loading overlay. Put this in Assets/Plugins/WebGL/legion.jslib:

mergeInto(LibraryManager.library, {
  SDK_LegionLoadingStep: function (messagePtr) {
    var message = UTF8ToString(messagePtr);   // marshal C# string → JS
    if (typeof window.legionLoadingStep === "function") window.legionLoadingStep(message);
  },
  SDK_LegionLoadingEnd: function () {
    if (typeof window.legionLoadingEnd === "function") window.legionLoadingEnd();
  }
});

Declare them in C# (guarded so the Editor still compiles):

using System.Runtime.InteropServices;

#if UNITY_WEBGL && !UNITY_EDITOR
[DllImport("__Internal")] static extern void SDK_LegionLoadingStep(string message);
[DllImport("__Internal")] static extern void SDK_LegionLoadingEnd();
#endif

Death screen externs

Required when the player can die (see Death screen). Add to the same legion.jslib; the respawn check returns an int because a DllImport cannot return a JS boolean:

  SDK_LegionDeathShow: function () {
    if (typeof window.legionDeathShow === "function") window.legionDeathShow();
  },
  SDK_LegionDeathRespawn: function () {
    if (typeof window.legionDeathRespawn !== "function") return 1;
    return window.legionDeathRespawn() ? 1 : 0;
  },
  SDK_LegionDeathHide: function () {
    if (typeof window.legionDeathHide === "function") window.legionDeathHide();
  }

#if UNITY_WEBGL && !UNITY_EDITOR
[DllImport("__Internal")] static extern void SDK_LegionDeathShow();
[DllImport("__Internal")] static extern int SDK_LegionDeathRespawn();
[DllImport("__Internal")] static extern void SDK_LegionDeathHide();
public static void DeathShow() => SDK_LegionDeathShow();
public static bool DeathRespawn() => SDK_LegionDeathRespawn() == 1;
public static void DeathHide() => SDK_LegionDeathHide();
#else
public static void DeathShow() { }
public static bool DeathRespawn() => true;   // Editor: no countdown
public static void DeathHide() { }
#endif

// On death:   LegionBridge.DeathShow();
// LegionListener.OnLegionDeathCountdown("4".."0"): show it on your Respawn button, active only at "0".
// Respawn button: if (LegionBridge.DeathRespawn()) RespawnPlayer();

SendMessage receivers (JS → C#) #

These are the public C# methods the bridge calls. Implement the ones for features you use, on GameObjects named exactly as shown. Every payload is a single string.

Auth handshake #

The bridge listens to onUserChanged, then authenticates the Boxity identity against your own game server and forwards the resulting session to Unity.

Legion.SDK.auth.onUserChanged(user)
  ├─ user != null
  │    ├─ result = await Legion.SDK.auth.authenticateWithServer(GAME_AUTH_URL)
  │    │     (SDK POSTs { token: <bloxity JWT>, user } to YOUR server)
  │    ├─ valid game-server response?  (must contain user.legionId / selected_*)
  │    │     ├─ yes → SendMessage('AuthManager','ProcessJsonAfterLogin', JSON.stringify(result))
  │    │     └─ no  → reject (retryable)
  └─ user == null
       └─ SendMessage('AuthManager','Logout2')

Example endpoints (your server, not Boxity): https://usa-1.gunblox.io/api/accounts/login/legion, https://usa-1.2v2.io/api/accounts/login/legion.

What your /login/legion endpoint must do

• Accept the POST body { token, user } and verify the Boxity JWT (confirm the user _id).
• Upsert a local game user keyed by legionId (sync pfp/skin/hat/back from Boxity).
• Return your own session JSON — the presence of user.legionId is how the bridge knows it's a real game-server response (raw Boxity avatar data is rejected):

{
  "accessToken":  "<your game JWT>",
  "refreshToken": "<your refresh token>",
  "user": {
    "legionId": "...", "username": "...", "displayName": "...",
    "pfp": "/pfps/...", "selected_skin": "...", "selected_hat": "..."
    /* + coins, premium, whatever your game needs */
  }
}

Rooms, party & social #

// When the local player joins/leaves a room or your game's own squad (not a Boxity party):
LegionBridge.UpdateRoom(currentRoomId, currentSquadId);   // "" when not joinable

// Boxity parties, own servers only (hosted on Boxity = automatic, see Party play):
LegionBridge.PartyEnable(maxPlayersPerRoom);   // in Start()
LegionBridge.PartyGetLaunch();                 // before joining → LegionListener.OnLegionPartyLaunch(json | "")
// json != "" and !managed: seat everyone sharing roomKey in ONE room, then:
LegionBridge.PartyJoined(room.Id);             // same id for every member
LegionBridge.PartyFailed("room-full");       // instead, when they cannot be seated together

// As remote players appear (escape nicknames before passing to JS!):
LegionBridge.PlayerInRoom(nickname);   // already in the room when you joined
LegionBridge.PlayerJoined(nickname);   // joined after you

// Friends list (async → SendMessage callback):
LegionBridge.FetchConnections();      // → FriendsManager.OnConnectionsReceived(json)
LegionBridge.InviteFriend(friendId);   // → FriendsManager.OnInviteSent("true"/"false")

Settings → Unity #

The bridge registers settings.listen(...) for each key and forwards changes to LegionListener:

At startup, call Legion.SDK.settings.triggerAll() (the bridge exposes it) to push every current value into Unity immediately.

Gems / IAP #

// C#: kick off a purchase. serverBaseUrl is your live game server.
LegionBridge.Purchase(sku, "https://fra-2.gunblox.io");

// JS bridge builds metadata.webhookUrl = serverBaseUrl + "/api/legion-webhook",
// calls Legion.SDK.bux.requestPurchase(sku, metadata), then:
//   SendMessage('IAPManager','OnLegionPurchaseResult',
//     '{"success":true,"sku":"coins_500","transactionId":"txn_…","error":""}')

Boxity prices the sku from your game's IAP catalog (selected by gameSlug), deducts Gems, and POSTs the fulfillment webhook to serverBaseUrl + "/api/legion-webhook". Your server grants the item and returns 2xx.

Minimal starter #

Distilled from the Gunblox/fps reference code. Drop these in, name the GameObjects to match, and fill in the bodies.

Assets/Scripts/LegionBridge.cs — C# → JS helper

using System.Runtime.InteropServices;
using UnityEngine;

/// Declares the C#→JS externs and wraps the window.* bridge functions.
public class LegionBridge : MonoBehaviour {
    public static LegionBridge Instance { get; private set; }

#if UNITY_WEBGL && !UNITY_EDITOR
    [DllImport("__Internal")] static extern void SDK_LegionLoadingStep(string m);
    [DllImport("__Internal")] static extern void SDK_LegionLoadingEnd();
#endif

    void Awake() => Instance = this;

    async void Start() {
        await System.Threading.Tasks.Task.Yield();   // wait until your managers exist
        CallJS("window.onUnityReady()");              // tell JS we can receive auth events
    }

    public static void LoadingStep(string m) {
#if UNITY_WEBGL && !UNITY_EDITOR
        SDK_LegionLoadingStep(m);
#endif
    }
    public static void LoadingEnd() {
#if UNITY_WEBGL && !UNITY_EDITOR
        SDK_LegionLoadingEnd();
#endif
    }

    // window.* helpers
    public static void UpdateRoom(string r, string p) => CallJS($"window.updateLegionRoom('{Esc(r)}','{Esc(p)}')");
    public static void PlayerJoined(string u) => CallJS($"window.legionPlayerJoined('{Esc(u)}')");
    public static void PlayerInRoom(string u) => CallJS($"window.legionPlayerInRoom('{Esc(u)}')");
    public static void FetchConnections() => CallJS("window.fetchLegionConnectionsForUnity()");
    public static void InviteFriend(string id) => CallJS($"window.inviteLegionFriendForUnity('{Esc(id)}')");
    public static void ShowAuthModal() => CallJS("window.showLegionAuthModal()");   // embedded
    public static void ShowAuthWindow() => CallJS("window.showLegionAuthWindow()"); // standalone
    public static void Logout() => CallJS("window.logoutLegion()");
    public static void Purchase(string sku, string serverBaseUrl) => CallJS($"window.legionPurchase('{Esc(sku)}','{Esc(serverBaseUrl)}')");

    static void CallJS(string js) {
#if UNITY_WEBGL && !UNITY_EDITOR
        Application.ExternalEval(js);
#else
        Debug.Log($"[LegionBridge] (editor) {js}");
#endif
    }
    static string Esc(string v) => string.IsNullOrEmpty(v) ? ""
        : v.Replace("\\","\\\\").Replace("'","\\'").Replace("\n","").Replace("\r","");
}

Assets/Scripts/LegionListener.cs — JS → C# receiver (GameObject "LegionListener")

using UnityEngine;

/// MUST be on a GameObject named EXACTLY "LegionListener".
public class LegionListener : MonoBehaviour {
    public void OnLegionVolumeChanged(string s) {
        if (int.TryParse(s, out var v)) AudioListener.volume = Mathf.Clamp01(v / 100f);
    }
    public void OnLegionMusicVolumeChanged(string s) { /* "0".."100" */ }
    public void OnLegionGraphicsQualityChanged(string q) {
        int lvl = q.ToLower() switch { "low"=>0, "medium"=>1, "high"=>2, "ultra"=>3, _=>-1 };
        if (lvl >= 0) QualitySettings.SetQualityLevel(lvl, true);
    }
    public void OnLegionShowFpsChanged(string s) { bool show = s == "true"; }
    public void OnLegionCameraSensitivityChanged(string s) { /* "0.1".."5.0" */ }
    public void OnLegionChatMessageSent(string msg) { /* relay to in-game chat */ }
    public void OnLegionRespawnRequested() { /* respawn local player */ }
    // Gunblox-only avatar sync (omit if cosmetics live elsewhere):
    public void OnLegionAvatarChanged(string json) { /* parse skinId/hatId/... */ }
    public void OnLegionProportionsChanged(string json) { /* parse height/... */ }
}

AuthManager.cs & FriendsManager.cs — receiver stubs

// GameObject "AuthManager"
public class AuthManager : MonoBehaviour {
    public void ProcessJsonAfterLogin(string json) { /* { accessToken, refreshToken, user{ legionId,... } } */ }
    public void Logout2() { /* clear tokens, set guest user */ }
    public void SetLoginPendingFromJS(string pending) { /* "true"|"false" (fps: SetAutoLoginPendingFromJS) */ }
}

// GameObject "FriendsManager"
public class FriendsManager : MonoBehaviour {
    public void OnConnectionsReceived(string jsonArray) { /* [{_id,username,pfp,presence{...}}] */ }
    public void OnConnectionRequestSent(string json) { /* {success,status?,error?} */ }
    public void OnInviteSent(string result) { /* "true"|"false" */ }
}

Reference

Data shapes #

interface LegionUser {
  _id: string; username: string;
  displayName?: string; email?: string; pfp?: string;
  avatar?: LegionAvatar;
}

interface LegionAvatar {
  hatId?: string | null; backId?: string | null;
  skinId?: string;                       // default "-1"
  headId?: string; armLId?: string; armRId?: string;
  legLId?: string; legRId?: string; torsoId?: string;
  hairId?: string;                       // "-1" = none; worn with a hat
  maskId?: string;                       // "-1" = none; masks, glasses, face props
  neckId?: string; chestId?: string; waistId?: string; handId?: string; shoesId?: string;
  faceId?: string; pantsId?: string; shirtId?: string; // skin overlays; see getSkinTextureUrl()
  proportions?: BodyProportions;          // each value defaults to 1.0
}

interface BodyProportions {
  height?: number; shoulderWidth?: number; armLength?: number;
  legOffsetX?: number; torsoScaleX?: number; neckHeight?: number; headScale?: number;
}

interface LegionFriend {
  _id: string; username: string;
  displayName?: string; pfp?: string; avatar?: LegionAvatar;
  presence: UserPresence;
}

interface UserPresence {
  status: 'online' | 'in-game' | 'away' | 'offline';
  lastSeen?: string; currentGame?: string; currentRoom?: string;
  currentParty?: string; gameSlug?: string; gameName?: string;
}

Settings keys #

REST endpoints (standalone mode) #

Base: the told apiUrl (https://api.bloxity.io on prod, see Environments). The SDK adds Authorization: Bearer <token> when a token exists. You rarely call these directly — the namespaces above wrap them — but they're useful for server-side validation.

CDN asset URLs #

Avatar meshes/textures live on the told staticUrl (https://static.bloxity.io on prod). Build URLs from the equipped ids (skip any id that is '-1'/''/'undefined'/null):

Where each worn item attaches on player.glb. Hats and back items use a fixed local offset. The newer accessories are authored in the body's rest pose, so parent them with local matrix restInverse(bone) × translate(origin), where restInverse is the inverse of the bone's rest transform in model space, captured right after player.glb loads (before any animation or proportions). Do not use skeleton.boneInverses here: on the leaf bones of player.glb they are 90° off the rest pose and put hand items sideways.

Gems webhook payload #

After deducting Gems, the Boxity API POSTs this JSON to your resolved webhook URL (metadata.webhookUrl → the IAP's webhookUrl → the game's default). Respond 2xx within 10 s to confirm the grant, or the Gems are auto-refunded.

// POST https://your-game-server.com/api/legion-webhook
// Header: x-legion-webhook-secret: <LEGION_WEBHOOK_SECRET>   (when configured)
{
  "transactionId": "txn_1718600000000_a1b2c3d4",
  "userId":        "6602f1a2b3c4d5e6f7080910",
  "username":      "coolplayer42",
  "gameSlug":      "my-game",
  "sku":           "coins_500",
  "productName":   "500 Coins",
  "productPrice":  50,
  "metadata":      { "playerId": "p_123" },
  "timestamp":     "2026-06-17T12:00:00.000Z"
}