star-sdk-cli 0.1.3 → 0.1.5

package/dist/cli.mjs

@@ -61,6 +61,17 @@ Star.game(ctx => {
 });
 \`\`\`
 
+## Initialization (Required for Leaderboards)
+
+If using leaderboards outside the Star platform (local dev, self-hosted), initialize with your game ID:
+
+\`\`\`javascript
+import Star from 'star-sdk';
+
+// Get your gameId from .starrc (created by: npx star-sdk init "Game Name")
+Star.init({ gameId: 'your-game-id-here' });
+\`\`\`
+
 ## Common Patterns
 
 ### Game Over -> Submit Score -> Show Leaderboard
@@ -110,6 +121,9 @@ Only these 17 presets exist:
 \`\`\`javascript
 import Star from 'star-sdk';
 
+// Initialize for leaderboard support (get gameId from .starrc)
+Star.init({ gameId: 'your-game-id' });
+
 Star.game(ctx => {
   const { canvas, width, height, ctx: c } = ctx;
   let score = 0;
@@ -314,7 +328,7 @@ var CANVAS_DOCS = `**Installation**
 First, add the package to your project:
 
 \`\`\`bash
-yarn add star-dom
+yarn add star-canvas
 \`\`\`
 
 ### Star DOM SDK
@@ -662,7 +676,7 @@ game(({ ctx, width, height, loop, toStagePoint, canvas }) => {
 
 \`\`\`ts
 import { game } from 'star-canvas';
-import { createLeaderboard } from '/star-sdk/v1/leaderboard.js';
+import { createLeaderboard } from 'star-leaderboard';
 
 const leaderboard = createLeaderboard();
 
@@ -919,7 +933,86 @@ game(({ ctx, width, height, loop, canvas, toStagePoint }) => {
 4. \u274C Not clearing state on pointerup \u2192 \`createDrag()\` fixes this
 5. \u274C Missing \`setPointerCapture()\` (drags break outside canvas) \u2192 **You must add this!**
 
-**Recommendation:** Use \`createDrag()\` + \`setPointerCapture()\` for bulletproof drag-and-drop.`;
+**Recommendation:** Use \`createDrag()\` + \`setPointerCapture()\` for bulletproof drag-and-drop.
+
+### Recipe 9: Image Backgrounds
+
+Two patterns for backgrounds: **full-canvas** (unique scenes) or **tileable patterns** (repeating textures).
+
+**Full-canvas background (scaled to fit):**
+
+\`\`\`ts
+import { game } from 'star-canvas';
+
+game(({ ctx, width, height, loop }) => {
+  const bg = new Image();
+  bg.src = 'https://example.com/background.png';  // Use generated asset URL
+
+  const player = { x: 320, y: 300 };
+
+  loop((dt) => {
+    // Draw background scaled to canvas (no tiling)
+    if (bg.complete) {
+      ctx.drawImage(bg, 0, 0, width, height);
+    } else {
+      ctx.fillStyle = '#1e293b';  // Fallback color while loading
+      ctx.fillRect(0, 0, width, height);
+    }
+
+    // Draw game objects on top
+    ctx.fillStyle = '#22d3ee';
+    ctx.fillRect(player.x - 16, player.y - 16, 32, 32);
+  });
+});
+\`\`\`
+
+**Tileable pattern background (repeating texture):**
+
+\`\`\`ts
+import { game } from 'star-canvas';
+
+game(({ ctx, width, height, loop }) => {
+  const tile = new Image();
+  tile.src = 'https://example.com/grass_tile.png';  // Use generated asset URL (seamlessTile: true)
+
+  let pattern = null;
+  tile.onload = () => {
+    pattern = ctx.createPattern(tile, 'repeat');
+  };
+
+  const player = { x: 320, y: 300 };
+
+  loop((dt) => {
+    // Draw tiled background
+    if (pattern) {
+      ctx.fillStyle = pattern;
+      ctx.fillRect(0, 0, width, height);
+    } else {
+      ctx.fillStyle = '#22c55e';  // Fallback color while loading
+      ctx.fillRect(0, 0, width, height);
+    }
+
+    // Draw game objects on top
+    ctx.fillStyle = '#3b82f6';
+    ctx.fillRect(player.x - 16, player.y - 16, 32, 32);
+  });
+});
+\`\`\`
+
+**When to use which:**
+
+| Type | Size | Use Case | Generation Settings |
+|------|------|----------|---------------------|
+| Full-canvas | 1024\xD71024 | Unique scenes, landscapes, detailed environments | \`model: "gemini"\`, no \`seamlessTile\` |
+| Tileable (all directions) | 256\xD7256 or 512\xD7512 | Grass, water, brick, abstract patterns | \`model: "gemini"\`, \`seamlessTile: "both"\` |
+| Horizontal tiling | 256\xD7512 or similar | Side-scroller parallax layers, horizon lines | \`model: "gemini"\`, \`seamlessTile: "horizontal"\` |
+| Vertical tiling | 512\xD7256 or similar | Vertical scroller backgrounds | \`model: "gemini"\`, \`seamlessTile: "vertical"\` |
+
+**Common mistakes:**
+- \u274C Generating a detailed scene and expecting it to tile \u2192 Use \`seamlessTile\` only for patterns
+- \u274C Using \`drawImage()\` without size params \u2192 Image won't scale to canvas
+- \u274C Not handling image load state \u2192 Blank canvas until loaded
+- \u274C Using \`seamlessTile: "both"\` when you only need one direction \u2192 AI has better success with single-axis tiling`;
 var LEADERBOARD_DOCS = `**Installation**
 
 \`\`\`bash
@@ -944,7 +1037,7 @@ const leaderboard = createLeaderboard();
 
 \`\`\`javascript
 import { createLeaderboard } from 'star-leaderboard';
-import { game } from '/star-sdk/v1/dom.js';
+import { game } from 'star-canvas';
 
 const leaderboard = createLeaderboard();
 
@@ -1033,7 +1126,7 @@ async function gameOver(finalScore) {
 
 \`\`\`javascript
 import { createLeaderboard } from 'star-leaderboard';
-import { game } from '/star-sdk/v1/dom.js';
+import { game } from 'star-canvas';
 
 const leaderboard = createLeaderboard();
 
@@ -1079,7 +1172,7 @@ async function showCustomLeaderboard() {
 
 \`\`\`javascript
 import { createLeaderboard } from 'star-leaderboard';
-import { game } from '/star-sdk/v1/dom.js';
+import { game } from 'star-canvas';
 
 const leaderboard = createLeaderboard();
 
@@ -1209,7 +1302,7 @@ const mp = createMultiplayer();
 
 \`\`\`javascript
 import { createMultiplayer } from 'star-multiplayer';
-import { game } from '/star-sdk/v1/dom.js';
+import { game } from 'star-canvas';
 
 const mp = createMultiplayer();
 
@@ -1662,7 +1755,7 @@ ${colors.bright}Star SDK CLI${colors.reset} v${VERSION}
 ${colors.dim}Commands:${colors.reset}
   ${colors.cyan}init <name>${colors.reset}        Register a new game
   ${colors.cyan}install [agent]${colors.reset}    Install Star SDK docs for AI coding agents
-  ${colors.cyan}docs [topic]${colors.reset}       Print API documentation to stdout
+  ${colors.cyan}docs [topic]${colors.reset}       Print API documentation (default: all docs)
   ${colors.cyan}whoami${colors.reset}             Show current configuration
 
 ${colors.dim}Supported agents:${colors.reset}
@@ -1691,8 +1784,9 @@ ${colors.dim}Examples:${colors.reset}
   npx star-sdk install aider     ${colors.dim}# Aider${colors.reset}
 
   ${colors.dim}# Print API docs (works with any LLM)${colors.reset}
-  npx star-sdk docs
-  npx star-sdk docs audio
+  npx star-sdk docs              ${colors.dim}# All docs${colors.reset}
+  npx star-sdk docs audio        ${colors.dim}# Just audio API${colors.reset}
+  npx star-sdk docs skill        ${colors.dim}# Just main skill file${colors.reset}
 
 ${colors.dim}Learn more:${colors.reset} https://buildwithstar.com/docs
 `);
@@ -1766,11 +1860,14 @@ async function initCommand(name, email) {
     log(`${colors.dim}Config saved to${colors.reset} ${colors.bright}.starrc${colors.reset}`);
     log("");
     log(`${colors.dim}Next steps:${colors.reset}`);
-    log(`  1. Import Star SDK in your game`);
-    log(`  2. Use Star.leaderboard.submit(score) to submit scores`);
+    log(`  1. Install: ${colors.cyan}npm install star-sdk${colors.reset}`);
+    log(`  2. Import Star SDK in your game`);
+    log(`  3. Initialize with your game ID`);
+    log(`  4. Use Star.leaderboard.submit(score) to submit scores`);
     log("");
     log(`${colors.dim}Example:${colors.reset}`);
     log(`  ${colors.cyan}import Star from 'star-sdk';${colors.reset}`);
+    log(`  ${colors.cyan}Star.init({ gameId: '${data.gameId}' });${colors.reset}`);
     log(`  ${colors.cyan}Star.leaderboard.submit(1500);${colors.reset}`);
     log("");
     log(`${colors.dim}Using an AI coding agent?${colors.reset}`);
@@ -1809,6 +1906,12 @@ function whoamiCommand() {
   }
   log("");
 }
+function transformForStdout(content) {
+  return content.replace(/\[(\w+)\.md\]\(\.\/\1\.md\)/g, "$1 (`npx star-sdk docs $1`)").replace(/see (\w+)\.md/g, "run `npx star-sdk docs $1`").replace(
+    /For detailed API documentation, see the linked files above\./,
+    "For detailed API docs: `npx star-sdk docs <topic>` where topic is audio, canvas, leaderboard, or multiplayer."
+  );
+}
 function getAllDocsContent() {
   return `${SKILL_CONTENT}
 
@@ -1966,19 +2069,20 @@ function installCommand(agent = "claude", scope = "global") {
 }
 function docsCommand(topic) {
   const docs = {
+    skill: SKILL_CONTENT,
     audio: AUDIO_DOCS,
     canvas: CANVAS_DOCS,
     leaderboard: LEADERBOARD_DOCS,
     multiplayer: MULTIPLAYER_DOCS
   };
   if (!topic) {
-    console.log(SKILL_CONTENT);
+    console.log(transformForStdout(SKILL_CONTENT));
   } else if (docs[topic]) {
     console.log(docs[topic]);
   } else {
     error(`Unknown topic: ${topic}`);
     log("");
-    log("Available topics: audio, canvas, leaderboard, multiplayer");
+    log("Available topics: skill, audio, canvas, leaderboard, multiplayer");
     process.exit(1);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "star-sdk-cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "CLI tool for Star SDK - register games and manage leaderboards",
   "type": "module",
   "bin": {