homegames-common 1.7.0 → 1.7.1

package/docs/homegames-context.md

@@ -478,6 +478,9 @@ class MyGame extends Game {
     // A player joined. info.name is their display name.
     handleNewPlayer({ playerId, info, settings, clientInfo }) {}
 
+    // A player changed their name in the player menu. Refresh their labels.
+    handlePlayerUpdate(playerId, { info, settings }) {}
+
     // A player left. Clean up their nodes/state.
     handlePlayerDisconnect(playerId) {}
 
@@ -553,6 +556,7 @@ constructor({ saveGame, saveData }) {
 
 **Method signatures are exact and important:**
 - `handleNewPlayer` receives a **single object** `{ playerId, info, settings, clientInfo, requestedGame }` — destructure it. `playerId` is a number. `info.name` is the player's name.
+- Players initially get a random two-word name. **More → Your name → Save name** changes it and remembers it in that browser. Local, RTC (including manual connections), and WebSocket sessions call `handlePlayerUpdate(playerId, { info, settings })` for a rename; `info.name` contains the new name and settings are preserved. Update any cached roster or label in this hook. Names are non-unique display text, 1–32 characters, never an identity or authorization key; use `playerId` for session state. Browser preferences stay outside game ZIPs/HTML, so recipients use their own names.
 - `handlePlayerDisconnect(playerId)` receives the **bare id**, not an object. (If a player id reconnects while already connected, the runtime fires `handlePlayerDisconnect` for the old connection and then `handleNewPlayer` again.)
 - `handleKeyDown(playerId, key)` / `handleKeyUp(playerId, key)` — two positional args.
 - A node's `onClick` receives `(playerId, x, y)` — see §9.

package/game-session.js

@@ -28,17 +28,7 @@ const { squishMap, DEFAULT_SQUISH_VERSION } = require('./game-loader');
 const { MAX_SAVE_DATA_BYTES, SAVE_PUSH_OPCODE, SAVE_REQUEST_OPCODE } = require('./save-games');
 const { normalizeCursor, encodeCursor } = require('./cursor');
 
-// Simple name generator for anonymous players
-const _NAME_WORDS = [
-    'chocolate', 'iguana', 'cardigan', 'enormous', 'gargantuan', 'orangutan',
-    'cookies', 'monstera', 'daisy', 'grapefruit', 'blueberry', 'mango',
-    'elephant', 'bamboo', 'sapphire', 'papaya', 'waffle', 'turquoise',
-    'aquatic', 'goblin', 'funky', 'hotdog', 'elegant', 'cascade', 'euphoria',
-];
-const _generateName = () => {
-    const pick = () => _NAME_WORDS[Math.floor(Math.random() * _NAME_WORDS.length)];
-    return pick() + ' ' + pick();
-};
+const { generateName: _generateName, initialName, normalizeName } = require('./player-identity');
 
 class GameSession {
     constructor(game, squishVersion, opts = {}) {
@@ -161,7 +151,8 @@ class GameSession {
         }
 
         this.players[playerId] = ws;
-        this.playerInfoMap[playerId] = playerOpts.info || {};
+        this.playerInfoMap[playerId] = { ...(playerOpts.info || {}) };
+        const preferredName = playerOpts.playerName === undefined ? null : initialName(playerOpts.playerName);
         this.clientInfoMap[playerId] = playerOpts.clientInfo || {};
         this.playerSettingsMap[playerId] = playerOpts.settings || { SOUND: true };
         if (playerOpts.isRemote) this.remotePlayerMap[playerId] = true;
@@ -183,8 +174,8 @@ class GameSession {
 
                 // Homenames may be unreachable (or have no record yet) — never
                 // hand the game a nameless player.
-                if (!this.playerInfoMap[playerId].name) {
-                    this.playerInfoMap[playerId].name = _generateName();
+                if (preferredName || !this.playerInfoMap[playerId].name) {
+                    this.playerInfoMap[playerId].name = preferredName || _generateName();
                 }
 
                 const playerPayload = {
@@ -244,8 +235,8 @@ class GameSession {
                     .catch(() => finishAdd());
             }
         } else {
-            if (!this.playerInfoMap[playerId].name) {
-                this.playerInfoMap[playerId].name = _generateName();
+            if (preferredName || !this.playerInfoMap[playerId].name) {
+                this.playerInfoMap[playerId].name = preferredName || _generateName();
             }
 
             const playerPayload = {
@@ -384,6 +375,14 @@ class GameSession {
         const pid = Number(playerId);
 
         try {
+            if (input.type === 'player-info') {
+                if (!this.players[playerId]) return;
+                let name; try { name = normalizeName(input.name); } catch (_) { return; }
+                if (this.playerInfoMap[playerId]?.name !== name) this.handlePlayerUpdate(pid, {
+                    info: { ...this.playerInfoMap[playerId], name }, settings: { ...this.playerSettingsMap[playerId] }
+                });
+                return;
+            }
             if (input.type === 'media' && this.players[playerId] && this.media) {
                 if (input.action === 'hello') {
                     this.media.join(pid, { live: false, recording: input.recording === 1 || input.recording === 2, audioRecording: input.recording === 2,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homegames-common",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "Homegames common tools",
   "main": "index.js",
   "scripts": {

package/player-identity.js

@@ -0,0 +1,31 @@
+'use strict';
+
+// Self-contained: the trusted wrapper also embeds this in downloaded HTML.
+function createPlayerIdentity() {
+    const normalizeName = value => {
+        if (typeof value !== 'string' || /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/.test(value)) throw new Error('Use a name without control characters.');
+        const name = value.normalize('NFC').trim().replace(/\s+/gu, ' ');
+        if (!name || name.length > 32) throw new Error('Choose a name between 1 and 32 characters.');
+        return name;
+    };
+    const words = ['chocolate', 'iguana', 'cardigan', 'enormous', 'gargantuan', 'orangutan',
+        'cookies', 'monstera', 'daisy', 'grapefruit', 'blueberry', 'mango', 'elephant', 'bamboo',
+        'sapphire', 'papaya', 'waffle', 'turquoise', 'aquatic', 'goblin', 'funky', 'hotdog', 'elegant', 'cascade', 'euphoria'];
+    const generateName = () => Array.from({length: 2}, () => words[Math.floor(Math.random() * words.length)]).join(' ');
+    const initialName = value => { try { return normalizeName(value); } catch (_) { return generateName(); } };
+    function profile(window) {
+        const key = 'homegames-player-name';
+        let name;
+        try { name = normalizeName(window.localStorage.getItem(key)); } catch (_) { name = generateName(); }
+        const set = value => {
+            name = normalizeName(value);
+            // Names still work when storage is disabled or the frame is opaque.
+            try { window.localStorage.setItem(key, name); } catch (_) {}
+            return name;
+        };
+        set(name);
+        return { get: () => name, set };
+    }
+    return { normalizeName, generateName, initialName, profile };
+}
+module.exports = { createPlayerIdentity, ...createPlayerIdentity() };

package/player-toolbar.js

@@ -31,6 +31,9 @@ function createPlayerToolbar(window, options = {}) {
 .hg-player-menu-actions{display:flex;flex-direction:column;gap:6px}.hg-player-menu button{width:100%;min-height:44px;padding:10px 12px;text-align:left}
 .hg-player-menu .hg-player-menu-status{font-size:12px;color:#b7bfb5;overflow-wrap:anywhere;margin:12px 0}
 .hg-player-menu .hg-player-menu-close{text-align:center;margin-top:10px}
+.hg-player-name{margin:0 0 16px;padding-bottom:16px;border-bottom:1px solid #4a5049}
+.hg-player-name label{display:block;margin-bottom:6px}.hg-player-name input{width:100%;min-height:44px;padding:10px;font:inherit;color:inherit;background:#141815;border:1px solid #4a5049;border-radius:8px}
+.hg-player-name button{margin-top:8px}.hg-player-name p{font-size:12px;color:#b7bfb5;margin:8px 0 0;overflow-wrap:anywhere}
 `;
     bar.append(style);
     const home = element(typeof options.home === 'string' ? 'a' : 'button', 'hg-player-icon', '⌂');
@@ -51,11 +54,26 @@ function createPlayerToolbar(window, options = {}) {
     const menu = element('dialog', 'hg-player-menu'); menu.setAttribute('aria-label', 'Game options');
     const menuTitle = element('h2', '', 'Game options'), list = element('div', 'hg-player-menu-actions');
     const menuStatus = element('p', 'hg-player-menu-status');
+    const nameForm = element('form', 'hg-player-name'); nameForm.hidden = true;
+    const nameLabel = element('label', '', 'Your name'), nameInput = element('input', '');
+    nameInput.type = 'text'; nameInput.maxLength = 32; nameInput.required = true; nameInput.autocomplete = 'nickname';
+    nameInput.setAttribute('aria-label', 'Your name'); nameLabel.append(nameInput);
+    const nameSave = element('button', '', 'Save name'); nameSave.type = 'submit';
+    const nameStatus = element('p', ''); nameStatus.setAttribute('role', 'status');
+    nameForm.append(nameLabel, nameSave, nameStatus);
+    let playerName = '', changeName;
+    nameForm.onsubmit = async event => {
+        event.preventDefault(); if (!changeName || nameSave.disabled) return;
+        nameSave.disabled = true;
+        try { playerName = await changeName(nameInput.value); nameInput.value = playerName; nameStatus.textContent = 'Name updated for this session.'; }
+        catch (error) { nameStatus.textContent = error.message || String(error); }
+        finally { nameSave.disabled = false; }
+    };
     const done = element('button', 'hg-player-menu-close', 'Done'); done.type = 'button'; done.onclick = () => menu.close();
-    menu.append(menuTitle, list, menuStatus, done); document.body.append(menu);
+    menu.append(menuTitle, nameForm, list, menuStatus, done); document.body.append(menu);
     let menuActive = false;
     const resume = () => { if (menuActive) { menuActive = false; options.onClose?.(); } };
-    more.onclick = () => { if (!menu.open) { menuActive = true; options.onOpen?.(); menu.showModal(); } };
+    more.onclick = () => { if (!menu.open) { nameInput.value = playerName; nameStatus.textContent = ''; menuActive = true; options.onOpen?.(); menu.showModal(); } };
     menu.addEventListener('close', resume);
     menu.addEventListener('click', event => { if (event.target === menu) { const r = menu.getBoundingClientRect(); if (event.clientX < r.left || event.clientX > r.right || event.clientY < r.top || event.clientY > r.bottom) menu.close(); } });
     let disposed = false;
@@ -63,6 +81,11 @@ function createPlayerToolbar(window, options = {}) {
         bar, menu, statusElement: status,
         setTitle(value) { title.textContent = title.title = value || 'Homegames'; },
         setStatus(value) { status.textContent = status.title = menuStatus.textContent = value || ''; },
+        setPlayerName(value, onChange) {
+            playerName = value; changeName = onChange; nameForm.hidden = !onChange;
+            if (!menu.open) nameInput.value = value;
+            if (onChange) more.hidden = false;
+        },
         setAction(key, value) {
             if (!value) { const old = actions.get(key); if (old) { old.hidden = true; if (old !== share && old !== exportsButton && old !== downloadButton) old.remove(); actions.delete(key); } return; }
             let button = actions.get(key);

package/portable-client.js

@@ -13,7 +13,7 @@ function attachClientHost(window, frame, recordAudio, exportStorage, createExpor
         });
     }
     const status = text => { if (options.onPlayerStatus) options.onPlayerStatus(text); else toolbar?.setStatus(text); };
-    function command(action) { if (port && !closed) port.postMessage({ type: 'player-control', action }); }
+    function command(action, value) { if (port && !closed) port.postMessage({ type: 'player-control', action, value }); }
     async function download(format) {
         try {
             status('Preparing game download…');
@@ -31,6 +31,10 @@ function attachClientHost(window, frame, recordAudio, exportStorage, createExpor
                 if (typeof message.title === 'string') toolbar?.setTitle(message.title.slice(0, 200));
                 if (typeof message.status === 'string') status(message.status.slice(0, 300));
                 if (message.ready) {
+                    toolbar?.setPlayerName(options.profile?.get() || '', message.playerNames && options.profile ? value => {
+                        if (closed) throw new Error('This player has closed. Reopen the game to change your name.');
+                        const name = options.profile.set(value); command('player-name', name); return name;
+                    } : null);
                     for (const [key, label] of [['share', 'Share'], ['copy-share', 'Share a copy'], ['manual-connect', 'Manual connection'], ['exports', 'View exports']]) {
                         toolbar?.setAction(key, key !== 'exports' && !message.sharing ? null : { label, run: () => command(key) });
                     }
@@ -71,7 +75,7 @@ function attachClientHost(window, frame, recordAudio, exportStorage, createExpor
             else if (!(message.bytes instanceof Uint8Array) || !message.bytes.length || message.bytes.length > (entry.format === 'html' ? 220 : 65) * 1024 * 1024) entry.reject(new Error('Invalid game download'));
             else entry.resolve(message.bytes);
         };
-        frame.contentWindow.postMessage({ type: 'homegames-client-port-v1' }, '*', [channel.port2]);
+        frame.contentWindow.postMessage({ type: 'homegames-client-port-v1', playerName: options.profile?.get() }, '*', [channel.port2]);
         if (!toolbar && createPlayerToolbar) {
             toolbar = createPlayerToolbar(window, { title: options.title, home: options.home, status: 'Starting game…',
                 onOpen: () => command('pause-input'), onClose: () => command('resume-input') });
@@ -85,18 +89,21 @@ function attachClientHost(window, frame, recordAudio, exportStorage, createExpor
         for (const entry of pending.values()) { clearTimeout(entry.timer); entry.reject(new Error('Player closed')); } pending.clear(); } };
 }
 function connectClientSource(window, download, exports = {}, controls = {}) {
-    let port, closed = false, sequence = 0, resolveConnect, state;
+    let port, closed = false, sequence = 0, resolveConnect, state, playerName;
     const recordings = new Map();
     const connected = new Promise(resolve => { resolveConnect = resolve; });
     const connectTimer = setTimeout(resolveConnect, 15000);
     const listener = event => {
         if (closed || event.source !== window.parent || event.data?.type !== 'homegames-client-port-v1' || !event.ports[0]) return;
-        window.removeEventListener('message', listener); port = event.ports[0]; clearTimeout(connectTimer); resolveConnect();
+        window.removeEventListener('message', listener); port = event.ports[0]; playerName = event.data.playerName; clearTimeout(connectTimer); resolveConnect();
         if (state) port.postMessage({ type: 'player-state', ...state });
         port.onmessage = async event => {
             const message = event.data;
             if (!closed && message?.type === 'player-control' && Object.hasOwn(controls, message.action)) {
-                try { await controls[message.action](); } catch (error) { port.postMessage({type:'player-state', status:error.message}); }
+                try {
+                    if (message.action === 'player-name') playerName = message.value;
+                    await controls[message.action](message.value);
+                } catch (error) { port.postMessage({type:'player-state', status:error.message}); }
                 return;
             }
             if (message?.type === 'audio-result' || message?.type === 'export-result') { const entry = recordings.get(message.id); if (!entry) return; recordings.delete(message.id); clearTimeout(entry.timer); message.error ? entry.reject(new Error(message.error)) : entry.resolve(message.value); return; }
@@ -127,6 +134,7 @@ function connectClientSource(window, download, exports = {}, controls = {}) {
         });
     });
     return { setState(value) { state = { ...state, ...value }; if (!closed) port?.postMessage({ type:'player-state', ...state }); },
+        getPlayerName: async () => { await connected; return playerName; },
         recordAudio: info => request('record-audio', {recording:info}),
         recordVideo: info => request('record-video', {recording:info}),
         viewExports: () => request('view-exports'),

package/portable-html.js

@@ -9,6 +9,7 @@ const { createExportsViewer } = require('./exports-viewer');
 const { recordVideo } = require('./video-recording');
 const { createExportStorage } = require('./export-storage');
 const { createPlayerToolbar } = require('./player-toolbar');
+const { createPlayerIdentity } = require('./player-identity');
 const inline = value => JSON.stringify(value).replace(/</g, '\\u003c');
 const escapeHtml = value => String(value).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 const filename = name => {
@@ -74,15 +75,15 @@ if(format==='zip')return copy.bytes;
 return new TextEncoder().encode(await HomegamesClient.PortableProject.buildIsolatedHtml(copy.project,{clientBundleSource:document.scripts[0].textContent,installationId:crypto.randomUUID(),sharing:payload.sharing}));
 },{list:()=>client.listExports(),read:name=>client.readExport(name)}, {
 share:()=>client.showShare(),exports:()=>client.viewExports(),'copy-share':shareCopy,'manual-connect':()=>pairing?.show(),
-'pause-input':()=>client.setInputEnabled(false),'resume-input':()=>client.setInputEnabled(true)
+'pause-input':()=>client.setInputEnabled(false),'resume-input':()=>client.setInputEnabled(true),'player-name':name=>client.setPlayerName(name)
 });
-const ready=status=>clientSource.setState({title:project.metadata.name||'Homegame',status,ready:true,sharing:!!payload.sharing});
-client=new HomegamesClient({containerId:'game',chrome:false,localHome:false,share:payload.sharing,saveStore,platform:clientSource,
+const ready=status=>clientSource.setState({title:project.metadata.name||'Homegame',status,ready:true,sharing:!!payload.sharing,playerNames:typeof client.setPlayerName==='function'});
+client=new HomegamesClient({containerId:'game',chrome:false,localHome:false,share:payload.sharing,saveStore,platform:clientSource,playerName:await clientSource.getPlayerName?.(),
 loadLocalGame:async()=>HomegamesClient.PortableProject.prepareTrustedLocalGame(project,{trusted:true,installationId:payload.installationId}),
 onReady:()=>ready('Playing locally'),onSessionStatus:state,onError:fail});
 pairing=payload.sharing?HomegamesClient.createManualPairing({container:document.body,getSession:()=>client._localSession,
 onOpen:()=>client.setInputEnabled(false),onClose:()=>client.setInputEnabled(true),
-join:transport=>{client.stop();client=new HomegamesClient({containerId:'game',chrome:false,transport,platform:clientSource,onReady:()=>ready('Connected manually to host'),onClose:()=>state('Host disconnected'),onError:fail});client.start();}}):null;
+join:async transport=>{client.stop();client=new HomegamesClient({containerId:'game',chrome:false,transport,platform:clientSource,playerName:await clientSource.getPlayerName?.(),onReady:()=>ready('Connected manually to host'),onClose:()=>state('Host disconnected'),onError:fail});client.start();}}):null;
 window.addEventListener('pagehide',()=>{copyShare?.close();pairing?.dispose();client.stop();clientSource.close();});client.startLocalGame({});
 }catch(error){fail(error);}
 })();
@@ -115,7 +116,7 @@ const originalHtml='<!doctype html>\\n'+document.documentElement.outerHTML;
 let frame,saveHost,clientHost;
 const toolbar=(${createPlayerToolbar.toString()})(window,{title:payload.title,status:'Starting game…',onOpen:()=>clientHost?.command('pause-input'),onClose:()=>clientHost?.command('resume-input')});document.body.prepend(toolbar.bar);
 const showSaveStatus=message=>toolbar.setStatus(message);
-async function mount(){clientHost?.close();if(saveHost)await saveHost.close();frame?.remove();frame=(${createFrame.toString()})(document,payload.document);saveHost=(${attachSaveHost.toString()})(window,frame,{...payload.saves,onStatus:value=>showSaveStatus(value.message)});clientHost=(${attachClientHost.toString()})(window,frame,(${recordAudio.toString()}),(${createExportStorage.toString()})(window,payload.saves),(${createExportsViewer.toString()}),(${recordVideo.toString()}),(${createPlayerToolbar.toString()}),{toolbar,htmlId:'portable-html-copy',zipId:'portable-copy'});document.body.appendChild(frame);}
+async function mount(){clientHost?.close();if(saveHost)await saveHost.close();frame?.remove();frame=(${createFrame.toString()})(document,payload.document);saveHost=(${attachSaveHost.toString()})(window,frame,{...payload.saves,onStatus:value=>showSaveStatus(value.message)});clientHost=(${attachClientHost.toString()})(window,frame,(${recordAudio.toString()}),(${createExportStorage.toString()})(window,payload.saves),(${createExportsViewer.toString()}),(${recordVideo.toString()}),(${createPlayerToolbar.toString()}),{toolbar,htmlId:'portable-html-copy',zipId:'portable-copy',profile:(${createPlayerIdentity.toString()})().profile(window)});document.body.appendChild(frame);}
 const fallback=(bytes,type,name)=>{const url=URL.createObjectURL(new Blob([bytes],{type}));const a=document.createElement('a');a.href=url;a.download=name;a.click();setTimeout(()=>URL.revokeObjectURL(url),30000);};
 toolbar.setAction('download-html',{label:'Download game HTML',id:'portable-html-copy',run:()=>fallback(originalHtml,'text/html',payload.name.replace(/\\.zip$/,'.html'))});
 toolbar.setAction('download-zip',{label:'Download game ZIP',id:'portable-copy',run:()=>fallback(Uint8Array.from(atob(payload.archive),c=>c.charCodeAt(0)),'application/zip',payload.name)});