@powly/sdk 0.4.1 → 0.8.0

package/dist/powly.mjs

@@ -1,6 +1,6 @@
-/* Powly SDK 0.4.1: ES module */
+/* Powly SDK 0.8.0: ES module */
 /** This SDK's version; Powly's Studio shows it next to the downloads. */
-const SDK_VERSION = "0.4.1";
+const SDK_VERSION = "0.8.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,16 +12,69 @@ const SDK_VERSION = "0.4.1";
 // 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);
+/** Channel ids: letters, digits, _ and -, starting with a letter, up to 32. */
+const AUDIO_CHANNEL_ID = /^[A-Za-z][A-Za-z0-9_-]{0,31}$/;
+const MAX_AUDIO_CHANNELS = 8;
+const MAX_AUDIO_LABEL = 32;
+/** The channels a game sent, cleaned up: valid ids, short labels, no repeats, at most 8. */
+function audioChannelsOf(value) {
+    if (!Array.isArray(value))
+        return [];
+    const channels = [];
+    for (const entry of value) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const { id, label, volume, toggle } = entry;
+        if (typeof id !== "string" || !AUDIO_CHANNEL_ID.test(id))
+            continue;
+        if (channels.some((channel) => channel.id === id))
+            continue;
+        const text = typeof label === "string" ? label.trim().slice(0, MAX_AUDIO_LABEL) : "";
+        const slider = volume !== false;
+        // Neither a slider nor a switch would show nothing: both, then.
+        const onOff = toggle !== false || !slider;
+        channels.push({ id, label: text || id, volume: slider, toggle: onOff });
+        if (channels.length === MAX_AUDIO_CHANNELS)
+            break;
+    }
+    return channels;
+}
+/** A volume between 0 and 1, or null. */
+const volumeOf = (value) => typeof value === "number" && Number.isFinite(value) ? Math.min(Math.max(value, 0), 1) : null;
+/** What a game may ask the Powly page for. */
+const HOST_METHODS = [
+    "getSessionToken",
+    "purchases.open",
+    "fullscreen.toggle",
+    "invites.open",
+    "players.open",
+    "twitch.connect",
+    "audio.set",
+    "audio.channels",
+    "quit",
+];
+/** "players.open": what Powly's player dialog opens on. */
+const PLAYER_VIEWS = ["profile", "report"];
 const isInitMessage = (data) => typeof data === "object" &&
     data !== null &&
     data.protocol === PROTOCOL &&
     data.type === "init" &&
     data.version === PROTOCOL_VERSION;
-const isRequestMessage = (data) => typeof data === "object" &&
+/** A request with a method this Powly doesn't know (from a newer SDK): answered with an error. */
+const isRequestShaped = (data) => typeof data === "object" &&
     data !== null &&
     data.type === "request" &&
-    Number.isInteger(data.id) &&
-    ["getSessionToken", "purchases.open", "fullscreen.toggle", "invites.open"].includes(data.method);
+    Number.isInteger(data.id);
+const isRequestMessage = (data) => isRequestShaped(data) &&
+    HOST_METHODS.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 +100,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 +114,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 +264,7 @@ function startPacSensor(port, { guard = false } = {}, win = window) {
         synthetic: 0,
         clicks: 0,
         teleportClicks: 0,
+        activity: 0,
     };
     const keyTimes = [];
     const clickTimes = [];
@@ -225,6 +282,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 +310,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 +397,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 +406,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)
@@ -822,6 +904,11 @@ function createRooms(options) {
 //     });
 //   }
 //
+// A game with a Twitch mode among others (Twitch chat "optional" in Studio) passes
+// `{ prompt: true }` when the player picks that mode: if they haven't connected Twitch, Powly asks
+// them to in its own dialog (drawn by Powly, outside the game), and `connect()` resolves once
+// they did or closed it.
+//
 // Chat is Twitch IRC over a WebSocket (https://dev.twitch.tv/docs/chat/irc/). The connection comes
 // back by itself when it drops, and stops when the launch ends.
 const TWITCH_CHAT_URL = "wss://irc-ws.chat.twitch.tv:443";
@@ -1062,8 +1149,12 @@ function createTwitch(options) {
     };
     return {
         info: options.getInfo,
-        async connect() {
-            const info = await options.getInfo();
+        async connect(connectOptions = {}) {
+            let info = await options.getInfo();
+            if (info.status === "not_connected" && connectOptions.prompt && options.prompt) {
+                if (await options.prompt())
+                    info = await options.getInfo();
+            }
             const next = info.status === "connected" ? info.channel : null;
             if (!next || stopped) {
                 disconnect();
@@ -1102,6 +1193,154 @@ function createTwitch(options) {
     };
 }
 
+// Powly's sound menu for games (`powly.audio`): the player's overall volume, a mute (Powly's M
+// key), and the kinds of sound the game registers (channels: music, drawing sounds…), each with a
+// volume slider and an on/off switch, or one of them. The player sets them in Powly's options
+// bar; the game hears "change".
+//
+//   const powly = await Powly.init({
+//     audio: { channels: [{ id: "music", label: "Music" }] },
+//   });
+//   await powly.audio.register({ id: "drawing", label: "Drawing sounds", volume: false });
+//   music.volume = powly.audio.level("music");
+//   powly.audio.on("change", () => { music.volume = powly.audio.level("music"); });
+//   if (powly.audio.level("drawing") > 0) playScribble();
+//
+// The overall volume and mute apply by themselves (`auto`, on by default): the SDK puts a volume
+// control in front of the page's speakers, for Web Audio (every connection to an AudioContext's
+// destination goes through it) and for <audio>/<video> (their volume is scaled). So every game
+// on this SDK follows Powly's volume, and channels only need the channel's own value:
+// `level(channel)` is what to play at either way.
+/** Volume of the page's sound overall: 0 when muted. */
+const masterLevel = (state) => (state.muted ? 0 : state.volume);
+/** Live references to objects, for walking them later without keeping them alive. */
+function weakList() {
+    const seen = new WeakSet();
+    const refs = new Set();
+    return {
+        add(item) {
+            if (seen.has(item))
+                return false;
+            seen.add(item);
+            refs.add(new WeakRef(item));
+            return true;
+        },
+        has: (item) => seen.has(item),
+        *[Symbol.iterator]() {
+            for (const ref of refs) {
+                const item = ref.deref();
+                if (item)
+                    yield item;
+                else
+                    refs.delete(ref);
+            }
+        },
+    };
+}
+/**
+ * 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.
+ */
+function installMasterGain(win = window) {
+    let level = 1;
+    // Web Audio.
+    const gainOf = new WeakMap();
+    const gains = weakList();
+    const Destination = win.AudioDestinationNode;
+    const Offline = win.OfflineAudioContext;
+    const nodeProto = win.AudioNode?.prototype;
+    const connect = nodeProto?.connect;
+    const disconnect = nodeProto?.disconnect;
+    /** The gain node standing in for `target` when it's a real-time context's destination. */
+    const standIn = (target) => {
+        if (!Destination || !(target instanceof Destination))
+            return null;
+        const context = target.context;
+        if (Offline && context instanceof Offline)
+            return null;
+        let gain = gainOf.get(context);
+        if (!gain) {
+            gain = context.createGain();
+            gain.gain.value = level;
+            gains.add(gain);
+            connect?.call(gain, target);
+            gainOf.set(context, gain);
+        }
+        return gain;
+    };
+    if (nodeProto && connect && disconnect) {
+        nodeProto.connect = function (target, ...rest) {
+            const gain = gains.has(this) ? null : standIn(target);
+            if (!gain)
+                return connect.call(this, target, ...rest);
+            connect.call(this, gain, ...rest);
+            // Chaining keeps working: connect() answers what it was given.
+            return target;
+        };
+        nodeProto.disconnect = function (...args) {
+            const gain = gains.has(this) ? null : standIn(args[0]);
+            return gain ? disconnect.call(this, gain, ...args.slice(1)) : disconnect.apply(this, args);
+        };
+    }
+    // Media elements: the volume the game set, and the one played (times `level`).
+    const media = win.HTMLMediaElement?.prototype;
+    const volume = media ? Object.getOwnPropertyDescriptor(media, "volume") : undefined;
+    const wanted = new WeakMap();
+    const elements = weakList();
+    const routed = new WeakSet();
+    const apply = (element) => {
+        const own = wanted.get(element) ?? 1;
+        volume?.set?.call(element, routed.has(element) ? own : own * level);
+    };
+    const track = (element) => {
+        if (!wanted.has(element))
+            wanted.set(element, volume?.get?.call(element) ?? 1);
+        elements.add(element);
+        apply(element);
+    };
+    if (media && volume?.get && volume.set) {
+        const { get, set } = volume;
+        Object.defineProperty(media, "volume", {
+            configurable: true,
+            enumerable: volume.enumerable,
+            get() {
+                return wanted.get(this) ?? get.call(this);
+            },
+            set(value) {
+                // Out of range throws, like the browser's own setter.
+                set.call(this, value);
+                wanted.set(this, value);
+                track(this);
+            },
+        });
+        const play = media.play;
+        media.play = function () {
+            track(this);
+            return play.call(this);
+        };
+    }
+    const createSource = win.AudioContext?.prototype.createMediaElementSource;
+    if (createSource) {
+        win.AudioContext.prototype.createMediaElementSource = function (element) {
+            routed.add(element);
+            track(element);
+            return createSource.call(this, element);
+        };
+    }
+    return {
+        set(next) {
+            level = next;
+            for (const gain of gains)
+                gain.gain.value = level;
+            for (const element of elements)
+                apply(element);
+        },
+    };
+}
+
+
 
 
 
@@ -1119,6 +1358,8 @@ function createTwitch(options) {
 //   const token = await powly.getSessionToken(); // send it to your backend, which verifies it
 //   const room = await powly.rooms.create();    // realtime parties (src/rooms.ts)
 //   await powly.twitch.connect();                // the streamer's Twitch chat (src/twitch.ts)
+//   await powly.players.open(playerId);          // Powly's profile dialog: add, block, report
+//   powly.audio.level("music");                  // Powly's sound menu (src/audio.ts)
 //
 // Nothing here is a security boundary: the game runs in the player's browser. Your backend must
 // verify session tokens (JWKS) or exchange them, and Powly checks everything server-side.
@@ -1163,6 +1404,12 @@ function init(options = {}) {
     if (origins.length === 0) {
         return Promise.reject(new PowlyError("This game only runs when launched from Powly."));
     }
+    const audioChannels = audioChannelsOf(options.audio?.channels ?? []);
+    // Before the game's engine makes a sound, so its connections go through the volume control.
+    const auto = options.audio?.auto !== false;
+    if (auto)
+        masterGain ??= installMasterGain();
+    const master = auto ? masterGain : null;
     return new Promise((resolve, reject) => {
         const channels = origins.map((origin) => {
             const channel = new MessageChannel();
@@ -1172,6 +1419,10 @@ function init(options = {}) {
                 type: "init",
                 sdkVersion: SDK_VERSION,
                 pac: 1,
+                ...(isOptionsButtonCorner(options.optionsButton) && {
+                    optionsButton: options.optionsButton,
+                }),
+                audio: { channels: audioChannels },
             };
             channel.port1.onmessage = (event) => {
                 const data = event.data;
@@ -1180,7 +1431,7 @@ function init(options = {}) {
                     for (const other of channels)
                         if (other !== channel)
                             other.port1.close();
-                    resolve(createSession(channel.port1, data));
+                    resolve(createSession(channel.port1, data, { channels: audioChannels, master }));
                 }
                 else if (data?.type === "failed") {
                     clearTimeout(timer);
@@ -1198,13 +1449,47 @@ function init(options = {}) {
         }, options.timeoutMs ?? 10_000);
     });
 }
-function createSession(port, ready) {
+/** The page's volume control (src/audio.ts), put in once even if init runs again. */
+let masterGain = null;
+/** The sound settings Powly sent, with every channel (on, at full volume, when it sent none). */
+function audioStateOf(value, channels) {
+    const sent = (typeof value === "object" && value !== null ? value : {});
+    const levels = ((typeof sent.channels === "object" && sent.channels) || {});
+    return {
+        volume: volumeOf(sent.volume) ?? 1,
+        muted: sent.muted === true,
+        channels: Object.fromEntries(channels.map((channel) => {
+            const level = levels[channel.id];
+            return [channel.id, { volume: volumeOf(level?.volume) ?? 1, on: level?.on !== false }];
+        })),
+    };
+}
+function createSession(port, ready, sound) {
     let token = ready.token;
     let expiresAt = Date.now() + ready.expiresIn * 1000;
     let refreshing = null;
     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;
+    // The player's sound settings; the page's volume follows them (auto).
+    let channels = sound.channels;
+    let audio = audioStateOf(ready.audio, channels);
+    const audioListeners = new Set();
+    sound.master?.set(masterLevel(audio));
+    const setAudio = (next) => {
+        audio = next;
+        sound.master?.set(masterLevel(audio));
+        for (const listener of audioListeners) {
+            try {
+                listener(audio);
+            }
+            catch (error) {
+                console.error("[powly] an audio listener failed", error);
+            }
+        }
+    };
     port.onmessage = (event) => {
         const data = event.data;
         if (data?.type === "response") {
@@ -1218,7 +1503,19 @@ function createSession(port, ready) {
                 waiting.reject(new PowlyError(data.error));
         }
         else if (data?.type === "event") {
-            for (const listener of listeners.get(data.event) ?? [])
+            const message = data;
+            if (message.event === "audio") {
+                if ("audio" in message)
+                    setAudio(audioStateOf(message.audio, channels));
+                return;
+            }
+            const name = message.event;
+            if (name === "shown") {
+                if (shown)
+                    return;
+                shown = true;
+            }
+            for (const listener of listeners.get(name) ?? [])
                 listener();
         }
     };
@@ -1278,7 +1575,10 @@ function createSession(port, ready) {
         invite: sendInvite,
     });
     listeners.get("ended")?.add(() => realtime.stop());
-    const twitch = createTwitch({ getInfo: () => api("/twitch") });
+    const twitch = createTwitch({
+        getInfo: () => api("/twitch"),
+        prompt: async () => (await call("twitch.connect")).connected,
+    });
     listeners.get("ended")?.add(() => twitch.stop());
     const saves = {
         get: async (key) => {
@@ -1325,6 +1625,52 @@ function createSession(port, ready) {
                 return (await call("invites.open", { params, members }));
             },
         },
+        players: {
+            open: async (playerId, options = {}) => (await call("players.open", {
+                playerId,
+                ...(options.view && { view: options.view }),
+            })),
+        },
+        audio: {
+            get volume() {
+                return audio.volume;
+            },
+            get muted() {
+                return audio.muted;
+            },
+            get channels() {
+                return Object.fromEntries(Object.entries(audio.channels).map(([id, state]) => [id, { ...state }]));
+            },
+            level(channel) {
+                const state = channel === undefined ? undefined : audio.channels[channel];
+                const own = state ? (state.on ? state.volume : 0) : 1;
+                return sound.master ? own : own * masterLevel(audio);
+            },
+            async register(channel) {
+                const next = audioChannelsOf([
+                    ...channels.filter((existing) => existing.id !== channel?.id),
+                    channel,
+                ]);
+                if (!next.some((entry) => entry.id === channel?.id)) {
+                    throw new PowlyError(`A channel needs an id of letters, digits, _ and -, and a game has up to ${MAX_AUDIO_CHANNELS}.`);
+                }
+                // Same order as before; a changed channel keeps its place.
+                channels = [
+                    ...channels.map((existing) => next.find((entry) => entry.id === existing.id) ?? existing),
+                    ...next.filter((entry) => !channels.some((existing) => existing.id === entry.id)),
+                ];
+                const result = await call("audio.channels", { channels });
+                setAudio(audioStateOf(result, channels));
+            },
+            async set(changes) {
+                const result = await call("audio.set", { audio: changes });
+                setAudio(audioStateOf(result, channels));
+            },
+            on(_event, listener) {
+                audioListeners.add(listener);
+                return () => audioListeners.delete(listener);
+            },
+        },
         rooms: realtime.rooms,
         twitch: {
             info: twitch.info,
@@ -1360,12 +1706,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.1",
+  "version": "0.8.0",
   "type": "module",
   "description": "Powly game SDK: launch handshake, session tokens and platform services.",
   "license": "MIT",
@@ -46,4 +46,4 @@
     "example:zip": "node scripts/example-zip.ts",
     "mirror": "node scripts/mirror.ts"
   }
-}
+}