Game Over and Levels

Every scored run ends with one call. The host takes it from there: results screen, best score, crowns, achievements that ride the score, and the play-again button that brings the player back to you.

Scored Games

sdk.singlePlayer.actions.gameOver({ score: finalScore })

Call it once, when the run is over, then freeze. The host scores only the first call of a run, so a stray early call, such as one from a death animation's callback, records a stale score and the real one is ignored. Guard your update loop on a running flag so nothing scores or spawns afterwards.

Then wait. sdk.onPlay fires when the player wants another run. Reset your run state in place; everything built at boot survives.

Custom games (lifecycle: "custom" in remix.json) never call gameOver: they run their own flow and endings. Only Arcade and Levels games get Remix's built-in achievements; a Custom game declares its own.

Level Games

Set both fields in remix.json, with the real authored count:

{ "lifecycle": "levels", "levelCount": 16 }

At runtime, level mode is on only when gameInfo.levelBased is present. The platform can turn it off, so key level behaviour off that block, never off your own level content.

The host owns progression. It stores unlocks and best stars, draws the level select and the results, and picks which level plays next. The game only does three things:

Start from the host's level. On boot, read levelBased.progress.currentLevelIndex (1-based) and build that level.

Report every attempt.

sdk.singlePlayer.actions.gameOver({
  score: 0,                      // ignored for level games
  levelAttempt: {
    levelIndex,                  // 1-based level just played
    stars,                       // 0 = failed, 1 | 2 | 3 = completed
  },
})

Honour the host's restart.

sdk.onPlay((data) => {
  const level = data?.levelIndex ?? currentLevelIndex   // omitted data is a replay
  buildLevel(level)
})

Never advance the level yourself, never save unlocks or stars in game state, and never treat the boot index as a new selection. The host records the first report of each attempt and ignores repeats.

Read progression through the getters when you need it for a HUD: sdk.levelStars, sdk.highestUnlockedLevel, sdk.totalStars.

A launched level game's count can grow on later versions but cannot shrink, and its mode is locked once launched.