@powly/sdk 0.4.0 → 0.6.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 fiioonnn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -10,7 +10,7 @@ invites, multiplayer rooms, Twitch chat).
 npm install @powly/sdk
 ```
 
-Starting a new game? `npm create powly-game@latest my-game` sets up a React + Vite project with
+Starting a new game? `npm create powly@latest my-game` sets up a React + Vite project with
 the SDK.
 
 ## Use
@@ -31,7 +31,7 @@ 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>
+<script src="https://cdn.jsdelivr.net/npm/@powly/sdk@0.6.0/dist/powly.js"></script>
 ```
 
 ## Testing
@@ -54,3 +54,18 @@ await Powly.init({ powlyOrigin: "https://games.example.com" });
 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.
+
+## This repository
+
+The SDK is developed in Powly's main repository and mirrored here with each release; this is
+`@powly/sdk` 0.6.0. Issues are welcome; changes land through the main repository.
+
+To build it yourself (Node.js 24 or newer):
+
+```bash
+npm install
+npm run build
+```
+
+`dist/powly.mjs`, `dist/powly.js` and `dist/powly.d.ts` are what npm ships. `examples/` has
+Starfall, a small example game, and the SDK playground (every SDK function behind a button).

package/dist/powly.d.ts

@@ -1,9 +1,13 @@
-/* Powly SDK 0.4.0: types for powly.js and powly.mjs */
+/* Powly SDK 0.6.0: types for powly.js and powly.mjs */
 /** This SDK's version; Powly's Studio shows it next to the downloads. */
-export declare const SDK_VERSION = "0.4.0";
+export declare const SDK_VERSION = "0.6.0";
 
 export declare const PROTOCOL = "powly-sdk";
 export declare const PROTOCOL_VERSION = 1;
+/** The corners Powly's options button (its mascot, which opens the player's options) can be in. */
+export declare const OPTIONS_BUTTON_CORNERS: readonly ["top-left", "top-right", "bottom-left", "bottom-right"];
+export type OptionsButtonCorner = (typeof OPTIONS_BUTTON_CORNERS)[number];
+export declare const isOptionsButtonCorner: (value: unknown) => value is OptionsButtonCorner;
 export type InitMessage = {
     protocol: typeof PROTOCOL;
     version: number;
@@ -14,6 +18,11 @@ export type InitMessage = {
      * SDKs leave it out.
      */
     pac?: 1;
+    /**
+     * Where the game wants Powly's options button to start (`Powly.init({ optionsButton })`); the
+     * player's own choice wins. Left out: Powly's default (top left).
+     */
+    optionsButton?: OptionsButtonCorner;
 };
 export type PlayerProfile = {
     /** This player's ID in this game: stable, and different in every game. */
@@ -45,7 +54,7 @@ export type FailedMessage = {
     type: "failed";
     error: string;
 };
-export type HostMethod = "getSessionToken" | "purchases.open" | "fullscreen.toggle" | "invites.open";
+export type HostMethod = "getSessionToken" | "purchases.open" | "fullscreen.toggle" | "invites.open" | "quit";
 export type RequestMessage = {
     type: "request";
     id: number;
@@ -73,7 +82,11 @@ export type ResponseMessage = {
     ok: false;
     error: string;
 };
-export type HostEventName = "pause" | "resume" | "ended";
+/**
+ * "shown": Powly's loading screen is gone and the game is on screen (once per launch). "pause" /
+ * "resume": Powly UI covers the game or the tab is hidden, and back. "ended": the launch ended.
+ */
+export type HostEventName = "shown" | "pause" | "resume" | "ended";
 export type EventMessage = {
     type: "event";
     event: HostEventName;
@@ -113,6 +126,8 @@ export type PacSample = {
         keyIntervalSd: number | null;
         clickIntervals: number;
         clickIntervalSd: number | null;
+        /** Every trusted interaction: key presses, clicks, taps, pointer movement, wheel, gamepads. */
+        activity: number;
     };
 };
 export declare const isPacSample: (data: unknown) => data is PacSample;
@@ -515,6 +530,12 @@ export type InitOptions = {
     powlyOrigin?: string | string[];
     /** How long to wait for Powly to answer (ms). Default 10 s. */
     timeoutMs?: number;
+    /**
+     * Which corner Powly's options button (its mascot, which opens the player's options) starts in:
+     * "top-left" (the default), "top-right", "bottom-left" or "bottom-right". Pick the one your own
+     * UI leaves free. Players can still move it, and their choice wins.
+     */
+    optionsButton?: OptionsButtonCorner;
 };
 export type LeaderboardEntry = {
     rank: number;
@@ -647,8 +668,20 @@ export type PowlySession = {
     fullscreen: {
         toggle(): Promise<void>;
     };
-    /** Powly UI opened over the game ("pause"), closed ("resume"), or the launch ended ("ended"). */
+    /**
+     * Closes the game, like the exit button in Powly's options bar: the player goes back to the
+     * game's store page and the launch ends ("ended" fires). Save the player's progress first.
+     */
+    quit(): Promise<void>;
+    /**
+     * Powly's loading screen is gone and the game is on screen ("shown": start the intro or music
+     * here), Powly UI opened over the game ("pause"), closed ("resume"), or the launch ended
+     * ("ended"). "shown" comes once per launch; listening for it later calls the listener right
+     * away.
+     */
     on(event: HostEventName, listener: () => void): () => void;
+    /** Whether Powly's loading screen is gone and the game is on screen ("shown" came). */
+    readonly shown: boolean;
 };
 /** Starts the SDK. Rejects when the game wasn't launched from Powly. */
 export declare function init(options?: InitOptions): Promise<PowlySession>;

package/dist/powly.js

@@ -1,8 +1,8 @@
-/* Powly SDK 0.4.0: defines window.Powly */
+/* Powly SDK 0.6.0: defines window.Powly */
 (function () {
 "use strict";
 /** This SDK's version; Powly's Studio shows it next to the downloads. */
-const SDK_VERSION = "0.4.0";
+const SDK_VERSION = "0.6.0";
 
 // The messages between a game (this SDK, inside Powly's iframe) and the Powly page that framed it.
 // Shared with the host side (apps/web/components/player/sdk-host.ts).
@@ -14,6 +14,14 @@ const SDK_VERSION = "0.4.0";
 // 3. From then on the game also reports to Powly Anti-Cheat over the port (`PacSample`, src/pac.ts).
 const PROTOCOL = "powly-sdk";
 const PROTOCOL_VERSION = 1;
+/** The corners Powly's options button (its mascot, which opens the player's options) can be in. */
+const OPTIONS_BUTTON_CORNERS = [
+    "top-left",
+    "top-right",
+    "bottom-left",
+    "bottom-right",
+];
+const isOptionsButtonCorner = (value) => OPTIONS_BUTTON_CORNERS.includes(value);
 const isInitMessage = (data) => typeof data === "object" &&
     data !== null &&
     data.protocol === PROTOCOL &&
@@ -23,7 +31,7 @@ const isRequestMessage = (data) => typeof data === "object" &&
     data !== null &&
     data.type === "request" &&
     Number.isInteger(data.id) &&
-    ["getSessionToken", "purchases.open", "fullscreen.toggle", "invites.open"].includes(data.method);
+    ["getSessionToken", "purchases.open", "fullscreen.toggle", "invites.open", "quit"].includes(data.method);
 
 // The Powly origins this build of the SDK trusts by default: a game only handshakes with a parent
 // page on one of them (unless it passes `powlyOrigin` to `Powly.init()` itself). Set at build
@@ -49,8 +57,9 @@ class PowlyError extends Error {
 // the server's to catch speed hacks), browser functions that were replaced (speed hack scripts and
 // extensions patch timers), traces of automated browsers, and how input arrives (scripted events,
 // clicks without pointer movement as AI agents make them, machine-regular timing as macros and
-// auto-clickers make them). Nothing is sent anywhere else, and nothing here reads what the player
-// types: only event counts and timings.
+// auto-clickers make them), and whether the player plays at all (any trusted input, gamepads
+// included: Powly closes games nobody plays). Nothing is sent anywhere else, and nothing here
+// reads what the player types: only event counts and timings.
 //
 // In real players' runs (not developer mode) the SDK also guards the game's code against being
 // copied (`guard`): the browser's context menu and its view-source, save-page and developer-tools
@@ -62,6 +71,8 @@ class PowlyError extends Error {
 // `tamperedFunctions` are shared with the Powly page (apps/web/components/player/pac-sensor.ts).
 /** How often the SDK reports (ms). */
 const PAC_SAMPLE_MS = 5000;
+/** A gamepad axis past this counts as input (sticks rest a little off centre). */
+const GAMEPAD_DEADZONE = 0.3;
 const isPacSample = (data) => typeof data === "object" &&
     data !== null &&
     data.type === "pac" &&
@@ -210,6 +221,7 @@ function startPacSensor(port, { guard = false } = {}, win = window) {
         synthetic: 0,
         clicks: 0,
         teleportClicks: 0,
+        activity: 0,
     };
     const keyTimes = [];
     const clickTimes = [];
@@ -227,6 +239,9 @@ function startPacSensor(port, { guard = false } = {}, win = window) {
                 input.synthetic += 1;
             return;
         }
+        input.activity += 1;
+        if (event.type === "wheel")
+            return;
         if (event.type === "pointermove" || event.type === "pointerover") {
             const move = event;
             pointer = { x: move.clientX, y: move.clientY };
@@ -252,7 +267,26 @@ function startPacSensor(port, { guard = false } = {}, win = window) {
         }
         pointer = { x: down.clientX, y: down.clientY };
     };
-    const types = ["keydown", "pointerdown", "pointermove", "pointerover"];
+    const types = ["keydown", "pointerdown", "pointermove", "pointerover", "wheel"];
+    // Gamepads send no events: a pressed button or a pushed stick, looked at a few times a second.
+    const watchGamepads = () => {
+        let pads;
+        try {
+            pads = [...(win.navigator.getGamepads?.() ?? [])];
+        }
+        catch {
+            return;
+        }
+        for (const pad of pads) {
+            if (!pad?.connected)
+                continue;
+            if (pad.buttons.some((button) => button.pressed) ||
+                pad.axes.some((axis) => Math.abs(axis) > GAMEPAD_DEADZONE)) {
+                input.activity += 1;
+                return;
+            }
+        }
+    };
     for (const type of types) {
         win.addEventListener(type, onInput, { capture: true, passive: true });
     }
@@ -320,6 +354,7 @@ function startPacSensor(port, { guard = false } = {}, win = window) {
         input.synthetic = 0;
         input.clicks = 0;
         input.teleportClicks = 0;
+        input.activity = 0;
         dateJump = 0;
         devtools = false;
     };
@@ -328,11 +363,13 @@ function startPacSensor(port, { guard = false } = {}, win = window) {
     const clearInterval = win.clearInterval.bind(win);
     const dateTimer = setInterval(watchDate, 1000);
     const reportTimer = setInterval(report, PAC_SAMPLE_MS);
+    const gamepadTimer = setInterval(watchGamepads, 250);
     const trapTimer = trap ? setInterval(springTrap, 1500) : undefined;
     report();
     return () => {
         clearInterval(dateTimer);
         clearInterval(reportTimer);
+        clearInterval(gamepadTimer);
         if (trapTimer !== undefined)
             clearInterval(trapTimer);
         for (const type of types)
@@ -1174,6 +1211,9 @@ function init(options = {}) {
                 type: "init",
                 sdkVersion: SDK_VERSION,
                 pac: 1,
+                ...(isOptionsButtonCorner(options.optionsButton) && {
+                    optionsButton: options.optionsButton,
+                }),
             };
             channel.port1.onmessage = (event) => {
                 const data = event.data;
@@ -1207,6 +1247,8 @@ function createSession(port, ready) {
     let nextId = 1;
     const pending = new Map();
     const listeners = new Map();
+    // "shown" comes once; games that listen for it later still hear it.
+    let shown = false;
     port.onmessage = (event) => {
         const data = event.data;
         if (data?.type === "response") {
@@ -1220,7 +1262,13 @@ function createSession(port, ready) {
                 waiting.reject(new PowlyError(data.error));
         }
         else if (data?.type === "event") {
-            for (const listener of listeners.get(data.event) ?? [])
+            const name = data.event;
+            if (name === "shown") {
+                if (shown)
+                    return;
+                shown = true;
+            }
+            for (const listener of listeners.get(name) ?? [])
                 listener();
         }
     };
@@ -1362,12 +1410,24 @@ function createSession(port, ready) {
                 await call("fullscreen.toggle");
             },
         },
+        quit: async () => {
+            await call("quit");
+        },
         on(event, listener) {
             const set = listeners.get(event) ?? new Set();
             set.add(listener);
             listeners.set(event, set);
+            if (event === "shown" && shown) {
+                queueMicrotask(() => {
+                    if (set.has(listener))
+                        listener();
+                });
+            }
             return () => set.delete(listener);
         },
+        get shown() {
+            return shown;
+        },
     };
 }
 const Powly = { init, SDK_VERSION, PowlyError };

package/dist/powly.mjs

@@ -1,6 +1,6 @@
-/* Powly SDK 0.4.0: ES module */
+/* Powly SDK 0.6.0: ES module */
 /** This SDK's version; Powly's Studio shows it next to the downloads. */
-const SDK_VERSION = "0.4.0";
+const SDK_VERSION = "0.6.0";
 
 // The messages between a game (this SDK, inside Powly's iframe) and the Powly page that framed it.
 // Shared with the host side (apps/web/components/player/sdk-host.ts).
@@ -12,6 +12,14 @@ const SDK_VERSION = "0.4.0";
 // 3. From then on the game also reports to Powly Anti-Cheat over the port (`PacSample`, src/pac.ts).
 const PROTOCOL = "powly-sdk";
 const PROTOCOL_VERSION = 1;
+/** The corners Powly's options button (its mascot, which opens the player's options) can be in. */
+const OPTIONS_BUTTON_CORNERS = [
+    "top-left",
+    "top-right",
+    "bottom-left",
+    "bottom-right",
+];
+const isOptionsButtonCorner = (value) => OPTIONS_BUTTON_CORNERS.includes(value);
 const isInitMessage = (data) => typeof data === "object" &&
     data !== null &&
     data.protocol === PROTOCOL &&
@@ -21,7 +29,7 @@ const isRequestMessage = (data) => typeof data === "object" &&
     data !== null &&
     data.type === "request" &&
     Number.isInteger(data.id) &&
-    ["getSessionToken", "purchases.open", "fullscreen.toggle", "invites.open"].includes(data.method);
+    ["getSessionToken", "purchases.open", "fullscreen.toggle", "invites.open", "quit"].includes(data.method);
 
 // The Powly origins this build of the SDK trusts by default: a game only handshakes with a parent
 // page on one of them (unless it passes `powlyOrigin` to `Powly.init()` itself). Set at build
@@ -47,8 +55,9 @@ class PowlyError extends Error {
 // the server's to catch speed hacks), browser functions that were replaced (speed hack scripts and
 // extensions patch timers), traces of automated browsers, and how input arrives (scripted events,
 // clicks without pointer movement as AI agents make them, machine-regular timing as macros and
-// auto-clickers make them). Nothing is sent anywhere else, and nothing here reads what the player
-// types: only event counts and timings.
+// auto-clickers make them), and whether the player plays at all (any trusted input, gamepads
+// included: Powly closes games nobody plays). Nothing is sent anywhere else, and nothing here
+// reads what the player types: only event counts and timings.
 //
 // In real players' runs (not developer mode) the SDK also guards the game's code against being
 // copied (`guard`): the browser's context menu and its view-source, save-page and developer-tools
@@ -60,6 +69,8 @@ class PowlyError extends Error {
 // `tamperedFunctions` are shared with the Powly page (apps/web/components/player/pac-sensor.ts).
 /** How often the SDK reports (ms). */
 const PAC_SAMPLE_MS = 5000;
+/** A gamepad axis past this counts as input (sticks rest a little off centre). */
+const GAMEPAD_DEADZONE = 0.3;
 const isPacSample = (data) => typeof data === "object" &&
     data !== null &&
     data.type === "pac" &&
@@ -208,6 +219,7 @@ function startPacSensor(port, { guard = false } = {}, win = window) {
         synthetic: 0,
         clicks: 0,
         teleportClicks: 0,
+        activity: 0,
     };
     const keyTimes = [];
     const clickTimes = [];
@@ -225,6 +237,9 @@ function startPacSensor(port, { guard = false } = {}, win = window) {
                 input.synthetic += 1;
             return;
         }
+        input.activity += 1;
+        if (event.type === "wheel")
+            return;
         if (event.type === "pointermove" || event.type === "pointerover") {
             const move = event;
             pointer = { x: move.clientX, y: move.clientY };
@@ -250,7 +265,26 @@ function startPacSensor(port, { guard = false } = {}, win = window) {
         }
         pointer = { x: down.clientX, y: down.clientY };
     };
-    const types = ["keydown", "pointerdown", "pointermove", "pointerover"];
+    const types = ["keydown", "pointerdown", "pointermove", "pointerover", "wheel"];
+    // Gamepads send no events: a pressed button or a pushed stick, looked at a few times a second.
+    const watchGamepads = () => {
+        let pads;
+        try {
+            pads = [...(win.navigator.getGamepads?.() ?? [])];
+        }
+        catch {
+            return;
+        }
+        for (const pad of pads) {
+            if (!pad?.connected)
+                continue;
+            if (pad.buttons.some((button) => button.pressed) ||
+                pad.axes.some((axis) => Math.abs(axis) > GAMEPAD_DEADZONE)) {
+                input.activity += 1;
+                return;
+            }
+        }
+    };
     for (const type of types) {
         win.addEventListener(type, onInput, { capture: true, passive: true });
     }
@@ -318,6 +352,7 @@ function startPacSensor(port, { guard = false } = {}, win = window) {
         input.synthetic = 0;
         input.clicks = 0;
         input.teleportClicks = 0;
+        input.activity = 0;
         dateJump = 0;
         devtools = false;
     };
@@ -326,11 +361,13 @@ function startPacSensor(port, { guard = false } = {}, win = window) {
     const clearInterval = win.clearInterval.bind(win);
     const dateTimer = setInterval(watchDate, 1000);
     const reportTimer = setInterval(report, PAC_SAMPLE_MS);
+    const gamepadTimer = setInterval(watchGamepads, 250);
     const trapTimer = trap ? setInterval(springTrap, 1500) : undefined;
     report();
     return () => {
         clearInterval(dateTimer);
         clearInterval(reportTimer);
+        clearInterval(gamepadTimer);
         if (trapTimer !== undefined)
             clearInterval(trapTimer);
         for (const type of types)
@@ -1172,6 +1209,9 @@ function init(options = {}) {
                 type: "init",
                 sdkVersion: SDK_VERSION,
                 pac: 1,
+                ...(isOptionsButtonCorner(options.optionsButton) && {
+                    optionsButton: options.optionsButton,
+                }),
             };
             channel.port1.onmessage = (event) => {
                 const data = event.data;
@@ -1205,6 +1245,8 @@ function createSession(port, ready) {
     let nextId = 1;
     const pending = new Map();
     const listeners = new Map();
+    // "shown" comes once; games that listen for it later still hear it.
+    let shown = false;
     port.onmessage = (event) => {
         const data = event.data;
         if (data?.type === "response") {
@@ -1218,7 +1260,13 @@ function createSession(port, ready) {
                 waiting.reject(new PowlyError(data.error));
         }
         else if (data?.type === "event") {
-            for (const listener of listeners.get(data.event) ?? [])
+            const name = data.event;
+            if (name === "shown") {
+                if (shown)
+                    return;
+                shown = true;
+            }
+            for (const listener of listeners.get(name) ?? [])
                 listener();
         }
     };
@@ -1360,12 +1408,24 @@ function createSession(port, ready) {
                 await call("fullscreen.toggle");
             },
         },
+        quit: async () => {
+            await call("quit");
+        },
         on(event, listener) {
             const set = listeners.get(event) ?? new Set();
             set.add(listener);
             listeners.set(event, set);
+            if (event === "shown" && shown) {
+                queueMicrotask(() => {
+                    if (set.has(listener))
+                        listener();
+                });
+            }
             return () => set.delete(listener);
         },
+        get shown() {
+            return shown;
+        },
     };
 }
 const Powly = { init, SDK_VERSION, PowlyError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powly/sdk",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Powly game SDK: launch handshake, session tokens and platform services.",
   "license": "MIT",
@@ -12,6 +12,13 @@
     "browser-games"
   ],
   "homepage": "https://powly.gg",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fiioonnn/powly-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fiioonnn/powly-sdk/issues"
+  },
   "exports": {
     ".": {
       "types": "./dist/powly.d.ts",
@@ -36,6 +43,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json && node scripts/bundle.ts",
     "typecheck": "tsc --noEmit",
-    "example:zip": "node scripts/example-zip.ts"
+    "example:zip": "node scripts/example-zip.ts",
+    "mirror": "node scripts/mirror.ts"
   }
 }