Remix Craig

SDK Overview

The Remix SDK handshake, the three calls every game makes, and the optional calls worth using.

The Remix SDK is the bridge between a game and the surface it runs on. It is a small message layer: the game posts events, the host answers with data. The same code runs on the mobile app, remix.gg and Remix Desktop.

Installation

Uploads through Remix Desktop, the CLI and the HTTP API add the SDK script tag for you, and the SDK is available as window.RemixSDK. A document you paste into the Studio on remix.gg needs the tag in its <head>:

<script src="https://cdn.jsdelivr.net/npm/@remix-gg/sdk@latest/dist/index.min.js"></script>

Nothing needs to be installed to ship. Load the SDK once: a copy bundled into your own code runs the handshake twice.

For editor types, install the package:

npm install @remix-gg/sdk

import type { RemixSDK, GameInfo, Player } from '@remix-gg/sdk'

const sdk: RemixSDK = window.RemixSDK

A project that Remix Desktop or the CLI scaffolds reaches the same surface through its own remix.ts. A game built on @remix-gg/three reaches it through game.platform, which createGame hands it already connected. See Three.js.

The Three Obligations

A game that does not do all three is not finished, whatever it looks like.

  1. Wait for the handshake. await sdk.ready() resolves with the GameInfo the host sent: the player, the safe area, any saved state, and the game's declared achievements. Never start a run before it resolves.
  2. Call gameOver exactly once per run. The host scores the first call and draws the results screen. Guard your update loop so nothing scores or spawns afterwards.
  3. Handle play. The host calls it for a replay and, in level games, with the level to start. Reset the run in place. A page reload drops the host connection.
const sdk = window.RemixSDK

sdk.onPlay((data) => startRun(data?.levelIndex))
sdk.onToggleMute(({ isMuted }) => audio.muted = isMuted)

const info = await sdk.ready()
startRun(info.levelBased?.progress.currentLevelIndex)

function endRun(score: number) {
  sdk.singlePlayer.actions.gameOver({ score })
}

Optional Calls Worth Using

  • sdk.hapticFeedback(type?) buzzes the device on 'light' | 'medium' | 'hard' | 'success' | 'error'. A tap that buzzes feels twice as responsive. It is a no-op where there is nothing to buzz.
  • sdk.singlePlayer.actions.saveGameState({ gameState }) persists progress between sessions. See Saving Progress.
  • sdk.leaderboards, sdk.achievements and sdk.saves are the platform's progression surfaces. Each resolves null instead of rejecting when a host cannot answer, so a game runs unchanged everywhere.

What the Host Does for You

The host owns mute, the results screen, play-again, level selection and best stars, the achievement popup, the main score's leaderboard and the game page. A game that draws its own results screen or its own main-score leaderboard fights the platform on every surface. Report, then wait for play. Named leaderboards are the exception: the platform ranks them, and your game draws them from sdk.leaderboards.

Reference