star-sdk 0.1.0

package/README.md

@@ -0,0 +1,157 @@
+# Star SDK
+
+Unified SDK for browser game development. Audio, canvas, and leaderboards.
+
+```javascript
+import Star from 'star-sdk';
+
+Star.audio.play('coin');
+Star.game(ctx => { ... });
+Star.leaderboard.submit(1500);
+```
+
+## Installation
+
+```bash
+npm install star-sdk
+# or
+yarn add star-sdk
+```
+
+## Quick Start
+
+```javascript
+import Star from 'star-sdk';
+
+Star.game(ctx => {
+  const { canvas, width, height, ctx: c } = ctx;
+  let score = 0;
+
+  // Preload sounds
+  Star.audio.preload({
+    coin: 'coin',  // Built-in synth preset
+    jump: 'jump',
+  });
+
+  // Game loop
+  ctx.loop((dt) => {
+    c.fillStyle = '#1a1a2e';
+    c.fillRect(0, 0, width, height);
+
+    c.fillStyle = '#fff';
+    c.font = '24px sans-serif';
+    c.fillText(\`Score: \${score}\`, 20, 40);
+  });
+
+  // Input
+  canvas.onclick = () => {
+    score += 10;
+    Star.audio.play('coin');
+  };
+});
+```
+
+## Features
+
+### Audio
+
+Procedural sounds and music with built-in presets.
+
+```javascript
+// 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 and coordinate conversion.
+
+```javascript
+Star.game(ctx => {
+  const { canvas, width, height, ctx: c, ui } = ctx;
+
+  ctx.loop((dt) => {
+    // dt = delta time in seconds
+    c.clearRect(0, 0, width, height);
+  });
+
+  // Delegated events
+  ctx.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.
+
+```javascript
+// Submit score
+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
+});
+```
+
+## External Games
+
+For games hosted outside the Star platform:
+
+```bash
+# Register your game
+npx star-sdk init "My Game"
+```
+
+This creates a \`.starrc\` file with your game ID. The SDK auto-detects this configuration.
+
+## Deploy to Star
+
+Get more from your game with Star hosting:
+
+- Free hosting
+- Play session tracking (see how long players play)
+- Analytics dashboard
+- Discovery / game feed
+
+```bash
+npx star-sdk deploy
+```
+
+## Coming Soon
+
+- **Multiplayer** - Real-time game state synchronization (in alpha)
+- **Monetization** - Let players support your games
+
+## Documentation
+
+Full documentation at [buildwithstar.com/docs/sdk](https://buildwithstar.com/docs/sdk)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";var u=Object.defineProperty;var b=Object.getOwnPropertyDescriptor;var O=Object.getOwnPropertyNames;var M=Object.prototype.hasOwnProperty;var x=(e,t)=>{for(var r in t)u(e,r,{get:t[r],enumerable:!0})},h=(e,t,r,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let s of O(t))!M.call(e,s)&&s!==r&&u(e,s,{get:()=>t[s],enumerable:!(o=b(t,s))||o.enumerable});return e};var G=e=>h(u({},"__esModule",{value:!0}),e);var I={};x(I,{Star:()=>c,audio:()=>f.createStarAudio,default:()=>A,game:()=>S.game,leaderboard:()=>g.createLeaderboard,multiplayer:()=>y.createMultiplayer});module.exports=G(I);var f=require("star-audio"),S=require("star-canvas"),g=require("star-leaderboard"),y=require("star-multiplayer"),p=null,l=null,i=null,d=()=>typeof window<"u",L=()=>typeof process<"u"&&process.versions?.node;function m(){if(d()||!L())return null;try{let e=require("fs"),r=require("path").join(process.cwd(),".starrc");if(!e.existsSync(r))return null;let o=e.readFileSync(r,"utf-8");return JSON.parse(o)}catch{return null}}function a(){if(!l&&d()){let{createStarAudio:e}=require("star-audio");l=e()}return l}function n(){if(!i){let e=p?.gameId,t=p?.apiBase;if(!e){let o=m();o?.gameId&&(e=o.gameId)}let{createLeaderboard:r}=require("star-leaderboard");i=r({gameId:e,apiBase:t})}return i}var c={init(e){p=e,i&&(i.destroy?.(),i=null)},audio:{play:(e,t)=>a().play(e,t),preload:e=>a().preload(e),music:{crossfadeTo:(e,t)=>a().music.crossfadeTo(e,t),stop:e=>a().music.stop(e)},setMusicVolume:e=>a().setMusicVolume(e),setSfxVolume:e=>a().setSfxVolume(e),setMute:e=>a().setMute(e),toggleMute:()=>a().toggleMute(),isMuted:()=>a().isMuted()},game(e,t){let{game:r}=require("star-canvas");r(e,t)},leaderboard:{submit:e=>n().submit(e),show:()=>n().show(),getScores:e=>n().getScores(e),share:e=>n().share(e)},multiplayer:{async create(e){let{createMultiplayer:t}=require("star-multiplayer"),r=t();return await r.start(e),r}},loadConfig:m,version:"0.1.0"},A=c;0&&(module.exports={Star,audio,game,leaderboard,multiplayer});

package/dist/index.d.cts

@@ -0,0 +1,140 @@
+import * as star_leaderboard from 'star-leaderboard';
+import { GetScoresOptions, ShareOptions } from 'star-leaderboard';
+export { GetScoresOptions, LeaderboardData, LeaderboardOptions, ScoreEntry, ShareOptions, ShareResult, StarLeaderboard, SubmitResult, createLeaderboard as leaderboard } from 'star-leaderboard';
+import * as star_audio from 'star-audio';
+import { PlayOptions, Manifest } from 'star-audio';
+export { Manifest, PlayOptions, StarAudio, StarAudioOptions, createStarAudio as audio } from 'star-audio';
+import { GameContext, GameOptions } from 'star-canvas';
+export { GameContext, GameLoop, GameOptions, GameTick, GameUI, game } from 'star-canvas';
+import { StartOptions, StarMultiplayer } from 'star-multiplayer';
+export { StartOptions as MultiplayerOptions, Player, StarMultiplayer, createMultiplayer as multiplayer } from 'star-multiplayer';
+
+interface StarConfig {
+    gameId: string;
+    name?: string;
+    email?: string;
+    dashboardUrl?: string;
+}
+/**
+ * Load configuration from .starrc file (Node.js only).
+ * Returns null in browser or if file doesn't exist.
+ */
+declare function loadConfigFromFile(): StarConfig | null;
+declare const Star: {
+    /**
+     * Initialize the SDK for external (non-platform) use.
+     * Not needed when running inside Star platform - auto-detected.
+     *
+     * @param options - Configuration with gameId and optional apiBase
+     *
+     * @example
+     * ```javascript
+     * // For external games only
+     * Star.init({ gameId: 'abc123' });
+     * ```
+     */
+    init(options: {
+        gameId: string;
+        apiBase?: string;
+    }): void;
+    /**
+     * Audio manager - procedural sounds and music.
+     *
+     * @example
+     * ```javascript
+     * Star.audio.play('coin');
+     * Star.audio.music.crossfadeTo('level2');
+     * ```
+     */
+    audio: {
+        play: (id: string, opts?: PlayOptions) => star_audio.SoundHandle | null;
+        preload: (manifest: Manifest) => Promise<void>;
+        music: {
+            crossfadeTo: (id: string, opts?: {
+                duration?: number;
+                loop?: boolean;
+            }) => Promise<void>;
+            stop: (fadeSec?: number) => void;
+        };
+        setMusicVolume: (v: number) => void;
+        setSfxVolume: (v: number) => void;
+        setMute: (m: boolean) => void;
+        toggleMute: () => void;
+        isMuted: () => boolean;
+    };
+    /**
+     * Initialize the game canvas and context.
+     * Handles DOM timing, DPR scaling, and provides a game loop.
+     *
+     * @param setup - Function called when canvas is ready
+     * @param options - Canvas and stage configuration
+     *
+     * @example
+     * ```javascript
+     * Star.game(ctx => {
+     *   const { canvas, width, height } = ctx;
+     *
+     *   ctx.loop((dt) => {
+     *     ctx.ctx.fillStyle = '#000';
+     *     ctx.ctx.fillRect(0, 0, width, height);
+     *   });
+     * });
+     * ```
+     */
+    game(setup: (g: GameContext) => void, options?: GameOptions): void;
+    /**
+     * Leaderboard - submit scores and display rankings.
+     *
+     * @example
+     * ```javascript
+     * await Star.leaderboard.submit(1500);
+     * Star.leaderboard.show();
+     * ```
+     */
+    leaderboard: {
+        submit: (score: number) => Promise<star_leaderboard.SubmitResult>;
+        show: () => void;
+        getScores: (opts?: GetScoresOptions) => Promise<star_leaderboard.LeaderboardData>;
+        share: (opts?: ShareOptions) => Promise<star_leaderboard.ShareResult>;
+    };
+    /**
+     * Multiplayer - real-time game state synchronization.
+     *
+     * @example
+     * ```javascript
+     * const mp = await Star.multiplayer.create({ maxPlayers: 4 });
+     *
+     * mp.onState(state => { gameState = state; });
+     * mp.onInput((id, input) => { state.players[id].y = input.y; });
+     *
+     * ctx.loop((dt) => {
+     *   mp.hostTick(dt, () => { updatePhysics(dt); return state; });
+     *   render(state);
+     * });
+     *
+     * canvas.onpointermove = (e) => mp.input({ y: e.clientY });
+     * ```
+     */
+    multiplayer: {
+        create(options?: StartOptions): Promise<StarMultiplayer>;
+    };
+    /**
+     * Load configuration from .starrc file (Node.js only).
+     * Useful for build scripts or SSR.
+     *
+     * @returns Config object or null if not found
+     *
+     * @example
+     * ```javascript
+     * const config = Star.loadConfig();
+     * if (config) {
+     *   console.log(`Game ID: ${config.gameId}`);
+     * }
+     * ```
+     */
+    loadConfig: typeof loadConfigFromFile;
+    /** SDK version */
+    version: string;
+};
+
+export { Star, Star as default };

package/dist/index.d.ts

@@ -0,0 +1,140 @@
+import * as star_leaderboard from 'star-leaderboard';
+import { GetScoresOptions, ShareOptions } from 'star-leaderboard';
+export { GetScoresOptions, LeaderboardData, LeaderboardOptions, ScoreEntry, ShareOptions, ShareResult, StarLeaderboard, SubmitResult, createLeaderboard as leaderboard } from 'star-leaderboard';
+import * as star_audio from 'star-audio';
+import { PlayOptions, Manifest } from 'star-audio';
+export { Manifest, PlayOptions, StarAudio, StarAudioOptions, createStarAudio as audio } from 'star-audio';
+import { GameContext, GameOptions } from 'star-canvas';
+export { GameContext, GameLoop, GameOptions, GameTick, GameUI, game } from 'star-canvas';
+import { StartOptions, StarMultiplayer } from 'star-multiplayer';
+export { StartOptions as MultiplayerOptions, Player, StarMultiplayer, createMultiplayer as multiplayer } from 'star-multiplayer';
+
+interface StarConfig {
+    gameId: string;
+    name?: string;
+    email?: string;
+    dashboardUrl?: string;
+}
+/**
+ * Load configuration from .starrc file (Node.js only).
+ * Returns null in browser or if file doesn't exist.
+ */
+declare function loadConfigFromFile(): StarConfig | null;
+declare const Star: {
+    /**
+     * Initialize the SDK for external (non-platform) use.
+     * Not needed when running inside Star platform - auto-detected.
+     *
+     * @param options - Configuration with gameId and optional apiBase
+     *
+     * @example
+     * ```javascript
+     * // For external games only
+     * Star.init({ gameId: 'abc123' });
+     * ```
+     */
+    init(options: {
+        gameId: string;
+        apiBase?: string;
+    }): void;
+    /**
+     * Audio manager - procedural sounds and music.
+     *
+     * @example
+     * ```javascript
+     * Star.audio.play('coin');
+     * Star.audio.music.crossfadeTo('level2');
+     * ```
+     */
+    audio: {
+        play: (id: string, opts?: PlayOptions) => star_audio.SoundHandle | null;
+        preload: (manifest: Manifest) => Promise<void>;
+        music: {
+            crossfadeTo: (id: string, opts?: {
+                duration?: number;
+                loop?: boolean;
+            }) => Promise<void>;
+            stop: (fadeSec?: number) => void;
+        };
+        setMusicVolume: (v: number) => void;
+        setSfxVolume: (v: number) => void;
+        setMute: (m: boolean) => void;
+        toggleMute: () => void;
+        isMuted: () => boolean;
+    };
+    /**
+     * Initialize the game canvas and context.
+     * Handles DOM timing, DPR scaling, and provides a game loop.
+     *
+     * @param setup - Function called when canvas is ready
+     * @param options - Canvas and stage configuration
+     *
+     * @example
+     * ```javascript
+     * Star.game(ctx => {
+     *   const { canvas, width, height } = ctx;
+     *
+     *   ctx.loop((dt) => {
+     *     ctx.ctx.fillStyle = '#000';
+     *     ctx.ctx.fillRect(0, 0, width, height);
+     *   });
+     * });
+     * ```
+     */
+    game(setup: (g: GameContext) => void, options?: GameOptions): void;
+    /**
+     * Leaderboard - submit scores and display rankings.
+     *
+     * @example
+     * ```javascript
+     * await Star.leaderboard.submit(1500);
+     * Star.leaderboard.show();
+     * ```
+     */
+    leaderboard: {
+        submit: (score: number) => Promise<star_leaderboard.SubmitResult>;
+        show: () => void;
+        getScores: (opts?: GetScoresOptions) => Promise<star_leaderboard.LeaderboardData>;
+        share: (opts?: ShareOptions) => Promise<star_leaderboard.ShareResult>;
+    };
+    /**
+     * Multiplayer - real-time game state synchronization.
+     *
+     * @example
+     * ```javascript
+     * const mp = await Star.multiplayer.create({ maxPlayers: 4 });
+     *
+     * mp.onState(state => { gameState = state; });
+     * mp.onInput((id, input) => { state.players[id].y = input.y; });
+     *
+     * ctx.loop((dt) => {
+     *   mp.hostTick(dt, () => { updatePhysics(dt); return state; });
+     *   render(state);
+     * });
+     *
+     * canvas.onpointermove = (e) => mp.input({ y: e.clientY });
+     * ```
+     */
+    multiplayer: {
+        create(options?: StartOptions): Promise<StarMultiplayer>;
+    };
+    /**
+     * Load configuration from .starrc file (Node.js only).
+     * Useful for build scripts or SSR.
+     *
+     * @returns Config object or null if not found
+     *
+     * @example
+     * ```javascript
+     * const config = Star.loadConfig();
+     * if (config) {
+     *   console.log(`Game ID: ${config.gameId}`);
+     * }
+     * ```
+     */
+    loadConfig: typeof loadConfigFromFile;
+    /** SDK version */
+    version: string;
+};
+
+export { Star, Star as default };

package/dist/index.mjs

@@ -0,0 +1 @@
+var o=(e=>typeof require<"u"?require:typeof Proxy<"u"?new Proxy(e,{get:(t,r)=>(typeof require<"u"?require:t)[r]}):e)(function(e){if(typeof require<"u")return require.apply(this,arguments);throw Error('Dynamic require of "'+e+'" is not supported')});import{createStarAudio as b}from"star-audio";import{game as M}from"star-canvas";import{createLeaderboard as h}from"star-leaderboard";import{createMultiplayer as L}from"star-multiplayer";var l=null,u=null,i=null,p=()=>typeof window<"u",m=()=>typeof process<"u"&&process.versions?.node;function d(){if(p()||!m())return null;try{let e=o("fs"),r=o("path").join(process.cwd(),".starrc");if(!e.existsSync(r))return null;let s=e.readFileSync(r,"utf-8");return JSON.parse(s)}catch{return null}}function a(){if(!u&&p()){let{createStarAudio:e}=o("star-audio");u=e()}return u}function n(){if(!i){let e=l?.gameId,t=l?.apiBase;if(!e){let s=d();s?.gameId&&(e=s.gameId)}let{createLeaderboard:r}=o("star-leaderboard");i=r({gameId:e,apiBase:t})}return i}var c={init(e){l=e,i&&(i.destroy?.(),i=null)},audio:{play:(e,t)=>a().play(e,t),preload:e=>a().preload(e),music:{crossfadeTo:(e,t)=>a().music.crossfadeTo(e,t),stop:e=>a().music.stop(e)},setMusicVolume:e=>a().setMusicVolume(e),setSfxVolume:e=>a().setSfxVolume(e),setMute:e=>a().setMute(e),toggleMute:()=>a().toggleMute(),isMuted:()=>a().isMuted()},game(e,t){let{game:r}=o("star-canvas");r(e,t)},leaderboard:{submit:e=>n().submit(e),show:()=>n().show(),getScores:e=>n().getScores(e),share:e=>n().share(e)},multiplayer:{async create(e){let{createMultiplayer:t}=o("star-multiplayer"),r=t();return await r.start(e),r}},loadConfig:d,version:"0.1.0"},S=c;export{c as Star,b as audio,S as default,M as game,h as leaderboard,L as multiplayer};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "star-sdk",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Unified Star SDK for game development. Audio, canvas, leaderboards, multiplayer.",
+  "type": "module",
+  "sideEffects": false,
+  "starSdk": {
+    "internalImport": "import Star from '/star-sdk/v1/star.js';",
+    "publicImport": "import Star from 'star-sdk';",
+    "outputs": [{ "src": "dist/index.mjs", "dest": "v1/star.js" }],
+    "skill": {
+      "name": "star-sdk",
+      "description": "Unified Star SDK for game development. Audio, canvas, leaderboards, multiplayer."
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "star",
+    "sdk",
+    "games",
+    "web",
+    "audio",
+    "canvas",
+    "leaderboard",
+    "multiplayer"
+  ],
+  "dependencies": {
+    "star-audio": "*",
+    "star-canvas": "*",
+    "star-leaderboard": "*",
+    "star-multiplayer": "*"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.5"
+  }
+}