dewdrop-sdk 0.4.0 → 0.4.1

package/README.md

@@ -27,8 +27,9 @@ or later.
 On Dewdrop, `localStorage` and IndexedDB aren't local: nothing your game
 writes to them is stored in the player's browser or on their device, and they
 start empty each time a player opens your game. `saves.save()` keeps what they
-hold in Dewdrop's storage for that player, and `saves.load()` puts it back;
-each upload of your game starts with none.
+hold in Dewdrop's storage for that player, and `saves.load()` puts it back,
+in later uploads of your game too. A game with a `backend.js` keeps no saves:
+its state is its rooms', and both calls refuse with `NotSupportedError`.
 `npm run dev` does the same in your browser: every page load starts with
 `localStorage` and IndexedDB empty, and saves are kept in the browser, in a
 database named `dewdrop-saves` your game doesn't see, for the game
@@ -36,6 +37,27 @@ database named `dewdrop-saves` your game doesn't see, for the game
 of one dev server share the browser's storage, so loading one empties the
 others'.
 
+## Rooms locally
+
+`npm run dev` runs your `backend.js` for each room the tabs join: `?room=`
+names the room, `?player=` the player, and `?players=` how many players a
+room the tab opens seats, 100 unless it says 1 to 100, as Dewdrop's rooms
+do; `?players=1` is singleplayer. A player is counted once however many tabs
+they play from, and a tab past a full room is refused, with the reason in
+the console. In the backend, `clients.capacity` is the room's size.
+
+## Sessions that end
+
+On Dewdrop a session can end ahead of time: for maintenance, or a newer
+version of your game published. Its player sees a countdown and reconnects
+on their own, and your game hears of it first, up to fifteen minutes
+before: `session.ending` from `dewdrop-sdk` is `{at, reason}`, `at` in
+milliseconds as `Date.now()` counts and `reason` `'restart'` or `'update'`,
+and an `ending` event fires each time it changes, its withdrawal to `null`
+included. Call `saves.save()` then to keep what the player has done. `npm
+run dev` ends no session ahead of time, so `session.ending` stays `null`
+there.
+
 ## Docs
 
 How to build your game, from the look to model calls, multiplayer, saves and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dewdrop-sdk",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Build a three.js game for Dewdrop: the Vite plugin, model calls, multiplayer and saves.",
   "license": "MIT",
   "type": "module",

package/src/backend-host.js

@@ -11,7 +11,7 @@ import { pathToFileURL } from 'node:url';
 import { attachClients } from './clients.js';
 
 process.env.DEW_DEV_ORIGIN = workerData.origin;
-const start = attachClients(parentPort);
+const start = attachClients(parentPort, { capacity: workerData.capacity });
 await import(pathToFileURL(workerData.entry).href);
 process.on('uncaughtException', (error) => console.error(`uncaught ${error?.stack ?? error}`));
 start();

package/src/backend.js

@@ -7,7 +7,7 @@
 // past its cap. The page's URL says which room the tab joins and under
 // what name; on Dewdrop the game's page says which room, and the name is
 // the player's username.
-import { MAX_NET_CLIENT_FRAME_BYTES, createInbox, createOutbox, defineHandlers, label, side, unpack } from './net.js';
+import { MAX_NET_CLIENTS, MAX_NET_CLIENT_FRAME_BYTES, createInbox, createOutbox, defineHandlers, label, side, unpack } from './net.js';
 import { NO_CHANNEL } from './route.js';
 
 let channel = null;
@@ -58,20 +58,35 @@ function name(text) {
   return label(text.replace(/\p{Cc}/gu, '').trim());
 }
 
-// Where a page's URL joins its tab: the room `?room=` names and the name
-// `?player=` names, each held to Dewdrop's rule — the empty room without
+// The players a room seats as `?players=` names them: a whole number from
+// 1 to MAX_NET_CLIENTS, or the most without one or with any other.
+function players(text) {
+  return /^[0-9]{1,3}$/.test(text) && Number(text) >= 1 && Number(text) <= MAX_NET_CLIENTS ? Number(text) : MAX_NET_CLIENTS;
+}
+
+// Where a page's URL joins its tab: the room `?room=` names, the name
+// `?player=` names, and the players `?players=` says the room seats should
+// the tab make it, each held to Dewdrop's rule — the empty room without
 // one, or with one that names no room; unnamed without a name, or with one
 // that is nothing but space and control characters.
 export function joining(search) {
   const params = new URLSearchParams(search);
-  return { room: room(params.get('room') ?? ''), player: name(params.get('player') ?? '') };
+  return { room: room(params.get('room') ?? ''), player: name(params.get('player') ?? ''), players: players(params.get('players') ?? '') };
+}
+
+// Whether the page's game has a backend, as the plugin said; false until
+// it has.
+export function gameHasBackend() {
+  return hasBackend;
 }
 
 // Joins the backend of `room` under `player`'s name over `hot`, the page's
-// hot context, once the plugin has said whether the game has one:
-// `present` is that, `schedule` runs a function at the next animation
-// frame. Without a plugin there is no channel, and `send` says so.
-export function attachBackend(hot, { channel: routed, hasBackend: present, frame: schedule, room = '', player = '' }) {
+// hot context, once the plugin has said whether the game has one, a room
+// it makes seating `players`: `present` is that, `schedule` runs a
+// function at the next animation frame. Without a plugin there is no
+// channel, and `send` says so. A room that seats no more says so in the
+// console, as Dewdrop refuses the connect, and the tab's sends reach no one.
+export function attachBackend(hot, { channel: routed, hasBackend: present, frame: schedule, room = '', player = '', players = MAX_NET_CLIENTS }) {
   if (!routed) return;
   channel = hot;
   hasBackend = present;
@@ -83,5 +98,6 @@ export function attachBackend(hot, { channel: routed, hasBackend: present, frame
     draining = true;
     frame(deliver);
   });
-  hot.send('dew:join', { room, player });
+  hot.on('dew:full', ({ capacity }) => console.error(`[dewdrop] this room is full: it seats ${capacity === 1 ? '1 player' : `${capacity} players`}`));
+  hot.send('dew:join', { room, player, players });
 }

package/src/clients.js

@@ -1,15 +1,16 @@
 // `clients` on a developer's machine: the backend's side of the messages a
-// game exchanges with its clients, run by the plugin in a thread of the
-// dev server with a port to the plugin, which carries each message over
-// the socket to the tab it names. The thread ticks sixty times a second:
+// game exchanges with its clients, and the most players its room seats,
+// run by the plugin in a thread of the dev server with a port to the
+// plugin, which carries each message over the socket to the tab it names. The thread ticks sixty times a second:
 // each tick delivers what the clients sent as `join`, `leave`, `message`,
 // and `gap` events — a join naming the player's label — runs the
 // animation-frame callbacks, and sends the frame's messages.
-import { MAX_NET_BACKEND_FRAME_BYTES, NET_TICK_MS, ClientEvent, createInbox, createOutbox, defineHandlers, side, unpack } from './net.js';
+import { MAX_NET_BACKEND_FRAME_BYTES, MAX_NET_CLIENTS, NET_TICK_MS, ClientEvent, createInbox, createOutbox, defineHandlers, side, unpack } from './net.js';
 
 const outbox = createOutbox(MAX_NET_BACKEND_FRAME_BYTES);
 const inbox = createInbox();
 let port = null;
+let seats = 0;
 
 // A client number as the backend was told it: a whole number from one.
 function number(op, value) {
@@ -28,6 +29,12 @@ class Clients extends EventTarget {
     if (port === null) throw new DOMException('clients is unavailable in a client', 'NotSupportedError');
     outbox.push('clients.broadcast', 0, data);
   }
+  // The most players the room seats, as it was made: 1 for a room of one,
+  // a player counted once however many clients they play from.
+  get capacity() {
+    if (port === null) throw new DOMException('clients is unavailable in a client', 'NotSupportedError');
+    return seats;
+  }
 }
 defineHandlers(Clients.prototype, ['join', 'leave', 'message', 'gap']);
 
@@ -76,9 +83,11 @@ function frame() {
 // held until the returned function starts the ticks, which the host calls
 // once the backend has evaluated, so the first tick delivers what arrived
 // meanwhile, the first join included, to the handlers the module
-// registered. `tick` runs the frame once per tick from then on.
-export function attachClients(channel, { tick = (fn) => setInterval(fn, NET_TICK_MS) } = {}) {
+// registered. `tick` runs the frame once per tick from then on, and
+// `capacity` is the most players the room seats.
+export function attachClients(channel, { tick = (fn) => setInterval(fn, NET_TICK_MS), capacity = MAX_NET_CLIENTS } = {}) {
   port = channel;
+  seats = capacity;
   side.backend = true;
   if (typeof globalThis.requestAnimationFrame !== 'function') {
     globalThis.requestAnimationFrame = requestAnimationFrame;

package/src/index.js

@@ -4,10 +4,12 @@
 // over its route, `backend` over its socket to the backend the plugin
 // runs, `clients`, in that backend, over its port back, and `saves` into
 // the browser's own storage, which the plugin's script empties as each
-// page loads.
+// page loads; `session` says when a session ends ahead of time, which here
+// none does.
 export { llm } from './llm.js';
 export { backend } from './backend.js';
 export { clients } from './clients.js';
+export { session } from './session.js';
 import { attachBackend, joining } from './backend.js';
 import { load, save } from './saves.js';
 
@@ -30,5 +32,6 @@ if (typeof document !== 'undefined' && import.meta.hot) {
     frame: (fn) => requestAnimationFrame(fn),
     room: joined.room,
     player: joined.player,
+    players: joined.players,
   });
 }

package/src/net.js

@@ -15,6 +15,9 @@ export const NET_RECORD_HEADER_BYTES = 16;
 // The most bytes a player's label takes: the name the player joined
 // under, which the backend hears on the join.
 export const MAX_NET_PLAYER_BYTES = 64;
+// The most players a room seats, and the most clients it holds: a room's
+// size is 1 to this.
+export const MAX_NET_CLIENTS = 100;
 // How often the local backend ticks: sixty times a second.
 export const NET_TICK_MS = 1000 / 60;
 

package/src/saves.js

@@ -6,7 +6,7 @@
 // names and the player the page's URL names, and `load` puts it back.
 // Calls run in the order they are made, and the checks and their messages
 // are Dewdrop's, so a call that fails here fails there the same way.
-import { joining } from './backend.js';
+import { gameHasBackend, joining } from './backend.js';
 import { SAVES_STATE } from './fresh.js';
 import { side } from './net.js';
 import { NO_SAVES } from './route.js';
@@ -24,10 +24,11 @@ let last = Promise.resolve();
 let loads = 0;
 
 // Runs `run` once every call made before has settled and the page's
-// storage has started empty; refused at once in a backend, and in a page
-// without the plugin's script.
+// storage has started empty; refused at once in a game with a backend —
+// its backend and its tabs alike, as on Dewdrop, where such a game keeps
+// no saves — and in a page without the plugin's script.
 function inOrder(op, run) {
-  if (side.backend) return Promise.reject(new DOMException('saves is unavailable in a backend', 'NotSupportedError'));
+  if (side.backend || gameHasBackend()) return Promise.reject(new DOMException('saves is unavailable in a game with a backend', 'NotSupportedError'));
   const state = globalThis[Symbol.for(SAVES_STATE)];
   if (state === undefined) return Promise.reject(new TypeError(`${op}: ${NO_SAVES}`));
   const call = last.then(() => state.ready).then(() => run(state));

package/src/serve.js

@@ -1,7 +1,10 @@
 // The dev server's backend host, its stand-in for Dewdrop. A thread runs
 // the project's backend.js for each room the tabs join, from the room's
 // first tab's join until five minutes after its last tab's leave, as on
-// Dewdrop, so a tab that comes back in that time rejoins it; the tabs are
+// Dewdrop, so a tab that comes back in that time rejoins it; a room seats
+// the players its first tab's page said, a player counted once however
+// many tabs they play from and an unnamed tab as one each, and refuses a
+// tab past them as Dewdrop refuses its connect; the tabs are
 // numbered from one per room, never twice while its thread runs; each
 // tab's frame of sends reaches its room's thread over the port
 // with the tab's number, and each of the thread's sends reaches the tab it
@@ -14,7 +17,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { Worker } from 'node:worker_threads';
-import { label } from './net.js';
+import { MAX_NET_CLIENTS, label } from './net.js';
 
 // How long a room's backend runs on after its last tab's leave, as on
 // Dewdrop.
@@ -47,12 +50,14 @@ export function createBackendHost({ entry, ws, watcher, origin = () => '', log =
   const rooms = new Map();
   const tabs = new Map();
 
-  // One room's backend: its thread from the room's first tab's join until
-  // EMPTY_ROOM_MS after its last tab's leave with none joining since, its
-  // tabs by number from one.
-  function createRoom(key) {
+  // One room's backend, seating `capacity` players: its thread from the
+  // room's first tab's join until EMPTY_ROOM_MS after its last tab's leave
+  // with none joining since, its tabs by number from one with their
+  // players' names.
+  function createRoom(key, capacity) {
     const name = key === '' ? 'the backend' : `the backend of room ${JSON.stringify(key)}`;
     const members = new Map();
+    const names = new Map();
     let worker = null;
     let next = 1;
     let broken = false;
@@ -68,7 +73,7 @@ export function createBackendHost({ entry, ws, watcher, origin = () => '', log =
 
     function start() {
       files = backendFiles(entry);
-      worker = new Worker(new URL('./backend-host.js', import.meta.url), { workerData: { entry, origin: origin() } });
+      worker = new Worker(new URL('./backend-host.js', import.meta.url), { workerData: { entry, origin: origin(), capacity } });
       const started = worker;
       started.on('message', (message) => {
         if (message.kind === 'send' && worker === started) deliver(message.sends);
@@ -89,6 +94,7 @@ export function createBackendHost({ entry, ws, watcher, origin = () => '', log =
       idle = null;
       for (const client of members.keys()) tabs.delete(client);
       members.clear();
+      names.clear();
       next = 1;
       if (ended !== null) ended.terminate();
     }
@@ -101,13 +107,26 @@ export function createBackendHost({ entry, ws, watcher, origin = () => '', log =
       broken = true;
     }
 
+    // The room's players, each once: its tabs' names, and each unnamed tab.
+    function seated() {
+      const players = [...names.values()];
+      return players.filter((player, at) => player === '' || players.indexOf(player) === at).length;
+    }
+
     const room = {
       join(client, player) {
         if (broken) return;
+        const returning = player !== '' && [...names.values()].includes(player);
+        if (members.size >= MAX_NET_CLIENTS || (!returning && seated() >= capacity)) {
+          log.error(`[dewdrop] a tab is refused ${name}: it seats ${capacity === 1 ? '1 player' : `${capacity} players`}`);
+          client.send('dew:full', { capacity });
+          return;
+        }
         clearTimeout(idle);
         idle = null;
         const number = next++;
         members.set(client, number);
+        names.set(client, player);
         tabs.set(client, room);
         if (worker === null) start();
         worker.postMessage([{ kind: 'join', client: number, player }]);
@@ -117,6 +136,7 @@ export function createBackendHost({ entry, ws, watcher, origin = () => '', log =
         const number = members.get(client);
         if (number === undefined) return;
         members.delete(client);
+        names.delete(client);
         tabs.delete(client);
         worker.postMessage([{ kind: 'leave', client: number }]);
         if (members.size === 0) {
@@ -151,14 +171,17 @@ export function createBackendHost({ entry, ws, watcher, origin = () => '', log =
   }
 
   const host = {
-    // A tab joins the room its page named under the name it gave; a page
-    // that named neither joins the empty room unnamed.
-    join(client, { room = '', player = '' } = {}) {
+    // A tab joins the room its page named under the name it gave, a room
+    // it makes seating the players its page said; a page that named
+    // neither joins the empty room unnamed, and one that named no size a
+    // room seating the most.
+    join(client, { room = '', player = '', players = MAX_NET_CLIENTS } = {}) {
       if (tabs.has(client)) return;
       const key = typeof room === 'string' ? room : '';
       let it = rooms.get(key);
       if (it === undefined) {
-        it = createRoom(key);
+        const capacity = Number.isInteger(players) && players >= 1 && players <= MAX_NET_CLIENTS ? players : MAX_NET_CLIENTS;
+        it = createRoom(key, capacity);
         rooms.set(key, it);
       }
       it.join(client, label(player));
@@ -171,7 +194,7 @@ export function createBackendHost({ entry, ws, watcher, origin = () => '', log =
     },
     close,
   };
-  ws.on('dew:join', (data, client) => host.join(client, { room: data?.room, player: data?.player }));
+  ws.on('dew:join', (data, client) => host.join(client, { room: data?.room, player: data?.player, players: data?.players }));
   ws.on('dew:send', (data, client) => host.receive(client, data.items ?? []));
   watcher.on('change', (file) => {
     if (files.has(resolve(file))) restart(`${file} changed`);

package/src/session.js

@@ -0,0 +1,17 @@
+// `session` on a developer's machine. On Dewdrop a session can end ahead of
+// time — for maintenance, or a newer version of its game published — and
+// hears of it first, up to fifteen minutes before: `session.ending` is
+// `{at, reason}`, `at` in milliseconds since the epoch as `Date.now()` counts
+// and `reason` `'restart'` or `'update'`, and an `ending` event fires each
+// time it changes, its withdrawal to null included, so a game can save and
+// say so. `npm run dev` ends no session ahead of time, so here `ending`
+// stays null and the event never fires; a game tries its handler by calling
+// it.
+import { defineHandlers } from './net.js';
+
+class Session extends EventTarget {
+  get ending() { return null; }
+}
+defineHandlers(Session.prototype, ['ending']);
+
+export const session = new Session();