@ikirmikir/game-sdk 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @ikirmikir/game-sdk
 
-Optional SDK for browser games on [Ikirmikir](https://ikirmikir.com): real loading progress, gameplay start and stop, pause and resume, the player's sound switch, player context (language, device, touch) and sharing. Any engine that runs in a browser. Outside Ikirmikir it runs in local mode, so one build works everywhere, and no call ever throws.
+Optional SDK for browser games on [Ikirmikir](https://ikirmikir.com): real loading progress, gameplay start and stop, pause and resume, the player's sound switch, player context (language, device, touch), sharing, and multiplayer rooms to play with friends (1.1). Any engine that runs in a browser. Outside Ikirmikir it runs in local mode, so one build works everywhere, and no call ever throws.
 
 ```bash
 npm install @ikirmikir/game-sdk
@@ -14,12 +14,16 @@ ik.game.loadingProgress(50);
 ik.game.loadingDone();
 ik.on("pause", () => game.pause());
 ik.on("mute", muted => { audio.muted = muted; });
+
+const { room, error } = await ik.multiplayer.create({ maxPlayers: 2 }); // inside Ikirmikir only
+room?.on("message", (data, from) => applyMove(data));
+room?.send({ cell: 4 });
 ```
 
 Without a bundler, use `dist/ikirmikir.js` (gives `window.Ikirmikir`), from this package or the CDN:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@ikirmikir/game-sdk@1.0.0/dist/ikirmikir.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@ikirmikir/game-sdk@1.1.0/dist/ikirmikir.js"></script>
 ```
 
 Quick start, API reference and a test tool: https://ikirmikir.com/developers/

package/dist/ikirmikir.js

@@ -1,2 +1,2 @@
-/*! @ikirmikir/game-sdk 1.0.0 | MIT | https://ikirmikir.com/developers/ */
-"use strict";(()=>{var I=["loading","gameplay","pause","mute","context","share"],h=e=>typeof e=="object"&&e!==null&&!Array.isArray(e),P=(e,t)=>typeof e=="string"&&e.length>0&&e.length<=t,C=(e,t,i)=>Number.isInteger(e)&&e>=t&&e<=i,c=e=>typeof e=="boolean";function x(e){if(!h(e)||e.ik!==1)return null;switch(e.type){case"welcome":{let t=e.context;return!Array.isArray(e.features)||!c(e.muted)||!h(t)||!P(t.language,35)||t.device!=="mobile"&&t.device!=="desktop"||!c(t.touch)?null:{ik:1,type:"welcome",features:I.filter(u=>e.features.includes(u)),context:{language:t.language,device:t.device,touch:t.touch},muted:e.muted}}case"pause":return{ik:1,type:"pause"};case"resume":return{ik:1,type:"resume"};case"mute":return c(e.muted)?{ik:1,type:"mute",muted:e.muted}:null;case"shared":return C(e.id,0,1e9)&&c(e.shared)?{ik:1,type:"shared",id:e.id,shared:e.shared}:null;default:return null}}function b(e){return e==="https://ikirmikir.com"||e==="http://localhost:3000"||e==="http://127.0.0.1:3000"||/^https:\/\/([0-9a-f]{8}\.)?ikirmikir\.pages\.dev$/.test(e)}var M="1.0.0",R=1500,w;function T(e){return w??(w=F(e))}async function F({gameId:e}){let t={pause:new Set,resume:new Set,mute:new Set},i=(r,...a)=>t[r].forEach(o=>{try{o(...a)}catch(n){console.error(n)}}),u="local",f=A(),p=!1,g=[],s,m=new Map,S=1,k=-1,l=!1,y=!1,d=r=>{if(s)try{parent.postMessage({ik:1,...r},s)}catch{}};if(typeof window<"u"&&window.parent!==window){let r=new Promise(a=>{addEventListener("message",o=>{if(o.source!==window.parent||!b(o.origin)||s&&o.origin!==s)return;let n=x(o.data);if(n){if(n.type==="welcome")return s?void 0:(s=o.origin,u="ikirmikir",f=n.context,p=n.muted,g=n.features,a(!0));s&&(n.type==="pause"||n.type==="resume"?i(n.type):n.type==="mute"?n.muted!==p&&(p=n.muted,i("mute",p)):n.type==="shared"&&(m.get(n.id)?.(n.shared),m.delete(n.id)))}}),setTimeout(()=>a(!1),R)});try{parent.postMessage({ik:1,type:"hello",gameId:String(e).slice(0,64),sdk:M},"*")}catch{}await r}return u==="local"&&(g=["gameplay","loading","pause","context",...E()?["share"]:[]],typeof document<"u"&&document.addEventListener("visibilitychange",()=>i(document.hidden?"pause":"resume"))),{get env(){return u},get context(){return{...f}},get muted(){return p},has:r=>g.includes(r),game:{loadingProgress(r){let a=Math.max(0,Math.min(100,Math.round(Number(r)||0)));y||a===k||(k=a,d({type:"loading",progress:a}))},loadingDone(){y||(y=!0,d({type:"ready"}))},gameplayStart(){l||(l=!0,d({type:"gameplay",playing:l}))},gameplayStop(){l&&(l=!1,d({type:"gameplay",playing:l}))}},on(r,a){let o=t[r];return!o||typeof a!="function"?()=>{}:(o.add(a),()=>{o.delete(a)})},async share(){if(u==="local"){if(!E())return{shared:!1};try{return await navigator.share({url:location.href}),{shared:!0}}catch{return{shared:!1}}}let r=S++;return new Promise(a=>{m.set(r,o=>a({shared:o})),setTimeout(()=>{m.delete(r)&&a({shared:!1})},6e4),d({type:"share",id:r})})}}}function A(){let e=typeof navigator<"u"?navigator:void 0,t=!!e&&e.maxTouchPoints>0,i=typeof matchMedia<"u"&&matchMedia("(pointer: coarse)").matches;return{language:(e?.language||"en").split("-")[0],device:i?"mobile":"desktop",touch:t}}var E=()=>typeof navigator<"u"&&typeof navigator.share=="function",O={init:T,VERSION:M};globalThis.Ikirmikir=O;})();
+/*! @ikirmikir/game-sdk 1.1.0 | MIT | https://ikirmikir.com/developers/ */
+"use strict";(()=>{var h={maxPlayers:8,maxMessageBytes:4096,messagesPerSecond:20,reconnectSeconds:30,emptyMinutes:10};var P=e=>typeof e=="string"&&/^[A-HJ-NP-Z2-9]{5}$/.test(e),G=["not-found","full","too-big","slow-down","unavailable","bad-request"];function j(e){try{let n=JSON.stringify(e);return n===void 0?-1:new TextEncoder().encode(n).length}catch{return-1}}var I=1,U=["loading","gameplay","pause","mute","context","share","multiplayer"],$=["reconnecting","connected","closed"],C=e=>typeof e=="object"&&e!==null&&!Array.isArray(e),A=(e,n)=>typeof e=="string"&&e.length>0&&e.length<=n,E=(e,n,m)=>Number.isInteger(e)&&e>=n&&e<=m,R=e=>typeof e=="boolean",T=e=>typeof e=="string"&&/^[a-z0-9]{1,16}$/.test(e),N=e=>C(e)&&T(e.id)&&A(e.name,32)&&R(e.connected),F=e=>Array.isArray(e)&&e.length<=h.maxPlayers&&e.every(N),M=e=>({id:e.id,name:e.name,connected:e.connected});function L(e){if(!C(e)||e.ik!==I)return null;switch(e.type){case"welcome":{let n=e.context;if(!Array.isArray(e.features)||!R(e.muted)||!C(n)||!A(n.language,35)||n.device!=="mobile"&&n.device!=="desktop"||!R(n.touch))return null;let m=U.filter(p=>e.features.includes(p)),c=P(e.invite)?e.invite:null;return{ik:1,type:"welcome",features:m,context:{language:n.language,device:n.device,touch:n.touch},muted:e.muted,invite:c}}case"pause":return{ik:1,type:"pause"};case"resume":return{ik:1,type:"resume"};case"mute":return R(e.muted)?{ik:1,type:"mute",muted:e.muted}:null;case"shared":return E(e.id,0,1e9)&&R(e.shared)?{ik:1,type:"shared",id:e.id,shared:e.shared}:null;case"mp.room":return E(e.id,0,1e9)&&P(e.code)&&A(e.link,300)&&N(e.you)&&F(e.players)&&E(e.max,2,h.maxPlayers)?{ik:1,type:"mp.room",id:e.id,code:e.code,link:e.link,you:M(e.you),players:e.players.map(M),max:e.max}:null;case"mp.error":return E(e.id,0,1e9)&&G.includes(e.error)?{ik:1,type:"mp.error",id:e.id,error:e.error}:null;case"mp.player":return N(e.player)?{ik:1,type:"mp.player",player:M(e.player)}:null;case"mp.away":case"mp.back":case"mp.gone":return T(e.id)?{ik:1,type:e.type,id:e.id}:null;case"mp.msg":return T(e.from)&&"data"in e?{ik:1,type:"mp.msg",from:e.from,data:e.data}:null;case"mp.status":return $.includes(e.status)&&F(e.players)?{ik:1,type:"mp.status",status:e.status,players:e.players.map(M)}:null;default:return null}}function _(e){return e==="https://ikirmikir.com"||e==="http://localhost:3000"||e==="http://127.0.0.1:3000"||/^https:\/\/([0-9a-f]{8}\.)?ikirmikir\.pages\.dev$/.test(e)}function z(e,n,m,c){let p=new Map,v=1,y=null;function d(r){let o={join:new Set,leave:new Set,away:new Set,back:new Set,message:new Set,status:new Set},i=r.players,g=!0,k=(t,...a)=>o[t].forEach(f=>{try{f(...a)}catch(w){console.error(w)}}),b=t=>i.find(a=>a.id===t),l=(t,a,f)=>{let w=b(t);w&&(w.connected=a,k(f,{...w}))},s={code:r.code,link:r.link,you:r.you,max:r.max,get players(){return i.map(t=>({...t}))},send(t){let a=j(t);return!g||a<0||a>h.maxMessageBytes?!1:(e({type:"mp.send",data:t}),!0)},invite:()=>g?c():Promise.resolve({shared:!1}),leave(){g&&(g=!1,y=null,e({type:"mp.leave"}))},on(t,a){let f=o[t];return!f||typeof a!="function"?()=>{}:(f.add(a),()=>{f.delete(a)})}};function u(t){if(g)switch(t.type){case"mp.player":return i=[...i.filter(a=>a.id!==t.player.id),t.player],k("join",{...t.player});case"mp.away":return l(t.id,!1,"away");case"mp.back":return l(t.id,!0,"back");case"mp.gone":{let a=b(t.id);i=i.filter(f=>f.id!==t.id),a&&k("leave",{...a});return}case"mp.msg":{let a=b(t.from);a&&k("message",t.data,{...a});return}case"mp.status":return t.status==="connected"&&(i=t.players),t.status==="closed"&&(g=!1,y=null),k("status",t.status)}}return{room:s,handle:u}}function x(r){if(!n())return Promise.resolve({error:"not-available-here"});y?.room.leave();let o=v++;return new Promise(i=>{p.set(o,i),setTimeout(()=>{p.delete(o)&&i({error:"unavailable"})},2e4),e({...r,id:o})})}let O={get invite(){return m()},create(r){let o=Math.round(Number(r?.maxPlayers??h.maxPlayers));return o>=2&&o<=h.maxPlayers?x({type:"mp.create",maxPlayers:o}):Promise.resolve({error:"bad-request"})},join(r){let o=String(r??"").trim().toUpperCase();return P(o)?x({type:"mp.join",code:o}):Promise.resolve({error:"not-found"})}};function S(r){if(r.type==="mp.room"){let o=p.get(r.id);return o&&(p.delete(r.id),y=d(r),o({room:y.room})),!0}return r.type==="mp.error"?(p.get(r.id)?.({error:r.error}),p.delete(r.id),!0):r.type.startsWith("mp.")?(y?.handle(r),!0):!1}return{api:O,receive:S}}var J="1.1.0",q=1500,D;function V(e){return D??(D=K(e))}async function K({gameId:e}){let n={pause:new Set,resume:new Set,mute:new Set},m=(l,...s)=>n[l].forEach(u=>{try{u(...s)}catch(t){console.error(t)}}),c="local",p=W(),v=!1,y=[],d,x=new Map,O=1,S=-1,r=!1,o=!1,i=l=>{if(d)try{parent.postMessage({ik:I,...l},d)}catch{}},g=null,k=z(i,()=>c==="ikirmikir"&&y.includes("multiplayer"),()=>g,()=>b(!0));async function b(l){if(c==="local"){if(l||!H())return{shared:!1};try{return await navigator.share({url:location.href}),{shared:!0}}catch{return{shared:!1}}}let s=O++;return new Promise(u=>{x.set(s,t=>u({shared:t})),setTimeout(()=>{x.delete(s)&&u({shared:!1})},6e4),i({type:"share",id:s,...l?{room:!0}:{}})})}if(typeof window<"u"&&window.parent!==window){let l=new Promise(s=>{addEventListener("message",u=>{if(u.source!==window.parent||!_(u.origin)||d&&u.origin!==d)return;let t=L(u.data);if(t){if(t.type==="welcome")return d?void 0:(d=u.origin,c="ikirmikir",p=t.context,v=t.muted,y=t.features,g=t.invite,s(!0));!d||k.receive(t)||(t.type==="pause"||t.type==="resume"?m(t.type):t.type==="mute"?t.muted!==v&&(v=t.muted,m("mute",v)):t.type==="shared"&&(x.get(t.id)?.(t.shared),x.delete(t.id)))}}),setTimeout(()=>s(!1),q)});try{parent.postMessage({ik:I,type:"hello",gameId:String(e).slice(0,64),sdk:J},"*")}catch{}await l}return c==="local"&&(y=["gameplay","loading","pause","context",...H()?["share"]:[]],typeof document<"u"&&document.addEventListener("visibilitychange",()=>m(document.hidden?"pause":"resume"))),{get env(){return c},get context(){return{...p}},get muted(){return v},has:l=>y.includes(l),game:{loadingProgress(l){let s=Math.max(0,Math.min(100,Math.round(Number(l)||0)));o||s===S||(S=s,i({type:"loading",progress:s}))},loadingDone(){o||(o=!0,i({type:"ready"}))},gameplayStart(){r||(r=!0,i({type:"gameplay",playing:r}))},gameplayStop(){r&&(r=!1,i({type:"gameplay",playing:r}))}},on(l,s){let u=n[l];return!u||typeof s!="function"?()=>{}:(u.add(s),()=>{u.delete(s)})},share:()=>b(!1),multiplayer:k.api}}function W(){let e=typeof navigator<"u"?navigator:void 0,n=!!e&&e.maxTouchPoints>0,m=typeof matchMedia<"u"&&matchMedia("(pointer: coarse)").matches;return{language:(e?.language||"en").split("-")[0],device:m?"mobile":"desktop",touch:n}}var H=()=>typeof navigator<"u"&&typeof navigator.share=="function",B={init:V,VERSION:J};globalThis.Ikirmikir=B;})();

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import { type Context, type Feature } from "./protocol";
+import { type Multiplayer } from "./multiplayer";
 export type { Context, Feature } from "./protocol";
-export declare const VERSION = "1.0.0";
+export type { Multiplayer, MultiplayerError, Player, Room, RoomResult, RoomStatus } from "./multiplayer";
+export declare const VERSION = "1.1.0";
 type Events = {
     pause: () => void;
     resume: () => void;
@@ -31,6 +33,8 @@ export interface Sdk {
     share(): Promise<{
         shared: boolean;
     }>;
+    /** Rooms to play with friends, inside Ikirmikir only (has("multiplayer")). */
+    readonly multiplayer: Multiplayer;
 }
 export interface InitOptions {
     /** The game's id on Ikirmikir, for example "runbro". */

package/dist/index.js

@@ -1,12 +1,40 @@
-/*! @ikirmikir/game-sdk 1.0.0 | MIT | https://ikirmikir.com/developers/ */
+/*! @ikirmikir/game-sdk 1.1.0 | MIT | https://ikirmikir.com/developers/ */
+
+// src/room.ts
+var LIMITS = {
+  maxPlayers: 8,
+  maxMessageBytes: 4096,
+  // one game message, as JSON
+  messagesPerSecond: 20,
+  // per player
+  reconnectSeconds: 30,
+  // a dropped player keeps their seat this long
+  emptyMinutes: 10
+  // a room nobody is in closes after this long
+};
+var isRoomCode = (s) => typeof s === "string" && /^[A-HJ-NP-Z2-9]{5}$/.test(s);
+var ROOM_ERRORS = ["not-found", "full", "too-big", "slow-down", "unavailable", "bad-request"];
+function jsonSize(v) {
+  try {
+    const s = JSON.stringify(v);
+    return s === void 0 ? -1 : new TextEncoder().encode(s).length;
+  } catch {
+    return -1;
+  }
+}
 
 // src/protocol.ts
 var PROTOCOL = 1;
-var FEATURES = ["loading", "gameplay", "pause", "mute", "context", "share"];
+var FEATURES = ["loading", "gameplay", "pause", "mute", "context", "share", "multiplayer"];
+var STATUSES = ["reconnecting", "connected", "closed"];
 var obj = (d) => typeof d === "object" && d !== null && !Array.isArray(d);
 var str = (v, max) => typeof v === "string" && v.length > 0 && v.length <= max;
 var int = (v, min, max) => Number.isInteger(v) && v >= min && v <= max;
 var bool = (v) => typeof v === "boolean";
+var pid = (v) => typeof v === "string" && /^[a-z0-9]{1,16}$/.test(v);
+var player = (p) => obj(p) && pid(p.id) && str(p.name, 32) && bool(p.connected);
+var players = (v) => Array.isArray(v) && v.length <= LIMITS.maxPlayers && v.every(player);
+var cleanPlayer = (p) => ({ id: p.id, name: p.name, connected: p.connected });
 function readPageMessage(d) {
   if (!obj(d) || d.ik !== PROTOCOL) return null;
   switch (d.type) {
@@ -15,7 +43,8 @@ function readPageMessage(d) {
       if (!Array.isArray(d.features) || !bool(d.muted) || !obj(c)) return null;
       if (!str(c.language, 35) || c.device !== "mobile" && c.device !== "desktop" || !bool(c.touch)) return null;
       const features = FEATURES.filter((f) => d.features.includes(f));
-      return { ik: 1, type: "welcome", features, context: { language: c.language, device: c.device, touch: c.touch }, muted: d.muted };
+      const invite = isRoomCode(d.invite) ? d.invite : null;
+      return { ik: 1, type: "welcome", features, context: { language: c.language, device: c.device, touch: c.touch }, muted: d.muted, invite };
     }
     case "pause":
       return { ik: 1, type: "pause" };
@@ -25,6 +54,20 @@ function readPageMessage(d) {
       return bool(d.muted) ? { ik: 1, type: "mute", muted: d.muted } : null;
     case "shared":
       return int(d.id, 0, 1e9) && bool(d.shared) ? { ik: 1, type: "shared", id: d.id, shared: d.shared } : null;
+    case "mp.room":
+      return int(d.id, 0, 1e9) && isRoomCode(d.code) && str(d.link, 300) && player(d.you) && players(d.players) && int(d.max, 2, LIMITS.maxPlayers) ? { ik: 1, type: "mp.room", id: d.id, code: d.code, link: d.link, you: cleanPlayer(d.you), players: d.players.map(cleanPlayer), max: d.max } : null;
+    case "mp.error":
+      return int(d.id, 0, 1e9) && ROOM_ERRORS.includes(d.error) ? { ik: 1, type: "mp.error", id: d.id, error: d.error } : null;
+    case "mp.player":
+      return player(d.player) ? { ik: 1, type: "mp.player", player: cleanPlayer(d.player) } : null;
+    case "mp.away":
+    case "mp.back":
+    case "mp.gone":
+      return pid(d.id) ? { ik: 1, type: d.type, id: d.id } : null;
+    case "mp.msg":
+      return pid(d.from) && "data" in d ? { ik: 1, type: "mp.msg", from: d.from, data: d.data } : null;
+    case "mp.status":
+      return STATUSES.includes(d.status) && players(d.players) ? { ik: 1, type: "mp.status", status: d.status, players: d.players.map(cleanPlayer) } : null;
     default:
       return null;
   }
@@ -33,8 +76,143 @@ function isIkirmikirOrigin(origin) {
   return origin === "https://ikirmikir.com" || origin === "http://localhost:3000" || origin === "http://127.0.0.1:3000" || /^https:\/\/([0-9a-f]{8}\.)?ikirmikir\.pages\.dev$/.test(origin);
 }
 
+// src/multiplayer.ts
+function multiplayer(send, inside, invite, shareInvite) {
+  const pending = /* @__PURE__ */ new Map();
+  let nextId = 1, current = null;
+  function makeRoom(m) {
+    const listeners = { join: /* @__PURE__ */ new Set(), leave: /* @__PURE__ */ new Set(), away: /* @__PURE__ */ new Set(), back: /* @__PURE__ */ new Set(), message: /* @__PURE__ */ new Set(), status: /* @__PURE__ */ new Set() };
+    let players2 = m.players, open = true;
+    const emit = (e, ...args) => listeners[e].forEach((fn) => {
+      try {
+        fn(...args);
+      } catch (err) {
+        console.error(err);
+      }
+    });
+    const find = (id) => players2.find((p) => p.id === id);
+    const mark = (id, connected, e) => {
+      const p = find(id);
+      if (p) {
+        p.connected = connected;
+        emit(e, { ...p });
+      }
+    };
+    const room = {
+      code: m.code,
+      link: m.link,
+      you: m.you,
+      max: m.max,
+      get players() {
+        return players2.map((p) => ({ ...p }));
+      },
+      send(data) {
+        const n = jsonSize(data);
+        if (!open || n < 0 || n > LIMITS.maxMessageBytes) return false;
+        send({ type: "mp.send", data });
+        return true;
+      },
+      invite: () => open ? shareInvite() : Promise.resolve({ shared: false }),
+      leave() {
+        if (open) {
+          open = false;
+          current = null;
+          send({ type: "mp.leave" });
+        }
+      },
+      on(event, listener) {
+        const set = listeners[event];
+        if (!set || typeof listener !== "function") return () => {
+        };
+        set.add(listener);
+        return () => {
+          set.delete(listener);
+        };
+      }
+    };
+    function handle(e) {
+      if (!open) return;
+      switch (e.type) {
+        case "mp.player":
+          players2 = [...players2.filter((p) => p.id !== e.player.id), e.player];
+          return emit("join", { ...e.player });
+        case "mp.away":
+          return mark(e.id, false, "away");
+        case "mp.back":
+          return mark(e.id, true, "back");
+        case "mp.gone": {
+          const p = find(e.id);
+          players2 = players2.filter((x) => x.id !== e.id);
+          if (p) emit("leave", { ...p });
+          return;
+        }
+        case "mp.msg": {
+          const p = find(e.from);
+          if (p) emit("message", e.data, { ...p });
+          return;
+        }
+        case "mp.status":
+          if (e.status === "connected") players2 = e.players;
+          if (e.status === "closed") {
+            open = false;
+            current = null;
+          }
+          return emit("status", e.status);
+      }
+    }
+    return { room, handle };
+  }
+  function ask(m) {
+    if (!inside()) return Promise.resolve({ error: "not-available-here" });
+    current?.room.leave();
+    const id = nextId++;
+    return new Promise((resolve) => {
+      pending.set(id, resolve);
+      setTimeout(() => {
+        if (pending.delete(id)) resolve({ error: "unavailable" });
+      }, 2e4);
+      send({ ...m, id });
+    });
+  }
+  const api = {
+    get invite() {
+      return invite();
+    },
+    create(options) {
+      const max = Math.round(Number(options?.maxPlayers ?? LIMITS.maxPlayers));
+      if (!(max >= 2 && max <= LIMITS.maxPlayers)) return Promise.resolve({ error: "bad-request" });
+      return ask({ type: "mp.create", maxPlayers: max });
+    },
+    join(code) {
+      const c = String(code ?? "").trim().toUpperCase();
+      return isRoomCode(c) ? ask({ type: "mp.join", code: c }) : Promise.resolve({ error: "not-found" });
+    }
+  };
+  function receive(m) {
+    if (m.type === "mp.room") {
+      const done = pending.get(m.id);
+      if (!done) return true;
+      pending.delete(m.id);
+      current = makeRoom(m);
+      done({ room: current.room });
+      return true;
+    }
+    if (m.type === "mp.error") {
+      pending.get(m.id)?.({ error: m.error });
+      pending.delete(m.id);
+      return true;
+    }
+    if (m.type.startsWith("mp.")) {
+      current?.handle(m);
+      return true;
+    }
+    return false;
+  }
+  return { api, receive };
+}
+
 // src/index.ts
-var VERSION = "1.0.0";
+var VERSION = "1.1.0";
 var HANDSHAKE_MS = 1500;
 var instance;
 function init(options) {
@@ -59,6 +237,27 @@ async function start({ gameId }) {
     } catch {
     }
   };
+  let invite = null;
+  const mp = multiplayer(send, () => env === "ikirmikir" && features.includes("multiplayer"), () => invite, () => shareVia(true));
+  async function shareVia(room) {
+    if (env === "local") {
+      if (room || !canShare()) return { shared: false };
+      try {
+        await navigator.share({ url: location.href });
+        return { shared: true };
+      } catch {
+        return { shared: false };
+      }
+    }
+    const id = nextShare++;
+    return new Promise((resolve) => {
+      shares.set(id, (shared) => resolve({ shared }));
+      setTimeout(() => {
+        if (shares.delete(id)) resolve({ shared: false });
+      }, 6e4);
+      send({ type: "share", id, ...room ? { room: true } : {} });
+    });
+  }
   if (typeof window !== "undefined" && window.parent !== window) {
     const welcome = new Promise((resolve) => {
       addEventListener("message", (e) => {
@@ -72,9 +271,10 @@ async function start({ gameId }) {
           context = m.context;
           muted = m.muted;
           features = m.features;
+          invite = m.invite;
           return resolve(true);
         }
-        if (!page) return;
+        if (!page || mp.receive(m)) return;
         if (m.type === "pause" || m.type === "resume") emit(m.type);
         else if (m.type === "mute") {
           if (m.muted !== muted) {
@@ -145,25 +345,8 @@ async function start({ gameId }) {
         set.delete(listener);
       };
     },
-    async share() {
-      if (env === "local") {
-        if (!canShare()) return { shared: false };
-        try {
-          await navigator.share({ url: location.href });
-          return { shared: true };
-        } catch {
-          return { shared: false };
-        }
-      }
-      const id = nextShare++;
-      return new Promise((resolve) => {
-        shares.set(id, (shared) => resolve({ shared }));
-        setTimeout(() => {
-          if (shares.delete(id)) resolve({ shared: false });
-        }, 6e4);
-        send({ type: "share", id });
-      });
-    }
+    share: () => shareVia(false),
+    multiplayer: mp.api
   };
 }
 function localContext() {

package/dist/multiplayer.d.ts

@@ -0,0 +1,56 @@
+import type { GameMessage, MultiplayerError, PageMessage, Player, RoomStatus } from "./protocol";
+export type { MultiplayerError, Player, RoomStatus } from "./protocol";
+type RoomEvents = {
+    join: (player: Player) => void;
+    leave: (player: Player) => void;
+    away: (player: Player) => void;
+    back: (player: Player) => void;
+    message: (data: unknown, from: Player) => void;
+    status: (status: RoomStatus) => void;
+};
+export interface Room {
+    /** The room code, for example "KX7Q2". Friends can type it to join. */
+    readonly code: string;
+    /** The invite link: opening it brings a friend into this room. */
+    readonly link: string;
+    /** You, as the other players see you (a fun name like "Rickshaw 42"). */
+    readonly you: Player;
+    /** Everyone in the room, you included, in the order they came in. */
+    readonly players: Player[];
+    /** Most players the room takes. */
+    readonly max: number;
+    /** Send something to every other player: anything JSON can hold, up to 4 KB. False when it can't be sent. */
+    send(data: unknown): boolean;
+    /** Open the share sheet with this room's invite link (Ikirmikir copies the link when there is no share sheet). */
+    invite(): Promise<{
+        shared: boolean;
+    }>;
+    /** Leave the room for good. */
+    leave(): void;
+    /** Listen for room events. Returns a function that stops listening. */
+    on<E extends keyof RoomEvents>(event: E, listener: RoomEvents[E]): () => void;
+}
+export type RoomResult = {
+    room: Room;
+    error?: undefined;
+} | {
+    room?: undefined;
+    error: MultiplayerError;
+};
+export interface Multiplayer {
+    /** The room code when the player arrived through an invite link, else null. Join it with join(invite). */
+    readonly invite: string | null;
+    /** Make a new room and join it. maxPlayers: 2 to 8 (default 8). */
+    create(options?: {
+        maxPlayers?: number;
+    }): Promise<RoomResult>;
+    /** Join a room by its code (letters are not case sensitive). */
+    join(code: string): Promise<RoomResult>;
+}
+type Send = (m: GameMessage extends infer M ? M extends GameMessage ? Omit<M, "ik"> : never : never) => void;
+export declare function multiplayer(send: Send, inside: () => boolean, invite: () => string | null, shareInvite: () => Promise<{
+    shared: boolean;
+}>): {
+    api: Multiplayer;
+    receive: (m: PageMessage) => boolean;
+};

package/dist/protocol.d.ts

@@ -1,5 +1,10 @@
+import { type Player, type RoomError } from "./room";
 export declare const PROTOCOL = 1;
-export type Feature = "loading" | "gameplay" | "pause" | "mute" | "context" | "share";
+export type Feature = "loading" | "gameplay" | "pause" | "mute" | "context" | "share" | "multiplayer";
+export type { Player } from "./room";
+/** Why a room could not be made or joined. "not-available-here": the game is not inside Ikirmikir. */
+export type MultiplayerError = RoomError | "not-available-here";
+export type RoomStatus = "reconnecting" | "connected" | "closed";
 export interface Context {
     language: string;
     device: "mobile" | "desktop";
@@ -25,6 +30,24 @@ export type GameMessage = {
     ik: 1;
     type: "share";
     id: number;
+    room?: true;
+} | {
+    ik: 1;
+    type: "mp.create";
+    id: number;
+    maxPlayers: number;
+} | {
+    ik: 1;
+    type: "mp.join";
+    id: number;
+    code: string;
+} | {
+    ik: 1;
+    type: "mp.send";
+    data: unknown;
+} | {
+    ik: 1;
+    type: "mp.leave";
 };
 export type PageMessage = {
     ik: 1;
@@ -32,6 +55,7 @@ export type PageMessage = {
     features: Feature[];
     context: Context;
     muted: boolean;
+    invite: string | null;
 } | {
     ik: 1;
     type: "pause";
@@ -47,6 +71,38 @@ export type PageMessage = {
     type: "shared";
     id: number;
     shared: boolean;
+} | {
+    ik: 1;
+    type: "mp.room";
+    id: number;
+    code: string;
+    link: string;
+    you: Player;
+    players: Player[];
+    max: number;
+} | {
+    ik: 1;
+    type: "mp.error";
+    id: number;
+    error: RoomError;
+} | {
+    ik: 1;
+    type: "mp.player";
+    player: Player;
+} | {
+    ik: 1;
+    type: "mp.away" | "mp.back" | "mp.gone";
+    id: string;
+} | {
+    ik: 1;
+    type: "mp.msg";
+    from: string;
+    data: unknown;
+} | {
+    ik: 1;
+    type: "mp.status";
+    status: RoomStatus;
+    players: Player[];
 };
 /** For the Ikirmikir page: a valid message from a game, or null. */
 export declare function readGameMessage(d: unknown): GameMessage | null;

package/dist/protocol.js

@@ -1,12 +1,44 @@
-/*! @ikirmikir/game-sdk 1.0.0 | MIT | https://ikirmikir.com/developers/ */
+/*! @ikirmikir/game-sdk 1.1.0 | MIT | https://ikirmikir.com/developers/ */
+
+// src/room.ts
+var LIMITS = {
+  maxPlayers: 8,
+  maxMessageBytes: 4096,
+  // one game message, as JSON
+  messagesPerSecond: 20,
+  // per player
+  reconnectSeconds: 30,
+  // a dropped player keeps their seat this long
+  emptyMinutes: 10
+  // a room nobody is in closes after this long
+};
+var isRoomCode = (s) => typeof s === "string" && /^[A-HJ-NP-Z2-9]{5}$/.test(s);
+var ROOM_ERRORS = ["not-found", "full", "too-big", "slow-down", "unavailable", "bad-request"];
+function jsonSize(v) {
+  try {
+    const s = JSON.stringify(v);
+    return s === void 0 ? -1 : new TextEncoder().encode(s).length;
+  } catch {
+    return -1;
+  }
+}
 
 // src/protocol.ts
 var PROTOCOL = 1;
-var FEATURES = ["loading", "gameplay", "pause", "mute", "context", "share"];
+var FEATURES = ["loading", "gameplay", "pause", "mute", "context", "share", "multiplayer"];
+var STATUSES = ["reconnecting", "connected", "closed"];
 var obj = (d) => typeof d === "object" && d !== null && !Array.isArray(d);
 var str = (v, max) => typeof v === "string" && v.length > 0 && v.length <= max;
 var int = (v, min, max) => Number.isInteger(v) && v >= min && v <= max;
 var bool = (v) => typeof v === "boolean";
+var pid = (v) => typeof v === "string" && /^[a-z0-9]{1,16}$/.test(v);
+var player = (p) => obj(p) && pid(p.id) && str(p.name, 32) && bool(p.connected);
+var players = (v) => Array.isArray(v) && v.length <= LIMITS.maxPlayers && v.every(player);
+var cleanPlayer = (p) => ({ id: p.id, name: p.name, connected: p.connected });
+var sendable = (v) => {
+  const n = jsonSize(v);
+  return n >= 0 && n <= LIMITS.maxMessageBytes;
+};
 function readGameMessage(d) {
   if (!obj(d) || d.ik !== PROTOCOL) return null;
   switch (d.type) {
@@ -19,7 +51,15 @@ function readGameMessage(d) {
     case "gameplay":
       return bool(d.playing) ? { ik: 1, type: "gameplay", playing: d.playing } : null;
     case "share":
-      return int(d.id, 0, 1e9) ? { ik: 1, type: "share", id: d.id } : null;
+      return int(d.id, 0, 1e9) && (d.room === void 0 || bool(d.room)) ? { ik: 1, type: "share", id: d.id, ...d.room ? { room: true } : {} } : null;
+    case "mp.create":
+      return int(d.id, 0, 1e9) && int(d.maxPlayers, 2, LIMITS.maxPlayers) ? { ik: 1, type: "mp.create", id: d.id, maxPlayers: d.maxPlayers } : null;
+    case "mp.join":
+      return int(d.id, 0, 1e9) && isRoomCode(d.code) ? { ik: 1, type: "mp.join", id: d.id, code: d.code } : null;
+    case "mp.send":
+      return "data" in d && sendable(d.data) ? { ik: 1, type: "mp.send", data: d.data } : null;
+    case "mp.leave":
+      return { ik: 1, type: "mp.leave" };
     default:
       return null;
   }
@@ -32,7 +72,8 @@ function readPageMessage(d) {
       if (!Array.isArray(d.features) || !bool(d.muted) || !obj(c)) return null;
       if (!str(c.language, 35) || c.device !== "mobile" && c.device !== "desktop" || !bool(c.touch)) return null;
       const features = FEATURES.filter((f) => d.features.includes(f));
-      return { ik: 1, type: "welcome", features, context: { language: c.language, device: c.device, touch: c.touch }, muted: d.muted };
+      const invite = isRoomCode(d.invite) ? d.invite : null;
+      return { ik: 1, type: "welcome", features, context: { language: c.language, device: c.device, touch: c.touch }, muted: d.muted, invite };
     }
     case "pause":
       return { ik: 1, type: "pause" };
@@ -42,6 +83,20 @@ function readPageMessage(d) {
       return bool(d.muted) ? { ik: 1, type: "mute", muted: d.muted } : null;
     case "shared":
       return int(d.id, 0, 1e9) && bool(d.shared) ? { ik: 1, type: "shared", id: d.id, shared: d.shared } : null;
+    case "mp.room":
+      return int(d.id, 0, 1e9) && isRoomCode(d.code) && str(d.link, 300) && player(d.you) && players(d.players) && int(d.max, 2, LIMITS.maxPlayers) ? { ik: 1, type: "mp.room", id: d.id, code: d.code, link: d.link, you: cleanPlayer(d.you), players: d.players.map(cleanPlayer), max: d.max } : null;
+    case "mp.error":
+      return int(d.id, 0, 1e9) && ROOM_ERRORS.includes(d.error) ? { ik: 1, type: "mp.error", id: d.id, error: d.error } : null;
+    case "mp.player":
+      return player(d.player) ? { ik: 1, type: "mp.player", player: cleanPlayer(d.player) } : null;
+    case "mp.away":
+    case "mp.back":
+    case "mp.gone":
+      return pid(d.id) ? { ik: 1, type: d.type, id: d.id } : null;
+    case "mp.msg":
+      return pid(d.from) && "data" in d ? { ik: 1, type: "mp.msg", from: d.from, data: d.data } : null;
+    case "mp.status":
+      return STATUSES.includes(d.status) && players(d.players) ? { ik: 1, type: "mp.status", status: d.status, players: d.players.map(cleanPlayer) } : null;
     default:
       return null;
   }

package/dist/room.d.ts

@@ -0,0 +1,56 @@
+export declare const LIMITS: {
+    maxPlayers: number;
+    maxMessageBytes: number;
+    messagesPerSecond: number;
+    reconnectSeconds: number;
+    emptyMinutes: number;
+};
+/** Room codes: 5 characters, no I, O, 0 or 1, so they are easy to read out and type. */
+export declare const CODE_CHARS = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+export declare const isRoomCode: (s: unknown) => s is string;
+export type RoomError = "not-found" | "full" | "too-big" | "slow-down" | "unavailable" | "bad-request";
+export declare const ROOM_ERRORS: RoomError[];
+export interface Player {
+    id: string;
+    name: string;
+    connected: boolean;
+}
+export type ServerMessage = {
+    t: "welcome";
+    code: string;
+    you: Player;
+    token: string;
+    players: Player[];
+    max: number;
+} | {
+    t: "join";
+    player: Player;
+} | {
+    t: "away";
+    id: string;
+} | {
+    t: "back";
+    id: string;
+} | {
+    t: "leave";
+    id: string;
+} | {
+    t: "msg";
+    from: string;
+    data: unknown;
+} | {
+    t: "error";
+    error: RoomError;
+};
+export type ClientMessage = {
+    t: "send";
+    data: unknown;
+} | {
+    t: "leave";
+};
+/** Size of a value as JSON, or -1 when it can't be sent (functions, cycles, undefined). */
+export declare function jsonSize(v: unknown): number;
+/** For the room server: a valid message from a page, or null. */
+export declare function readClientMessage(text: string): ClientMessage | null;
+/** For the page: a valid message from the room server, or null. */
+export declare function readServerMessage(text: string): ServerMessage | null;

package/dist/room.js

@@ -0,0 +1,75 @@
+/*! @ikirmikir/game-sdk 1.1.0 | MIT | https://ikirmikir.com/developers/ */
+
+// src/room.ts
+var LIMITS = {
+  maxPlayers: 8,
+  maxMessageBytes: 4096,
+  // one game message, as JSON
+  messagesPerSecond: 20,
+  // per player
+  reconnectSeconds: 30,
+  // a dropped player keeps their seat this long
+  emptyMinutes: 10
+  // a room nobody is in closes after this long
+};
+var CODE_CHARS = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+var isRoomCode = (s) => typeof s === "string" && /^[A-HJ-NP-Z2-9]{5}$/.test(s);
+var ROOM_ERRORS = ["not-found", "full", "too-big", "slow-down", "unavailable", "bad-request"];
+var obj = (d) => typeof d === "object" && d !== null && !Array.isArray(d);
+var id = (v) => typeof v === "string" && /^[a-z0-9]{1,16}$/.test(v);
+var player = (p) => obj(p) && id(p.id) && typeof p.name === "string" && p.name.length <= 32 && typeof p.connected === "boolean";
+var clean = (p) => ({ id: p.id, name: p.name, connected: p.connected });
+function jsonSize(v) {
+  try {
+    const s = JSON.stringify(v);
+    return s === void 0 ? -1 : new TextEncoder().encode(s).length;
+  } catch {
+    return -1;
+  }
+}
+function readClientMessage(text) {
+  let d;
+  try {
+    d = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!obj(d)) return null;
+  if (d.t === "leave") return { t: "leave" };
+  if (d.t === "send" && "data" in d) return { t: "send", data: d.data };
+  return null;
+}
+function readServerMessage(text) {
+  let d;
+  try {
+    d = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!obj(d)) return null;
+  switch (d.t) {
+    case "welcome":
+      return isRoomCode(d.code) && player(d.you) && typeof d.token === "string" && Array.isArray(d.players) && d.players.every(player) && Number.isInteger(d.max) ? { t: "welcome", code: d.code, you: clean(d.you), token: d.token, players: d.players.map(clean), max: d.max } : null;
+    case "join":
+      return player(d.player) ? { t: "join", player: clean(d.player) } : null;
+    case "away":
+    case "back":
+    case "leave":
+      return id(d.id) ? { t: d.t, id: d.id } : null;
+    case "msg":
+      return id(d.from) && "data" in d ? { t: "msg", from: d.from, data: d.data } : null;
+    case "error":
+      return ROOM_ERRORS.includes(d.error) ? { t: "error", error: d.error } : null;
+    default:
+      return null;
+  }
+}
+export {
+  CODE_CHARS,
+  LIMITS,
+  ROOM_ERRORS,
+  isRoomCode,
+  jsonSize,
+  readClientMessage,
+  readServerMessage
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikirmikir/game-sdk",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Optional SDK for games on Ikirmikir: loading, gameplay, pause, sound, player context and share. Works standalone too.",
   "license": "MIT",
   "homepage": "https://ikirmikir.com/developers/",
@@ -20,6 +20,10 @@
     "./protocol": {
       "types": "./dist/protocol.d.ts",
       "default": "./dist/protocol.js"
+    },
+    "./room": {
+      "types": "./dist/room.d.ts",
+      "default": "./dist/room.js"
     }
   },
   "publishConfig": {