dewdrop-sdk 0.5.0 → 0.5.2

package/README.md

@@ -1,112 +1,10 @@
 # dewdrop-sdk
 
-The package that builds a three.js game for Dewdrop and runs it locally: the
-Vite plugin, model calls, multiplayer and saves.
+Build a three.js game for Dewdrop and run it locally: the Vite plugin, model
+calls, multiplayer, saves and voice.
 
-## Set up
-
-In a Vite 6 or later project:
-
-```sh
-npm install -D dewdrop-sdk
-npm install --save-exact three@0.185.1
-```
-
-```js
-// vite.config.js
-import dew from 'dewdrop-sdk/vite';
-export default { plugins: [dew()] };
-```
-
-`npx dewctl init` sets up a new game this way, with the Dewdrop CLI beside it.
-To update a project, run `npm install -D dewdrop-sdk@latest`; saves need 0.4.0
-or later, voice 0.5.0.
-
-## Saves locally
-
-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,
-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
-`dewdrop.json` names and the player `?player=` names, across your edits. Tabs
-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.
-
-## Voice
-
-```js
-import { backend, voice } from 'dewdrop-sdk';
-
-// This player's microphone, a chunk at a time, sent to the backend each frame.
-const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
-const capture = voice.capture(stream);                 // capture.stop() to go quiet
-function frame() {
-  for (const chunk of capture.read()) backend.send(chunk);  // Int16Array, 800 samples at 48 kHz
-  requestAnimationFrame(frame);
-}
-requestAnimationFrame(frame);
-
-// Another player's voice, as the backend sends it on: from their figure,
-// loud up close, fading with distance.
-const source = voice.source(listener.context);
-const sound = new PositionalAudio(listener);           // on their avatar
-sound.setNodeSource(source.node);                      // or source.node.connect(anywhere)
-backend.onmessage = ({ data }) => source.write(new Int16Array(data, 4));  // behind the backend's own header
-```
-
-Dewdrop carries no voice between players itself: your `backend.js`
-decides who hears whom — those within earshot, a team, everyone — and
-sends each chunk on through its ordinary messages, so a game can mix,
-mute, record or transcribe as it sees fit. `voice.capture(stream)` takes
-the live microphone stream from `getUserMedia` and hands back the
-capture: `read()` returns the chunks that arrived since the last read,
-each an `Int16Array` of 800 samples, mono, at `voice.SAMPLE_RATE`
-(48 kHz), and `stop()` ends it; one capture at a time, a second throws
-an `InvalidStateError`. A read is at most eight chunks of 1,600 bytes,
-which a client's frame sends to its backend whole within its 16 KiB
-with room beside, so a game may send every chunk it reads; a backend's
-frame sends some 160 copies on within its 256 KiB, so a crowd all
-speaking at once is more than one frame carries and a backend sheds the
-rest — voice is late or nothing — or compresses first. `voice.source(context)`
-is plain Web Audio: `node` is a node of `context` for `connect` or a
-three.js `PositionalAudio`'s `setNodeSource`, `write(samples)` plays an
-`Int16Array` or `Float32Array` right after those written before it —
-the first two chunks ahead of the clock, so a chunk a little early or
-late plays without a gap — dropping what runs eight chunks ahead, and
-`close()` leaves the graph. `npm run dev` reads your browser's
-microphone through an audio worklet and hands your game the same chunks,
-so voice works between tabs locally as it does on Dewdrop.
-
-## Docs
-
-How to build your game, from the look to model calls, multiplayer, saves and
-what works on Dewdrop, is in the docs: https://alpha.dewdrop.world/docs
+How to set up a project and everything the SDK does is in the docs:
+https://alpha.dewdrop.world/docs
 
 ## License
 

package/package.json

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

package/src/index.js

@@ -5,8 +5,9 @@
 // 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; `session` says when a session ends ahead of time, which here
-// none does; and `voice` reads the microphone through the browser's own
-// audio worklet, the chunks Dewdrop's server would decode.
+// none does, and lets a game end its player's session, which here ends
+// nothing; and `voice` reads the microphone through the browser's own
+// audio worklet, into the chunks a game gets on Dewdrop.
 export { llm } from './llm.js';
 export { backend } from './backend.js';
 export { clients } from './clients.js';

package/src/session.js

@@ -1,16 +1,31 @@
 // `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';
+// time — for maintenance, a newer version of its game published, its player
+// idle for fifteen minutes, its player away for ten — the page hidden, or
+// another game of theirs showing — or its player choosing to play in
+// another tab — and hears of it first, up to fifteen minutes before, a
+// minute for an idle or an away player, and as it ends for a player playing
+// elsewhere: `session.ending` is `{at, reason}`, `at` in milliseconds since
+// the epoch as `Date.now()` counts and `reason` `'restart'`, `'update'`,
+// `'idle'`, `'away'`, `'elsewhere'` or `'exit'`, and an `ending` event fires
+// each time it changes, its withdrawal to null included, so a game can save
+// and say so. A game ends its player's session itself with
+// `session.exit()`, which on Dewdrop takes the player back to Dewdrop's
+// home page while the room's other players play on, the game hearing
+// `'exit'` as it goes; a backend has no player to send anywhere, so there it
+// throws NotSupportedError. `npm run dev` ends no session, so here `ending`
+// stays null and the event never fires, a game trying its handler by
+// calling it, and `exit()` ends nothing: the console says so, once.
+import { defineHandlers, side } from './net.js';
 
+let told = false;
 class Session extends EventTarget {
   get ending() { return null; }
+  exit() {
+    if (side.backend) throw new DOMException('session.exit is unavailable in a backend', 'NotSupportedError');
+    if (told) return;
+    told = true;
+    console.info('[dewdrop] session.exit(): on Dewdrop this ends the session and takes the player back to Dewdrop’s home page; npm run dev keeps the game running');
+  }
 }
 defineHandlers(Session.prototype, ['ending']);
 

package/src/voice.js

@@ -1,29 +1,18 @@
-// `voice` on a developer's machine: the runtime's surface — the player's
-// microphone a chunk at a time, and a source that plays such chunks
-// through the game's own audio graph — where Dewdrop carries no voice
-// between players itself: a game sends what it captures to its backend
-// through its messages, and the backend sends it on to the players it
-// chooses. On Dewdrop the server decodes the microphone the browser
-// streams onto the game's voice stream; here the browser's own audio
-// worklet reads the microphone and hands the game the same chunks, so a
-// game captures in `npm run dev` as it captures on Dewdrop. `source` is
-// plain Web Audio, the same function as Dewdrop's, and plays here as
-// there.
+// `voice` on a developer's machine: the player's microphone a chunk at a
+// time, as a game gets it on Dewdrop, where Dewdrop carries no voice
+// between players and plays none itself: a game sends what it captures
+// to its backend through its messages, the backend sends it on to the
+// players it chooses, and their games play it through their own audio
+// graphs. Here the browser's own audio worklet reads the microphone and
+// hands the game the same chunks, so a game captures in `npm run dev` as
+// it captures on Dewdrop.
 
-// Hand-copied from the runtime, which tests/sync.test.mjs pins: the rate
-// of the samples a capture reads and a source plays, the samples in one
-// of a capture's chunks, 1/60 s, and the chunks that wait for a game that
-// reads late, the newest kept.
+// The chunks as Dewdrop hands them to a game: the rate of their samples,
+// the samples in one chunk, 1/60 s, and the chunks that wait for a game
+// that reads late, the newest kept.
 export const SAMPLE_RATE = 48000;
 export const VOICE_CHUNK_SAMPLES = 800;
 export const VOICE_CHUNKS_HELD = 8;
-// How far ahead of the context's clock a source begins what is written
-// to it — the first chunk, and the first after it ran dry — in seconds:
-// two chunks, which a later chunk may come late by and still follow the
-// last without a gap; and how far ahead writes may run before the newest
-// is dropped instead, so a voice falls no further behind.
-const SOURCE_LEAD = 2 * VOICE_CHUNK_SAMPLES / SAMPLE_RATE;
-const MAX_SOURCE_LEAD = 8 * VOICE_CHUNK_SAMPLES / SAMPLE_RATE;
 
 // The processor that reads the microphone in the browser's audio thread:
 // it takes the microphone's frames at the context's rate, steps through
@@ -141,52 +130,6 @@ function capture(stream) {
   return mine;
 }
 
-function isObjectLike(value) { return value !== null && (typeof value === 'object' || typeof value === 'function'); }
-
-// A source for `context`'s graph that plays the chunks written to it as
-// they come — Int16Array or Float32Array samples at SAMPLE_RATE, mono,
-// as `capture` reads them or as another player's reached this game —
-// each right after the last: `node` is the source, for `connect`
-// or a three.js PositionalAudio's `setNodeSource`; `write` plays a chunk
-// after those before it; `close` leaves the graph. Plain Web Audio — a
-// buffer source a write, begun SOURCE_LEAD ahead of the context's clock
-// and following the last, and nothing of Dewdrop's — so a game may play a
-// voice its own way instead. The runtime's web/voice.js carries this same
-// function, which tests/sync.test.mjs pins line for line.
-function source(context) {
-  if (!isObjectLike(context) || typeof context.createBufferSource !== 'function') {
-    throw new TypeError('voice.source: context is not an AudioContext');
-  }
-  const node = context.createGain();
-  // When the next chunk written plays, on the context's clock.
-  let at = 0;
-  return Object.freeze({
-    node,
-    write(samples) {
-      const tag = Object.prototype.toString.call(samples);
-      if (tag !== '[object Int16Array]' && tag !== '[object Float32Array]') {
-        throw new TypeError('voice.source: write takes an Int16Array or a Float32Array of samples');
-      }
-      if (samples.length === 0) return;
-      const now = context.currentTime;
-      // The first write, or one after the chunks before it played out:
-      // SOURCE_LEAD ahead of the clock. While they still play, right
-      // after them, however early or late this one came, which is what
-      // rides out the jitter; too far ahead of the clock: dropped.
-      if (at <= now) at = now + SOURCE_LEAD;
-      else if (at > now + MAX_SOURCE_LEAD) return;
-      const buffer = context.createBuffer(1, samples.length, SAMPLE_RATE);
-      const channel = buffer.getChannelData(0);
-      if (tag === '[object Float32Array]') channel.set(samples);
-      else for (let i = 0; i < samples.length; i++) channel[i] = samples[i] / 32768;
-      const player = context.createBufferSource();
-      player.buffer = buffer;
-      player.connect(node);
-      player.start(at);
-      at += buffer.duration;
-    },
-    close() { node.disconnect(); },
-  });
-}
-
-export const voice = Object.freeze({ capture, source, SAMPLE_RATE });
+// SAMPLE_RATE is the chunks' rate, for the buffers a game plays them
+// through.
+export const voice = Object.freeze({ capture, SAMPLE_RATE });