@moonbase-machines/player 0.10.0 → 0.12.0

package/README.md

@@ -3,18 +3,28 @@
 The player for Mark Wharton's titles of 1985 to 1995, one way in for every title and every way to play it (`play.js`):
 
 - **Original** (`way: 'original'`, `engines/original.js`): the game's own disk, untouched, on Moonbase's Apple IIe or
-  Commodore 64 (`@moonbase-machines/apple2e`, `c64`), on Moonbase's own ROMs, which need nothing of Apple's or
-  Commodore's.
+  Commodore 64 (`@moonbase-machines/apple2e`, `c64`). It's the Original on the makers' ROMs, where the page gives
+  them (`roms`), and the Replica on Moonbase's own ROMs, which need nothing of Apple's or Commodore's.
 - **Remake** (`way: 'remake'`): the game's scenes, lifted from its code and compiled to JavaScript, on the remake's
   engine (`engines/scenes.js`, a title of `card` or `vector` scenes), or the title's own engine, a module in its folder.
 
+[The four layers](../../docs/layers.md) explains how the Original, the Replica and the Remake differ, and what runs
+each one.
+
 The player makes its part of the page and owns it, the same for every title: the section (classes `player`, the way,
 the title's slug), the stage sized a whole number of the device's pixels to each of the screen's dots, the options
 line and the status, the keys (one listener, each machine's codes, `keys.js`), the sound, a Commodore 64's printer,
-the saves (`saves.js`), and what the page asks of it (`watch`, `claim`, `pace`, a route). An engine plays the game on
-the stage and returns its handle (`play.js` says what it may have). What a player saves goes on **the player's disk**
-(`disk/`): a title's own disk of files in this browser (IndexedDB), with its own dialogs (`disk/dialogs.js`, in a modal
-window, `modal.js`); the player opens it, on the backend the page gives. A game saved in one way loads in the other.
+the saves (`saves.js`), the settings the player and its engine act on, each declared where it acts and shown only
+there (`settings.js`), and what the page asks of it (`watch`, `claim`, `pace`, keys and a route). An engine plays
+the game on the stage and returns its handle (`play.js` says what it may have). The page tells the player everything
+and the player reads no address and keeps nothing itself: the page gives the title's disk, a virtual disk of files
+(`disk/disk.js` `openDisk`), and the person's settings, a typed store (`settings.js`: a setting is a declared name,
+type, default and owner; only a declared setting can be read or kept, its value checked). Both come from a
+**provider** (`provider.js`), which chooses once a visit where files and settings live, the backend (this browser's,
+IndexedDB; an account's, a site's own); a site makes one a page from a module of its own, giving its policy of
+settings (hidden, fixed, or a value for the visit) and the player never chooses. Nothing in the package knows of an
+address: a page that lets its address set anything reads it itself, each input by its type. The disk has its own
+dialogs (`disk/dialogs.js`, in a modal window, `modal.js`). A game saved in one way loads in the other.
 
 No title is named in it. A title is a folder of its own, kept with the title, which the page gives the player:
 
@@ -23,7 +33,8 @@ No title is named in it. A title is a folder of its own, kept with the title, wh
   scenes call, by address, and what its engine needs beside them: `remake/cards.js` and `remake/vector.js` say what
   each engine reads), the modules it brings (`modules`, its problems; `view`, its view's own drawing), its font's own
   glyphs (`font`), its stylesheet (`style`);
-- its scenes (`<name>.scene`) and `compiled/` (`moonbase-compile`).
+- its scenes (`<name>.scene`) and `compiled/` (`moonbase-compile`); `remake/README.md` says what a scene is, how it
+  is compiled and run, and the two engines.
 
 Beside it the game's data, `<name>.json` (its disks' files, its kind, and where it saves: `saves`).
 
@@ -33,8 +44,12 @@ Beside it the game's data, `<name>.json` (its disks' files, its kind, and where
 <section id="player"></section>
 <script type="module">
   import { play } from '@moonbase-machines/player/play.js';
+  import { titleDisk } from '@moonbase-machines/player/disk/disk.js';
+  import { provider } from '@moonbase-machines/player/provider.js';
+  const { disk, settings } = await provider();   // (this browser's)
   await play({ way: 'remake', slug: 'game', title: new URL('title/', location).href, data: new URL('game.json', location).href,
-    root: document.getElementById('player'), words: { printer: { line: '', print: 'Print', tear: 'Tear off' } } });
+    root: document.getElementById('player'), disk: await disk(titleDisk('game')), settings,
+    words: { printer: { line: '', print: 'Print', tear: 'Tear off' } } });
 </script>
 ```
 

package/bin/moonbase-play.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 // A title played on this machine: its page at http://127.0.0.1:8002/, its Remake where it has one, and an Original for
-// each game's data beside it (/?way=original, or with more than one /?game=<name>), on the browser's own player's
-// disk; each file sent with `Cache-Control: no-cache` so that a refresh asks for every module again. The folder holds
+// each game's data beside it (/?way=original, or with more than one /?game=<name>); its disk and settings from the
+// package's own provider (provider.js), this browser's, as the page has no site to give them; the page's own inputs
+// its own, each checked: ?way and ?game one of the ways it has, ?keys=space,return keys to press at the start; each
+// file sent with `Cache-Control: no-cache` so that a refresh asks for every module again. The folder holds
 // the title's folder, title/ (title.js, its scenes, compiled/), if it is remade, and its games' data, <name>.json
 // each, or for a title of its own engine data/; the @moonbase-machines packages are served from node_modules at
 // /packages/, where the page's import map finds them. A folder with an index.html of its own is served as it is.
@@ -30,9 +32,10 @@ async function page() {
   const games = await Promise.all(readdirSync(root).filter(f => f.endsWith('.json') && f !== 'package.json').sort((a, b) => (b === title?.slug + '.json') - (a === title?.slug + '.json') || a.slice(0, -5).localeCompare(b.slice(0, -5)))
     .map(async f => ({ name: f.slice(0, -5), data: f, game: JSON.parse(await readFile(join(root, f), 'utf8')) })));
   const slug = title?.slug ?? games[0]?.name, name = title?.name ?? games[0]?.game.title ?? slug;
-  // (the ways: the remake, its data the title's own or, for a title of its own engine, data/; an original for each game)
-  const ways = [...(title ? [{ label: 'Remake', search: '', way: 'remake', data: existsSync(join(root, slug + '.json')) ? slug + '.json' : 'data/' }] : []),
-    ...games.map((g, i) => ({ label: games.length > 1 ? g.game.title : 'Original', search: !title && !i ? '' : games.length > 1 ? `?game=${g.name}` : '?way=original', way: 'original', data: g.data }))];
+  // (the ways: the remake, its data the title's own or, for a title of its own engine, data/; an original for each
+  // game, by the game's name where there are several; each with its address)
+  const ways = [...(title ? [{ label: 'Remake', search: '', way: 'remake', game: null, data: existsSync(join(root, slug + '.json')) ? slug + '.json' : 'data/' }] : []),
+    ...games.map((g, i) => ({ label: games.length > 1 ? g.game.title : 'Original', search: !title && !i ? '' : games.length > 1 ? `?game=${g.name}` : '?way=original', way: 'original', game: games.length > 1 ? g.name : null, data: g.data }))];
   const map = { imports: Object.fromEntries(PACKAGES.map(p => [`@moonbase-machines/${p}/`, `/packages/${p}/`])) };
   return `<!doctype html>
 <html lang="en">
@@ -52,11 +55,19 @@ ${ways.length > 1 ? `<nav>${ways.map(w => `<a href="/${w.search}">${esc(w.label)
 </main>
 <script type="module">
 const ways = ${JSON.stringify(ways)};
-const way = ways.find(w => w.search === location.search) ?? ways[0];
+const [{ play }, { titleDisk }, { provider }] = await Promise.all(['play.js', 'disk/disk.js', 'provider.js'].map(m => import('@moonbase-machines/player/' + m)));
+// (the page's own inputs, each checked: the way or a game by its name, one of those it has, else the first; the keys
+// to press, names of letters, digits and dashes; anything else refused and said)
+const q = new URLSearchParams(location.search), refused = (n, what) => { console.warn('?' + n + '=' + q.get(n) + ' refused: not ' + what); return null; };
+const one = (n, of) => !q.has(n) ? null : of.includes(q.get(n)) ? q.get(n) : refused(n, 'one of ' + of.join(', '));
+const askedGame = one('game', ways.map(w => w.game).filter(Boolean)), askedWay = one('way', [...new Set(ways.map(w => w.way))]);
+const way = ways.find(w => askedGame ? w.game === askedGame : askedWay ? w.way === askedWay : true) ?? ways[0];
 for (const a of document.querySelectorAll('nav a')) if (a.search === way.search) a.setAttribute('aria-current', 'page');
-const { play } = await import('@moonbase-machines/player/play.js');
+const keys = !q.has('keys') ? undefined : /^[\\w-]+(,[\\w-]+)*$/.test(q.get('keys')) ? q.get('keys').split(',') : refused('keys', 'names separated by commas') ?? undefined;
 const at = path => new URL(path, location.origin + '/').href;
+const { disk, settings } = await provider();
 await play({ way: way.way, slug: ${JSON.stringify(slug)}, title: ${title ? "at('title/')" : 'null'}, data: at(way.data), root: document.getElementById('player'),
+  disk: await disk(titleDisk(${JSON.stringify(slug)})), settings, keys,
   words: { printer: { line: 'What the printer has printed.', print: 'Print', tear: 'Tear off' } } });
 </script>
 </body>

package/disk/disk.js

@@ -8,8 +8,9 @@
 // @moonbase-machines/c64/drive.js's find), so a read is never waited for. A write changes the copy at once and is stored behind
 // it, in order.
 //
-//   const disk = await openDisk(name, { backend })   backend: local() (local.js, the default)
-//                                                     or memory() (memory.js)
+//   const disk = await openDisk(name, { backend })   backend: where its files are kept, the provider's choice
+//                                                     (provider.js), never the disk's: local() (local.js, this
+//                                                     browser's) or memory() (memory.js)
 //   disk.list()                 [{ name, size, modified, meta }], newest first
 //   disk.read(name)             its bytes, or null
 //   disk.write(name, bytes, meta)   a promise, kept when stored
@@ -24,12 +25,9 @@
 //
 // The backend is where a disk's files are kept: { kept, where, load(disk), put(disk, file), delete(disk, name) },
 // a file { name, bytes, meta, modified }. This browser's is local(); an account's will be the API's.
-import { local } from './local.js';
-import { memory } from './memory.js';
 
-export async function openDisk(name, { backend } = {}) {
-  // (a browser that keeps nothing, as a private window may: the disk in memory, and said so)
-  if (!backend) { try { backend = await local(); } catch { backend = memory({ kept: false }); } }
+export async function openDisk(name, { backend }) {
+  if (!backend) throw new Error('openDisk: a backend is the provider\'s to give (provider.js)');
   const files = new Map((await backend.load(name)).map(f => [f.name, f]));
   let queue = Promise.resolve();
   // (each job stored in turn; one that fails is said (`failed`) and the next goes on, its own promise rejected for a