star-sdk-cli 0.1.18 → 0.1.20

package/dist/cli.mjs

@@ -122,6 +122,17 @@ function endGame() {
 }
 \`\`\`
 
+### Submit with Player Name (Arcade Style)
+
+Let players enter their name on game over \u2014 classic arcade feel. If skipped, a guest name is auto-generated.
+
+\`\`\`javascript
+Star.leaderboard.submit(score, { playerName: 'ACE' });  // Custom name
+Star.leaderboard.submit(score);                          // Auto guest name
+\`\`\`
+
+Collect the name on game over using \`g.ui.render()\` for an input field. See \`leaderboard.md\` Pattern 4.
+
 ### Submit Score Only (No UI)
 
 \`\`\`javascript
@@ -154,6 +165,18 @@ Star.audio.preload({ coin: 'coin', jump: 'jump' });
 Star.audio.play('coin');  // Works on mobile, desktop, everywhere
 \`\`\`
 
+### Hover Effects for Canvas Buttons
+
+\`g.pointer\` tracks position every frame \u2014 use it for hover states:
+
+\`\`\`javascript
+g.loop((dt) => {
+  const hoverLb = state === 'gameover' && inRect(g.pointer, lbBtn);
+  drawButton('VIEW LEADERBOARD', lbBtn, hoverLb ? '#9061f9' : '#7c3aed');
+  g.canvas.style.cursor = hoverLb ? 'pointer' : 'default';
+});
+\`\`\`
+
 ### Coordinate Handling
 
 \`g.tap\` and \`g.pointer\` are already in canvas-space coordinates. No conversion needed:
@@ -574,6 +597,7 @@ A safe manager for your HTML overlay, stacked on top of the canvas.
   - \`ui.render(html: string)\`: **Use this** to set your UI. It's safe and won't destroy the canvas.
     - Automatically skips updates if HTML is unchanged (safe to call in loop for static content)
     - For best performance with dynamic content (score), only call when values actually change
+    - **Positioning:** The UI overlay covers the full viewport, not just the letterboxed game area. Use percentage-based positioning (e.g., \`top: 50%; left: 50%; transform: translate(-50%, -50%)\`) to stay centered within the visible area. Fixed offsets like \`bottom: 18px\` may land in the letterbox bars on some screen sizes.
   - \`ui.el(selector)\`: Scoped \`querySelector\` for the UI root.
   - \`ui.all(selector)\`: Scoped \`querySelectorAll\` for the UI root.
 
@@ -630,6 +654,15 @@ g.loop((dt) => {
 });
 \`\`\`
 
+**Hover effects for canvas buttons:**
+\`\`\`ts
+g.loop((dt) => {
+  const hoverLb = state === 'gameover' && inRect(g.pointer, lbBtn);
+  drawButton('VIEW LEADERBOARD', lbBtn, hoverLb ? '#9061f9' : '#7c3aed');
+  g.canvas.style.cursor = hoverLb ? 'pointer' : 'default';
+});
+\`\`\`
+
 Taps on interactive UI elements (from \`on()\` or native \`<button>\`) are automatically suppressed from \`g.tap\`.
 
 ### Cursor Management
@@ -1249,10 +1282,11 @@ game(({ ctx, width, height, loop, ui, on, canvas }) => {
 
 **Core Methods:**
 \`\`\`javascript
-leaderboard.submit(score)       // Submit score, returns Promise<{ success, rank, scoreId }>
-leaderboard.show()              // Show leaderboard UI
-leaderboard.getScores(options)  // Fetch scores for custom UI
-leaderboard.share(options)      // Generate shareable link
+leaderboard.submit(score)                      // Submit score (guest name auto-generated)
+leaderboard.submit(score, { playerName })      // Submit with custom player name
+leaderboard.show()                             // Show leaderboard UI
+leaderboard.getScores(options)                 // Fetch scores for custom UI
+leaderboard.share(options)                     // Generate shareable link
 \`\`\`
 
 **Properties:**
@@ -1325,7 +1359,20 @@ game(({ ui, on }) => {
 });
 \`\`\`
 
-### Pattern 4: Custom Leaderboard UI
+### Pattern 4: Custom Player Names
+
+Players can set their own name for the leaderboard:
+
+\`\`\`javascript
+leaderboard.submit(score, { playerName: 'ACE' });  // Custom name
+leaderboard.submit(score);                          // Auto guest name
+\`\`\`
+
+If \`playerName\` is not provided, a guest name like "Guest1234" is auto-generated.
+
+A natural place to collect the name is on the game over screen (arcade-style "enter your initials"). Use \`ui.render()\` for the input field and \`on()\` for handlers. Call \`submitScore()\` before \`show()\` or \`startGame()\` so the score saves even if the player skips the name input. Store \`playerName\` outside the loop so it persists across rounds.
+
+### Pattern 5: Custom Leaderboard UI
 
 \`\`\`javascript
 import { createLeaderboard } from 'star-leaderboard';
@@ -1349,7 +1396,7 @@ async function showCustomLeaderboard() {
 }
 \`\`\`
 
-### Pattern 5: Full Game Example
+### Pattern 6: Full Game Example
 
 \`\`\`javascript
 import { createLeaderboard } from 'star-leaderboard';
@@ -1357,7 +1404,8 @@ import { game } from 'star-canvas';
 
 const leaderboard = createLeaderboard({ gameId: '<gameId from .starrc>' });
 
-game(({ ctx, width, height, loop, ui, on, canvas }) => {
+game((g) => {
+  const { ctx, width, height, ui, on } = g;
   let score = 0;
   let state = 'menu';
 
@@ -1394,11 +1442,10 @@ game(({ ctx, width, height, loop, ui, on, canvas }) => {
     leaderboard.show();
   });
 
-  canvas.addEventListener('pointerdown', () => {
-    if (state === 'menu' || state === 'gameover') startGame();
-  });
-
-  loop((dt) => {
+  g.loop((dt) => {
+    if (g.tap) {
+      if (state === 'menu' || state === 'gameover') startGame();
+    }
     // Game logic...
   });
 });
@@ -1463,7 +1510,7 @@ leaderboard.submit(reactionTimeMs);
 
 4. **Don't store leaderboard state** - Just call the SDK methods when needed. The SDK handles caching.
 
-5. **Works for guests** - Guests get a generated name like "Guest1234". They can sign in later to claim scores.`;
+5. **Works for guests** - Guests get an auto-generated name like "Guest1234". Pass \`{ playerName }\` to let players choose their own name.`;
 
 // src/cli.ts
 var VERSION = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "star-sdk-cli",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "CLI for Star SDK — register games, install AI docs, and deploy to Star hosting",
   "type": "module",
   "bin": {