remix-game-sdk

Remix Game SDK リファレンス（@remix-gg/sdk）

Remix 向けのゲームコードを生成または修正するときは、このファイルを使用してください。

ランタイムモデル

• Remix がホストするアップロードでは、SDK は window.RemixSDK として利用できます。
• 下位互換性のため、window.FarcadeSDK も引き続きエイリアスとして割り当てられますが、新しいコードでは window.RemixSDK を使用してください。
• SDK のスクリプトを HTML の <head> に含めてください：
  • <script src="https://cdn.jsdelivr.net/npm/@remix-gg/sdk@latest/dist/index.min.js"></script>
• アップロードする単一ファイルのゲームコードでは、パッケージのインポートに依存しないでください。
• プレイヤーやゲームのデータを読み取る前に、必ず await window.RemixSDK.ready() を呼び出してください。

v1 エージェントの検証に必要なフック

これらのチェックは GET /v1/games/{gameId}/versions/{versionId}/validate で必須です：

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

よく使われる SDK の機能

プロパティ／ゲッター：

• 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 のゲッターを呼び出す。
• 必須の検証フック（gameOver、onPlayAgain、onToggleMute）のいずれかを省略する。
• vibrate、checkpoint、save など、存在しない SDK メソッドを使用する。
• SDK が sdk.purchase(...) を公開しているのに、新しいコードで singlePlayer.actions.purchase(...) を使用する。
• HUD や操作要素がモバイルのオーバーレイと重なる可能性があるのに、contentSafeAreaInset を無視する。
• saveGameState ではなく、localStorage／sessionStorage を主な永続化手段として使用する。