@remix-gg/mcp 0.4.3

package/skills/workflows/add-image-to-game.md

@@ -0,0 +1,121 @@
+# Add Image to Game Workflow
+
+## Overview
+
+This skill guides you through generating an AI image and integrating its hosted
+URL into your game HTML. The `generateImage` tool handles generation **and**
+upload in one step, returning a hosted URL directly.
+
+## Prerequisites
+
+- The game HTML file must already exist (follow the **game-creation** workflow
+  first if starting from scratch).
+- A game must be created on the Remix platform (you need a game ID for
+  `generateImage`).
+
+## Steps
+
+### 1. Check for Existing Game ID
+
+**IMPORTANT: Do NOT call `createGame` without checking first.**
+
+Read `.remix-settings.json` in the current directory. If it exists and contains
+a `gameId`, use that value — the game is already created and you can skip
+straight to step 2.
+
+Only if `.remix-settings.json` does not exist or has no `gameId` should you
+follow the **upload-game** workflow to create one.
+
+### 2. Generate and Upload the Image
+
+Call `generateImage` with the game ID and a descriptive prompt. The tool
+generates the image, uploads it as a game asset, and returns a text block
+containing the hosted URL.
+
+```
+generateImage({
+  gameId: "<your-game-id>",
+  prompt: "a pixel-art treasure chest on a grassy hill",
+  fileName: "treasure-chest"   // optional — defaults to a slugified prompt
+})
+```
+
+The `fileName` is just a base name without extension — the file extension is
+determined by the image format returned from the server. Prompts do not need to
+specify transparency, background removal, or other formatting details — the
+server augments prompts automatically for game-ready output.
+
+The response is a single **text** block with the asset URL, file name, and
+prompt. No base64 image data is returned.
+
+### 3. Integrate the URL into the Game
+
+Add the asset URL to the game HTML. **Size the image to match the game entity
+it represents** — do not render it at its native resolution. For example, if a
+treasure chest is a 32x32 tile in your game, draw or display the image at 32x32
+regardless of the source image dimensions.
+
+The integration method depends on how the image is used:
+
+**As an HTML image element:**
+```html
+<img src="https://returned-asset-url.png" alt="Treasure chest" width="32" height="32" />
+```
+
+**As a CSS background:**
+```css
+.game-bg {
+  background-image: url("https://returned-asset-url.png");
+}
+```
+
+**As a JavaScript-loaded image (for canvas games):**
+```js
+const img = new Image();
+img.src = "https://returned-asset-url.png";
+img.onload = () => {
+  // draw at the entity's size, not the image's native size
+  ctx.drawImage(img, x, y, entityWidth, entityHeight);
+};
+```
+
+## Examples
+
+### Adding a Background to a Canvas Game
+
+```js
+const bg = new Image();
+bg.src = "https://uploaded-asset-url/background.png";
+bg.onload = () => {
+  function draw() {
+    ctx.drawImage(bg, 0, 0, canvas.width, canvas.height);
+    // draw game objects on top...
+    requestAnimationFrame(draw);
+  }
+  draw();
+};
+```
+
+### Adding a Sprite Sheet
+
+```js
+const spriteSheet = new Image();
+spriteSheet.src = "https://uploaded-asset-url/player-sprites.png";
+spriteSheet.onload = () => {
+  // draw a 32x32 frame from the sprite sheet
+  ctx.drawImage(spriteSheet, frameX, frameY, 32, 32, player.x, player.y, 32, 32);
+};
+```
+
+## Tips
+
+- **Be specific in prompts.** Include art style, color palette, and context
+  (e.g. "pixel-art 16-bit style red dragon"). No need to specify transparency
+  or background handling — the server takes care of that.
+- **Use descriptive file names.** Pass `fileName: "player-idle-sprite"`
+  instead of relying on the auto-generated slug. Do not include a file
+  extension — it is determined by the generated image format.
+- **Preload images before gameplay.** Wait for `onload` before starting the
+  game loop to avoid flickering or missing assets.
+- **Repeat for multiple images.** Run through steps 2-3 for each image the
+  game needs.

package/skills/workflows/add-sprite-to-game.md

@@ -0,0 +1,127 @@
+# Add Sprite Sheet to Game Workflow
+
+## Overview
+
+This skill guides you through generating an animated sprite sheet and
+integrating it into your game. The `generateSpriteSheet` tool generates a
+grid of animation frames using AI, removes the background, and returns
+hosted URLs for both the original and transparent versions.
+
+## When to Use Sprite Sheets vs Single Images
+
+| Use case | Tool |
+|---|---|
+| Static object (background, item, UI element) | `generateImage` |
+| Animated character, effect, or object with multiple frames | `generateSpriteSheet` |
+
+Use sprite sheets whenever you need animation — walking cycles, attacks,
+explosions, coin spins, etc.
+
+## Prerequisites
+
+- The game HTML file must already exist (follow the **game-creation** workflow
+  first if starting from scratch).
+- A game must be created on the Remix platform (you need a game ID).
+
+## Steps
+
+### 1. Check for Existing Game ID
+
+**IMPORTANT: Do NOT call `createGame` without checking first.**
+
+Read `.remix-settings.json` in the current directory. If it exists and contains
+a `gameId`, use that value. Only if it does not exist should you follow the
+**upload-game** workflow to create one.
+
+### 2. Generate the Sprite Sheet
+
+Call `generateSpriteSheet` with the game ID, a descriptive prompt, and
+optionally a grid size (default 4 = 4x4 = 16 frames).
+
+```
+generateSpriteSheet({
+  gameId: "<your-game-id>",
+  prompt: "a pixel-art knight walking, side view, 2D game character",
+  gridSize: 4
+})
+```
+
+The response includes:
+- `spriteUrl` — the original sprite sheet image
+- `transparentSpriteUrl` — background-removed version (use this one in games)
+- `metadata.gridSize` — number of rows/columns
+- `metadata.gridDimensions` — e.g. "4x4"
+- `promptRewritten` — the enhanced prompt used by the AI
+- `warnings` — any issues to be aware of
+
+### 3. Integrate the Sprite Sheet into the Game
+
+Use the `transparentSpriteUrl` in your game code. Here is a complete
+pattern for loading and animating a sprite sheet on a canvas:
+
+```js
+const GRID_SIZE = 4;           // must match the gridSize you requested
+const FRAME_COUNT = GRID_SIZE * GRID_SIZE;
+const FRAME_DURATION = 100;    // ms per frame
+
+const spriteSheet = new Image();
+spriteSheet.src = "https://returned-transparent-sprite-url.png";
+
+let currentFrame = 0;
+let lastFrameTime = 0;
+
+spriteSheet.onload = () => {
+  const frameWidth = spriteSheet.width / GRID_SIZE;
+  const frameHeight = spriteSheet.height / GRID_SIZE;
+
+  function animate(timestamp) {
+    if (timestamp - lastFrameTime >= FRAME_DURATION) {
+      currentFrame = (currentFrame + 1) % FRAME_COUNT;
+      lastFrameTime = timestamp;
+    }
+
+    const col = currentFrame % GRID_SIZE;
+    const row = Math.floor(currentFrame / GRID_SIZE);
+
+    ctx.clearRect(x, y, entityWidth, entityHeight);
+    ctx.drawImage(
+      spriteSheet,
+      col * frameWidth, row * frameHeight,   // source x, y
+      frameWidth, frameHeight,                // source width, height
+      x, y,                                   // destination x, y
+      entityWidth, entityHeight               // destination width, height
+    );
+
+    requestAnimationFrame(animate);
+  }
+
+  requestAnimationFrame(animate);
+};
+```
+
+### 4. Choosing Grid Size
+
+| Grid size | Frames | Best for |
+|---|---|---|
+| 2 (2x2) | 4 | Simple loops: coin spin, blinking |
+| 3 (3x3) | 9 | Short animations: jump, attack |
+| 4 (4x4) | 16 | Standard walk/run cycles (default) |
+| 5 (5x5) | 25 | Detailed animations: explosions |
+| 6 (6x6) | 36 | Complex sequences: combo attacks |
+
+## Tips
+
+- **Be specific in prompts.** Include art style, perspective, and animation
+  type. Example: "a pixel-art wizard casting a fireball spell, side view,
+  2D game character". The server enhances prompts automatically, but
+  specificity helps.
+- **Use `transparentSpriteUrl`** for in-game rendering — it has the
+  background removed so sprites composite cleanly over your game scene.
+- **Match `GRID_SIZE` to your request.** If you pass `gridSize: 3`, set
+  `GRID_SIZE = 3` in your animation code.
+- **Preload before gameplay.** Wait for `onload` before starting the game
+  loop to avoid missing frames.
+- **Adjust `FRAME_DURATION`** to control animation speed. Lower values
+  (50–80ms) feel snappy; higher values (120–200ms) feel relaxed.
+- **Use a reference image** by passing `imageUrl` if you want the sprite
+  to match an existing character design.

package/skills/workflows/game-creation.md

@@ -0,0 +1,124 @@
+# Game Creation Workflow
+
+## Overview
+
+This skill guides you through creating a new HTML game on the Remix platform.
+
+## Prerequisites
+
+- The `REMIX_API_KEY` environment variable must be set.
+
+## Constraints
+
+- The game must target a **2:3 aspect ratio** (e.g. 720×1080).
+- It must fill the entire viewport at that ratio — use `width: 100vw; height: 100vh`
+  on the game container. No scrollbars, no overflow.
+- The game **must support touch controls** as the primary input method (the Remix
+  platform is primarily mobile/touch-based). Keyboard and mouse controls are
+  welcome but optional.
+
+## Steps
+
+### 1. Check for Existing Game
+
+Before doing anything else, check if a `.remix-settings.json` file exists in
+the project root. If it contains `gameId` and `versionId`, you already have a
+registered game — **do NOT call `createGame` again**. Use the existing IDs for
+all subsequent tool calls (uploadVersion, generateImage, etc.).
+
+Only proceed to create a new game (via the **upload-game** workflow) if no
+settings file exists or it is missing `gameId`/`versionId`.
+
+### 2. Clarify the Brief (if needed)
+
+Assess the user's description before planning. If it gives you enough to build a
+focused, fun first version, **skip this step** and go straight to planning.
+
+**Skip clarification if the description covers:**
+- What type of game it is (genre or mechanic)
+- The core loop or win/lose condition
+- A visual style or theme
+- Any special requirements (e.g. specific controls, progression, power-ups)
+
+**Ask questions when the description is short, vague, or ambiguous** — for
+example: "make a fun game", "build a platformer", or "I want something relaxing".
+
+When you do ask, keep it to **3–5 focused questions** drawn from these areas:
+
+- **Game type / mechanic**: "Is this a tap-to-jump endless runner, a side-scrolling
+  platformer with levels, or something else?"
+- **Win/lose condition**: "Does the player try to reach a high score, complete a
+  level, survive as long as possible, or something else?"
+- **Theme / visuals**: "Any preferred visual style — pixel art, minimal shapes,
+  a specific color palette, or a theme like space/jungle/retro?"
+- **Difficulty & progression**: "Should difficulty ramp up over time, or stay
+  constant?"
+- **Audio**: "Should the game have sound effects and/or music, or be silent by
+  default?"
+
+Only ask questions that will meaningfully change the game. Do **not** ask if the
+answer is obvious from context or if it won't affect the first version.
+
+### 3. Plan the Game
+
+Decide on the game concept, mechanics, and visual style. Keep scope small —
+a single-file HTML game should be playable in under 30 seconds.
+
+### 4. Write the HTML
+
+Create a single HTML file with inline `<style>` and `<script>` tags. Structure:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Game Title</title>
+  <script src="https://cdn.jsdelivr.net/npm/@remix-gg/sdk@latest/dist/index.min.js"></script>
+  <style>
+    /* Game styles can go here */
+  </style>
+</head>
+<body>
+  <!-- Game markup can go here -->
+  <script>
+    // Game logic here
+  </script>
+</body>
+</html>
+```
+
+### Required RemixSDK Functions
+
+The `validateGame` tool checks that all three of these are present:
+
+1. **`RemixSDK.singlePlayer.actions.gameOver({ score })`** — Call when the game
+   ends, passing the player's final score as `{ score: number }`. This reports
+   the score to the platform.
+
+2. **`RemixSDK.onPlayAgain(callback)`** — Register a callback (no arguments)
+   that fires when the player requests to play again. The callback should reset
+   game state and restart the game.
+
+3. **`RemixSDK.onToggleMute(callback)`** — Register a callback that receives
+   `{ isMuted: boolean }`. The game must mute or unmute all audio based on the
+   `isMuted` value.
+
+### 5. Validate
+
+Use the `validateGame` tool with the game's `filePath` to check for common issues.
+Do NOT read the game file — the tool reads it internally. Fix any issues
+the tool reports before proceeding.
+
+### 6. Upload the Game
+
+Follow the **upload-game** workflow to create the game on the Remix platform and
+deploy your HTML code. Remember: if you already have IDs from step 1, the
+upload-game workflow will skip game creation and go straight to uploading.
+
+## Tips
+
+- Use `requestAnimationFrame` for game loops, not `setInterval`.
+- Touch controls are required (primary input); keyboard/mouse are optional extras.
+- Keep the total HTML under 100KB for fast loading.