@remix-gg/mcp 0.4.3

package/skills/workflows/manage-shop-items.md

@@ -0,0 +1,246 @@
+# Manage Shop Items Workflow
+
+## Overview
+
+This skill covers the full shop-item lifecycle for a Remix game. Use it
+to list current shop items, create new ones, update existing metadata, delete
+or deactivate items, and integrate item consumption in game code.
+
+The safe default is:
+
+1. Run `listShopItems` first.
+2. Reuse or update an existing item when the intended slug already exists.
+3. Create only when the intended slug is not already present.
+
+## Prerequisites
+
+- The game HTML file must already exist.
+- A game must already be created on the Remix platform.
+- If you already have custom icon art, upload or reuse that hosted asset URL.
+- If `iconUrl` is omitted when creating a `CONSUMABLE` or `ONE_TIME` item,
+  the tool will auto-generate and upload a shop icon for you.
+- Shop item lifecycle is backend-managed:
+  - create always starts as `PENDING`
+  - launch or approval moves `PENDING` items to `ACTIVE`
+  - delete soft-deletes items to `INACTIVE`
+
+## 1. List Or Inspect Items
+
+Always list current items before creating, editing, or deleting. This avoids
+duplicate slugs, duplicate names, and accidental edits to the wrong item.
+
+```js
+listShopItems({
+  gameId: "<your-game-id>"
+})
+```
+
+Use the returned `itemId` for updates and deletes. Use the returned `slug` in
+game code purchase calls and inventory checks.
+
+If the intended slug or name already exists, update that item instead of
+creating a duplicate.
+
+## 2. Create Item
+
+Read `.remix-settings.json` first and use the existing `gameId` when present.
+
+Choose the item behavior before calling the tool:
+
+- `CONSUMABLE` for items players can buy many times, like extra lives.
+- `ONE_TIME` for permanent one-time unlocks.
+- `TIER_UNLOCK` for progression-style tier unlocks.
+
+Create the item:
+
+```js
+createShopItem({
+  gameId: "<your-game-id>",
+  name: "Extra Life",
+  slug: "extra-life",
+  itemType: "CONSUMABLE",
+  bitsCost: 50,
+  description: "Spend one to restore a life after game over."
+})
+```
+
+New items are created as `PENDING` automatically. Launching a game moves its
+items to `ACTIVE`. Deleting an item soft-deletes it to `INACTIVE`.
+
+For tier unlocks, pass `itemType: "TIER_UNLOCK"` and `tier`.
+
+Provide `iconUrl` only when you want a specific custom icon. Otherwise, let
+the tool auto-generate the icon for `CONSUMABLE` and `ONE_TIME` items.
+`TIER_UNLOCK` items do not auto-generate icons.
+
+After creation, tell the user which outcome happened:
+
+- the item was created with their provided icon
+- the item was created and an icon was auto-generated
+- the item was created but icon generation failed, so it has no icon yet
+
+## 3. Update Or Delete Items
+
+Update only the fields that should change:
+
+```js
+updateShopItem({
+  gameId: "<your-game-id>",
+  itemId: "<item-id>",
+  name: "Extra Life Pack",
+  bitsCost: 75
+})
+```
+
+Delete or deactivate an item:
+
+```js
+deleteShopItem({
+  gameId: "<your-game-id>",
+  itemId: "<item-id>"
+})
+```
+
+Deletion is a soft delete. The backend moves the item to `INACTIVE`; clients do
+not manage item status directly.
+
+## 4. Integrate Consumable Usage In Game Code
+
+Call `await sdk.ready()` before checking shop item state. Shop items should use
+the Remix SDK purchase flow and inventory data, not custom payment logic.
+
+Register `sdk.onPurchaseComplete(...)` during setup. This is required so your
+game applies the purchase result even when the purchase finishes outside the
+immediate in-game `await sdk.purchase(...)` call, such as when a drawer or
+platform UI completes the purchase after the game triggered it or when the
+platform sends the completion event back into the running game session.
+
+**Consumable Shop Item pattern (REQUIRED for item usage):**
+```javascript
+const sdk = window.RemixSDK
+await sdk.ready()
+
+function applyPurchase(itemSlug) {
+  if (itemSlug === 'extra-life') {
+    const currentState = sdk.gameState || {}
+    const currentSpent = Number(currentState.extraLivesSpent || 0)
+    sdk.singlePlayer.actions.saveGameState({
+      gameState: {
+        ...currentState,
+        extraLivesSpent: Math.max(0, currentSpent - 1),
+      },
+    })
+  }
+}
+
+sdk.onPurchaseComplete((data) => {
+  if (!data.success || !data.item) return
+  applyPurchase(data.item)
+})
+
+function getPurchasedQuantity(itemSlug) {
+  return sdk.getItemPurchaseCount(itemSlug)
+}
+
+function getConsumableBalance(itemSlug, spentKey) {
+  const purchased = getPurchasedQuantity(itemSlug)
+  const spent = Number(sdk.gameState?.[spentKey] || 0)
+  return Math.max(0, purchased - spent)
+}
+
+function consumeConsumable(itemSlug, spentKey, amount) {
+  const currentState = sdk.gameState || {}
+  const purchased = getPurchasedQuantity(itemSlug)
+  const currentSpent = Number(currentState[spentKey] || 0)
+  const nextSpent = Math.min(purchased, Math.max(0, currentSpent + amount))
+  const gameState = { ...currentState, [spentKey]: nextSpent }
+  sdk.singlePlayer.actions.saveGameState({ gameState })
+}
+
+// Example for extra-life
+const freeLives = 2
+const extraLivesBalance = getConsumableBalance('extra-life', 'extraLivesSpent')
+if (playerLives > freeLives) {
+  consumeConsumable('extra-life', 'extraLivesSpent', 1)
+}
+```
+
+Trigger purchases with the slug:
+
+```javascript
+const result = await sdk.purchase({ item: 'extra-life' })
+
+if (!result.success) {
+  showPurchaseError()
+}
+```
+
+Use `onPurchaseComplete()` as the single source of truth for applying the item
+effect. The awaited purchase result is fine for UI feedback like closing a menu
+or showing an error, but do not apply the game effect in both places.
+
+## Wrong Patterns
+
+**❌ WRONG - DO NOT DO THIS:**
+```javascript
+// WRONG - This will be rejected!
+localStorage.setItem('gameState', JSON.stringify(this.gameState))
+sessionStorage.setItem('gameState', JSON.stringify(this.gameState))
+
+// WRONG - These SDK functions DO NOT EXIST!
+window.RemixSDK.singlePlayer.actions.checkpoint({ gameState: {...} })
+window.RemixSDK.singlePlayer.actions.save({ gameState: {...} })
+
+// WRONG - These vibration methods DO NOT WORK!
+navigator.vibrate(200)
+window.RemixSDK.vibrate()
+
+// WRONG - Do not build custom bits/payment flow for item purchases
+customBitsCheckout('item-id')
+
+// WRONG - Do not probe multiple hypothetical purchase APIs
+const candidates = [
+  () => sdk.store?.actions?.purchase?.({ itemId }),
+  () => sdk.store?.actions?.purchaseItem?.({ itemId }),
+  () => sdk.monetization?.actions?.purchase?.({ itemId }),
+  () => sdk.payments?.actions?.purchase?.({ itemId }),
+  () => sdk.bits?.actions?.spend?.({ itemId, amount }),
+]
+
+// WRONG - Shop items use { item: 'item-slug' }, not { itemId }
+await sdk.purchase({ itemId: 'item-slug' })
+
+// WRONG - Do not skip purchase_complete handling
+await sdk.purchase({ item: 'extra-life' })
+
+// WRONG - Do not apply the same item effect in both the promise path
+// and onPurchaseComplete()
+const result = await sdk.purchase({ item: 'extra-life' })
+if (result.success) applyPurchase('extra-life')
+
+// WRONG - hasItem/getItemPurchaseCount checks before ready-check/game_info
+const ownsItemTooEarly = sdk.hasItem('item-slug')
+const quantityTooEarly = sdk.getItemPurchaseCount('item-slug')
+
+// WRONG - Do not hardcode store metadata in game code
+const SHOP_ITEMS = [{ id: 'save-game', name: 'Save Game', bits: 200, icon: '/save.png' }]
+
+// WRONG - Do not persist duplicated metadata in gameState
+window.RemixSDK.singlePlayer.actions.saveGameState({
+  gameState: {
+    unlockedItems: [{ id: 'save-game', name: 'Save Game', bits: 200 }]
+  }
+})
+```
+
+## Tips
+
+- Use short, stable slugs like `extra-life`, `double-jump`, or `shield-boost`.
+- For consumables, store only usage counters in `gameState`, not duplicated
+  store metadata.
+- If you need a very specific look, use **add-image-to-game** first and pass
+  the hosted `iconUrl` into item create or update calls.
+- If no custom art is needed, omit `iconUrl` and let `createShopItem`
+  auto-generate icons for `CONSUMABLE` and `ONE_TIME` items.
+- Always run `listShopItems` before create, update, or delete unless you
+  already have the exact `itemId` and intended `slug`.

package/skills/workflows/upload-game.md

@@ -0,0 +1,74 @@
+# Upload Game Workflow
+
+## Overview
+
+This skill guides you through uploading a completed HTML game to the Remix
+platform. It covers creating the game entry (if needed) and uploading the code.
+
+## Prerequisites
+
+- The `REMIX_API_KEY` environment variable must be set.
+- A completed HTML game file, ready for upload.
+
+**IMPORTANT:** Never read the HTML game file directly. Both `validateGame` and
+`uploadVersion` accept a `filePath` and read the file themselves. Just pass the
+path.
+
+## Steps
+
+### 1. Locate the Game File
+
+Find the path to the HTML file to upload. It should be a single self-contained
+HTML document with inline CSS and JS. You only need the **file path** — do not
+read the file.
+
+### 2. Validate
+
+Use the `validateGame` tool with the `filePath` to check the HTML for common
+issues:
+- Missing DOCTYPE or viewport meta
+- Inline event handlers (use addEventListener instead)
+- Infinite loops or blocking animations
+- External resource references (should be self-contained)
+
+Fix any reported issues before proceeding.
+
+### 3. Create the Game (only if no existing IDs)
+
+**IMPORTANT:** You MUST check for a `.remix-settings.json` file in the project
+root BEFORE calling `createGame`. If the file exists and contains both `gameId`
+and `versionId`, **do NOT call `createGame`** — skip directly to step 4 and
+use the existing IDs. Calling `createGame` when IDs already exist will create
+a duplicate game entry.
+
+Only if no settings file exists (or it is missing `gameId` or `versionId`),
+use the `createGame` tool with a `name` for the game. The tool will:
+- Register the game on the Remix platform
+- Return the **game ID** and **version ID**
+
+After `createGame` succeeds, write the returned IDs to `.remix-settings.json`:
+
+```json
+{
+  "gameId": "<returned game ID>",
+  "versionId": "<returned version ID>",
+  "name": "<game name>"
+}
+```
+
+### 4. Upload the Code
+
+Read `gameId` and `versionId` from `.remix-settings.json` (or use the values
+just obtained from `createGame`).
+
+Use the `uploadVersion` tool to upload the HTML to the game version:
+- Pass `gameId` and `versionId`
+- Pass the absolute path to the HTML file as the `filePath` argument (the tool reads the file itself — do NOT read the file contents first)
+
+The tool returns a confirmation with the game ID, version ID, and thread ID.
+
+## Tips
+
+- Always validate before uploading to catch issues early.
+- You can re-upload code to the same version as many times as needed.
+- If you need a fresh version, create a new game entry with `createGame`.