star-sdk-cli 0.1.5 → 0.1.6

package/dist/cli.mjs

@@ -1271,456 +1271,6 @@ const data = await leaderboard.getScores({
 4. **Don't store leaderboard state** - Just call the SDK methods when needed. The platform handles caching.
 
 5. **Works for guests** - Guests get a generated name like "Guest1234". They can sign in later to claim scores.`;
-var MULTIPLAYER_DOCS = `**Installation**
-
-\`\`\`bash
-yarn add star-multiplayer
-\`\`\`
-
-### Star Multiplayer SDK
-
-**Real-time multiplayer for Star games.** Host-authoritative state sync with automatic room management.
-
-**Import:**
-\`\`\`javascript
-import { createMultiplayer } from 'star-multiplayer';
-const mp = createMultiplayer();
-\`\`\`
-
-**CRITICAL:** Import in JavaScript - don't add \`<script>\` tags.
-
-**Features:**
-- **Host-authoritative** - One player runs game logic, others receive state
-- **Room-based** - Create/join rooms with 6-character invite codes
-- **Auto host migration** - If host leaves, another player becomes host
-- **Built-in lobby UI** - No need to build your own
-- **Works in iframes** - Uses postMessage relay to parent window
-
----
-
-**Quick Start:**
-
-\`\`\`javascript
-import { createMultiplayer } from 'star-multiplayer';
-import { game } from 'star-canvas';
-
-const mp = createMultiplayer();
-
-game(async ({ ctx, width, height, loop, canvas }) => {
-  // 1. Start - auto-finds or creates room, starts immediately
-  await mp.start();
-
-  // 2. Game state
-  let state = { players: {}, ball: { x: width/2, y: height/2, vx: 200, vy: 150 } };
-
-  // 3. Receive state updates - update shared objects, keep local player prediction
-  mp.onState((s) => {
-    state.ball = s.ball;
-    for (const [id, p] of Object.entries(s.players)) {
-      if (id !== mp.localPlayerId) {
-        state.players[id] = p;
-      }
-    }
-  });
-
-  // 4. Handle inputs (runs locally for prediction, on host for authoritative state)
-  mp.onInput((playerId, input) => {
-    if (!state.players[playerId]) {
-      state.players[playerId] = { y: height/2 };
-    }
-    state.players[playerId].y = input.y;
-  });
-
-  // 5. Game loop
-  loop((dt) => {
-    // Host: run physics + broadcast state (auto-throttled to 20Hz)
-    mp.hostTick(dt, () => {
-      state.ball.x += state.ball.vx * dt;
-      state.ball.y += state.ball.vy * dt;
-      if (state.ball.y < 0 || state.ball.y > height) state.ball.vy *= -1;
-      return state;
-    });
-
-    // Everyone: render with interpolation for smooth movement
-    const renderState = mp.getInterpolatedState(dt, state);
-    ctx.fillStyle = '#0f172a';
-    ctx.fillRect(0, 0, width, height);
-    for (const p of Object.values(renderState.players)) {
-      ctx.fillStyle = '#22d3ee';
-      ctx.fillRect(20, p.y - 40, 10, 80);
-    }
-    ctx.beginPath();
-    ctx.arc(renderState.ball.x, renderState.ball.y, 10, 0, Math.PI * 2);
-    ctx.fill();
-  });
-
-  // 6. Input - works for EVERYONE (applied locally for instant feedback)
-  canvas.onpointermove = (e) => {
-    const rect = canvas.getBoundingClientRect();
-    mp.input({ y: ((e.clientY - rect.top) / rect.height) * height });
-  };
-});
-\`\`\`
-
-**That's it!** The SDK handles:
-- Auto-matchmaking (finds open room or creates one)
-- URL detection (\`?room=CODE\` \u2192 joins specific room)
-- Throttling state broadcasts to 20Hz
-- Routing host's inputs to their own handler
-
----
-
-**Architecture:**
-
-\`\`\`
-Host (Player 1)          Server           Client (Player 2)
-     \u2502                     \u2502                     \u2502
-     \u2502 \u2500\u2500 state \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2502\u2500\u2500 state \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25B6\u2502
-     \u2502                     \u2502                     \u2502
-     \u2502\u25C0\u2500\u2500 input \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2502\u2500\u2500 input \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2502
-     \u2502                     \u2502                     \u2502
-     \u2502   (runs game logic) \u2502  (dumb relay)       \u2502 (renders state)
-\`\`\`
-
----
-
-**API Reference:**
-
-**State (read-only):**
-\`\`\`javascript
-mp.isHost          // true if you're the host
-mp.isReady         // true if game has started
-mp.players         // Array of { id: string }
-mp.localPlayerId   // Your player ID
-mp.roomCode        // Current room code
-\`\`\`
-
-**Setup:**
-\`\`\`javascript
-await mp.start();  // Uses all defaults - auto-matchmaking, 8 players
-
-// Or customize:
-await mp.start({
-  maxPlayers: 8,      // default: 8 (max players per room)
-  mode: 'auto',       // default: 'auto' - finds/creates rooms automatically
-                      // 'private' - shows lobby with shareable code
-  showLobby: true,    // default: true (only used in 'private' mode)
-  tickRate: 50,       // default: 50ms (20Hz state broadcasts)
-  prediction: true    // default: true (client-side prediction for instant input)
-});
-
-// Examples:
-await mp.start({ maxPlayers: 2 });                    // 1v1 game
-await mp.start({ maxPlayers: 100 });                  // Battle royale
-await mp.start({ mode: 'private' });                  // Friends-only with invite code
-await mp.start({ mode: 'private', maxPlayers: 4 });   // Small private game
-\`\`\`
-
-**Sync:**
-\`\`\`javascript
-mp.onState((state) => { ... })              // Receive state (returns unsubscribe)
-mp.onInput((playerId, input) => { ... })    // Handle continuous input (position, aim)
-mp.hostTick(dt, () => state)                // Run on host, broadcast returned state
-mp.input(data)                              // Send continuous input (position, aim)
-mp.getInterpolatedState(dt, state)          // Get smoothly interpolated state for rendering
-\`\`\`
-
-**Discrete Events (shooting, jumping, using items):**
-\`\`\`javascript
-mp.event(type, data)                        // Send event - guaranteed delivery
-mp.onEvent((playerId, type, data) => { })   // Handle events (HOST ONLY, authoritative)
-\`\`\`
-
-**Player Updates:**
-\`\`\`javascript
-mp.onLocalPlayerUpdate((player, prevPlayer) => { ... })  // Local player changed
-mp.onPlayerUpdate(playerId, (player, prevPlayer) => { ... })  // Specific player changed
-\`\`\`
-
-**Lifecycle Events:**
-\`\`\`javascript
-mp.onPlayers((players) => { ... })  // Player list changed
-mp.onPlayerJoin((player) => { ... })  // Another player joined (use to init their state)
-mp.onPlayerLeave((player) => { ... }) // A player left
-mp.onHost((isHost) => { ... })      // Host status changed (for host migration)
-mp.onError((message) => { ... })    // Error occurred
-\`\`\`
-
-**Cleanup:**
-\`\`\`javascript
-mp.leave()    // Leave room
-mp.destroy()  // Full cleanup
-\`\`\`
-
----
-
-**Tips:**
-
-1. **Use \`hostTick()\`** - It handles host detection and throttling. Don't use \`setInterval\`.
-
-2. **\`input()\` works on host** - Host's \`input()\` calls their \`onInput\` handler directly. Same code for everyone.
-
-3. **Handle host migration** - If host leaves, \`onHost(true)\` fires on new host. They should start running physics.
-
-4. **State design** - Only sync what changes: positions, scores, game objects. Not constants or textures.
-
-5. **Auto mode is default** - Players join instantly without friction. Use \`mode: 'private'\` only if you need invite codes.
-
-6. **Scale with maxPlayers** - Set \`maxPlayers: 2\` for 1v1, \`maxPlayers: 50\` for larger games. Default is 8.
-
-7. **Built-in prediction** - Your \`onInput\` handler runs immediately for local player input, eliminating input lag. Use \`mp.getInterpolatedState(dt, state)\` for smooth rendering of all players.
-
-8. **State pattern** - In \`onState\`, update shared objects (ball, score) but don't overwrite local player (keep your prediction). The SDK handles interpolation for other players.
-
-9. **Player count** - Use \`mp.players.length\` for player count in UI. Don't use \`Object.keys(state.players).length\` - that only counts players who've sent input.
-
-10. **Use \`mp.event()\` for discrete actions** - \`mp.input()\` is for continuous state (position, aim). Use \`mp.event('shoot', data)\` for discrete actions (shooting, jumping) - SDK guarantees delivery.
-
----
-
-**Where Code Runs (Important!):**
-
-| Code Type | Where | Why |
-|-----------|-------|-----|
-| Physics, collision | Host (\`hostTick\`) | Single source of truth |
-| Hit detection, damage | Host (\`onInput\`) | Prevents cheating |
-| State changes (health, score) | Host | Authoritative |
-| UI updates, messages | **Everyone** (\`onState\` or \`loop\`) | Each player sees their own |
-| Visual/sound effects | **Everyone** | Local feedback |
-| Input sending | **Everyone** (\`mp.input()\`) | All players send inputs |
-
-**Golden rule:**
-- **CHANGES state** \u2192 host only
-- **REACTS to state** \u2192 everyone locally
-
-\`\`\`javascript
-// \u274C WRONG - UI in host-only code
-mp.hostTick(dt, () => {
-  if (player.health <= 0) showDeathMessage(); // Only host sees!
-  return state;
-});
-
-// \u2705 RIGHT - React to state on every client
-mp.onState((state) => {
-  const wasAlive = localPlayer.health > 0;
-  localPlayer.health = state.players[mp.localPlayerId].health;
-  if (wasAlive && localPlayer.health <= 0) {
-    showDeathMessage(); // Everyone sees their own death!
-  }
-});
-\`\`\`
-
----
-
-**Common Patterns:**
-
-### Player Initialization (Important!)
-
-Initialize player state when they join, not when they first send input:
-
-\`\`\`javascript
-// \u274C WRONG - Players invisible until they move
-mp.onInput((playerId, input) => {
-  if (!state.players[playerId]) {
-    state.players[playerId] = { x: 0, y: 0, health: 100 };  // Too late!
-  }
-});
-
-// \u2705 RIGHT - Initialize on join
-mp.onPlayerJoin((player) => {
-  state.players[player.id] = {
-    x: Math.random() * width,
-    y: Math.random() * height,
-    health: 100
-  };
-});
-
-mp.onPlayerLeave((player) => {
-  delete state.players[player.id];
-});
-\`\`\`
-
-**Why this matters:** Without \`onPlayerJoin\`, a spectating player (not sending input) would be invisible to everyone.
-
-### Position Sync (3D/Complex Games)
-
-Clients send position, host tracks all players:
-
-\`\`\`javascript
-// Everyone: Send position every frame
-mp.input({
-  pos: [localPlayer.x, localPlayer.y, localPlayer.z],
-  yaw: localPlayer.yaw
-});
-
-// Host: Track in onInput
-const remotePlayers = {};
-mp.onInput((playerId, input) => {
-  if (!remotePlayers[playerId]) remotePlayers[playerId] = { health: 100 };
-  if (input.pos) {
-    remotePlayers[playerId].pos = input.pos;
-    remotePlayers[playerId].yaw = input.yaw;
-  }
-});
-\`\`\`
-
-### Actions (Shooting, Jumping, Items) - Use \`mp.event()\`
-
-**For discrete actions, use \`mp.event()\` instead of \`mp.input()\`.** The SDK guarantees delivery, deduplication, and preserves each event's data.
-
-**The Pattern:**
-
-\`\`\`javascript
-// \u274C WRONG - mp.input() loses rapid discrete actions (30Hz throttling)
-mp.input({ shoot: true }); // 3 rapid clicks = 1 shot!
-
-// \u2705 RIGHT - Two parts: cosmetic (instant) + authoritative (host)
-
-// PART 1: At the trigger point (EVERYONE runs this)
-if (shooting && canShoot(localPlayer)) {
-  // Cosmetic feedback - instant, local only
-  audio.play('shoot');
-  particles.muzzleFlash(localPlayer.pos);
-
-  // Send event to host for authoritative processing
-  mp.event('shoot', {
-    origin: [x, y, z],
-    dir: [dx, dy, dz]
-  });
-}
-
-// PART 2: Authoritative handler (HOST ONLY processes this)
-mp.onEvent((playerId, type, data) => {
-  if (type === 'shoot') {
-    // This creates the REAL bullet in game state
-    state.bullets.push({
-      owner: playerId,
-      pos: data.origin,
-      dir: data.dir
-    });
-  }
-});
-\`\`\`
-
-**Why two parts?**
-
-| Part | Who runs it | What it does |
-|------|-------------|--------------|
-| Cosmetic (at call site) | Everyone | Instant feedback: sound, particles, animations |
-| Authoritative (\`onEvent\`) | Host only | State changes: spawn bullets, apply damage |
-
-**This separation is intentional:**
-- **Cosmetic:** Your own shots feel instant (no network latency)
-- **Authoritative:** Game state is consistent (host is source of truth)
-- **Other players' bullets:** Appear in state broadcast, ~50ms later (acceptable for casual games)
-
-**Hearing other players' shots (optional):**
-\`\`\`javascript
-const seenBullets = new Set();
-mp.onState((state) => {
-  for (const bullet of state.bullets || []) {
-    if (!seenBullets.has(bullet.id) && bullet.owner !== mp.localPlayerId) {
-      audio.play('shoot');  // Hear remote player's shot
-      seenBullets.add(bullet.id);
-    }
-  }
-});
-\`\`\`
-
-**When to use which:**
-| Action Type | Method | Example |
-|-------------|--------|---------|
-| Continuous state | \`mp.input()\` | Position, aim direction, movement |
-| Discrete action | \`mp.event()\` | Shooting, jumping, using items, emotes |
-
-### Health (Host-Authoritative)
-
-Host owns health. Clients accept and react:
-
-\`\`\`javascript
-// \u274C WRONG - Client sends health (cheatable!)
-mp.input({ health: localPlayer.health });
-
-// \u2705 RIGHT - Host applies damage
-mp.onInput((playerId, input) => {
-  if (hit.playerId) remotePlayers[hit.playerId].health -= 25;
-});
-
-// \u2705 RIGHT - Client accepts AND reacts
-mp.onState((state) => {
-  const myHealth = state.players[mp.localPlayerId]?.health;
-  if (myHealth !== undefined) {
-    if (localPlayer.health > 0 && myHealth <= 0) showDeathMessage();
-    localPlayer.health = myHealth;
-  }
-});
-\`\`\`
-
-### Reacting to Player State Changes (Death, Score, etc.)
-
-Use \`onLocalPlayerUpdate\` to react when your player's state changes - the SDK tracks previous state for you:
-
-\`\`\`javascript
-mp.onLocalPlayerUpdate((player, prevPlayer) => {
-  // Detect death
-  if (prevPlayer.health > 0 && player.health <= 0) {
-    showDeathScreen();
-  }
-
-  // Detect respawn
-  if (prevPlayer.health <= 0 && player.health > 0) {
-    hideDeathScreen();
-  }
-
-  // Detect score increase
-  if (player.score > (prevPlayer.score || 0)) {
-    showScorePopup(player.score - prevPlayer.score);
-  }
-});
-\`\`\`
-
-For remote player effects (death animations, etc.):
-
-\`\`\`javascript
-// Subscribe to each remote player's updates
-for (const p of mp.players) {
-  if (p.id !== mp.localPlayerId) {
-    mp.onPlayerUpdate(p.id, (player, prev) => {
-      if (prev.health > 0 && player.health <= 0) {
-        playDeathAnimation(p.id);
-      }
-    });
-  }
-}
-\`\`\`
-
----
-
-**Anti-Patterns:**
-
-### Using \`mp.input()\` for Discrete Actions
-
-**Problem**: Using \`mp.input({ shoot: true })\` for shooting, jumping, or any discrete action.
-
-**Why it breaks**: \`mp.input()\` is throttled to 30Hz. Multiple rapid clicks collapse into a single value, losing inputs.
-
-\`\`\`javascript
-// \u274C BAD - mp.input() loses rapid discrete actions
-mp.input({ shoot: true }); // 3 rapid clicks = 1 shot!
-
-// \u274C ALSO BAD - counters in mp.input() still have issues
-mp.input({ shootCount: count }); // Bursts all shots at once, loses timing
-
-// \u2705 GOOD - Use mp.event() for discrete actions
-mp.event('shoot', { origin, dir }); // Each event preserved with its data
-\`\`\`
-
-**The rule is simple:**
-
-| Action Type | Method | Why |
-|-------------|--------|-----|
-| **Continuous** (position, aim) | \`mp.input()\` | Last value is correct, throttling is fine |
-| **Discrete** (shoot, jump, use item) | \`mp.event()\` | Each action must be delivered with its data |`;
 
 // src/cli.ts
 var VERSION = "0.1.0";
@@ -1909,7 +1459,7 @@ function whoamiCommand() {
 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."
+    "For detailed API docs: `npx star-sdk docs <topic>` where topic is audio, canvas, or leaderboard."
   );
 }
 function getAllDocsContent() {
@@ -1931,13 +1481,7 @@ ${CANVAS_DOCS}
 
 # Leaderboard API
 
-${LEADERBOARD_DOCS}
-
----
-
-# Multiplayer API
-
-${MULTIPLAYER_DOCS}`;
+${LEADERBOARD_DOCS}`;
 }
 function installClaudeCode(scope) {
   const skillDir = scope === "global" ? path.join(os.homedir(), ".claude", "skills", "star-sdk") : path.join(process.cwd(), ".claude", "skills", "star-sdk");
@@ -1946,7 +1490,6 @@ function installClaudeCode(scope) {
   fs.writeFileSync(path.join(skillDir, "audio.md"), AUDIO_DOCS);
   fs.writeFileSync(path.join(skillDir, "canvas.md"), CANVAS_DOCS);
   fs.writeFileSync(path.join(skillDir, "leaderboard.md"), LEADERBOARD_DOCS);
-  fs.writeFileSync(path.join(skillDir, "multiplayer.md"), MULTIPLAYER_DOCS);
   log("");
   success(`Star SDK skill installed to ${skillDir}`);
   log("");
@@ -1957,7 +1500,6 @@ function installClaudeCode(scope) {
   log(`  audio.md        ${colors.dim}Star.audio API docs${colors.reset}`);
   log(`  canvas.md       ${colors.dim}Star.game() API docs${colors.reset}`);
   log(`  leaderboard.md  ${colors.dim}Star.leaderboard API docs${colors.reset}`);
-  log(`  multiplayer.md  ${colors.dim}Star.multiplayer API docs${colors.reset}`);
   log("");
 }
 function installCodex(scope) {
@@ -1988,7 +1530,7 @@ function installCursor() {
   const rulesDir = path.join(process.cwd(), ".cursor", "rules");
   const filePath = path.join(rulesDir, "star-sdk.mdc");
   const content = `---
-description: Star SDK for browser game development with audio, canvas, leaderboards, and multiplayer
+description: Star SDK for browser game development with audio, canvas, and leaderboards
 globs: ["**/*.js", "**/*.ts", "**/*.jsx", "**/*.tsx", "**/*.html"]
 alwaysApply: false
 ---
@@ -2072,8 +1614,7 @@ function docsCommand(topic) {
     skill: SKILL_CONTENT,
     audio: AUDIO_DOCS,
     canvas: CANVAS_DOCS,
-    leaderboard: LEADERBOARD_DOCS,
-    multiplayer: MULTIPLAYER_DOCS
+    leaderboard: LEADERBOARD_DOCS
   };
   if (!topic) {
     console.log(transformForStdout(SKILL_CONTENT));
@@ -2082,7 +1623,7 @@ function docsCommand(topic) {
   } else {
     error(`Unknown topic: ${topic}`);
     log("");
-    log("Available topics: skill, audio, canvas, leaderboard, multiplayer");
+    log("Available topics: skill, audio, canvas, leaderboard");
     process.exit(1);
   }
 }

package/package.json

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