littlejsengine 1.18.24 → 1.18.25

package/dist/littlejs.release.js

@@ -35,7 +35,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.18.24';
+const engineVersion = '1.18.25';
 
 /** Frames per second to update
  *  @type {number}
@@ -92,6 +92,7 @@ function setPaused(isPaused=true) { paused = isPaused; }
 
 // Engine internal variables
 let frameTimeLastMS = 0, frameTimeBufferMS = 0, averageFPS = 0;
+let engineUpdateInternal; // assigned by engineInit so engineStep can drive it
 let showEngineVersion = true;
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -280,7 +281,8 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
 
         if (!debugVideoCaptureIsActive())
             renderFrame();
-        requestAnimationFrame(engineUpdate);
+        if (!engineManualStep)
+            requestAnimationFrame(engineUpdate);
 
         function renderFrame()
         {
@@ -308,6 +310,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
             primitiveCount = 0;
         }
     }
+    engineUpdateInternal = engineUpdate;
 
     function updateCanvas()
     {
@@ -462,10 +465,39 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     {
         // wait for gameInit to load
         await gameInit();
-        engineUpdate();
+        engineManualStep || engineUpdate();
     }
 }
 
+// max frames engineStep can advance in one call, 10 minutes at 60fps
+// large counts block until they finish, so this catches runaway values
+const engineStepMaxFrames = 36000;
+
+/** Advance the engine by a number of frames
+ *  Requires setEngineManualStep(true) before engineInit
+ *  Respects paused exactly as the normal update loop does
+ *  @param {number} [frames] - number of engine update ticks, max 36000, each running one fixed update at timeScale 1
+ *  @example
+ *  setHeadlessMode(true);
+ *  setEngineManualStep(true);
+ *  await engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost);
+ *  engineStep(600); // advance 10 seconds of game time
+ *  @memberof Engine */
+function engineStep(frames=1)
+{
+    ASSERT(engineManualStep,
+        'engineStep requires setEngineManualStep(true) before engineInit');
+    ASSERT(engineUpdateInternal, 'engineStep requires engineInit to complete');
+    // runtime guard so release builds (where the asserts are stripped) can't
+    // start a second requestAnimationFrame chain or call an undefined update
+    if (!engineManualStep || !engineUpdateInternal) return;
+    ASSERT(Number.isInteger(frames) && frames >= 0 && frames <= engineStepMaxFrames,
+        'engineStep requires a whole frame count from 0 to ' + engineStepMaxFrames);
+    frames = min(frames, engineStepMaxFrames); // release has no asserts, don't freeze
+    for (let i = frames; i > 0; --i)
+        engineUpdateInternal(frameTimeLastMS + 1e3 / frameRate);
+}
+
 /** Update each engine object, remove destroyed objects, and update time
  * can be called manually if objects need to be updated outside of main loop
  *  @memberof Engine */
@@ -1997,12 +2029,17 @@ function shareURL(title, url, callback)
 
 /** Read save data from local storage
  *  @param {string} saveName - unique name for the game/save
- *  @param {Object} [defaultSaveData] - default values for save
+ *  @param {Object} [defaultSaveData] - default values, result is {...default, ...loaded} so this must be an object
  *  @return {Object}
  *  @memberof Utilities */
 function readSaveData(saveName, defaultSaveData)
 {
-    ASSERT(isStringLike(saveName), 'loadData requires saveName string');
+    ASSERT(isStringLike(saveName), 'readSaveData requires saveName string');
+    ASSERT(defaultSaveData === undefined ||
+        (typeof defaultSaveData === 'object' && defaultSaveData !== null),
+        'readSaveData: default must be an object - the result is ' +
+        '{...default, ...loaded}, so a scalar default yields {}. ' +
+        'Use readSaveData(key, {best:0}).best');
 
     // tolerate localStorage being unavailable (iOS private mode, sandboxed
     // iframes) and corrupt JSON in stored data
@@ -2026,7 +2063,7 @@ function readSaveData(saveName, defaultSaveData)
  *  @memberof Utilities */
 function writeSaveData(saveName, saveData)
 {
-    ASSERT(isStringLike(saveName), 'saveData requires saveName string');
+    ASSERT(isStringLike(saveName), 'writeSaveData requires saveName string');
     // tolerate localStorage being unavailable or quota exceeded
     try { localStorage[saveName] = JSON.stringify(saveData); }
     catch { LOG('writeSaveData: failed to write', saveName); }
@@ -2194,6 +2231,13 @@ let showSplashScreen = false;
  *  @memberof Settings */
 let headlessMode = false;
 
+/** Disables the automatic requestAnimationFrame loop so the engine only
+ *  advances when engineStep is called, for tests and frame-stepping tools
+ *  @type {boolean}
+ *  @default
+ *  @memberof Settings */
+let engineManualStep = false;
+
 ///////////////////////////////////////////////////////////////////////////////
 // WebGL settings
 
@@ -2544,6 +2588,12 @@ function setShowSplashScreen(show) { showSplashScreen = show; }
  *  @memberof Settings */
 function setHeadlessMode(headless) { headlessMode = headless; }
 
+/** Set if the engine only advances when engineStep is called
+ *  Must be set before engineInit
+ *  @param {boolean} [enable]
+ *  @memberof Settings */
+function setEngineManualStep(enable=true) { engineManualStep = enable; }
+
 /** Set if WebGL rendering is enabled
  *  @param {boolean} enable
  *  @memberof Settings */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "littlejsengine",
-  "version": "1.18.24",
+  "version": "1.18.25",
   "description": "LittleJS - Tiny and Fast HTML5 Game Engine",
   "main": "dist/littlejs.esm.js",
   "types": "dist/littlejs.d.ts",
@@ -38,6 +38,7 @@
   ],
   "scripts": {
     "build": "node src/engineBuild.mjs",
+    "build-docs": "node tools/buildDocs.mjs",
     "test": "node --test --import ./test/setup.mjs \"test/**/*.test.mjs\""
   },
   "engines": {
@@ -45,9 +46,11 @@
   },
   "devDependencies": {
     "bestzip": "^2.2.1",
+    "clean-jsdoc-theme": "~4.2.9",
     "electron": "^38.2.0",
     "electron-packager": "^17.1.2",
     "google-closure-compiler": "~20230502.0.0",
+    "jsdoc": "~4.0.2",
     "roadroller": "~2.1.0",
     "typescript": "~5.1.6",
     "uglify-js": "~3.17.4"

package/src/engine.js

@@ -32,7 +32,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.18.24';
+const engineVersion = '1.18.25';
 
 /** Frames per second to update
  *  @type {number}
@@ -89,6 +89,7 @@ function setPaused(isPaused=true) { paused = isPaused; }
 
 // Engine internal variables
 let frameTimeLastMS = 0, frameTimeBufferMS = 0, averageFPS = 0;
+let engineUpdateInternal; // assigned by engineInit so engineStep can drive it
 let showEngineVersion = true;
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -277,7 +278,8 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
 
         if (!debugVideoCaptureIsActive())
             renderFrame();
-        requestAnimationFrame(engineUpdate);
+        if (!engineManualStep)
+            requestAnimationFrame(engineUpdate);
 
         function renderFrame()
         {
@@ -305,6 +307,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
             primitiveCount = 0;
         }
     }
+    engineUpdateInternal = engineUpdate;
 
     function updateCanvas()
     {
@@ -459,10 +462,39 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     {
         // wait for gameInit to load
         await gameInit();
-        engineUpdate();
+        engineManualStep || engineUpdate();
     }
 }
 
+// max frames engineStep can advance in one call, 10 minutes at 60fps
+// large counts block until they finish, so this catches runaway values
+const engineStepMaxFrames = 36000;
+
+/** Advance the engine by a number of frames
+ *  Requires setEngineManualStep(true) before engineInit
+ *  Respects paused exactly as the normal update loop does
+ *  @param {number} [frames] - number of engine update ticks, max 36000, each running one fixed update at timeScale 1
+ *  @example
+ *  setHeadlessMode(true);
+ *  setEngineManualStep(true);
+ *  await engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost);
+ *  engineStep(600); // advance 10 seconds of game time
+ *  @memberof Engine */
+function engineStep(frames=1)
+{
+    ASSERT(engineManualStep,
+        'engineStep requires setEngineManualStep(true) before engineInit');
+    ASSERT(engineUpdateInternal, 'engineStep requires engineInit to complete');
+    // runtime guard so release builds (where the asserts are stripped) can't
+    // start a second requestAnimationFrame chain or call an undefined update
+    if (!engineManualStep || !engineUpdateInternal) return;
+    ASSERT(Number.isInteger(frames) && frames >= 0 && frames <= engineStepMaxFrames,
+        'engineStep requires a whole frame count from 0 to ' + engineStepMaxFrames);
+    frames = min(frames, engineStepMaxFrames); // release has no asserts, don't freeze
+    for (let i = frames; i > 0; --i)
+        engineUpdateInternal(frameTimeLastMS + 1e3 / frameRate);
+}
+
 /** Update each engine object, remove destroyed objects, and update time
  * can be called manually if objects need to be updated outside of main loop
  *  @memberof Engine */

package/src/engineExport.js

@@ -19,6 +19,7 @@ export
     getPaused,
     setPaused,
     engineInit,
+    engineStep,
     engineObjectsUpdate,
     engineObjectsDestroy,
     engineObjectsCollect,
@@ -66,6 +67,7 @@ export
     fontDefault,
     showSplashScreen,
     headlessMode,
+    engineManualStep,
     tileDefaultSize,
     tileDefaultPadding,
     tileDefaultBleed,
@@ -120,6 +122,7 @@ export
     setFontDefault,
     setShowSplashScreen,
     setHeadlessMode,
+    setEngineManualStep,
     setGLEnable,
     setTileDefaultSize,
     setTileDefaultPadding,

package/src/engineSettings.js

@@ -121,6 +121,13 @@ let showSplashScreen = false;
  *  @memberof Settings */
 let headlessMode = false;
 
+/** Disables the automatic requestAnimationFrame loop so the engine only
+ *  advances when engineStep is called, for tests and frame-stepping tools
+ *  @type {boolean}
+ *  @default
+ *  @memberof Settings */
+let engineManualStep = false;
+
 ///////////////////////////////////////////////////////////////////////////////
 // WebGL settings
 
@@ -471,6 +478,12 @@ function setShowSplashScreen(show) { showSplashScreen = show; }
  *  @memberof Settings */
 function setHeadlessMode(headless) { headlessMode = headless; }
 
+/** Set if the engine only advances when engineStep is called
+ *  Must be set before engineInit
+ *  @param {boolean} [enable]
+ *  @memberof Settings */
+function setEngineManualStep(enable=true) { engineManualStep = enable; }
+
 /** Set if WebGL rendering is enabled
  *  @param {boolean} enable
  *  @memberof Settings */

package/src/engineUtilities.js

@@ -190,12 +190,17 @@ function shareURL(title, url, callback)
 
 /** Read save data from local storage
  *  @param {string} saveName - unique name for the game/save
- *  @param {Object} [defaultSaveData] - default values for save
+ *  @param {Object} [defaultSaveData] - default values, result is {...default, ...loaded} so this must be an object
  *  @return {Object}
  *  @memberof Utilities */
 function readSaveData(saveName, defaultSaveData)
 {
-    ASSERT(isStringLike(saveName), 'loadData requires saveName string');
+    ASSERT(isStringLike(saveName), 'readSaveData requires saveName string');
+    ASSERT(defaultSaveData === undefined ||
+        (typeof defaultSaveData === 'object' && defaultSaveData !== null),
+        'readSaveData: default must be an object - the result is ' +
+        '{...default, ...loaded}, so a scalar default yields {}. ' +
+        'Use readSaveData(key, {best:0}).best');
 
     // tolerate localStorage being unavailable (iOS private mode, sandboxed
     // iframes) and corrupt JSON in stored data
@@ -219,7 +224,7 @@ function readSaveData(saveName, defaultSaveData)
  *  @memberof Utilities */
 function writeSaveData(saveName, saveData)
 {
-    ASSERT(isStringLike(saveName), 'saveData requires saveName string');
+    ASSERT(isStringLike(saveName), 'writeSaveData requires saveName string');
     // tolerate localStorage being unavailable or quota exceeded
     try { localStorage[saveName] = JSON.stringify(saveData); }
     catch { LOG('writeSaveData: failed to write', saveName); }