Bounty Board Arcade SDK

Scores and game over

Submit integer score snapshots freely; the host throttles transport. Call gameOver() exactly once with the final score. For a shared seed daily mode, pass { mode: 'daily' } to both calls. Fractional scores are truncated toward zero. Scores post only when the game declares Leaderboards, and the server rejects any score above the game's ceiling: a max score, or a per second rate for endless games, with a generous default when neither is set.

Cloud saves

Serialize the complete progress model into one string and save at checkpoints or game over, never every frame. Hosted uploads run in an opaque origin sandbox without localStorage, so SDK save is primary there. URL embeds and standalone builds need their own same origin fallback.

Gate the account calls on getPlayer(), which resolves null for guests and never rejects or hangs. That keeps the try/catch for real transport failures instead of turning a signed out player into an error you have to remember to swallow.

import type { BBArcadeError } from '@bountyboard/arcade-sdk';

function writeLocalProgress(blob: string) {
  try {
    localStorage.setItem('progress', blob);
  } catch {
    // Hosted uploads use an opaque origin, so localStorage may be unavailable.
  }
}

function readLocalProgress(): Progress | null {
  try {
    const blob = localStorage.getItem('progress');
    return blob ? JSON.parse(blob) : null;
  } catch {
    return null;
  }
}

// Ask who is playing first. getPlayer() resolves null for guests and never
// rejects, so the guest case is a branch instead of a thrown error.
export async function loadProgress(): Promise<Progress | null> {
  const player = await BBArcade.getPlayer();
  if (!player) return readLocalProgress(); // and offer "Sign in to save"

  try {
    const blob = await BBArcade.load(); // null means no save yet
    return blob ? JSON.parse(blob) : null;
  } catch {
    return readLocalProgress();
  }
}

export async function saveProgress(progress: Progress) {
  const blob = JSON.stringify(progress); // one blob, about 1 MB max

  try {
    await BBArcade.save(blob);
  } catch (error) {
    const code = (error as BBArcadeError).code;

    // Normal outside a Bounty hosted upload. Use your own same-origin store.
    if (code === 'unsupported') writeLocalProgress(blob);
    // A guest reached save() without the gate above. Never report success.
    else if (code === 'unauthenticated') offerSignIn();
    else reportSaveFailure(code);
  }
}

Rejection codes: unsupported, unauthenticated, too_large, rejected, and error. save() rejects for a guest on purpose: a write that did not happen must never resolve as if it had, and it is the one moment where you can offer to sign in and keep the progress.

Compare leaderboard and cloud save options for HTML5 games.

Engine exports: the localStorage shim

Prefer save()/load() when you control the source. The shim is for engine runtimes whose storage layer cannot be rewired without patching engine internals: GameMaker HTML5 (where ini_open, ini_write_*, and game_save all sit on localStorage), Godot, Unity, and Construct. It replaces the throwing localStorage with a Storage shaped object backed by your cloud save, so those builds persist per player and across devices with no engine changes.

<!-- Script tag: load order is the whole integration. The SDK installs the
     shim at load, so the engine below finds a working localStorage. -->
<script src="https://www.bountyboard.gg/arcade-sdk/v1.js"></script>
<script src="html5game/YourGame.js"></script>

// Module builds: install it yourself, before any engine code runs.
import { BBArcade } from '@bountyboard/arcade-sdk';

BBArcade.storage.install();          // no-op where a real localStorage works

// getItem() is synchronous, but the cloud read that fills it is not.
const mode = await BBArcade.storage.ready();   // 'cloud' | 'memory' | 'native'
if (mode === 'memory') showGuestProgressNotice();

startGame();                         // now localStorage.getItem() sees the save

sessionStorage is shimmed too, but memory only. Guests and standalone play settle in memory mode: storage still works for the session, it is just never persisted. setItem throws QuotaExceededError past the ~1 MB save cap, like a real Storage.

Player identity and A/B variants

Player data is display only: name and optional avatar, never an account id, email, or role. getPlayer() reads the identity once at handshake time; subscribe with onPlayerChange() to react when the player logs in or out mid session. Variants are stable per player, game, and key; name the alphabetically first option as the safe control because that is what standalone and error paths receive.

const player = await BBArcade.getPlayer();
if (player) {
  greet(player.name);
  if (player.avatarUrl) drawAvatar(player.avatarUrl);
}

// Fires only when the identity changes (login/logout mid session).
const unsubscribe = BBArcade.onPlayerChange(next => updateGreeting(next));

// Alphabetical first is the standalone/error control: "control" here.
const cta = await BBArcade.getVariant('start-cta', ['control', 'short-label']);
renderStartButton(cta ?? 'control');

Prepared rewarded ads

Prepare at a natural break and keep your Watch Ad control disabled until status is ready. The retained show() call must stay in the browser's direct click/tap stack. Grant only on the final viewed result, pause gameplay and audio in onStart, and never loop or retry automatically.

const button = document.querySelector<HTMLButtonElement>('#watch-ad')!;
button.disabled = true;

// Prepare when the defeat/reward panel opens.
const prepared = await BBArcade.prepareRewardedAd({
  placement: 'death_revive',
  reward: 'extra_life',
  onStart: () => pauseGameAndAudio(),
});

if (prepared.status === 'ready') {
  button.disabled = false;
  button.addEventListener('click', () => {
    // Keep this first. No await, timeout, or network call before show().
    const resultPromise = prepared.show();
    button.disabled = true;

    void resultPromise.then(result => {
      resumeGameAndAudio();
      if (result.status === 'viewed') revivePlayer();
      else keepNormalFallbackAvailable();
    });
  }, { once: true });
} else {
  keepNormalFallbackAvailable();
}

Multiplayer rooms and lobbies

Multiplayer is enabled per game and has three rails. An approved game on Bounty's shared service gets the built in casual relay. The relay owns signed admission, roster, reconnect grace, capacity, host succession, and public message fan out, but it does not referee game state or results. Competitive or reward bearing play needs a server that runs the rules: a referee module inside Bounty Board's room service (today only first party games have one; ask on Discord), or a registered external authority that validates inputs, runs the simulation, and sends viewer safe state.

The first seat in a relay room fixes its capacity with joinData.roomSize, an integer from 2 to 64; missing or invalid means 8. The oldest retained seat is host, including during the 15 second reconnect grace. Relay state is { mode: 'relay', hostId, size, dropped }. Every game payload is public to every player, including the sender: there are no private relay messages or hidden state.

Relay payloads arrive in 20 Hz batches as { type: 'relay', messages: [{ from, data }] }; host changes arrive as { type: 'relay_host', hostId }. A payload may be at most 1 KiB of UTF-8 JSON, with 15 messages per player and 120 per room each second. Byte/rate excess is silently dropped and increments state.dropped. Relay metadata snapshots are 1 Hz. Relay rooms are endless, never emit end, and never report client trusted outcomes to Bounty Board.

Referee modules declare a 1 to 64 player range; relay rooms use 2 to 64. Players can use match: true to enter the game's open public room, or create: true/code for a shareable four character invite (a matched room's code also works as an invite). Registered external authorities set their own reviewed capacity and run their own matchmaking, so match: true is unavailable there.

joinRoom() is room transport, not one universal ready/start lobby state machine. Relay has the host contract above; referee modules and external authorities define their own ready, team, spectator, kick, start, and rematch schemas. The platform selects the tier for the game; joinData cannot choose it. When the promise resolves, welcome state is already in room.state and the initial roster is in room.players; render both before waiting for later events. Quick match is capacity based and may late join a running room, so spectator or late entry behavior is tier/game defined.

Simulation backed state sync is server round trip based. The SDK does not provide client side prediction, interpolation, or rollback. Plan around roughly 50 to 150 ms from input to viewer safe snapshot; smooth rendering locally, but correct to the next referee snapshot. Relay game messages instead arrive in the public 20 Hz event batches described above.

import type { BBArcadeError } from '@bountyboard/arcade-sdk';
import { joinRoom } from '@bountyboard/arcade-sdk/multiplayer';

try {
  const room = await joinRoom({
    create: true, // or code: 'ABCD', or match: true for public quick match
    // A relay founder may set roomSize to an integer from 2-64 (default 8).
    joinData: { roomSize: 4, avatar: 'golem' }, // always untrusted
  });

  // welcome already arrived: render these fields before waiting for an event.
  renderLobby(room.code, room.players, room.state);
  room.on('playerJoin', () => renderPlayers(room.players));
  room.on('playerLeave', () => renderPlayers(room.players));
  room.on('snapshot', ({ state }) => renderRoomState(state));
  room.on('event', event => handleRoomEvent(event));
  room.on('connection', ({ connected, reconnecting }) =>
    setConnectionState({ connected, reconnecting })
  );
  let ended = false;
  room.on('close', ({ reconnecting }) => {
    if (!reconnecting && !ended) showConnectionClosed();
  });
  room.on('end', ({ results }) => {
    ended = true;
    showResults(results); // finite refereed rooms only
  });

  onPlayerInput(input => {
    if (!room.trySend(input)) {
      if (!room.connected) setReconnecting(true);
      else showSendFailure(); // serialization/WebSocket.send failed locally
    }
  });
  onExit(() => room.leave());
} catch (error) {
  const { code } = error as BBArcadeError;
  showSoloFallback(code); // every BBArcadeErrorCode is an expected state
}

See the relay room wire guide for a focused implementation contract. Already have a mature server? Keep it as the single authority and add an isolated signed ticket adapter; read the public external authority contract before implementing the endpoint.

Site lock and WebXR

Site lock is an optional early anti rehosting check, not DRM. Bounty Board and localhost are always allowed, so allow is where you list the domains you host the build on yourself. A build we host needs no entries, and the domains below are placeholders. signed: true asks the host for a signed origin attestation and checks it against a public key built into the SDK; a missing host or an invalid attestation blocks. WebXR games should bracket immersive sessions so playtime does not disappear when the flat page becomes hidden.

// Site lock is a deterrent, not DRM. Run it before boot.
BBArcade.lockToHost({
  allow: ['play.yourgame.com', 'preview.yourgame.com'],
  signed: true,
});

// WebXR only: keep immersive playtime visible to the host.
session.addEventListener('end', () => BBArcade.xrSessionEnd());
BBArcade.xrSessionStart();

Lifecycle and scoring

Player data and experiments

Rewarded ads

Security and multiplayer