littlejsengine 1.25.0 → 1.26.1

package/plugins/wavedash.js

@@ -0,0 +1,229 @@
+/**
+ * LittleJS Wavedash Plugin
+ * - The Wavedash twin of the Newgrounds plugin: achievements and leaderboards, the same shape so a game can switch
+ * - Wavedash serves the game's page and puts its SDK in window.Wavedash before the game runs, so nothing is bundled;
+ *   off Wavedash (local, itch, GitHub Pages) there is none, and every call does nothing
+ * - Make the plugin when the game can draw, at the end of gameInit: Wavedash.init is called then, and until it is
+ *   Wavedash keeps its loading screen over the game
+ * - WavedashMedal is a Medal with the identifier of its Wavedash achievement; on Wavedash an unlock is sent as that
+ *   achievement and Wavedash shows its own toast in place of the engine's popup, off it the medal unlocks as any does
+ * - Wavedash refuses an achievement until it has loaded the player's, a moment after launch, so refused and earlier
+ *   unlocks are sent again every two seconds until it takes them; medals unlocked before, in the save, are sent too
+ * - Leaderboards are made from code: give the plugin a table of them, each with how it sorts and shows its scores,
+ *   and they are made at once, so each one exists from the first launch
+ * - The SDK checks its arguments' types and throws on a wrong one, so every call passes real booleans and whole
+ *   numbers and is caught; a game built with its own minifier keeps the SDK's names, see REFERENCE
+ * @namespace Wavedash
+ */
+
+'use strict';
+
+/** Global Wavedash plugin object
+ *  @type {WavedashPlugin}
+ *  @memberof Wavedash */
+let wavedash;
+
+// Engine internal variables not exposed to documentation
+const wavedashRetryMS = 2e3; // how long to wait before sending refused achievements again
+const wavedashRetries = 30;   // how many times one is sent before it is taken as never to be, about a minute
+const wavedashTimeoutMS = 15e3; // how long a leaderboard call may take, as the Newgrounds plugin waits
+const wavedashDisplayTypes = {number: 0, seconds: 1, milliseconds: 2, ticks: 3}; // the SDK's display types
+
+// the SDK Wavedash put on the page, read at each call, undefined off Wavedash
+const wavedashSDK = ()=> globalThis['Wavedash'];
+
+// a call's answer, or undefined if it does not come in time or fails, with a warning; the time limit is let go of once
+// the answer is in, so nothing waits on it after
+function wavedashWait(name, answer)
+{
+    let timer;
+    const limit = new Promise((resolve)=> timer = setTimeout(resolve, wavedashTimeoutMS));
+    return Promise.race([Promise.resolve(answer), limit])
+        .catch((error)=> { console.warn('Wavedash ' + name + ' failed: ' + error); })
+        .finally(()=> clearTimeout(timer));
+}
+
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * WavedashMedal: a medal that is also a Wavedash achievement, unlocked on Wavedash by its identifier
+ * @extends Medal
+ * @memberof Wavedash
+ * @example
+ * const medal_finish = new WavedashMedal(0, 'ACH_01_FINISH', 'Finish', 'Finish a level');
+ * medal_finish.unlock(); // Wavedash's toast on Wavedash, the engine's popup anywhere else
+ */
+class WavedashMedal extends Medal
+{
+    /** Create a WavedashMedal and add it to the list of medals
+     *  @param {number} id            - The unique identifier of the medal, as for any Medal
+     *  @param {string} achievement   - The identifier of its Wavedash achievement, as made with the Wavedash CLI
+     *  @param {string} name          - Name of the medal
+     *  @param {string} [description] - Description of the medal
+     *  @param {string} [icon]        - Icon for the medal
+     *  @param {string} [src]         - Image location for the medal
+     */
+    constructor(id, achievement, name, description, icon, src)
+    {
+        ASSERT(typeof achievement === 'string' && achievement !== '', 'WavedashMedal: achievement must be the identifier of a Wavedash achievement', achievement);
+        super(id, name, description, icon, src);
+
+        /** @property {string} - The identifier of its Wavedash achievement */
+        this.achievement = achievement;
+    }
+
+    /** Unlocks the medal if not already unlocked, saved as any medal is; on Wavedash its achievement is sent, until
+     *  Wavedash takes it, and Wavedash shows its own toast in place of the engine's popup; one unlocked before the
+     *  plugin is made is sent when it is
+     *  @return {Promise<boolean>} - Whether the medal is unlocked */
+    unlock()
+    {
+        // off Wavedash, or testing medals with debugMedals, the engine's own popup and nothing sent
+        if (medalsPreventUnlock || this.unlocked || !wavedashSDK() || debugMedals)
+            return super.unlock();
+        this.unlocked = true;
+        medalsSave();
+        wavedash?.sendAchievements();
+        return Promise.resolve(true);
+    }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Wavedash plugin: starts the Wavedash SDK, sends achievements and posts and reads leaderboards
+ * @memberof Wavedash
+ * @example
+ * // at the end of gameInit, with the leaderboards the game posts to
+ * new WavedashPlugin({LEVEL_1: {lowerWins: true, display: 'milliseconds'}, HIGH_SCORE: {}});
+ * wavedash.postScore('LEVEL_1', timeMs);
+ */
+class WavedashPlugin
+{
+    /** Start the Wavedash SDK when the game is on Wavedash, and make its leaderboards
+     *  @param {Object<string, {lowerWins?: boolean, display?: string}>} [leaderboards] - The game's leaderboards by
+     *    name: lowerWins for times and golf, where a lower score is better, higher wins when left out; display how
+     *    Wavedash shows a score, 'number', 'seconds', 'milliseconds' or 'ticks' (60 a second), 'number' when left out
+     */
+    constructor(leaderboards={})
+    {
+        ASSERT(!wavedash, 'WavedashPlugin already initialized');
+        ASSERT(!!leaderboards && typeof leaderboards === 'object', 'WavedashPlugin: leaderboards is an object of them by name');
+        wavedash = this;
+
+        /** @property {Object<string, Promise<string|undefined>>} - Each leaderboard's id by its name, once Wavedash
+         *  has made or found it, undefined when it could not
+         *  @type {Object<string, Promise<string|undefined>>} */
+        this.leaderboards = Object.create(null); // no inherited names, a board may be called constructor
+        /** @type {Object<string, {lowerWins?: boolean, display?: string}>} */
+        this.leaderboardSettings = leaderboards; // how each one sorts and shows its scores, read as its own entries
+        /** @type {Set<string>} */
+        this.achievementsSent = new Set; // the achievements Wavedash took this visit, or refused for good
+        /** @type {Object<string, number>} */
+        this.achievementTries = Object.create(null); // how many times each one not taken yet was sent
+        /** @type {number|undefined} */
+        this.achievementRetry = undefined; // the timer that sends refused ones again
+
+        // Wavedash keeps its loading screen until init, which is called once
+        wavedashWait('init', this.call('init'));
+        for (const name in leaderboards)
+            this.leaderboard(name);
+        this.sendAchievements(); // the medals the save already has, unlocked before or off Wavedash
+    }
+
+    /** Whether the game is on Wavedash, its SDK on the page
+     *  @return {boolean} */
+    isActive() { return !!wavedashSDK(); }
+
+    /** Call the SDK, undefined off Wavedash; a call that throws, as on an argument of the wrong type, says so in
+     *  the console and gives undefined
+     *  @param {string} name - The SDK function
+     *  @param {...*} args
+     *  @return {*}
+     *  @ignore */
+    call(name, ...args)
+    {
+        const sdk = wavedashSDK();
+        if (!sdk) return;
+        try { return sdk[name](...args); }
+        catch (error) { console.warn('Wavedash ' + name + ' failed: ' + error); }
+    }
+
+    /** A leaderboard's id by its name, made on Wavedash the first time it is asked for, with the settings it was given
+     *  @param {string} name
+     *  @return {Promise<string|undefined>}
+     *  @ignore */
+    leaderboard(name)
+    {
+        ASSERT(typeof name === 'string' && name !== '', 'Wavedash: a leaderboard name must be a string', name);
+        if (this.leaderboards[name]) return this.leaderboards[name];
+        const settings = Object.prototype.hasOwnProperty.call(this.leaderboardSettings, name) ?
+            this.leaderboardSettings[name] : undefined; // its own entry, not an inherited one
+        const {lowerWins=false, display='number'} = settings || {};
+        const known = wavedashDisplayTypes.hasOwnProperty(display);
+        ASSERT(known, 'Wavedash: a leaderboard display is number, seconds, milliseconds or ticks', display);
+        const made = this.call('getOrCreateLeaderboard', name, lowerWins ? 0 : 1, known ? wavedashDisplayTypes[display] : 0);
+        const id = wavedashWait('leaderboard ' + name, made).then((result)=>
+            result?.['success'] ? result['data']?.['id'] : undefined);
+        // one that could not be made is asked for again next time
+        id.then((value)=> value === undefined && this.leaderboards[name] === id && delete this.leaderboards[name]);
+        return this.leaderboards[name] = id;
+    }
+
+    /** Post a score to a leaderboard, Wavedash keeping the player's best; off Wavedash it does nothing
+     *  - A leaderboard not in the table given to the plugin is made the first time, higher wins and shown as a number
+     *  @param {string} name - The leaderboard's name
+     *  @param {number} score - A whole number, milliseconds for a time
+     *  @return {Promise<boolean>} - Whether it was posted */
+    async postScore(name, score)
+    {
+        ASSERT(isNumber(score), 'Wavedash postScore: score must be a number', score);
+        if (!this.isActive()) return false;
+        const id = await this.leaderboard(name);
+        if (id === undefined) return false;
+        const result = await wavedashWait('postScore', this.call('uploadLeaderboardScore', id, round(score), true));
+        return !!result?.['success'];
+    }
+
+    /** Read a leaderboard's entries, undefined off Wavedash or when it could not be read
+     *  @param {string} name - The leaderboard's name
+     *  @param {number} [offset] - How many entries to skip over
+     *  @param {number} [limit] - How many entries to read
+     *  @param {boolean} [friendsOnly] - Only the player and their friends
+     *  @return {Promise<Array<Object>|undefined>} - The entries, as Wavedash gives them */
+    async getScores(name, offset=0, limit=10, friendsOnly=false)
+    {
+        if (!this.isActive()) return;
+        const id = await this.leaderboard(name);
+        if (id === undefined) return;
+        const result = await wavedashWait('getScores',
+            this.call('listLeaderboardEntries', id, offset|0, limit|0, !!friendsOnly));
+        return result?.['success'] ? result['data'] : undefined;
+    }
+
+    /** Send every unlocked WavedashMedal's achievement Wavedash has not taken yet, again every two seconds while it
+     *  refuses some, as it does until it has loaded the player's achievements; one refused for about a minute is
+     *  taken as an identifier Wavedash does not have, said once in the console, and not sent again this visit
+     *  @ignore */
+    sendAchievements()
+    {
+        if (!this.isActive() || debugMedals) return;
+        let refused = false;
+        medalsForEach((medal)=>
+        {
+            const achievement = medal instanceof WavedashMedal && medal.unlocked && medal.achievement;
+            if (!achievement || this.achievementsSent.has(achievement)) return;
+            const result = this.call('setAchievement', achievement, true);
+            if (result === true || result?.['success'] === true)
+                this.achievementsSent.add(achievement);
+            else if ((this.achievementTries[achievement] = (this.achievementTries[achievement] || 0) + 1) < wavedashRetries)
+                refused = true;
+            else
+            {
+                console.warn('Wavedash refused achievement ' + achievement + ' ' + wavedashRetries +
+                    ' times; is it made, with that identifier?');
+                this.achievementsSent.add(achievement); // not sent again this visit
+            }
+        });
+        clearTimeout(this.achievementRetry);
+        this.achievementRetry = refused ? setTimeout(()=> this.sendAchievements(), wavedashRetryMS) : undefined;
+    }
+}

package/src/engine.js

@@ -32,7 +32,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.25.0';
+const engineVersion = '1.26.1';
 
 /** Frames per second to update
  *  @type {number}
@@ -66,6 +66,8 @@ let engineObjectsCollideStaticLast = [];
 let frame = 0;
 
 /** Current engine time since start in seconds
+ *  - Below 20 FPS it falls behind the clock, since a frame catches up at most 50 ms of updates, so a timer in
+ *    real seconds, one that must keep up on a slow device, goes by timeReal
  *  @type {number}
  *  @memberof Engine */
 let time = 0;
@@ -91,8 +93,13 @@ function getPaused() { return paused; }
  *  @memberof Engine */
 function setPaused(isPaused=true) { paused = isPaused; }
 
+/** Frames drawn per second, smoothed over the last few seconds, in release builds too
+ *  @type {number}
+ *  @memberof Engine */
+let averageFPS = 0;
+
 // Engine internal variables
-let frameTimeLastMS = 0, frameTimeBufferMS = 0, averageFPS = 0;
+let frameTimeLastMS = 0, frameTimeBufferMS = 0;
 
 // delta smoothing, after Time Delta Smoothing by Frank Force (2013): a frame is on screen for whole display frames,
 // so each delta is rounded to them and the rest is carried to the next, keeping the total real time; the frame
@@ -179,7 +186,134 @@ function engineObjectsCollidePairAdd(asker, other, resolve=false)
     others || engineObjectsCollidePairs.set(asker, others = new Map);
     others.set(other, resolve);
 }
+
+// with this many solids or more, a mover finds what is near it through a grid of cells rather than checking every
+// solid, a big game's cost going from every pair to what is close; it resolves the same contacts in the same order,
+// so a game plays the same either way, and a few solids are quicker checked all
+let engineCollideGridMin = 64;
+// the grid for this update, {list, built}: the list of solids, and the grid made from it the first time a 2D mover
+// walks it, so a frame with no 2D mover, as 3D solids alone, makes none; built is each cell's solids, each solid's
+// cells, and each solid's place in the list, which the contacts are taken in; solids too big for cells are near
+// everything
+let engineCollideGrid;
+
+// the grid of a list of solids, its cells about twice a typical solid so most are in one to four
+function engineCollideGridBuild(list)
+{
+    let extent = 0;
+    for (const o of list)
+        extent += min(max(abs(o.size.x), abs(o.size.y)), 16) || 0; // a negative size is a mirrored one
+    const index = new Map;
+    const grid = {size: max(2 * extent / list.length, .5), cells: new Map, at: new Map, index, big: new Set,
+        seen: new Map, stamp: 0, byIndex: (a, b)=> index.get(a) - index.get(b)}; // what a query found, and its order
+    list.forEach((o, i)=> { index.set(o, i); engineCollideGridPlace(grid, o); });
+    return grid;
+}
+
+// the cells an object's box covers, first and last along x and y, in one kept array to read at once; a negative size
+// is a mirrored sprite of that size
+const engineCollideGridBox = [0, 0, 0, 0];
+function engineCollideGridCells(grid, o)
+{
+    const s = grid.size, w = abs(o.size.x) / 2, h = abs(o.size.y) / 2, box = engineCollideGridBox;
+    box[0] = floor((o.pos.x - w) / s), box[1] = floor((o.pos.y - h) / s);
+    box[2] = floor((o.pos.x + w) / s), box[3] = floor((o.pos.y + h) / s);
+    return box;
+}
+
+// whether a box is kept in its cells: not over 1024 of them, and within 2^31 cells of the origin, past which a cell
+// loop would not end, as ++ stops changing a number past 2^53, and the keys would not be exact; one with no finite
+// box does not fit either, and is near every mover
+const engineCollideGridFits = (x0, y0, x1, y1)=> (x1 - x0 + 1) * (y1 - y0 + 1) <= 1024 &&
+    abs(x0) < 2**31 && abs(y0) < 2**31 && abs(x1) < 2**31 && abs(y1) < 2**31;
+
+// put a solid in the cells its box covers now, out of those it was in; a box on a cell's edge is in both cells, so
+// solids that touch share one
+function engineCollideGridPlace(grid, o)
+{
+    if (!grid.index.has(o)) return;
+    const [x0, y0, x1, y1] = engineCollideGridCells(grid, o);
+    const big = !engineCollideGridFits(x0, y0, x1, y1);
+    const was = grid.at.get(o);
+    if (was && was[0] === x0 && was[1] === y0 && was[2] === x1 && was[3] === y1 && was[4] === big) return;
+    if (was && !was[4])
+        for (let x = was[0]; x <= was[2]; ++x)
+        for (let y = was[1]; y <= was[3]; ++y)
+        {
+            const cell = grid.cells.get(x * 1048576 + y);
+            cell.splice(cell.indexOf(o), 1);
+        }
+    grid.big.delete(o);
+    if (big)
+        grid.big.add(o);
+    else
+        for (let x = x0; x <= x1; ++x)
+        for (let y = y0; y <= y1; ++y)
+        {
+            const key = x * 1048576 + y;
+            const cell = grid.cells.get(key);
+            cell ? cell.push(o) : grid.cells.set(key, [o]);
+        }
+    grid.at.set(o, [x0, y0, x1, y1, big]);
+}
+
+// the solids a mover is near, after a place in the list, in list order, filled into near; each found once, by the
+// query's stamp
+function engineCollideGridNear(grid, o, after, near)
+{
+    const [x0, y0, x1, y1] = engineCollideGridCells(grid, o);
+    const stamp = ++grid.stamp;
+    near.length = 0;
+    for (const other of grid.big)
+        engineCollideGridAdd(grid, other, after, stamp, near);
+    if (engineCollideGridFits(x0, y0, x1, y1))
+    {
+        for (let x = x0; x <= x1; ++x)
+        for (let y = y0; y <= y1; ++y)
+        {
+            const cell = grid.cells.get(x * 1048576 + y);
+            if (cell)
+                for (const other of cell)
+                    engineCollideGridAdd(grid, other, after, stamp, near);
+        }
+    }
+    else
+        for (const other of grid.index.keys()) // a mover too big for cells is near everything
+            engineCollideGridAdd(grid, other, after, stamp, near);
+    near.sort(grid.byIndex);
+}
+
+// add a solid to what a query found, once, when it is after the place in the list
+function engineCollideGridAdd(grid, other, after, stamp, near)
+{
+    if (grid.seen.get(other) === stamp) return;
+    grid.seen.set(other, stamp);
+    grid.index.get(other) > after && near.push(other);
+}
+
+// the solids a mover checks, as checking every one would reach them: in list order, and found again from where it is
+// whenever its box has moved, as a push does, so a solid it is pushed into later in the list is still checked
+function* engineCollideGridWalk(o)
+{
+    const grid = engineCollideGrid.built ||= engineCollideGridBuild(engineCollideGrid.list);
+    let after = -1, x, y, w, h, k = 0;
+    const near = [];
+    for (;;)
+    {
+        if (o.pos.x !== x || o.pos.y !== y || o.size.x !== w || o.size.y !== h)
+        {
+            x = o.pos.x, y = o.pos.y, w = o.size.x, h = o.size.y;
+            engineCollideGridNear(grid, o, after, near);
+            k = 0;
+        }
+        if (k >= near.length) return;
+        const other = near[k++];
+        after = grid.index.get(other);
+        yield other;
+    }
+}
 let engineInitialized = false; // engineInit ran, with or without a canvas
+let engineInitDone; // the promise the first engineInit hands back, which a second call hands back too
 // the loads startup waits for, each counted for the loading screen, and how many are done; undefined once the game
 // loop starts
 let engineLoads, engineLoadsDone = 0;
@@ -223,7 +357,7 @@ function engineAddPlugin(update, render, glContextLost, glContextRestored, preRe
         p.update === update && p.render === render &&
         p.glContextLost === glContextLost &&
         p.glContextRestored === glContextRestored &&
-        p.preRender === preRender));
+        p.preRender === preRender), 'engineAddPlugin: this plugin was already added');
 
     const plugin = new EnginePlugin(update, render, glContextLost, glContextRestored, preRender);
     pluginList.push(plugin);
@@ -305,8 +439,10 @@ function engineLoadingScreenDraw(elapsed)
  *  @param {GameCallback} [gameUpdatePost] - Called after physics and objects are updated, even when paused, use for UI updates
  *  @param {GameCallback} [gameRender] - Called before objects are rendered, use for drawing backgrounds/world elements
  *  @param {GameCallback} [gameRenderPost] - Called after objects are rendered, use for drawing UI/overlays
- *  @param {Array<string>} [imageSources=[]] - List of image file paths to preload (e.g., ['player.png', 'tiles.png'])
- *  @param {HTMLElement} [rootElement] - Root DOM element to attach canvas to, defaults to document.body
+ *  @param {Array<string>|string} [imageSources=[]] - List of image file paths to preload (e.g., ['player.png', 'tiles.png']), or one path
+ *  @param {HTMLElement} [rootElement] - Root DOM element to attach canvas to, defaults to document.body; it is
+ *                                       styled for a game (no scroll bars or selection, touch-action none),
+ *                                       where its own inline style does not say otherwise
  *    It keeps its own inline styles and the canvas centers inside it, but the canvas is still sized from the window,
  *    so set canvasFixedSize or canvasMaxSize to fit a smaller element
  *  @example
@@ -323,13 +459,15 @@ function engineLoadingScreenDraw(elapsed)
  *  @return {Promise<void>} - Done when the images have loaded and gameInit has run */
 async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost, imageSources=[], rootElement)
 {
-    showEngineVersion && console.log(`${engineName} Engine v${engineVersion}`);
     ASSERT(!engineInitialized, 'engine already initialized');
     // runtime guard so release builds (where the assert is stripped) don't
-    // double-register listeners / double-add canvases on a second call
-    if (engineInitialized) return;
+    // double-register listeners / double-add canvases on a second call, which is done when the first is
+    if (engineInitialized) return engineInitDone;
     engineInitialized = true;
+    showEngineVersion && console.log(`${engineName} Engine v${engineVersion}`);
     engineLoads = [], engineLoadsDone = 0;
+    if (typeof imageSources === 'string')
+        imageSources = [imageSources]; // one image given alone
     ASSERT(isArray(imageSources), 'pass in images as array');
 
     // allow passing in empty functions
@@ -367,8 +505,10 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         // by ~page-load-time when RAF starts handing real timestamps
         if (!frameTimeLastMS) frameTimeDeltaMS = 0;
         frameTimeLastMS = frameTimeMS;
-        if (debug || debugWatermark)
-            averageFPS = lerp(averageFPS, 1e3/(frameTimeDeltaMS||1), .05);
+        // the first frame's rate seeds the average, so it does not start out climbing from 0; a gap of over a
+        // second, a hidden tab coming back, is not a frame
+        if (frameTimeDeltaMS && frameTimeDeltaMS < 1e3)
+            averageFPS = averageFPS ? lerp(averageFPS, 1e3/frameTimeDeltaMS, .05) : 1e3/frameTimeDeltaMS;
         // the time the frame will be on screen, in whole display frames; engineStep's steps are exact already
         if (!manualStepAtStart)
             frameTimeDeltaMS = engineSmoothDelta(frameTimeDeltaMS);
@@ -471,8 +611,6 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
             debugUpdate();
             gameUpdatePost();
             inputUpdatePost();
-            if (debugVideoCaptureIsActive())
-                renderFrame();
         }
 
         // manual step turned on by this frame's updates, set the buffer the loop and smoothing just moved again
@@ -494,7 +632,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
 
         // render only when something changed, displays that refresh faster
         // than the fixed update rate would otherwise redraw identical frames
-        if (!debugVideoCaptureIsActive() && (wasUpdated || windowChanged))
+        if (wasUpdated || windowChanged)
             renderFrame();
         engineManualStep || engineScheduleFrame();
 
@@ -526,14 +664,13 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
             inputRender();
             debugRender();
             glFlush();
-            debugRenderPost();
             drawCount = 0;
             primitiveCount = 0;
         }
     }
 
     // skip setup if headless
-    if (headlessMode) return startEngine([]);
+    if (headlessMode) return engineInitDone = startEngine([]);
 
     // ensure body exists for minimal HTML where the script runs before <body> is parsed
     if (!document.body)
@@ -611,21 +748,25 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         promises.push(splash);
     }
 
-    // the splash first, the images load under it, then the loading screen for the rest
-    showSplashScreen && await promises[promises.length - 1];
-    return startEngine(promises);
+    // kept before anything is awaited, so a second call has it
+    return engineInitDone = startEngine(promises);
 
-    // gameInit runs once the images are in, and the game loop starts once it and everything loaded while it ran are
-    // done, the loading screen showing in the meantime; an error in gameInit reaches the caller
+    // the splash first, the images load under it, then gameInit runs once they are in, and the game loop starts once
+    // it and everything loaded while it ran are done, the loading screen showing in the meantime; an error in gameInit
+    // reaches the caller
     async function startEngine(images)
     {
+        showSplashScreen && !headlessMode && await images[images.length - 1]; // headless has no splash
         const init = (async ()=> { await Promise.all(images); await gameInit(); })();
         engineAddLoad(init);
         await engineWaitForLoads();
         engineLoads = undefined;
         await init;
         engineUpdateInternal = engineUpdate; // engineStep only runs once the game is set up
-        engineManualStep || engineUpdate();
+        if (engineManualStep) return;
+        if (debug) return engineUpdate(); // a debug build stops at an error, the first frame's as any
+        try { engineUpdate(); }
+        catch (error) { engineFrameFailed(error); } // a release build goes on past it, as on any later frame
     }
 }
 
@@ -643,7 +784,7 @@ function engineUpdateCanvas()
     if (canvasFixedSize.x)
     {
         // set canvas fixed size
-        mainCanvasSize = canvasFixedSize.copy();
+        mainCanvasSize.set(canvasFixedSize.x, canvasFixedSize.y);
 
         // fit to window using css width and height
         const innerAspect = innerWidth / innerHeight;
@@ -667,7 +808,8 @@ function engineUpdateCanvas()
 
         // responsive aspect ratio, of the size after canvasMaxSize, which can change its shape
         const innerAspect = mainCanvasSize.x / mainCanvasSize.y;
-        ASSERT(!canvasMaxAspect || canvasMinAspect <= canvasMaxAspect);
+        ASSERT(!canvasMaxAspect || canvasMinAspect <= canvasMaxAspect,
+            'canvasMinAspect must not be above canvasMaxAspect', canvasMinAspect, canvasMaxAspect);
         if (canvasMaxAspect && innerAspect > canvasMaxAspect)
         {
             // full height
@@ -703,9 +845,12 @@ function engineUpdateCanvas()
     }
     else
     {
-        // setting the size also resets the context state, match that
+        // setting the size also resets the context state, match that, what a game may have left on it too
         mainContext.setTransform(1, 0, 0, 1, 0, 0);
         mainContext.globalCompositeOperation = 'source-over';
+        mainContext.globalAlpha = 1;
+        mainContext.filter = 'none';
+        mainContext.shadowColor = 'rgba(0,0,0,0)';
         mainContext.clearRect(0, 0, bufferSizeX, bufferSizeY);
     }
 
@@ -726,6 +871,18 @@ function engineUpdateCanvas()
     mainContext.lineCap  = 'round';
 }
 
+// a release build goes on past an error in a frame, a frozen game is the worst a player can get; an error is logged
+// when it is not the last one again, one every frame would flood the console
+function engineFrameFailed(error)
+{
+    const text = String(error);
+    text === engineFrameErrorLast || console.error(error);
+    engineFrameErrorLast = text;
+    // the frame's input is cleared as its tick would have, or a key press that threw would be pressed again
+    inputUpdatePost();
+    engineScheduleFrame();
+}
+
 // ask for the next frame of the loop, once however often it is called before that frame, and skip it if manual
 // step was turned on since, so turning it off and on again within a frame can not start a second loop
 function engineScheduleFrame()
@@ -738,17 +895,7 @@ function engineScheduleFrame()
         if (engineManualStep) return;
         if (debug) return engineUpdateInternal(frameTimeMS); // a debug build stops at an error, where it shows it
         try { engineUpdateInternal(frameTimeMS); }
-        catch (error)
-        {
-            // a release build goes on past an error in a frame, a frozen game is the worst a player can get; an error
-            // is logged when it is not the last one again, one every frame would flood the console
-            const text = String(error);
-            text === engineFrameErrorLast || console.error(error);
-            engineFrameErrorLast = text;
-            // the frame's input is cleared as its tick would have, or a key press that threw would be pressed again
-            inputUpdatePost();
-            engineScheduleFrame();
-        }
+        catch (error) { engineFrameFailed(error); }
     };
     if (typeof requestAnimationFrame === 'function')
         requestAnimationFrame(next);
@@ -769,7 +916,7 @@ const engineStepMaxFrames = 36000;
  *  setHeadlessMode(true);
  *  setEngineManualStep(true);
  *  await engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost);
- *  engineStep(600); // advance 10 seconds of game time
+ *  engineStep(600); // 600 updates of 1/60 second; the first is at time 0, so time is then 599/60
  *  @memberof Engine */
 function engineStep(frames=1)
 {
@@ -806,11 +953,23 @@ function engineObjectsUpdate()
         o.collideSolidObjects && (engineObjectsCollide.push(o), (o.mass ? engineObjectsCollideStaticLast : fixed).push(o));
     for (const o of fixed)
         engineObjectsCollideStaticLast.push(o);
+    // written only when there is a grid: V8 keeps a variable that is never written as a constant, and writing it
+    // every frame makes this function deoptimize again and again in a game with no grid
+    if (engineObjectsCollideStaticLast.length >= engineCollideGridMin)
+        engineCollideGrid = {list: engineObjectsCollideStaticLast, built: undefined};
 
-    // update physics before object update
-    for (const o of engineObjects)
-        if (!o.parent && !o.destroyed)
-            o.updatePhysics();
+    // update physics before object update, each solid put where it moved to in the grid, for the movers after it;
+    // the grid is let go even when a callback throws, so an updatePhysics called before the next update checks all
+    try
+    {
+        for (const o of engineObjects)
+            if (!o.parent && !o.destroyed)
+            {
+                o.updatePhysics();
+                engineCollideGrid?.built && engineCollideGridPlace(engineCollideGrid.built, o);
+            }
+    }
+    finally { engineCollideGrid && (engineCollideGrid = undefined); }
 
     // recursive object update: the children are walked from a copy on a shared stack, since a child that
     // destroys itself leaves its parent's list on the spot and the next child would slide past the loop