remix-game-sdk

Remix Game SDK 参考（@remix-gg/sdk）

生成或修复 Remix 游戏代码时，请使用此文件。

运行时模型

• 在 Remix 托管的上传内容中，SDK 可通过 window.RemixSDK 使用。
• window.FarcadeSDK 仍会被赋值为向后兼容的别名，但新代码应使用 window.RemixSDK。
• 在 HTML <head> 中引入 SDK 脚本：
  • <script src="https://cdn.jsdelivr.net/npm/@remix-gg/sdk@latest/dist/index.min.js"></script>
• 上传的单文件游戏代码不得依赖软件包导入。
• 读取玩家／游戏数据前，务必先调用 await window.RemixSDK.ready()。

v1 Agent 验证所需的钩子

以下检查是 GET /v1/games/{gameId}/versions/{versionId}/validate 的必需项：

• window.RemixSDK.singlePlayer.actions.gameOver({ score })
• window.RemixSDK.onPlayAgain(() => { ... })
• window.RemixSDK.onToggleMute(({ isMuted }) => { ... })

常用 SDK 接口

属性／getter：

• window.RemixSDK.player
• window.RemixSDK.players
• window.RemixSDK.gameState
• window.RemixSDK.gameInfo
• window.RemixSDK.purchasedItems
• window.RemixSDK.inventory
• window.RemixSDK.shopItems
• window.RemixSDK.isReady
• window.RemixSDK.hasItem(itemId)
• window.RemixSDK.getItemPurchaseCount(itemId)
• window.RemixSDK.getShopItem(slug)

实用的 gameInfo 字段：

• viewContext：用于提供动态消息／全屏／挑战／锦标赛上下文
• contentSafeAreaInset：用于适配移动端布局，避免覆盖内容的安全区域
• initialGameState：用于还原持久化状态

单人游戏操作：

• window.RemixSDK.singlePlayer.actions.gameOver({ score })
• window.RemixSDK.singlePlayer.actions.saveGameState({ gameState })
• window.RemixSDK.purchase({ item })
• window.RemixSDK.onPurchaseComplete(({ success, item }) => { ... })
• window.RemixSDK.singlePlayer.actions.reportError({ message, ... })
• window.RemixSDK.hapticFeedback()

多人游戏操作：

• window.RemixSDK.multiplayer.actions.gameOver({ scores })
• window.RemixSDK.onGameStateUpdated(callback)

对于基础单人游戏，多人游戏操作／事件为可选项。

最简集成模板

async function initGame() {
  const sdk = window.RemixSDK
  await sdk.ready()

  let muted = true
  sdk.onToggleMute(({ isMuted }) => {
    muted = isMuted
  })

  sdk.onPlayAgain(() => {
    restart()
  })

  function finish(score) {
    sdk.singlePlayer.actions.gameOver({ score })
  }

  function save(state) {
    sdk.singlePlayer.actions.saveGameState({ gameState: state })
  }

  function restart() {
    // reset local game state and render
  }

  // start gameplay loop...
}

initGame()

应避免的错误

• 在 ready() 完成前调用 SDK getter。
• 遗漏必需验证钩子（gameOver、onPlayAgain、onToggleMute）中的任何一个。
• 使用不存在的 SDK 方法，例如 vibrate、checkpoint 或 save。
• SDK 提供 sdk.purchase(...) 时，在新代码中仍使用 singlePlayer.actions.purchase(...)。
• HUD 或控件可能与移动端覆盖内容冲突时，忽略 contentSafeAreaInset。
• 将 localStorage／sessionStorage 用作主要持久化方式，而不使用 saveGameState。