Star SDK

Browser game SDK with built-in leaderboards (no backend needed), mobile-safe audio, and canvas helpers. Works on iOS Safari. Perfect for AI-generated games.

import Star from 'star-sdk';
Star.init({ gameId: '<gameId from .starrc>' }); // run: npx star-sdk init

Star.audio.play('coin');
Star.game(g => { /* g.tap, g.pointer for input */ });
Star.leaderboard.submit(1500);

Why Star SDK?

| Need | Without Star | With Star | |------|--------------|-----------| | Leaderboards | Build a backend, database, auth | Star.leaderboard.submit(score) | | Mobile audio | Handle unlock gestures, AudioContext resume | Just call Star.audio.play() | | HiDPI canvas | Manual DPR scaling, coordinate math | Automatic | | iOS Safari | Debug audio/touch issues for hours | It just works |

vs Phaser/PixiJS

Star SDK is simpler. No scene system, no asset loader config. Built-in leaderboards mean you ship a complete game, not just a demo.

vs Kaboom.js

Star SDK works on mobile out of the box. Leaderboards are included — no backend needed.

vs Vanilla Canvas

Star SDK handles the annoying stuff: audio unlocking, DPR scaling, touch coordinates, game loop timing. You write game logic, not boilerplate.

One-Liner Game

npx star-sdk init && cat > index.html << 'EOF'
<script type="module">
import Star from 'https://esm.sh/star-sdk';
Star.init({ gameId: '<gameId from .starrc>' }); // run: npx star-sdk init
Star.game(g => {
  const { ctx, width, height } = g;
  let score = 0;
  Star.audio.preload({ coin: 'coin' });
  g.loop(() => {
    if (g.tap) { score++; Star.audio.play('coin'); }
    ctx.fillStyle = '#1a1a2e';
    ctx.fillRect(0, 0, width, height);
    ctx.fillStyle = '#fff';
    ctx.font = '48px sans-serif';
    ctx.fillText(score, width/2 - 20, height/2);
  });
});
</script>
EOF
open index.html  # or: python -m http.server

Installation

npm install star-sdk
# or
yarn add star-sdk

Setup (Required for Leaderboards)

Register your game to get a gameId:

npx star-sdk init "My Game"

This creates a .starrc file with your gameId. Open it, copy the gameId value, and pass it to Star.init(). The gameId is a server-issued token — do not make one up.

Quick Start

import Star from 'star-sdk';
Star.init({ gameId: '<gameId from .starrc>' }); // run: npx star-sdk init

Star.game(g => {
  const { ctx, width, height } = g;
  let score = 0;

  // Preload sounds
  Star.audio.preload({
    coin: 'coin',  // Built-in synth preset
    jump: 'jump',
  });

  // Game loop — input and drawing happen here
  g.loop((dt) => {
    // Input (polling — automatically in canvas coordinates)
    if (g.tap) {
      score += 10;
      Star.audio.play('coin');
    }

    // Draw
    ctx.fillStyle = '#1a1a2e';
    ctx.fillRect(0, 0, width, height);
    ctx.fillStyle = '#fff';
    ctx.font = '24px sans-serif';
    ctx.fillText(\`Score: \${score}\`, 20, 40);
  });
});

Features

Audio

Procedural sounds and music with built-in presets.

// Play built-in sounds
Star.audio.play('coin');
Star.audio.play('laser');
Star.audio.play('explosion');

// Music control
Star.audio.music.crossfadeTo('level2', { duration: 2 });
Star.audio.music.stop(1);

// Volume
Star.audio.setMusicVolume(0.8);
Star.audio.setSfxVolume(0.9);
Star.audio.toggleMute();

Built-in presets: `beep`, `coin`, `pickup`, `jump`, `hurt`, `explosion`, `powerup`, `shoot`, `laser`, `error`, `click`, `success`, `bonus`, `select`, `unlock`, `swoosh`, `hit`

Canvas

Game loop with automatic DPR scaling, input polling, and coordinate conversion.

Star.game(g => {
  const { ctx, width, height, ui } = g;

  g.loop((dt) => {
    // dt = delta time in seconds
    // Input polling (coordinates are canvas-space, automatic)
    if (g.tap) { /* tap/click this frame: g.tap.x, g.tap.y */ }
    if (g.pointer.down) { /* held: g.pointer.x, g.pointer.y */ }

    ctx.clearRect(0, 0, width, height);
  });

  // Delegated events for HTML UI buttons
  g.on('click', '.button', (e) => { ... });

  // UI overlay (HTML on top of canvas)
  ui.render(\`<div class="score">Score: \${score}</div>\`);
}, {
  preset: 'landscape',  // or 'portrait', 'responsive'
});

Leaderboard

Submit scores and display rankings. Requires Star.init({ gameId }) (see Quick Start).

// Submit score (Star.init() must be called first)
const result = await Star.leaderboard.submit(1500);
if (result.success) {
  console.log(\`Ranked #\${result.rank}!\`);
}

// Show platform UI
Star.leaderboard.show();

// Fetch scores manually
const { scores } = await Star.leaderboard.getScores({
  timeframe: 'weekly',
  limit: 10
});

Examples

Complete working games in the examples/ directory:

• click-frenzy — 5-second click speed game with leaderboard
• dodge — Avoid falling obstacles, keyboard and touch controls
• reaction-time — Test your reflexes over 5 rounds

Each example is a single HTML file — open it in a browser, no build step needed.

TypeScript

Star SDK ships with full type definitions.

import Star from 'star-sdk';

Star.init({ gameId: '<gameId from .starrc>' });

Star.game((g) => {
  const { ctx, width, height } = g;
  let score: number = 0;

  Star.audio.preload({ coin: 'coin', jump: 'jump' });

  g.loop((dt: number) => {
    if (g.tap) {
      score += 10;
      Star.audio.play('coin');
    }

    ctx.fillStyle = '#111827';
    ctx.fillRect(0, 0, width, height);
    ctx.fillStyle = '#fff';
    ctx.font = '24px sans-serif';
    ctx.fillText(`Score: ${score}`, 20, 40);
  });
});

Built with Star SDK

• Stick Slaughter — Battle waves of stick figures in this action game
• Cozy Noodle Shop — Run a noodle stand, take orders, cook bowls
• Moonlit Carnage — Vampire survivors-style autoshooter
• Library Larry — Help Larry organize the library
• One-Shotted Pong — Classic pong with a twist

Built something with Star SDK? Share it with us!

AI-Friendly

Star SDK ships with skill files that teach AI coding tools how to use the SDK correctly. When an LLM reads the skills/ directory, it learns the full API, common patterns, and pitfalls to avoid.

npx star-sdk install          # Claude Code (default)
npx star-sdk install cursor   # Cursor
npx star-sdk install codex    # OpenAI Codex

This is what "built by LLMs, for LLMs" means — Star SDK is designed to be used autonomously by AI agents, not just by humans reading docs.

Deploy to Star

Deploy your game with one command. Free hosting, no configuration needed.

• Free hosting with a shareable link
• Leaderboards work automatically

npx star-sdk deploy

Documentation

Full documentation at buildwithstar.com/docs/sdk

License

MIT