@powly/sdk 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @powly/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The SDK for games on [Powly](https://powly.gg): the launch handshake with Powly, the player's
+profile, session tokens and the platform services (saves, leaderboards, achievements, friends,
+invites, multiplayer rooms, Twitch chat).
+
+## Install
+
+```bash
+npm install @powly/sdk
+```
+
+Starting a new game? `npm create powly-game@latest my-game` sets up a React + Vite project with
+the SDK.
+
+## Use
+
+Call `Powly.init()` as early as possible (before loading your game's assets): Powly expects the
+handshake promptly, and it only succeeds when the game was launched from Powly.
+
+```ts
+import Powly from "@powly/sdk";
+
+const powly = await Powly.init();
+
+powly.profile.username;
+const level = (await powly.saves.get<number>("level")) ?? 1;
+await powly.leaderboards.submit("high-score", 1200);
+```
+
+Without a bundler, load the classic script instead; it defines `window.Powly`:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@powly/sdk@0.4.0/dist/powly.js"></script>
+```
+
+## Testing
+
+Run your dev server and open it in **Studio → Developer mode** (for example
+`http://localhost:5173`). Opened directly, `Powly.init()` rejects with "This game only runs when
+launched from Powly."
+
+## Self-hosted Powly
+
+This package trusts `https://powly.gg` and `http://localhost:3000`. For another Powly
+installation, pass its origin:
+
+```ts
+await Powly.init({ powlyOrigin: "https://games.example.com" });
+```
+
+## Security
+
+The game runs in the player's browser, so nothing here is a security boundary. Saves and
+leaderboard scores are written by your backend unless the studio allows browser writes for them;
+your backend verifies session tokens or exchanges them for an access token.