onelobby 0.4.1 → 0.5.0

package/dist/onelobby.d.ts

@@ -4,8 +4,9 @@ import { Lobby, type RateLimit } from "./lobby.js";
 import { type LobbySummary } from "./signaling.js";
 import { type LinkFactory, type SocketFactory } from "./transport.js";
 import type { VoiceCodec, FrameSource, AudioSink } from "./voice-types.js";
+import { type Blueprint } from "./blueprint.js";
 export declare const LIB_NAME = "onelobby";
-export declare const LIB_VERSION = "0.4.1";
+export declare const LIB_VERSION = "0.5.0";
 /** Where `rememberSeat` keeps the resume token: the subset of the Web Storage API it uses. */
 export interface SeatStorage {
     getItem(key: string): string | null;
@@ -73,6 +74,16 @@ export interface OneLobbyOptions {
     /** @deprecated use `advanced.createSink` */
     createSink?: (() => AudioSink) | null;
 }
+/** Per-launch settings for `OneLobby.fromConfig`; everything else comes from the blueprint. */
+export interface FromConfigOverrides {
+    /** The player's name. Checked against `players.identity` and `players.maxNameLength`. */
+    displayName?: string;
+    /** Wins over `hosting.lobbyServer` (the file is the bottom layer: put `?lobby=` / storage / `<meta>` lookups here). */
+    lobbyServer?: string;
+    /** Default: `lobby.rejoin` from the file. */
+    rememberSeat?: boolean;
+    advanced?: AdvancedOptions;
+}
 export interface HostOptions {
     name: string;
     maxPlayers: number;
@@ -120,6 +131,16 @@ export declare class OneLobby extends Emitter<OneLobbyEvents> {
     private createMic;
     private createSink;
     private storage;
+    /** The validated, frozen onelobby.json this kit was built from (`OneLobby.fromConfig`); undefined for `new OneLobby`. */
+    readonly blueprint?: Blueprint;
+    /**
+     * Build a kit from an onelobby.json (already parsed; docs/design/blueprint.md s.7). Throws `bad_config` for an
+     * invalid file or name, `identity_anonymous` for a name when `players.identity` is "anonymous". Then `host()` and
+     * `hostDirect()` default their options from the file and the file's chat/listing switches are enforced.
+     */
+    static fromConfig(json: unknown, overrides?: FromConfigOverrides): OneLobby;
+    /** @internal Host options the blueprint implies (empty without one). */
+    blueprintHostDefaults(): Partial<HostOptions>;
     constructor(o: OneLobbyOptions);
     private get seatKey();
     private loadSeat;
@@ -137,7 +158,8 @@ export declare class OneLobby extends Emitter<OneLobbyEvents> {
     /** The signaling socket only (no hello yet); with a timeout (direct IP), no answer is `direct_unreachable`. */
     private open;
     private makeLobby;
-    host(h: HostOptions): Promise<Lobby>;
+    /** With a blueprint (`fromConfig`) every option defaults from `lobby.*`; explicit options win. */
+    host(opts?: Partial<HostOptions>): Promise<Lobby>;
     join(code: string): Promise<Lobby>;
     /**
      * Join a direct-IP host (docs/direct-ip.md): a join code from the host's screen (`6B01-RGFE-P2B`, any case, spaces

package/dist/onelobby.global.js

@@ -1,4 +1,4 @@
-/*! onelobby 0.4.1 | MIT license */
+/*! onelobby 0.5.0 | MIT license */
 "use strict";
 var OneLobby = (() => {
   var __defProp = Object.defineProperty;
@@ -22,6 +22,7 @@ var OneLobby = (() => {
   // src/global.ts
   var global_exports = {};
   __export(global_exports, {
+    BlueprintError: () => BlueprintError,
     CHAT_MAX_BYTES: () => CHAT_MAX_BYTES,
     Chat: () => Chat,
     DEFAULT_READY_TIMEOUT_MS: () => DEFAULT_READY_TIMEOUT_MS,
@@ -42,12 +43,14 @@ var OneLobby = (() => {
     closeCodeFor: () => closeCodeFor,
     codeFromUrl: () => codeFromUrl,
     decodeJoinCode: () => decodeJoinCode,
+    defineBlueprint: () => defineBlueprint,
     defineLobbyElement: () => defineLobbyElement,
     describeError: () => describeError,
     formatCode: () => formatCode,
     lobbyServerUrl: () => lobbyServerUrl,
     looksLikeJoinCode: () => looksLikeJoinCode,
     normalizeCode: () => normalizeCode,
+    parseBlueprint: () => parseBlueprint,
     shareUrl: () => shareUrl,
     webCodecsOpusAvailable: () => webCodecsOpusAvailable,
     webRtcLinkFactoryFor: () => webRtcLinkFactoryFor
@@ -3014,9 +3017,243 @@ registerProcessor('onelobby-capture', OneLobbyCapture);
     return { host, port, isIPv6: v6, display, url: `ws://${display}/`, candidate: `candidate:1 1 UDP 2122317823 ${host} ${port} typ host` };
   }
 
+  // src/blueprint.ts
+  function defineBlueprint(x) {
+    return x;
+  }
+  var BlueprintError = class extends OneLobbyError {
+    constructor(path, rule, detail) {
+      super("bad_config", `onelobby.json: ${path ? path + ": " : ""}${detail}`);
+      this.path = path;
+      this.rule = rule;
+    }
+    path;
+    rule;
+  };
+  var obj = (props, req) => ({ k: "obj", props, req });
+  var bool = { k: "bool" };
+  var str = (o = {}) => ({ k: "str", ...o });
+  var int = (min, max, zeroOr) => ({ k: "int", min, max, zeroOr });
+  var en = (...vals) => ({ k: "enum", vals });
+  var ROOT = obj(
+    {
+      version: { k: "const", val: 1 },
+      game: obj(
+        { id: str({ pattern: /^[A-Za-z0-9._-]{1,64}$/ }), netVersion: str({ min: 1, max: 32 }), title: str({ max: 64 }) },
+        ["id"]
+      ),
+      engine: en("web", "node-browser", "godot-csharp", "unity", "dotnet"),
+      hosting: obj({
+        direct: bool,
+        server: bool,
+        lobbyServer: str(),
+        directPort: int(1024, 65535),
+        openPort: bool,
+        relayOnly: bool,
+        allowedOrigins: { k: "strarr" }
+      }),
+      lobby: obj({
+        maxPlayers: int(2, 64),
+        listed: bool,
+        approveJoins: bool,
+        password: bool,
+        lateJoin: bool,
+        rejoin: bool,
+        joinLink: bool,
+        meta: { k: "meta" }
+      }),
+      sync: obj({ mode: en("raw", "lockstep", "replication"), tickRate: int(1, 120), hashEveryTicks: int(1, 1e5) }),
+      players: obj({ identity: en("name", "anonymous", "platform"), maxNameLength: int(1, 24) }),
+      chat: obj({ text: bool, voice: bool, voiceMode: en("pushToTalk", "voiceActivity") }),
+      session: obj({
+        hostLeaves: en("end", "migrate"),
+        pause: en("off", "host", "anyone"),
+        readyTimeoutMs: int(0, 6e5),
+        peerTimeoutMs: int(6e3, 6e5, true),
+        rateLimit: { k: "rate" },
+        runInBackground: bool
+      }),
+      platforms: obj({ steam: { k: "steam" }, epic: { k: "epic" }, discord: bool }),
+      ui: obj({ kind: en("drop-in", "generated", "none"), entry: str(), theme: en("light", "dark", "auto") })
+    },
+    ["game"]
+  );
+  var IGNORED = /* @__PURE__ */ new Set(["$schema", "$comment"]);
+  var Fail = class {
+    constructor(path, rule, detail) {
+      this.path = path;
+      this.rule = rule;
+      this.detail = detail;
+    }
+    path;
+    rule;
+    detail;
+  };
+  var join = (p, k) => p ? `${p}.${k}` : String(k);
+  var isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+  function check(n, v, path) {
+    switch (n.k) {
+      case "obj": {
+        if (!isObj(v)) throw new Fail(path, "type", "must be an object");
+        for (const r of n.req ?? []) if (!(r in v)) throw new Fail(join(path, r), "required", "is required");
+        for (const k of Object.keys(v)) if (!IGNORED.has(k) && !(k in n.props)) throw new Fail(join(path, k), "unknown_key", "unknown key");
+        for (const [k, sub] of Object.entries(n.props)) if (k in v) check(sub, v[k], join(path, k));
+        return;
+      }
+      case "str": {
+        if (typeof v !== "string") throw new Fail(path, "type", "must be a string");
+        if (n.min !== void 0 && v.length < n.min || n.max !== void 0 && v.length > n.max)
+          throw new Fail(path, "length", `must be ${n.min ?? 0} to ${n.max ?? "any"} characters`);
+        if (n.pattern && !n.pattern.test(v)) throw new Fail(path, "pattern", `must match ${n.pattern.source}`);
+        return;
+      }
+      case "int": {
+        if (typeof v !== "number" || !Number.isInteger(v)) throw new Fail(path, "type", "must be an integer");
+        if (n.zeroOr && v === 0) return;
+        if (n.min !== void 0 && v < n.min || n.max !== void 0 && v > n.max)
+          throw new Fail(path, "range", `must be ${n.zeroOr ? "0 or " : ""}${n.min ?? "any"} to ${n.max ?? "any"}`);
+        return;
+      }
+      case "bool":
+        if (typeof v !== "boolean") throw new Fail(path, "type", "must be true or false");
+        return;
+      case "enum":
+        if (typeof v !== "string" || !n.vals.includes(v)) throw new Fail(path, "enum", `must be one of ${n.vals.join(", ")}`);
+        return;
+      case "const":
+        if (v !== n.val) throw new Fail(path, "const", `must be ${n.val}`);
+        return;
+      case "strarr": {
+        if (!Array.isArray(v)) throw new Fail(path, "type", "must be an array of strings");
+        v.forEach((x, i) => {
+          if (typeof x !== "string") throw new Fail(join(path, i), "type", "must be a string");
+        });
+        return;
+      }
+      case "meta": {
+        if (!isObj(v)) throw new Fail(path, "type", "must be an object of strings");
+        const keys = Object.keys(v);
+        if (keys.length > 16) throw new Fail(path, "length", "at most 16 keys");
+        for (const k of keys) {
+          if (k.length > 64) throw new Fail(join(path, k), "length", "key is longer than 64 characters");
+          const x = v[k];
+          if (typeof x !== "string") throw new Fail(join(path, k), "type", "must be a string");
+          if (x.length > 64) throw new Fail(join(path, k), "length", "value is longer than 64 characters");
+        }
+        return;
+      }
+      case "rate":
+        check(obj({ messages: int(1), perMs: int(1) }, ["messages", "perMs"]), v, path);
+        return;
+      case "steam":
+        if (typeof v === "boolean") return;
+        if (!isObj(v)) throw new Fail(path, "type", "must be true, false or { appId }");
+        check(obj({ appId: int(1) }), v, path);
+        return;
+      case "epic": {
+        if (typeof v === "boolean") return;
+        if (!isObj(v)) throw new Fail(path, "type", "must be true, false or { productId }");
+        for (const k of Object.keys(v)) if (!IGNORED.has(k) && typeof v[k] !== "string") throw new Fail(join(path, k), "type", "must be a string");
+        return;
+      }
+    }
+  }
+  var sect = (x) => isObj(x) ? x : {};
+  function strip(o) {
+    if (Array.isArray(o)) return o.map(strip);
+    if (!isObj(o)) return o;
+    const out = {};
+    for (const [k, v] of Object.entries(o)) if (k !== "$comment" && k !== "$schema") out[k] = strip(v);
+    return out;
+  }
+  function deepFreeze(o) {
+    if (typeof o === "object" && o !== null && !Object.isFrozen(o)) {
+      Object.freeze(o);
+      for (const v of Object.values(o)) deepFreeze(v);
+    }
+    return o;
+  }
+  function fill(input) {
+    const game = sect(input.game);
+    const engine = input.engine;
+    const hosting = sect(input.hosting);
+    const lobby = sect(input.lobby);
+    const sync = sect(input.sync);
+    const players = sect(input.players);
+    const chat = sect(input.chat);
+    const session = sect(input.session);
+    const platforms = sect(input.platforms);
+    const ui = sect(input.ui);
+    const tickRate = sync.tickRate ?? 20;
+    const web = engine === "web";
+    const out = {
+      version: 1,
+      game: { id: game.id, netVersion: game.netVersion ?? "1", ...game.title !== void 0 ? { title: game.title } : {} },
+      ...engine !== void 0 ? { engine } : {},
+      hosting: {
+        direct: hosting.direct ?? !web,
+        server: hosting.server ?? web,
+        lobbyServer: hosting.lobbyServer ?? "",
+        directPort: hosting.directPort ?? 47810,
+        openPort: hosting.openPort ?? true,
+        relayOnly: hosting.relayOnly ?? false,
+        allowedOrigins: hosting.allowedOrigins ?? []
+      },
+      lobby: {
+        maxPlayers: lobby.maxPlayers ?? 4,
+        listed: lobby.listed ?? false,
+        approveJoins: lobby.approveJoins ?? false,
+        password: lobby.password ?? false,
+        lateJoin: lobby.lateJoin ?? true,
+        rejoin: lobby.rejoin ?? true,
+        joinLink: lobby.joinLink ?? (web || engine === "node-browser"),
+        meta: lobby.meta ?? {}
+      },
+      sync: { mode: sync.mode ?? "raw", tickRate, hashEveryTicks: sync.hashEveryTicks ?? tickRate },
+      players: { identity: players.identity ?? "name", maxNameLength: players.maxNameLength ?? 24 },
+      chat: { text: chat.text ?? true, voice: chat.voice ?? false, voiceMode: chat.voiceMode ?? "pushToTalk" },
+      session: {
+        hostLeaves: session.hostLeaves ?? "end",
+        pause: session.pause ?? "off",
+        readyTimeoutMs: session.readyTimeoutMs ?? 15e3,
+        peerTimeoutMs: session.peerTimeoutMs ?? 0,
+        ...session.rateLimit !== void 0 ? { rateLimit: session.rateLimit } : {},
+        runInBackground: session.runInBackground ?? true
+      },
+      platforms: { steam: platforms.steam ?? false, epic: platforms.epic ?? false, discord: platforms.discord ?? false },
+      ui: {
+        kind: ui.kind ?? (web ? "drop-in" : "generated"),
+        ...ui.entry !== void 0 ? { entry: ui.entry } : {},
+        theme: ui.theme ?? "auto"
+      }
+    };
+    return out;
+  }
+  function crossRules(b) {
+    if (!b.hosting.direct && !b.hosting.server) throw new Fail("hosting", "hosting_none", "at least one of direct, server must be true");
+    if (b.lobby.listed && b.lobby.approveJoins) throw new Fail("lobby", "listed_and_approve", "listed and approveJoins cannot both be true");
+    if (b.engine === "web" && b.hosting.direct) throw new Fail("hosting.direct", "direct_needs_listener", "engine web cannot host direct (a browser cannot listen on a port)");
+    const csharp = b.engine === "godot-csharp" || b.engine === "unity" || b.engine === "dotnet";
+    if (b.sync.mode === "replication" && !csharp) throw new Fail("sync.mode", "replication_needs_csharp", "replication needs engine godot-csharp, unity or dotnet");
+    if (b.sync.mode === "replication" && b.session.hostLeaves === "migrate") throw new Fail("session.hostLeaves", "migrate_with_replication", "replication has no host migration; use end");
+    if (b.session.hostLeaves === "migrate" && !b.hosting.server) throw new Fail("session.hostLeaves", "migrate_needs_server", "migrate needs hosting.server (direct lobbies always end)");
+  }
+  function parseBlueprint(json) {
+    let b;
+    try {
+      check(ROOT, json, "");
+      b = fill(strip(json));
+      crossRules(b);
+    } catch (e) {
+      if (e instanceof Fail) throw new BlueprintError(e.path, e.rule, e.detail);
+      throw e;
+    }
+    return deepFreeze(b);
+  }
+
   // src/onelobby.ts
   var LIB_NAME = "onelobby";
-  var LIB_VERSION = "0.4.1";
+  var LIB_VERSION = "0.5.0";
   var DEFAULT_READY_TIMEOUT_MS = 15e3;
   function hasMic() {
     return typeof navigator !== "undefined" && !!navigator.mediaDevices?.getUserMedia && typeof AudioWorkletNode !== "undefined";
@@ -3034,7 +3271,7 @@ registerProcessor('onelobby-capture', OneLobbyCapture);
     for (const l of liveSeats) if (l.resumeToken === token) return true;
     return false;
   }
-  var OneLobby = class extends Emitter {
+  var OneLobby = class _OneLobby extends Emitter {
     options;
     socketFactory;
     linkFactory;
@@ -3044,6 +3281,53 @@ registerProcessor('onelobby-capture', OneLobbyCapture);
     createMic;
     createSink;
     storage;
+    /** The validated, frozen onelobby.json this kit was built from (`OneLobby.fromConfig`); undefined for `new OneLobby`. */
+    blueprint;
+    /**
+     * Build a kit from an onelobby.json (already parsed; docs/design/blueprint.md s.7). Throws `bad_config` for an
+     * invalid file or name, `identity_anonymous` for a name when `players.identity` is "anonymous". Then `host()` and
+     * `hostDirect()` default their options from the file and the file's chat/listing switches are enforced.
+     */
+    static fromConfig(json, overrides = {}) {
+      const bp = parseBlueprint(json);
+      const name = (overrides.displayName ?? "").trim();
+      if (name) {
+        if (bp.players.identity === "anonymous") throw new OneLobbyError("identity_anonymous", "this game uses anonymous players: no display names");
+        if (name.length > bp.players.maxNameLength)
+          throw new BlueprintError("displayName", "length", `must be at most ${bp.players.maxNameLength} characters`);
+      }
+      const kit = new _OneLobby({
+        gameId: bp.game.id,
+        netVersion: bp.game.netVersion,
+        lobbyServer: overrides.lobbyServer ?? bp.hosting.lobbyServer,
+        mode: bp.sync.mode === "lockstep" ? "lockstep" : "raw",
+        // replication is C# only; JS speaks raw
+        tickRate: bp.sync.tickRate,
+        hashEveryTicks: bp.sync.hashEveryTicks,
+        displayName: name,
+        relayOnly: bp.hosting.relayOnly,
+        readyTimeoutMs: bp.session.readyTimeoutMs,
+        peerTimeoutMs: bp.session.peerTimeoutMs,
+        rememberSeat: overrides.rememberSeat ?? bp.lobby.rejoin,
+        advanced: overrides.advanced
+      });
+      kit.blueprint = bp;
+      return kit;
+    }
+    /** @internal Host options the blueprint implies (empty without one). */
+    blueprintHostDefaults() {
+      const bp = this.blueprint;
+      if (!bp) return {};
+      const name = this.options.displayName;
+      return {
+        name: name ? `${name}'s game` : "Game",
+        maxPlayers: bp.lobby.maxPlayers,
+        visibility: bp.lobby.listed ? "public" : bp.lobby.approveJoins ? "private" : "unlisted",
+        lateJoin: bp.lobby.lateJoin,
+        meta: { ...bp.lobby.meta },
+        ...bp.session.rateLimit ? { rateLimit: { ...bp.session.rateLimit } } : {}
+      };
+    }
     constructor(o) {
       super();
       const tickRate = o.tickRate ?? 20;
@@ -3152,6 +3436,7 @@ registerProcessor('onelobby-capture', OneLobbyCapture);
     }
     /** The signaling socket only (no hello yet); with a timeout (direct IP), no answer is `direct_unreachable`. */
     async open(url, factory, timeoutMs) {
+      if (!url.trim() && factory === defaultSocketFactory) throw new OneLobbyError("no_server", "no lobby server address (set hosting.lobbyServer or pass lobbyServer)");
       const sig = new SignalingClient(url, factory, this.clock);
       if (timeoutMs > 0) {
         let cancel = () => {
@@ -3189,6 +3474,7 @@ registerProcessor('onelobby-capture', OneLobbyCapture);
         rateLimit
       });
       lobby.errorSink = (e) => this.emit("error", e);
+      if (this.blueprint) guardLobby(lobby, this.blueprint);
       if (this.storage && !direct) {
         liveSeats.add(lobby);
         this.saveSeat(lobby.code, lobby.resumeToken);
@@ -3200,7 +3486,9 @@ registerProcessor('onelobby-capture', OneLobbyCapture);
       }
       return lobby;
     }
-    async host(h) {
+    /** With a blueprint (`fromConfig`) every option defaults from `lobby.*`; explicit options win. */
+    async host(opts) {
+      const h = { name: "Game", maxPlayers: 4, ...this.blueprintHostDefaults(), ...definedOnly(opts) };
       const { sig, welcome } = await this.connect();
       try {
         const state = await sig.request(
@@ -3331,6 +3619,7 @@ registerProcessor('onelobby-capture', OneLobbyCapture);
       }
     }
     async list(opts = {}) {
+      if (this.blueprint && !this.blueprint.hosting.server) throw new OneLobbyError("listing_disabled", "this game has no lobby server (hosting.server is false)");
       const { sig } = await this.connect();
       try {
         const res = await sig.request(
@@ -3351,6 +3640,35 @@ registerProcessor('onelobby-capture', OneLobbyCapture);
       return addr.display;
     }
   }
+  function definedOnly(o) {
+    const out = {};
+    if (o) {
+      for (const [k, v] of Object.entries(o)) if (v !== void 0) out[k] = v;
+    }
+    return out;
+  }
+  function guardLobby(lobby, bp) {
+    lobby.voice.mode = bp.chat.voiceMode;
+    if (!bp.chat.voice) {
+      const voice = lobby.voice;
+      const d = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(voice), "enabled");
+      if (d?.get && d.set) {
+        Object.defineProperty(voice, "enabled", {
+          configurable: true,
+          get: () => d.get.call(voice),
+          set: (v) => {
+            if (v) throw new OneLobbyError("voice_disabled", "this game has voice chat turned off (chat.voice is false)");
+            d.set.call(voice, v);
+          }
+        });
+      }
+    }
+    if (!bp.chat.text) {
+      lobby.chat.send = () => {
+        throw new OneLobbyError("chat_disabled", "this game has text chat turned off (chat.text is false)");
+      };
+    }
+  }
 
   // src/friendly.ts
   var ErrorCodes = {
@@ -3378,7 +3696,13 @@ registerProcessor('onelobby-capture', OneLobbyCapture);
     Closed: "closed",
     ServerLost: "server_lost",
     InvalidToken: "invalid_token",
-    NoServer: "no_server"
+    NoServer: "no_server",
+    // from a blueprint (onelobby.json)
+    BadConfig: "bad_config",
+    VoiceDisabled: "voice_disabled",
+    ChatDisabled: "chat_disabled",
+    ListingDisabled: "listing_disabled",
+    IdentityAnonymous: "identity_anonymous"
   };
   var TEXT = {
     // server errors (spec/signaling.md)
@@ -3401,7 +3725,13 @@ registerProcessor('onelobby-capture', OneLobbyCapture);
     server_lost: { message: "Lost the connection to the game server.", hint: "Your game may keep going; new players can't join until it's back." },
     invalid_token: { message: "Your old seat in that lobby is no longer available.", hint: "Join again with the lobby code." },
     ice_failed: { message: "Couldn't connect to the other players.", hint: "Some networks (school, work, public Wi-Fi) block game connections. Try another network or a phone hotspot." },
+    no_server: { message: "This game has no lobby server address yet.", hint: "Enter one in the multiplayer settings, or host from your own computer with a join code." },
     timeout: { message: "The connection took too long.", hint: "Check your internet connection, then try again." },
+    voice_disabled: { message: "Voice chat is turned off in this game." },
+    chat_disabled: { message: "Text chat is turned off in this game." },
+    listing_disabled: { message: "This game has no public lobby list.", hint: "Join with a code or a link from the host." },
+    identity_anonymous: { message: "This game doesn't use player names.", hint: "Everyone shows up as Player 1, Player 2, and so on." },
+    bad_config: { message: "The game's multiplayer settings file is not valid.", hint: "Let the game's owner know; the details are in the error message." },
     left: { message: "You left the lobby." },
     unknown: { message: "Something went wrong.", hint: "Try again. If it keeps happening, reload the page." }
   };