@powly/sdk 0.4.1 → 0.8.0

package/README.md

@@ -2,7 +2,7 @@
 
 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).
+invites, multiplayer rooms, Twitch chat, sound settings).
 
 ## Install
 
@@ -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.1/dist/powly.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@powly/sdk@0.8.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.8.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,51 @@
-/* Powly SDK 0.4.1: types for powly.js and powly.mjs */
+/* Powly SDK 0.8.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.1";
+export declare const SDK_VERSION = "0.8.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;
+/**
+ * A kind of sound the game has (music, drawing sounds…), which Powly's sound menu shows with a
+ * volume slider (`volume`, default true), an on/off switch (`toggle`, default true), or both.
+ */
+export type AudioChannel = {
+    id: string;
+    label: string;
+    volume?: boolean;
+    toggle?: boolean;
+};
+/** One channel's setting: its volume, 0 to 1, and whether it's on. */
+export type ChannelState = {
+    volume: number;
+    on: boolean;
+};
+/** Channel ids: letters, digits, _ and -, starting with a letter, up to 32. */
+export declare const AUDIO_CHANNEL_ID: RegExp;
+export declare const MAX_AUDIO_CHANNELS = 8;
+export declare const MAX_AUDIO_LABEL = 32;
+/**
+ * The player's sound settings from Powly's sound menu. `volume` (0 to 1) is the player's overall
+ * volume, `channels` the game's own (by channel id); `muted` silences everything.
+ */
+export type AudioState = {
+    volume: number;
+    muted: boolean;
+    channels: Record<string, ChannelState>;
+};
+/** The channels a game sent, cleaned up: valid ids, short labels, no repeats, at most 8. */
+export declare function audioChannelsOf(value: unknown): AudioChannel[];
+/** What a game changes from its own sound menu; channels by id, only the fields given. */
+export type AudioChanges = {
+    volume?: number;
+    muted?: boolean;
+    channels?: Record<string, Partial<ChannelState>>;
+};
+/** A volume between 0 and 1, or null. */
+export declare const volumeOf: (value: unknown) => number | null;
 export type InitMessage = {
     protocol: typeof PROTOCOL;
     version: number;
@@ -14,6 +56,18 @@ 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;
+    /**
+     * The SDK follows Powly's sound menu (SDK 0.8.0 and later): `channels` are the game's own
+     * volume controls, shown as sliders. Older SDKs leave it out.
+     */
+    audio?: {
+        channels: AudioChannel[];
+    };
 };
 export type PlayerProfile = {
     /** This player's ID in this game: stable, and different in every game. */
@@ -40,12 +94,19 @@ export type ReadyMessage = {
     pac?: {
         guard: boolean;
     };
+    /** The player's sound settings when the game starts. Missing from older Powly hosts. */
+    audio?: AudioState;
 };
 export type FailedMessage = {
     type: "failed";
     error: string;
 };
-export type HostMethod = "getSessionToken" | "purchases.open" | "fullscreen.toggle" | "invites.open";
+/** What a game may ask the Powly page for. */
+export declare const HOST_METHODS: readonly ["getSessionToken", "purchases.open", "fullscreen.toggle", "invites.open", "players.open", "twitch.connect", "audio.set", "audio.channels", "quit"];
+export type HostMethod = (typeof HOST_METHODS)[number];
+/** "players.open": what Powly's player dialog opens on. */
+export declare const PLAYER_VIEWS: readonly ["profile", "report"];
+export type PlayerView = (typeof PLAYER_VIEWS)[number];
 export type RequestMessage = {
     type: "request";
     id: number;
@@ -57,11 +118,33 @@ export type RequestMessage = {
      * dialog shows them as in the party, without an Invite button.
      */
     members?: string[];
+    /** "players.open": the player (their player ID in this game) to show. */
+    playerId?: string;
+    /** "players.open": open on the profile (the default) or straight on reporting them. */
+    view?: PlayerView;
+    /** "audio.set": what the game's own sound menu changed. */
+    audio?: AudioChanges;
+    /** "audio.channels": every channel the game has now (registered later than init). */
+    channels?: AudioChannel[];
 };
 /** What "invites.open" answers once Powly's dialog closed: the friends the player invited. */
 export type InvitesOpenResult = {
     invited: string[];
 };
+/**
+ * What "players.open" answers once Powly's player dialog closed: whether the player has that
+ * player blocked now (the game may hide their chat, say). Whether they reported them stays private.
+ */
+export type PlayersOpenResult = {
+    blocked: boolean;
+};
+/**
+ * What "twitch.connect" answers once Powly's Connect Twitch dialog closed: whether the player's
+ * Twitch is connected now (the SDK then reads GET /twitch again).
+ */
+export type TwitchConnectResult = {
+    connected: boolean;
+};
 export type ResponseMessage = {
     type: "response";
     id: number;
@@ -73,13 +156,28 @@ 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;
+}
+/** The player changed the sound settings (Powly's sound menu, or its M key). */
+ | {
+    type: "event";
+    event: "audio";
+    audio: AudioState;
 };
 export type HostMessage = ReadyMessage | FailedMessage | ResponseMessage | EventMessage;
 export declare const isInitMessage: (data: unknown) => data is InitMessage;
+/** A request with a method this Powly doesn't know (from a newer SDK): answered with an error. */
+export declare const isRequestShaped: (data: unknown) => data is {
+    type: "request";
+    id: number;
+};
 export declare const isRequestMessage: (data: unknown) => data is RequestMessage;
 
 export declare const POWLY_ORIGINS: readonly string[];
@@ -113,6 +211,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;
@@ -466,14 +566,21 @@ type Events = {
     };
     state: TwitchChatState;
 };
+export type ConnectOptions = {
+    /** Ask the player to connect Twitch in Powly's dialog when they haven't. Default false. */
+    prompt?: boolean;
+};
 export type TwitchApi = {
     /** The game's setting and the player's channel, without opening chat. */
     info(): Promise<TwitchInfo>;
     /**
      * Opens the player's chat when they have a channel to read (`status: "connected"`). Resolves
      * with the info, once chat is joined (or failed to; it keeps retrying in the background).
+     * `prompt`: when the player hasn't connected Twitch, Powly first asks them to in its own dialog
+     * (they can connect it there without leaving the game); `status` is still "not_connected" if
+     * they closed it.
      */
-    connect(): Promise<TwitchInfo>;
+    connect(options?: ConnectOptions): Promise<TwitchInfo>;
     /** Closes chat; `connect()` opens it again. */
     disconnect(): void;
     readonly state: TwitchChatState;
@@ -494,6 +601,8 @@ export declare function parseIrcLine(line: string): IrcMessage | null;
 export declare function chatMessageOf(message: IrcMessage): TwitchChatMessage | null;
 export declare function createTwitch(options: {
     getInfo: () => Promise<TwitchInfo>;
+    /** Opens Powly's Connect Twitch dialog; resolves with whether Twitch is connected now. */
+    prompt?: () => Promise<boolean>;
     /** Twitch chat's WebSocket URL (tests point it elsewhere). */
     url?: string;
 }): TwitchApi & {
@@ -501,6 +610,58 @@ export declare function createTwitch(options: {
 };
 
 
+export type AudioOptions = {
+    /**
+     * The game's kinds of sound, shown in Powly's sound menu (up to 8): `{ id, label }`, with a
+     * volume slider (`volume: false` leaves it out) and an on/off switch (`toggle: false`).
+     */
+    channels?: AudioChannel[];
+    /**
+     * Apply the overall volume and mute to the page's sound by itself. Default true; turn it off
+     * when the game applies `level()` to everything itself.
+     */
+    auto?: boolean;
+};
+export type AudioApi = {
+    /** The player's overall volume, 0 to 1. */
+    readonly volume: number;
+    /** Everything silenced (Powly's mute, or its M key). */
+    readonly muted: boolean;
+    /** The game's channels by id: their volume (0 to 1) and whether they're on. */
+    readonly channels: Record<string, ChannelState>;
+    /**
+     * What to play at, 0 to 1: a channel's volume (0 while it's off), or (no channel) full volume.
+     * With `auto` off, the overall volume and mute are in it too.
+     */
+    level(channel?: string): number;
+    /**
+     * Adds a channel to Powly's sound menu after init (or changes its label or controls), e.g.
+     * once a mode with its own sounds starts. Up to 8 channels.
+     */
+    register(channel: AudioChannel): Promise<void>;
+    /**
+     * Changes the settings from the game's own sound menu, so Powly's stays the same:
+     * `{ volume, muted, channels: { music: { volume: 0.5 }, drawing: { on: false } } }`. Unknown
+     * channels are ignored.
+     */
+    set(changes: AudioChanges): Promise<void>;
+    /** The settings changed (in Powly's sound menu, or with `set`). */
+    on(event: "change", listener: (audio: AudioState) => void): () => void;
+};
+/** Volume of the page's sound overall: 0 when muted. */
+export declare const masterLevel: (state: AudioState) => number;
+/**
+ * Puts a volume control in front of the page's speakers: Web Audio connections to a real-time
+ * AudioContext's destination go through a gain node per context, and media elements' volume is
+ * scaled (the volume the game set still reads back unchanged; elements played through Web Audio
+ * are left to the gain node). Returns how to set it.
+ */
+export declare function installMasterGain(win?: Window & typeof globalThis): {
+    set(level: number): void;
+};
+
+
+
 
 
 
@@ -515,6 +676,18 @@ 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;
+    /**
+     * Powly's sound menu (src/audio.ts): the game's own volume `channels` (sliders next to the
+     * player's overall volume), and whether the SDK applies the overall volume and mute to the
+     * page's sound itself (`auto`, default true).
+     */
+    audio?: AudioOptions;
 };
 export type LeaderboardEntry = {
     rank: number;
@@ -586,6 +759,25 @@ export type PowlySession = {
             invited: string[];
         }>;
     };
+    /**
+     * Other players of this game, by their player ID (from rooms, leaderboards, friends…).
+     * `open` shows Powly's own dialog over the game (drawn by Powly, not the game) with their
+     * profile, where the player can add them as a friend, block or report them; with
+     * `{ view: "report" }` it opens straight on reporting them. Games can't file reports
+     * themselves: the player always confirms in Powly's dialog. Resolves when it closes, with
+     * whether the player has them blocked now (hide their chat, say). Fails for player IDs that
+     * aren't from this game.
+     */
+    players: {
+        open(playerId: string, options?: {
+            view?: PlayerView;
+        }): Promise<PlayersOpenResult>;
+    };
+    /**
+     * The player's sound settings from Powly's options bar: overall volume, mute and the game's
+     * channels (`Powly.init({ audio: { channels } })`). Play each channel at `level(channel)`.
+     */
+    audio: AudioApi;
     /** Realtime rooms (parties) with other players of this game. */
     rooms: RoomsApi;
     /**
@@ -647,8 +839,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>;