littlejsengine 1.18.29 → 1.20.0

package/src/engineUtilities.js

@@ -6,7 +6,7 @@
  * - File saving (text, canvas, data URLs)
  * - Native share dialog support
  * - Local storage save data management
- * - Gradient noise (1D and 2D)
+ * - Value noise (1D and 2D)
  * @namespace Utilities
  */
 
@@ -32,7 +32,9 @@ class Timer
         ASSERT(timeLeft === undefined || isNumber(timeLeft), 'Constructed Timer is invalid.', timeLeft);
         this.useRealTime = useRealTime;
         const globalTime = this.getGlobalTime();
+        /** @type {number|undefined} */
         this.time = timeLeft === undefined ? undefined : globalTime + timeLeft;
+        /** @type {number|undefined} */
         this.setTime = timeLeft;
     }
 
@@ -108,7 +110,7 @@ class Timer
  *  @memberof Utilities */
 function formatTime(t)
 {
-    const signStr = t < 0 ? '-' : '';
+    const signStr = t <= -1 ? '-' : ''; // no sign when it shows 0:00
     t = abs(t)|0;
     return signStr + (t/60|0) + ':' + (t%60<10?'0':'') + t%60;
 }
@@ -122,7 +124,9 @@ async function fetchJSON(url)
     const response = await fetch(url);
     if (!response.ok)
         throw new Error(`Failed to fetch JSON from ${url}: ${response.status} ${response.statusText}`);
-    return response.json();
+    const json = await response.json();
+    editorJSONFetched(url, json); // debug builds remember the file a level came from, to save it by that name
+    return json;
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -133,7 +137,20 @@ async function fetchJSON(url)
  *  @param {string} [type]
  *  @memberof Utilities */
 function saveText(text, filename='text', type='text/plain')
-{ saveDataURL(URL.createObjectURL(new Blob([text], {'type':type})), filename); }
+{ saveDataURL(URL.createObjectURL(new Blob([text], {'type':type})), filename, 1e3); } // freed once the download has it
+
+/** Create an offscreen canvas to draw into, and return its 2D context
+ *  - The canvas is context.canvas, which is what TextureInfo and the like take
+ *  @param {number} width - In pixels
+ *  @param {number} [height] - In pixels, defaults to the width for a square
+ *  @param {boolean} [willReadFrequently] - Keep it in software, faster when getImageData is called on it often
+ *  @return {OffscreenCanvasRenderingContext2D}
+ *  @memberof Utilities */
+function createCanvasContext(width, height=width, willReadFrequently=false)
+{
+    ASSERT(isNumber(width) && isNumber(height), 'canvas width and height must be numbers', width, height);
+    return new OffscreenCanvas(width, height).getContext('2d', {willReadFrequently});
+}
 
 /** Save a canvas to disk
  *  @param {HTMLCanvasElement|OffscreenCanvas} canvas
@@ -183,15 +200,17 @@ function shareURL(title, url, callback)
 {
     ASSERT(isStringLike(title), 'shareURL requires title string');
     ASSERT(isStringLike(url), 'shareURL requires url string');
-    navigator.share?.({title, url}).then(()=>callback?.());
+    navigator.share?.({title, url}).then(()=>callback?.(), ()=>{}); // a player who cancels is not an error
 }
 
 ///////////////////////////////////////////////////////////////////////////////
 
 /** Read save data from local storage
+ *  - The result has the type of defaultSaveData, or any when there is none
+ *  @template {Object<string, any>} [T=any]
  *  @param {string} saveName - unique name for the game/save
- *  @param {Object} [defaultSaveData] - default values, result is {...default, ...loaded} so this must be an object
- *  @return {Object}
+ *  @param {T} [defaultSaveData] - default values, result is {...default, ...loaded} so this must be an object
+ *  @return {T}
  *  @memberof Utilities */
 function readSaveData(saveName, defaultSaveData)
 {
@@ -207,7 +226,7 @@ function readSaveData(saveName, defaultSaveData)
     let loadedData = {};
     try
     {
-        const data = localStorage[saveName];
+        const data = localStorage.getItem(saveName); // not the brackets, a name like 'key' or 'length' is a Storage member
         if (data)
         {
             try { loadedData = JSON.parse(data); }
@@ -215,18 +234,18 @@ function readSaveData(saveName, defaultSaveData)
         }
     }
     catch { LOG('readSaveData: localStorage unavailable — using defaults'); }
-    return { ...defaultSaveData, ...loadedData };
+    return { .../** @type {object} */ (defaultSaveData), ...loadedData };
 }
 
 /** Write save data to local storage
  *  @param {string} saveName - unique name for the game/save
- *  @param {Object} saveData - object containing data to be saved
+ *  @param {object} saveData - object containing data to be saved
  *  @memberof Utilities */
 function writeSaveData(saveName, saveData)
 {
     ASSERT(isStringLike(saveName), 'writeSaveData requires saveName string');
     // tolerate localStorage being unavailable or quota exceeded
-    try { localStorage[saveName] = JSON.stringify(saveData); }
+    try { localStorage.setItem(saveName, JSON.stringify(saveData)); }
     catch { LOG('writeSaveData: failed to write', saveName); }
 }
 
@@ -243,7 +262,7 @@ function noiseHash(i)
     return (h >>> 0) / 2**32;
 }
 
-/** 1D gradient noise — returns a smooth value in [0, 1] for any real x.
+/** 1D value noise — returns a smooth value in [0, 1] for any real x.
  *  Integer inputs land on deterministic lattice values; non-integer inputs
  *  are interpolated with smoothStep for C1 continuity.
  *  @param {number} x
@@ -255,7 +274,7 @@ function noise1D(x)
     return lerp(noiseHash(i), noiseHash(i + 1), smoothStep(x - i));
 }
 
-/** 2D gradient noise — returns a smooth value in [0, 1] for any real (x, y).
+/** 2D value noise — returns a smooth value in [0, 1] for any real (x, y).
  *  @param {number} x
  *  @param {number} y
  *  @return {number}