littlejsengine 1.23.0 → 1.24.0

package/src/engineUtilities.js

@@ -1,292 +1,292 @@
-/**
- * LittleJS Utility Classes and Functions
- * - Timer - tracks time automatically with support for pause and real-time modes
- * - Time formatting helper
- * - JSON file fetching
- * - File saving (text, canvas, data URLs)
- * - Native share dialog support
- * - Local storage save data management
- * - Value noise (1D and 2D)
- * @namespace Utilities
- */
-
-'use strict';
-
-/**
- * Timer object tracks how long has passed since it was set
- * @memberof Engine
- * @example
- * let a = new Timer;    // creates a timer that is not set
- * a.set(3);             // sets the timer to 3 seconds
- *
- * let b = new Timer(1); // creates a timer with 1 second left
- * b.unset();            // unset the timer
- */
-class Timer
-{
-    /** Create a timer object set time passed in
-     *  @param {number} [timeLeft] - How much time left before the timer is elapsed in seconds (undefined = unset)
-     *  @param {boolean} [useRealTime] - Should the timer keep running even when the game is paused? (useful for UI) */
-    constructor(timeLeft, useRealTime=false)
-    {
-        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;
-    }
-
-    /** Set the timer with seconds passed in
-     *  @param {number} [timeLeft] - How much time left before the timer is elapsed in seconds */
-    set(timeLeft=0)
-    {
-        ASSERT(isNumber(timeLeft), 'Timer is invalid.', timeLeft);
-        const globalTime = this.getGlobalTime();
-        this.time = globalTime + timeLeft;
-        this.setTime = timeLeft;
-    }
-
-    /** Set if the timer should keep running even when the game is paused
-     *  @param {boolean} [useRealTime] */
-    setUseRealTime(useRealTime=true)
-    {
-        ASSERT(!this.isSet(), 'Cannot change global time setting while timer is set.');
-        this.useRealTime = useRealTime;
-    }
-
-    /** Unset the timer */
-    unset() { this.time = undefined; }
-
-    /** Returns true if set
-     * @return {boolean} */
-    isSet() { return this.time !== undefined; }
-
-    /** Returns true if set and has not elapsed
-     * @return {boolean} */
-    active() { return this.getGlobalTime() < this.time; }
-
-    /** Returns true if set and elapsed
-     * @return {boolean} */
-    elapsed() { return this.getGlobalTime() >= this.time; }
-
-    /** Get how long since elapsed, returns 0 if not set (returns negative if currently active)
-     * @return {number} */
-    get() { return this.isSet()? this.getGlobalTime() - this.time : 0; }
-
-    /** Get percentage elapsed based on time it was set to, returns 0 if not set.
-     *  Zero-duration timers report 1 (already elapsed).
-     * @return {number} */
-    getPercent()
-    {
-        if (!this.isSet()) return 0;
-        if (!this.setTime) return 1;
-        return 1 - percent(this.time - this.getGlobalTime(), 0, this.setTime);
-    }
-
-    /** Get the time this timer was set to, returns 0 if not set
-     * @return {number} */
-    getSetTime() { return this.isSet() ? this.setTime : 0; }
-
-    /** Get the current global time this timer is based on
-     * @return {number} */
-    getGlobalTime() { return this.useRealTime ? timeReal : time; }
-
-    /** Returns this timer expressed as a string
-     * @return {string} */
-    toString() { return this.isSet() ? abs(this.get()) + ' seconds ' + (this.get()<0 ? 'before' : 'after' ) : 'unset'; }
-
-    /** Get how long since elapsed, returns 0 if not set (returns negative if currently active)
-     * @return {number} */
-    valueOf() { return this.get(); }
-}
-
-///////////////////////////////////////////////////////////////////////////////
-
-/** Formats seconds to mm:ss style for display purposes
- *  @param {number} t - time in seconds
- *  @return {string}
- *  @memberof Utilities */
-function formatTime(t)
-{
-    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;
-}
-
-/** Fetches a JSON file from a URL and returns the parsed JSON object. Must be used with await!
- *  @param {string} url - URL of JSON file
- *  @return {Promise<object>}
- *  @memberof Utilities */
-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}`);
-    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;
-}
-
-///////////////////////////////////////////////////////////////////////////////
-
-/** Save a text file to disk
- *  @param {string} text
- *  @param {string} [filename]
- *  @param {string} [type]
- *  @memberof Utilities */
-function saveText(text, filename='text', type='text/plain')
-{ 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
- *  @param {string} [filename]
- *  @param {string} [type]
- *  @memberof Utilities */
-function saveCanvas(canvas, filename='screenshot', type='image/png')
-{
-    if (canvas instanceof OffscreenCanvas)
-    {
-        // copy to temporary canvas and save
-        const saveCanvas = document.createElement('canvas');
-        saveCanvas.width = canvas.width;
-        saveCanvas.height = canvas.height;
-        saveCanvas.getContext('2d').drawImage(canvas, 0, 0);
-        saveDataURL(saveCanvas.toDataURL(type), filename);
-    }
-    else
-        saveDataURL(canvas.toDataURL(type), filename);
-}
-
-/** Save a data url to disk
- *  @param {string} url
- *  @param {string} [filename]
- *  @param {number} [revokeTime] - how long before revoking the url
- *  @memberof Utilities */
-function saveDataURL(url, filename='download', revokeTime)
-{
-    ASSERT(isStringLike(url), 'saveDataURL requires url string');
-    ASSERT(isStringLike(filename), 'saveDataURL requires filename string');
-
-    // create link for saving screenshots
-    const link = document.createElement('a');
-    link.download = filename;
-    link.href = url;
-    link.click();
-    if (revokeTime !== undefined)
-        setTimeout(()=> URL.revokeObjectURL(url), revokeTime);
-}
-
-/** Share content using the native share dialog if available
- *  @param {string} title - title of the share
- *  @param {string} url - url to share
- *  @param {Function} [callback] - Called when share is complete
- *  @memberof Utilities */
-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?.(), ()=>{}); // 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 {T} [defaultSaveData] - default values, result is {...default, ...loaded} so this must be an object
- *  @return {T}
- *  @memberof Utilities */
-function readSaveData(saveName, defaultSaveData)
-{
-    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
-    let loadedData = {};
-    try
-    {
-        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); }
-            catch { LOG('readSaveData: corrupt JSON for', saveName, '— using defaults'); }
-        }
-    }
-    catch { LOG('readSaveData: localStorage unavailable — using defaults'); }
-    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
- *  @memberof Utilities */
-function writeSaveData(saveName, saveData)
-{
-    ASSERT(isStringLike(saveName), 'writeSaveData requires saveName string');
-    // tolerate localStorage being unavailable or quota exceeded
-    try { localStorage.setItem(saveName, JSON.stringify(saveData)); }
-    catch { LOG('writeSaveData: failed to write', saveName); }
-}
-
-///////////////////////////////////////////////////////////////////////////////
-
-// Deterministic well-distributed hash of an integer lattice index to [0, 1).
-// Murmur3 finalizer — adjacent integers produce uncorrelated outputs.
-function noiseHash(i)
-{
-    let h = (i | 0) ^ 0x9e3779b9;
-    h = Math.imul(h ^ (h >>> 16), 0x85ebca6b);
-    h = Math.imul(h ^ (h >>> 13), 0xc2b2ae35);
-    h ^= h >>> 16;
-    return (h >>> 0) / 2**32;
-}
-
-/** 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
- *  @return {number}
- *  @memberof Utilities */
-function noise1D(x)
-{
-    const i = floor(x);
-    return lerp(noiseHash(i), noiseHash(i + 1), smoothStep(x - i));
-}
-
-/** 2D value noise — returns a smooth value in [0, 1] for any real (x, y).
- *  @param {number} x
- *  @param {number} y
- *  @return {number}
- *  @memberof Utilities */
-function noise2D(x, y)
-{
-    const ix = floor(x), iy = floor(y);
-    const fx = smoothStep(x - ix), fy = smoothStep(y - iy);
-    // large prime decorrelates neighboring rows
-    const h = (a, b) => noiseHash(a + b * 374761393);
-    return lerp(
-        lerp(h(ix,     iy    ), h(ix + 1, iy    ), fx),
-        lerp(h(ix,     iy + 1), h(ix + 1, iy + 1), fx),
-        fy);
+/**
+ * LittleJS Utility Classes and Functions
+ * - Timer - tracks time automatically with support for pause and real-time modes
+ * - Time formatting helper
+ * - JSON file fetching
+ * - File saving (text, canvas, data URLs)
+ * - Native share dialog support
+ * - Local storage save data management
+ * - Value noise (1D and 2D)
+ * @namespace Utilities
+ */
+
+'use strict';
+
+/**
+ * Timer object tracks how long has passed since it was set
+ * @memberof Engine
+ * @example
+ * let a = new Timer;    // creates a timer that is not set
+ * a.set(3);             // sets the timer to 3 seconds
+ *
+ * let b = new Timer(1); // creates a timer with 1 second left
+ * b.unset();            // unset the timer
+ */
+class Timer
+{
+    /** Create a timer object set time passed in
+     *  @param {number} [timeLeft] - How much time left before the timer is elapsed in seconds (undefined = unset)
+     *  @param {boolean} [useRealTime] - Should the timer keep running even when the game is paused? (useful for UI) */
+    constructor(timeLeft, useRealTime=false)
+    {
+        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;
+    }
+
+    /** Set the timer with seconds passed in
+     *  @param {number} [timeLeft] - How much time left before the timer is elapsed in seconds */
+    set(timeLeft=0)
+    {
+        ASSERT(isNumber(timeLeft), 'Timer is invalid.', timeLeft);
+        const globalTime = this.getGlobalTime();
+        this.time = globalTime + timeLeft;
+        this.setTime = timeLeft;
+    }
+
+    /** Set if the timer should keep running even when the game is paused
+     *  @param {boolean} [useRealTime] */
+    setUseRealTime(useRealTime=true)
+    {
+        ASSERT(!this.isSet(), 'Cannot change global time setting while timer is set.');
+        this.useRealTime = useRealTime;
+    }
+
+    /** Unset the timer */
+    unset() { this.time = undefined; }
+
+    /** Returns true if set
+     * @return {boolean} */
+    isSet() { return this.time !== undefined; }
+
+    /** Returns true if set and has not elapsed
+     * @return {boolean} */
+    active() { return this.getGlobalTime() < this.time; }
+
+    /** Returns true if set and elapsed
+     * @return {boolean} */
+    elapsed() { return this.getGlobalTime() >= this.time; }
+
+    /** Get how long since elapsed, returns 0 if not set (returns negative if currently active)
+     * @return {number} */
+    get() { return this.isSet()? this.getGlobalTime() - this.time : 0; }
+
+    /** Get percentage elapsed based on time it was set to, returns 0 if not set.
+     *  Zero-duration timers report 1 (already elapsed).
+     * @return {number} */
+    getPercent()
+    {
+        if (!this.isSet()) return 0;
+        if (!(this.setTime > 0)) return 1;
+        return 1 - percent(this.time - this.getGlobalTime(), 0, this.setTime);
+    }
+
+    /** Get the time this timer was set to, returns 0 if not set
+     * @return {number} */
+    getSetTime() { return this.isSet() ? this.setTime : 0; }
+
+    /** Get the current global time this timer is based on
+     * @return {number} */
+    getGlobalTime() { return this.useRealTime ? timeReal : time; }
+
+    /** Returns this timer expressed as a string
+     * @return {string} */
+    toString() { return this.isSet() ? abs(this.get()) + ' seconds ' + (this.get()<0 ? 'before' : 'after' ) : 'unset'; }
+
+    /** Get how long since elapsed, returns 0 if not set (returns negative if currently active)
+     * @return {number} */
+    valueOf() { return this.get(); }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+/** Formats seconds to mm:ss style for display purposes
+ *  @param {number} t - time in seconds
+ *  @return {string}
+ *  @memberof Utilities */
+function formatTime(t)
+{
+    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;
+}
+
+/** Fetches a JSON file from a URL and returns the parsed JSON object. Must be used with await!
+ *  @param {string} url - URL of JSON file
+ *  @return {Promise<object>}
+ *  @memberof Utilities */
+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}`);
+    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;
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+/** Save a text file to disk
+ *  @param {string} text
+ *  @param {string} [filename]
+ *  @param {string} [type]
+ *  @memberof Utilities */
+function saveText(text, filename='text', type='text/plain')
+{ 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
+ *  @param {string} [filename]
+ *  @param {string} [type]
+ *  @memberof Utilities */
+function saveCanvas(canvas, filename='screenshot', type='image/png')
+{
+    if (canvas instanceof OffscreenCanvas)
+    {
+        // copy to temporary canvas and save
+        const saveCanvas = document.createElement('canvas');
+        saveCanvas.width = canvas.width;
+        saveCanvas.height = canvas.height;
+        saveCanvas.getContext('2d').drawImage(canvas, 0, 0);
+        saveDataURL(saveCanvas.toDataURL(type), filename);
+    }
+    else
+        saveDataURL(canvas.toDataURL(type), filename);
+}
+
+/** Save a data url to disk
+ *  @param {string} url
+ *  @param {string} [filename]
+ *  @param {number} [revokeTime] - how long before revoking the url
+ *  @memberof Utilities */
+function saveDataURL(url, filename='download', revokeTime)
+{
+    ASSERT(isStringLike(url), 'saveDataURL requires url string');
+    ASSERT(isStringLike(filename), 'saveDataURL requires filename string');
+
+    // create link for saving screenshots
+    const link = document.createElement('a');
+    link.download = filename;
+    link.href = url;
+    link.click();
+    if (revokeTime !== undefined)
+        setTimeout(()=> URL.revokeObjectURL(url), revokeTime);
+}
+
+/** Share content using the native share dialog if available
+ *  @param {string} title - title of the share
+ *  @param {string} url - url to share
+ *  @param {Function} [callback] - Called when share is complete
+ *  @memberof Utilities */
+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?.(), ()=>{}); // 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 {T} [defaultSaveData] - default values, result is {...default, ...loaded} so this must be an object
+ *  @return {T}
+ *  @memberof Utilities */
+function readSaveData(saveName, defaultSaveData)
+{
+    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
+    let loadedData = {};
+    try
+    {
+        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); }
+            catch { LOG('readSaveData: corrupt JSON for', saveName, '— using defaults'); }
+        }
+    }
+    catch { LOG('readSaveData: localStorage unavailable — using defaults'); }
+    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
+ *  @memberof Utilities */
+function writeSaveData(saveName, saveData)
+{
+    ASSERT(isStringLike(saveName), 'writeSaveData requires saveName string');
+    // tolerate localStorage being unavailable or quota exceeded
+    try { localStorage.setItem(saveName, JSON.stringify(saveData)); }
+    catch { LOG('writeSaveData: failed to write', saveName); }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+// Deterministic well-distributed hash of an integer lattice index to [0, 1).
+// Murmur3 finalizer — adjacent integers produce uncorrelated outputs.
+function noiseHash(i)
+{
+    let h = (i | 0) ^ 0x9e3779b9;
+    h = Math.imul(h ^ (h >>> 16), 0x85ebca6b);
+    h = Math.imul(h ^ (h >>> 13), 0xc2b2ae35);
+    h ^= h >>> 16;
+    return (h >>> 0) / 2**32;
+}
+
+/** 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
+ *  @return {number}
+ *  @memberof Utilities */
+function noise1D(x)
+{
+    const i = floor(x);
+    return lerp(noiseHash(i), noiseHash(i + 1), smoothStep(x - i));
+}
+
+/** 2D value noise — returns a smooth value in [0, 1] for any real (x, y).
+ *  @param {number} x
+ *  @param {number} y
+ *  @return {number}
+ *  @memberof Utilities */
+function noise2D(x, y)
+{
+    const ix = floor(x), iy = floor(y);
+    const fx = smoothStep(x - ix), fy = smoothStep(y - iy);
+    // large prime decorrelates neighboring rows
+    const h = (a, b) => noiseHash(a + b * 374761393);
+    return lerp(
+        lerp(h(ix,     iy    ), h(ix + 1, iy    ), fx),
+        lerp(h(ix,     iy + 1), h(ix + 1, iy + 1), fx),
+        fy);
 }

package/src/engineWebGL.js

@@ -770,6 +770,9 @@ function glDrawUntextured(x, y, sizeX, sizeY, angle, rgba)
     glDraw(x, y, sizeX, sizeY, angle, 0, 0, 0, 0, 0, rgba);
 }
 
+// the list and the vectors glDrawPointsTransform writes its points into
+const glPointsOut = [], glPointsPool = [];
+
 /** Transform and add a polygon to the gl draw list
  *  @param {Array<Vector2>} points - Array of Vector2 points
  *  @param {number} rgba - Color of the polygon as a 32-bit integer
@@ -782,15 +785,21 @@ function glDrawUntextured(x, y, sizeX, sizeY, angle, rgba)
  *  @memberof WebGL */
 function glDrawPointsTransform(points, rgba, x, y, sx, sy, angle, tristrip=true)
 {
-    const pointsOut = [];
+    // written into vectors kept for this, a circle would make one for each of its sides at every draw; they are
+    // read into the batch before this returns
+    const pointsOut = glPointsOut, pool = glPointsPool, count = points.length;
+    pointsOut.length = count;
     const sa = sin(-angle);
     const ca = cos(-angle);
-    for (const p of points)
+    for (let i = 0; i < count; ++i)
     {
         // transform the point
+        const p = points[i], out = pool[i] ||= vec2();
         const px = p.x*sx;
         const py = p.y*sy;
-        pointsOut.push(vec2(x + ca*px - sa*py, y + sa*px + ca*py));
+        out.x = x + ca*px - sa*py;
+        out.y = y + sa*px + ca*py;
+        pointsOut[i] = out;
     }
     const drawPoints = tristrip ? glPolyStrip(pointsOut) : pointsOut;
     glDrawPoints(drawPoints, rgba);