homegames-common 1.5.2 → 1.5.4

package/game-loader.js

@@ -33,6 +33,8 @@ const squishMap = {
     '135': 'squish-135',
     '136': 'squish-136',
     '138': 'squish-138',
+    // 1.3.9 — adds per-tick coalescing of squish/broadcast + Squisher.flush()
+    '139': 'squish-139',
 };
 
 const DEFAULT_SQUISH_VERSION = '135';

package/game-session-manager.js

@@ -18,7 +18,7 @@ const path = require('path');
 const fs = require('fs');
 const os = require('os');
 
-const { isDockerAvailable, isImageBuilt, ensureImage, runGameContainer, stopContainer, isContainerRunning } = require('./docker-helper');
+const { isDockerAvailable, isImageBuilt, ensureImage, runGameContainer, stopContainer, isContainerRunning, parseMemoryString } = require('./docker-helper');
 const { squishMap, DEFAULT_SQUISH_VERSION, fetchGameFromForgejo, loadGameClassFromPath, detectSquishVersion, parseSquishVersion } = require('./game-loader');
 
 // ---------------------------------------------------------------------------
@@ -74,6 +74,7 @@ class GameSessionManager {
      * @param {function} [opts.log] — logging function ({ info, error })
      * @param {number} [opts.bezelX] — bezel size X for init message (default 0)
      * @param {number} [opts.bezelY] — bezel size Y for init message (default 0)
+     * @param {string} [opts.memoryLimit] — Docker-style memory limit for child sessions (e.g. '128m'); overrides CHILD_SESSION_MEMORY_LIMIT config
      */
     constructor(opts = {}) {
         this.portPool = new PortPool(
@@ -84,7 +85,7 @@ class GameSessionManager {
         this.dockerImageName = opts.dockerImageName || 'homegames-runner';
         this.childServerPath = opts.childServerPath || null;
         this.gracePeriodMs = opts.gracePeriodMs || 30000;
-        this.lifecycleCheckMs = opts.lifecycleCheckMs || 10000;
+        this.lifecycleCheckMs = opts.lifecycleCheckMs || 3000;
         this.forgejo = opts.forgejo || {};
         this.saveDataRoot = opts.saveDataRoot || path.join(os.tmpdir(), 'hg-save-data');
         this.assetCachePath = opts.assetCachePath || null;
@@ -93,6 +94,16 @@ class GameSessionManager {
         this.certPath = opts.certPath || null;
         this.log = opts.log || { info: console.log, error: console.error };
 
+        // Memory limit for child game sessions. A single Docker-style string
+        // (e.g. '128m', '1g') configurable via config.json / env (getConfigValue),
+        // with an opts override. Docker consumes it directly; the fork path
+        // converts it to integer megabytes for V8's --max-old-space-size.
+        // require lazily: index.js requires this module, so it isn't fully
+        // populated at module-load time, but the constructor runs at runtime.
+        const { getConfigValue } = require('./index');
+        this.memoryLimit = opts.memoryLimit
+            || getConfigValue('CHILD_SESSION_MEMORY_LIMIT', '196m');
+
         this.sessions = {};
         this._dockerChecked = false;
         this._dockerOk = false;
@@ -250,6 +261,7 @@ class GameSessionManager {
             imageName: this.dockerImageName,
             gameEntryRelative,
             noFrame: input.noFrame || false,
+            memoryLimit: this.memoryLimit,
             extraEnv,
         });
 
@@ -351,7 +363,17 @@ class GameSessionManager {
                 }
             }
             // Apply required overrides (these take precedence)
-            env.NODE_PATH = `${process.cwd()}${path.sep}node_modules`;
+            // Resolve the game's `require('squish-NNN')` against the core
+            // install's node_modules (where the squish packages actually live),
+            // NOT process.cwd() — the core process is forked by Electron with an
+            // inherited cwd that has no node_modules, so a cwd-relative NODE_PATH
+            // would (intermittently) fail to find the requested squish version.
+            // childServerPath is <core>/src/child_game_server.js, so its
+            // grandparent dir is the core install root.
+            const coreModulesPath = this.childServerPath
+                ? path.join(path.dirname(path.dirname(this.childServerPath)), 'node_modules')
+                : `${process.cwd()}${path.sep}node_modules`;
+            env.NODE_PATH = coreModulesPath;
             env.SQUISH_PATH = squishPkg;
             // opts.env is filtered through the same allowlist — no arbitrary injection
             if (opts.env) {
@@ -362,12 +384,17 @@ class GameSessionManager {
                 }
             }
             
+            // V8's --max-old-space-size is in megabytes; convert the Docker-style
+            // memory limit string (bytes) to MB.
+            const maxOldSpaceMb = Math.max(1, Math.floor(parseMemoryString(this.memoryLimit) / (1024 * 1024)));
             const child = fork(this.childServerPath, [], {
                 env,
                 stdio: ['pipe', 'pipe', 'pipe', 'ipc'],
-                execArgv: ['--max-old-space-size=64'],
+                execArgv: [`--max-old-space-size=${maxOldSpaceMb}`],
             });
 
+            this._attachForkLogForwarding(child);
+
             child.send(JSON.stringify({
                 key: input.gameKey || path.basename(gamePath, '.js'),
                 squishVersion,
@@ -433,6 +460,38 @@ class GameSessionManager {
         });
     }
 
+    // -----------------------------------------------------------------------
+    // Forward forked child stdout/stderr to the parent terminal.
+    // Docker sessions are excluded — use GET /sessions/:id/logs or docker logs.
+    // -----------------------------------------------------------------------
+    _attachForkLogForwarding(child) {
+        const emitLine = (line) => {
+            if (!line) return;
+            console.log(`session log: ${line}`);
+        };
+
+        const attachStream = (stream) => {
+            if (!stream) return;
+            let buffer = '';
+            stream.on('data', (chunk) => {
+                buffer += chunk.toString();
+                const lines = buffer.split('\n');
+                buffer = lines.pop() || '';
+                for (const line of lines) {
+                    emitLine(line);
+                }
+            });
+            stream.on('end', () => {
+                if (buffer.length > 0) {
+                    emitLine(buffer);
+                }
+            });
+        };
+
+        attachStream(child.stdout);
+        attachStream(child.stderr);
+    }
+
     // -----------------------------------------------------------------------
     // Find the project root (nearest ancestor with node_modules or package.json)
     // so we mount enough of the tree for relative requires to work.
@@ -525,10 +584,30 @@ class GameSessionManager {
 
             if (s.type === 'docker') {
                 const running = await isContainerRunning(s.containerId);
-                this.log.info(`Session ${sessionId} lifecycle check: container running = ${running}`);
                 if (!running) {
                     this.log.info(`Session ${sessionId} container exited`);
                     this._cleanupSession(sessionId);
+                    return;
+                }
+
+                // Check player count — stop container if empty past grace period
+                try {
+                    const healthData = await this._querySessionHealth(s.port);
+                    const playerCount = healthData && healthData.playerCount !== undefined ? healthData.playerCount : -1;
+                    if (playerCount === 0) {
+                        s._emptyTicks++;
+                        const emptyMs = s._emptyTicks * this.lifecycleCheckMs;
+                        if (emptyMs >= this.gracePeriodMs) {
+                            this.log.info(`Session ${sessionId} empty for ${emptyMs}ms, stopping`);
+                            await stopContainer(s.containerId);
+                            this._cleanupSession(sessionId);
+                            return;
+                        }
+                    } else if (playerCount > 0) {
+                        s._emptyTicks = 0;
+                    }
+                } catch (e) {
+                    // Health check failed — container might be starting up, ignore
                 }
             } else if (s.type === 'fork') {
                 // For fork sessions, send heartbeat. The child_game_server.js
@@ -559,6 +638,28 @@ class GameSessionManager {
         this._cleanupSession(sessionId);
     }
 
+    _querySessionHealth(port) {
+        return new Promise((resolve) => {
+            const req = http.request({
+                hostname: 'localhost',
+                port,
+                path: '/health',
+                method: 'GET',
+                timeout: 2000,
+            }, (res) => {
+                let data = '';
+                res.on('data', (chunk) => { data += chunk; });
+                res.on('end', () => {
+                    try { resolve(JSON.parse(data)); }
+                    catch (e) { resolve(null); }
+                });
+            });
+            req.on('error', () => resolve(null));
+            req.on('timeout', () => { req.destroy(); resolve(null); });
+            req.end();
+        });
+    }
+
     _cleanupSession(sessionId) {
         const session = this.sessions[sessionId];
         if (!session) return;

package/game-session.js

@@ -88,7 +88,15 @@ class GameSession {
         }
 
         this.squisher = new Squisher(squisherOpts);
-        this.squisher.addListener(() => this._broadcastState());
+        // Coalesce broadcasts: a single game tick often mutates many nodes, each
+        // firing onStateChange -> a listener call. Without coalescing that's one
+        // full per-player send (frame.flat + Buffer.from + ws.send) per mutation.
+        // We defer to the end of the current event-loop turn so a burst of
+        // mutations produces a single broadcast carrying the final state.
+        // (The squisher still recomputes this.state synchronously per mutation,
+        // so getPlayerFrame/state stay fresh for the direct-send paths.)
+        this._broadcastScheduled = false;
+        this.squisher.addListener(() => this._scheduleBroadcast());
 
         this.gameMetadata = (typeof game.constructor.metadata === 'function') ? game.constructor.metadata() : {};
         this.maxPlayers = this.gameMetadata.maxPlayers || 64;
@@ -448,6 +456,18 @@ class GameSession {
     // Private: broadcasting
     // -----------------------------------------------------------------------
 
+    _scheduleBroadcast() {
+        if (this._broadcastScheduled) return;
+        this._broadcastScheduled = true;
+        const schedule = (typeof setImmediate === 'function')
+            ? setImmediate
+            : (fn) => setTimeout(fn, 0);
+        schedule(() => {
+            this._broadcastScheduled = false;
+            this._broadcastState();
+        });
+    }
+
     _broadcastState() {
         for (const pid in this.players) {
             try {
@@ -466,6 +486,11 @@ class GameSession {
     }
 
     _sendPlayerFrame(playerId, ws) {
+        // Newer squishers defer squish/broadcast and coalesce per tick. The
+        // direct-send paths (a player/spectator just joined) need the current
+        // state, so flush any pending changes first. No-op when nothing pending
+        // and on older squishers that don't implement flush().
+        if (typeof this.squisher.flush === 'function') this.squisher.flush();
         let frame = this.squisher.getPlayerFrame(playerId);
         if (!frame) frame = this.squisher.state;
         if (frame) {

package/index.js

@@ -33,7 +33,8 @@ const DEFAULT_CONFIG = {
     "API_URL": "https://api.homegames.io",
     "LINK_PROXY_URL": "wss://public.homegames.link:81",
     "LINK_URL": "wss://homegames.link",
-    "MAP_ENABLED": true
+    "MAP_ENABLED": true,
+    "CHILD_SESSION_MEMORY_LIMIT": "196m"
 };
 
 // ---------------------------------------------------------------------------
@@ -192,10 +193,21 @@ const dockerHelper = require('./docker-helper');
 const GameSession = require('./game-session');
 const GameSessionManager = require('./game-session-manager');
 
+const getHash = (input) => {
+    return crypto.createHash('md5').update(input).digest('hex');
+};
+
+
 // ---------------------------------------------------------------------------
 // Exports
 // ---------------------------------------------------------------------------
 
+// Canonical squish.js authoring guide — the single source of truth for every
+// consumer (the LLM worker, the studio "copy LLM context" feature, repo docs).
+// Read the text with getAuthoringDoc(), or hand a child process authoringDocPath.
+const AUTHORING_DOC_PATH = path.join(__dirname, 'docs', 'squishjs-game-authoring.md');
+const getAuthoringDoc = () => fs.readFileSync(AUTHORING_DOC_PATH, 'utf-8');
+
 module.exports = {
     // Utilities
     guaranteeDir,
@@ -203,6 +215,11 @@ module.exports = {
     getConfigValue,
     log,
     getAppDataPath,
+    getHash,
+
+    // Authoring guide (single source of truth)
+    authoringDocPath: AUTHORING_DOC_PATH,
+    getAuthoringDoc,
 
     // Game loading
     gameLoader,

package/package.json

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