littlejsengine 1.20.0 → 1.21.0

package/src/engine.js

@@ -32,7 +32,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.20.0';
+const engineVersion = '1.21.0';
 
 /** Frames per second to update
  *  @type {number}
@@ -40,11 +40,12 @@ const engineVersion = '1.20.0';
  *  @memberof Engine */
 const frameRate = 60;
 
-/** How many seconds each frame lasts, engine uses a fixed time step
+/** How many seconds the update covers: 1/60 with the fixed time step, or with engineVariableStep the time of the
+ *  display frame it runs on, times timeScale; while paused it keeps the last update's
  *  @type {number}
  *  @default 1/60
  *  @memberof Engine */
-const timeDelta = 1/frameRate;
+let timeDelta = 1/frameRate;
 
 /** Array containing all engine objects
  *  @type {Array<EngineObject>}
@@ -92,6 +93,75 @@ function setPaused(isPaused=true) { paused = isPaused; }
 
 // Engine internal variables
 let frameTimeLastMS = 0, frameTimeBufferMS = 0, averageFPS = 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
+// length is estimated from recent frames and kept internal, since the browser does not say what it is
+const frameDeltaHistory = [];
+let frameIntervalMS = 1e3 / 60, frameDeltaCarryMS = 0, frameDeltaCarryAverageMS = 0, frameDeltaSmoothing = true;
+function engineSmoothDelta(deltaMS)
+{
+    if (!(deltaMS > 0)) return 0;
+    if (deltaMS < 250) // a gap from a hidden tab is not a display frame
+    {
+        frameDeltaHistory.push(deltaMS);
+        frameDeltaHistory.length > 64 && frameDeltaHistory.shift();
+
+        // the frames each delta held are counted in the last estimate or in the lower quartile of the last 16,
+        // whichever the deltas fit better: the quartile is one frame even when a busy game misses most of them, and
+        // it takes over when the window moves to a display with another refresh rate, or the estimate went wrong
+        const recent = frameDeltaHistory.slice(-16).sort((a, b)=> a - b);
+        const [lastMS, lastOff] = engineFrameFit(frameIntervalMS);
+        const [quartileMS, quartileOff] = engineFrameFit(recent[recent.length >> 2]);
+        frameIntervalMS = lastOff <= quartileOff ? lastMS : quartileMS;
+
+        // deltas far from whole frames mean the display has no fixed refresh, with a margin so it does not flip
+        frameDeltaSmoothing = min(lastOff, quartileOff) < (frameDeltaSmoothing ? .2 : .12);
+    }
+
+    if (!frameDeltaSmoothing)
+    {
+        // deltas that are not whole frames of one length, like a variable refresh display, are the frame times
+        // as they are, with any carry paid, and smoothing starts over once they fit again
+        const rawMS = deltaMS + frameDeltaCarryMS;
+        frameDeltaCarryMS = min(rawMS, 0);
+        frameDeltaCarryAverageMS = 0;
+        return max(rawMS, 0);
+    }
+
+    // whole frames, 0 for one that came early or 2 after one was missed, the carry stays within half a frame; a
+    // little of its slow average is paid each frame, so jitter can not hold it at half a frame and flip every frame
+    const pullMS = frameDeltaCarryAverageMS / 32;
+    frameDeltaCarryMS += deltaMS;
+    const frames = round((frameDeltaCarryMS - pullMS) / frameIntervalMS);
+    if (frames < 1)
+        return 0; // the carry keeps it
+    const smoothMS = frames * frameIntervalMS + pullMS;
+    frameDeltaCarryMS -= smoothMS;
+    frameDeltaCarryAverageMS += (frameDeltaCarryMS - frameDeltaCarryAverageMS) / 32;
+    return smoothMS;
+}
+
+// fit the delta history as whole frames of about unitMS: the frame length is the least squares slope of time over
+// frames held, so jitter and whole ms timestamps average out, with how far the deltas are from whole frames
+function engineFrameFit(unitMS)
+{
+    let timeMS = 0, frames = 0, offMS = 0, sumF = 0, sumT = 0, sumFF = 0, sumFT = 0;
+    const count = frameDeltaHistory.length;
+    for (const d of frameDeltaHistory)
+    {
+        const held = max(1, round(d / unitMS));
+        timeMS += d;
+        frames += held;
+        offMS += abs(d - held * unitMS);
+        sumF += frames, sumT += timeMS, sumFF += frames * frames, sumFT += frames * timeMS;
+    }
+    const spread = count * sumFF - sumF * sumF;
+    return [spread ? (count * sumFT - sumF * sumT) / spread : unitMS, offMS / count / unitMS];
+}
+
+// where the fixed step's time counts from, moved when the variable step hands back so time goes on from there
+let timeFixedStart = 0, frameFixedStart = 0;
 let windowWidthLast = 0, windowHeightLast = 0, windowPixelRatioLast = 0;
 let engineUpdateInternal; // assigned by engineInit so engineStep can drive it
 let engineFrameScheduled = false; // a frame of the loop is asked for and has not run yet
@@ -109,6 +179,9 @@ function engineObjectsCollidePairAdd(asker, other, resolve=false)
     others.set(other, resolve);
 }
 let engineInitialized = false; // engineInit ran, with or without a canvas
+// 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;
 let engineObjectsUpdateCount = 0; // passes of engineObjectsUpdate so far, how a child knows it moved this pass
 const engineChildStack = []; // the children being updated, taken off the live lists so one leaving does not skip the next
 let showEngineVersion = true;
@@ -158,11 +231,68 @@ function engineAddPlugin(update, render, glContextLost, glContextRestored, preRe
 ///////////////////////////////////////////////////////////////////////////////
 // Main Engine Functions
 
+/** Add something the game loads to what startup waits for: while engineInit and gameInit run, the game loop starts
+ *  once it is done, and the loading screen counts it; images from loadTexture and sounds from files are added on
+ *  their own, and a load that fails counts as done; after startup it does nothing
+ *  @param {Promise<any>} promise
+ *  @return {Promise<any>} - The same promise
+ *  @example
+ *  async function gameInit() { level = await engineAddLoad(fetchJSON('level.json')); }
+ *  @memberof Engine */
+function engineAddLoad(promise)
+{
+    if (engineLoads)
+    {
+        engineLoads.push(promise);
+        const done = ()=> { ++engineLoadsDone; };
+        promise.then(done, done);
+    }
+    return promise;
+}
+
+// wait for every load, the ones added while waiting too, drawing the loading screen each frame meanwhile
+async function engineWaitForLoads()
+{
+    let waiting = true;
+    const start = performance.now();
+    const drawFrame = ()=>
+    {
+        if (!waiting) return;
+        engineLoadingScreenDraw((performance.now() - start) / 1e3);
+        setTimeout(drawFrame, 16);
+    };
+    headlessMode || drawFrame();
+    try
+    {
+        for (let count; count !== engineLoads.length;)
+        {
+            count = engineLoads.length;
+            await Promise.allSettled(engineLoads);
+        }
+    }
+    finally { waiting = false; }
+}
+
+// one frame of the loading screen, once loading has taken half a second, so a fast load never shows it; input
+// while it shows is dropped, as it is under the splash
+function engineLoadingScreenDraw(elapsed)
+{
+    if (headlessMode || !loadingScreen || elapsed < .5) return;
+    inputClear();
+    engineUpdateCanvas();
+    loadingScreen(engineLoadsDone / engineLoads.length);
+}
+
 /**
  * @callback GameInitCallback - Called after the engine starts, can be async
  * @return {void|Promise<void>}
  * @memberof Engine
  */
+/**
+ * @callback LoadingScreenCallback - Draws the loading screen on mainContext, each frame while the game loads
+ * @param {number} progress - The part of the loads done, 0 to 1
+ * @memberof Engine
+ */
 /**
  * @callback GameCallback - Update or render function for the game
  * @memberof Engine
@@ -197,6 +327,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     // double-register listeners / double-add canvases on a second call
     if (engineInitialized) return;
     engineInitialized = true;
+    engineLoads = [], engineLoadsDone = 0;
     ASSERT(isArray(imageSources), 'pass in images as array');
 
     // allow passing in empty functions
@@ -236,6 +367,9 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         frameTimeLastMS = frameTimeMS;
         if (debug || debugWatermark)
             averageFPS = lerp(averageFPS, 1e3/(frameTimeDeltaMS||1), .05);
+        // the time the frame will be on screen, in whole display frames; engineStep's steps are exact already
+        if (!manualStepAtStart)
+            frameTimeDeltaMS = engineSmoothDelta(frameTimeDeltaMS);
         audioUpdateVolume();
         // the time keys work while the debug overlay is open, or always when debugKeysAlways is set
         const debugKeys = debug && (debugOverlay || debugKeysAlways);
@@ -248,32 +382,61 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         timeReal += frameTimeDeltaMS * debugScale / 1e3;
         const combinedScale = timeScale * debugScale;
         frameTimeDeltaMS *= combinedScale;
-        // paused or a time scale of 0 is frozen: it ticks on unscaled time, so the update rate stays fixed instead of
-        // following however fast the display refreshes, and gameUpdatePost and input still run to leave it
-        const frozen = paused || !combinedScale;
-        frameTimeBufferMS += frozen ? frameTimeDeltaUnscaledMS : frameTimeDeltaMS;
-        frameTimeBufferMS = min(frameTimeBufferMS, 50 * (frozen ? 1 : max(1, combinedScale))); // clamp min framerate
-
-        // apply time delta smoothing, improves smoothness of framerate in some browsers
-        let wasUpdated = false, deltaSmooth = 0;
-        if (frameTimeBufferMS < 0 && frameTimeBufferMS > -9)
+        let wasUpdated = false;
+        if (engineVariableStep)
         {
-            // force at least one update each frame since it is waiting for refresh
-            deltaSmooth = frameTimeBufferMS;
-            frameTimeBufferMS = 0;
+            // one update for the frame with timeDelta the time it covers, per-frame values are the game's to scale;
+            // engineStep's frames are exactly 1/60, its first too, which has no frame before it to take a delta from
+            if (frameTimeDeltaUnscaledMS > 0 || manualStepAtStart)
+            {
+                // frozen stands still as in the fixed step, and timeDelta keeps the last update's
+                const frozenTick = paused || !combinedScale;
+                if (!frozenTick)
+                {
+                    timeDelta = manualStepAtStart ? combinedScale / frameRate :
+                        min(frameTimeDeltaUnscaledMS, 50) * combinedScale / 1e3; // clamp min framerate
+                    time += timeDelta;
+                    ++frame;
+                }
+                engineTick(frozenTick);
+            }
         }
-
-        // update multiple frames if necessary in case of slow framerate
-        for (; frameTimeBufferMS >= 0; frameTimeBufferMS -= 1e3 / frameRate)
+        else
         {
-            // read again each tick, so a pause set by the game stops the rest of this frame's catch-up ticks
-            const frozenTick = paused || !(timeScale * debugScale);
+            // paused or a time scale of 0 is frozen: it ticks on unscaled time, so the update rate stays fixed instead
+            // of following however fast the display refreshes, and gameUpdatePost and input still run to leave it
+            const frozen = paused || !combinedScale;
+            frameTimeBufferMS += frozen ? frameTimeDeltaUnscaledMS : frameTimeDeltaMS;
+            frameTimeBufferMS = min(frameTimeBufferMS, 50 * (frozen ? 1 : max(1, combinedScale))); // clamp min framerate
+
+            // apply time delta smoothing, improves smoothness of framerate in some browsers
+            let deltaSmooth = 0;
+            if (frameTimeBufferMS < 0 && frameTimeBufferMS > -9)
+            {
+                // force at least one update each frame since it is waiting for refresh
+                deltaSmooth = frameTimeBufferMS;
+                frameTimeBufferMS = 0;
+            }
 
-            // increment frame and update time, frozen does not advance time
-            if (!frozenTick)
-                time = frame++ / frameRate;
+            // update multiple frames if necessary in case of slow framerate
+            for (; frameTimeBufferMS >= 0; frameTimeBufferMS -= 1e3 / frameRate)
+            {
+                // read again each tick, so a pause set by the game stops the rest of this frame's catch-up ticks
+                const frozenTick = paused || !(timeScale * debugScale);
 
-            // update game and objects, when frozen update everything except them
+                // increment frame and update time, frozen does not advance time
+                if (!frozenTick)
+                    time = timeFixedStart + (frame++ - frameFixedStart) / frameRate;
+                engineTick(frozenTick);
+            }
+
+            // add the time smoothing back in
+            frameTimeBufferMS += deltaSmooth;
+        }
+
+        // one tick of the loop: update game and objects, when frozen update everything except them
+        function engineTick(frozenTick)
+        {
             wasUpdated = true;
             engineUpdateCanvas();
             inputUpdate();
@@ -300,9 +463,6 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
                 renderFrame();
         }
 
-        // add the time smoothing back in
-        frameTimeBufferMS += deltaSmooth;
-
         // manual step turned on by this frame's updates, set the buffer the loop and smoothing just moved again
         if (engineManualStep && !manualStepAtStart)
             frameTimeBufferMS = -.5e3 / frameRate;
@@ -361,7 +521,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     }
 
     // skip setup if headless
-    if (headlessMode) return startEngine();
+    if (headlessMode) return startEngine([]);
 
     // ensure body exists for minimal HTML where the script runs before <body> is parsed
     if (!document.body)
@@ -439,14 +599,19 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         promises.push(splash);
     }
 
-    // wait for all the promises to finish
-    await Promise.all(promises);
-    return startEngine();
+    // the splash first, the images load under it, then the loading screen for the rest
+    showSplashScreen && await promises.at(-1);
+    return startEngine(promises);
 
-    async function startEngine()
+    // 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
+    async function startEngine(images)
     {
-        // wait for gameInit to load
-        await gameInit();
+        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();
     }

package/src/engineAudio.js

@@ -281,8 +281,8 @@ class Sound
             // load the audio file, a URL object as bundlers give works like its string;
             // report failures rather than leaving an unhandled rejection, the sound just stays unloaded and silent
             const filename = asset + '';
-            this.loadSound(filename).catch(e=>
-                LOG('Sound load failed for', filename, '-', e.message));
+            engineAddLoad(this.loadSound(filename).catch(e=>
+                LOG('Sound load failed for', filename, '-', e.message))); // startup waits for it
         }
     }
 

package/src/engineBuild.mjs

@@ -49,11 +49,13 @@ const enginePluginFiles =
     `${PLUGIN_FOLDER}/drawUtilities.js`,
     `${PLUGIN_FOLDER}/textureSheet.js`,
     `${PLUGIN_FOLDER}/tweenSystem.js`,
+    `${PLUGIN_FOLDER}/sceneSystem.js`,
     `${PLUGIN_FOLDER}/pathFinder.js`,
     `${PLUGIN_FOLDER}/math3d.js`,
     `${PLUGIN_FOLDER}/render3d.js`,
     `${PLUGIN_FOLDER}/render3dExtras.js`,
     `${PLUGIN_FOLDER}/render3dVoxels.js`,
+    `${PLUGIN_FOLDER}/render3dLevel.js`,
     `${PLUGIN_FOLDER}/gltf.js`,
     `${PLUGIN_FOLDER}/threejs.js`,
 ];
@@ -63,6 +65,7 @@ const engineDebugFiles =
     `${PLUGIN_FOLDER}/tweakables.js`,
     `${PLUGIN_FOLDER}/render3dDebug.js`,
     `${SOURCE_FOLDER}/engineEditor.js`,
+    `${PLUGIN_FOLDER}/render3dEditor.js`,
 ];
 const engineExtraFiles =
 [

package/src/engineDebug.js

@@ -684,6 +684,14 @@ function debugRender()
             debugContext.fillText('9: Tweakables', x, y += h);
             debugContext.fillStyle = levelEditor.isOpen ? '#f00' : '#fff';
             debugContext.fillText('0: Edit Level', x, y += h);
+            for (const line of debugOverlayKeys)
+            {
+                // a key a debug plugin added, when it has something to say
+                const key = line();
+                if (!key) continue;
+                debugContext.fillStyle = key.on ? '#f00' : '#fff';
+                debugContext.fillText(key.text, x, y += h);
+            }
             debugContext.fillStyle = '#fff';
 
             let keysPressed = '';
@@ -910,4 +918,50 @@ function debugProtectConstant(obj)
     
     // freeze the object to prevent adding new properties
     return Object.freeze(obj);
-}
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// Input capture: the free camera and the 3D level editor take the keyboard and mouse, so the game under them reads
+// every key and mouse button as up, and no mouse movement or wheel; gamepads are left to the game
+
+let inputCaptureOn = false;      // something has taken the keyboard and mouse
+let inputCaptureReading = false; // it is reading them now
+let inputCaptureDeltaScreen, inputCaptureWheel = 0; // this update's mouse movement and wheel, for it alone
+
+// the game let go of a captured mouse itself, with pointerLockExit, since the debug tools last looked: a capture
+// that is lost without it is the browser's doing, which is how Chrome takes Escape
+let inputLockLetGo = false;
+function inputLockExit() { inputLockLetGo = true; }
+
+// the keys debug plugins add to the overlay's list, each a function that gives {text, on} or nothing to show
+const debugOverlayKeys = [];
+
+// take the keyboard and mouse from the game, or hand them back
+function inputCapture(on=true)
+{
+    inputCaptureOn = !!on;
+    inputCaptureDeltaScreen = vec2();
+    inputCaptureWheel = 0;
+}
+
+// read the input as the one that took it, keyIsDown and the rest work as always inside read
+function inputCaptureRead(read)
+{
+    const was = inputCaptureReading;
+    inputCaptureReading = true;
+    try { return read(); }
+    finally { inputCaptureReading = was; }
+}
+
+// if a read of the keyboard and mouse, device 0, is the game's while they are taken
+function inputCaptureHides(device) { return inputCaptureOn && !inputCaptureReading && !device; }
+
+// called first in inputUpdate: the mouse movement and wheel go to the one that took the input
+function inputCaptureMouse()
+{
+    if (!inputCaptureOn) return;
+    inputCaptureDeltaScreen = mouseDeltaScreen;
+    inputCaptureWheel = mouseWheel;
+    mouseDeltaScreen = vec2();
+    mouseWheel = 0;
+}

package/src/engineDraw.js

@@ -308,12 +308,20 @@ class TextureInfo
 }
 
 ///////////////////////////////////////////////////////////////////////////////
+/**
+ * @callback SpriteAnimationEndCallback - Called once when a SpriteAnimation's play ends
+ * @return {void}
+ * @memberof Draw
+ */
+
 /**
  * SpriteAnimation - Steps a tile through its frames over time: looping, once, or there and back
  * - Driven by the engine time like a Timer, so it pauses with the game and needs no update call
  * - Read tileInfo each frame for the frame to draw, from an object's update or before a drawTile
  * - loop, play and pingPong each start over from the first frame; stop holds the current one
+ * - play(onEnd) calls onEnd once the play ends, on the first read after it, since there is no update to call it
  * - Frames follow each other along the row, as tileInfo.frame counts them
+ * - SpriteAnimator switches between a character's animations by name
  * @example
  * const walk = new SpriteAnimation(tile(0, 16), 4, .1); // four frames, a tenth of a second each
  * const attack = new SpriteAnimation(tile(4, 16), 3, .05).play(); // once, then holds the last frame
@@ -345,6 +353,9 @@ class SpriteAnimation
         /** @property {number|undefined} - The frame held by stop, undefined while running
          *  @type {number|undefined} */
         this.heldFrame = undefined;
+        /** @property {SpriteAnimationEndCallback|undefined} - Called once when a play ends, on the first read after it
+         *  @type {SpriteAnimationEndCallback|undefined} */
+        this.onEnd = undefined;
     }
 
     /** Start over from the first frame and repeat forever
@@ -352,8 +363,14 @@ class SpriteAnimation
     loop() { return this.restart('loop'); }
 
     /** Start over from the first frame, run through once and hold the last frame, last to first at a negative speed
+     *  @param {function():void} [onEnd] - Called once when it ends, on the first read of it after that
      *  @return {SpriteAnimation} */
-    play() { return this.restart('once'); }
+    play(onEnd)
+    {
+        this.restart('once');
+        this.onEnd = onEnd;
+        return this;
+    }
 
     /** Start over from the first frame and run there and back forever
      *  @return {SpriteAnimation} */
@@ -363,7 +380,7 @@ class SpriteAnimation
      *  @return {SpriteAnimation} */
     stop() { this.heldFrame = this.frame; return this; }
 
-    /** Start over from the first frame in a mode
+    /** Start over from the first frame in a mode, with no end callback
      *  @param {string} [mode] - 'loop', 'once' or 'pingPong', the current mode when left out
      *  @return {SpriteAnimation} */
     restart(mode=this.mode)
@@ -371,6 +388,7 @@ class SpriteAnimation
         this.mode = mode;
         this.startTime = time;
         this.heldFrame = undefined;
+        this.onEnd = undefined;
         return this;
     }
 
@@ -382,6 +400,7 @@ class SpriteAnimation
      *  @return {number} */
     get frame()
     {
+        this.isDone; // a read after a play ends calls onEnd, which may start it over
         if (this.heldFrame !== undefined)
             return this.heldFrame;
         const n = this.frameCount, f = floor(this.elapsedFrames);
@@ -397,9 +416,81 @@ class SpriteAnimation
      *  @return {TileInfo} */
     get tileInfo() { return this.firstTile.frame(this.frame); }
 
-    /** True once a play has shown its last frame for its time
+    /** True once a play has shown its last frame for its time, the first read after that calls onEnd
      *  @return {boolean} */
-    get isDone() { return this.mode == 'once' && this.heldFrame === undefined && abs(this.elapsedFrames) >= this.frameCount; }
+    get isDone()
+    {
+        const done = this.mode == 'once' && this.heldFrame === undefined && abs(this.elapsedFrames) >= this.frameCount;
+        if (done && this.onEnd)
+        {
+            const onEnd = this.onEnd;
+            this.onEnd = undefined; // once, and it can start a new play with a callback of its own
+            onEnd();
+        }
+        return done;
+    }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * SpriteAnimator - A character's animations by name, like idle, walk and attack, and the one showing now
+ * - Each clip is a SpriteAnimation and keeps its own mode, loop, play or pingPong
+ * - set starts a clip over only when it changes or a play of it has ended, so it can be called every update
+ * - Read tileInfo each frame for the frame to draw, as with a SpriteAnimation
+ * @example
+ * const hero = new SpriteAnimator({
+ *     idle:   new SpriteAnimation(tile(0, 16), 2, .4),
+ *     walk:   new SpriteAnimation(tile(2, 16), 4, .1),
+ *     attack: new SpriteAnimation(tile(6, 16), 3, .05).play(),
+ * });
+ * hero.set('attack', ()=> hero.set('idle')); // back to idle when the attack ends
+ * // in update: this.tileInfo = hero.tileInfo;
+ * @memberof Draw
+ */
+class SpriteAnimator
+{
+    /** Create an animator from its clips, showing the first one
+     *  @param {Object<string, SpriteAnimation>} clips - The clips by name */
+    constructor(clips)
+    {
+        const names = Object.keys(clips);
+        ASSERT(names.length > 0, 'an animator needs at least one clip');
+        /** @property {Object<string, SpriteAnimation>} - The clips by name */
+        this.clips = clips;
+        /** @property {string} - The name of the clip showing now */
+        this.name = names[0];
+    }
+
+    /** Show a clip, starting it over in its own mode unless it is showing and has not ended
+     *  @param {string} name - The clip's name
+     *  @param {function():void} [onEnd] - Called once when a play clip ends, as with SpriteAnimation.play
+     *  @return {SpriteAnimator} */
+    set(name, onEnd)
+    {
+        ASSERT(this.clips[name], 'no clip named ' + name);
+        if (name == this.name && !this.clip.isDone)
+            return this;
+        this.name = name;
+        this.clip.restart();
+        this.clip.onEnd = onEnd;
+        return this;
+    }
+
+    /** The clip showing now
+     *  @return {SpriteAnimation} */
+    get clip() { return this.clips[this.name]; }
+
+    /** The tile of the frame showing now
+     *  @return {TileInfo} */
+    get tileInfo() { return this.clip.tileInfo; }
+
+    /** The frame of the clip showing now
+     *  @return {number} */
+    get frame() { return this.clip.frame; }
+
+    /** True once the clip showing now is a play that has ended
+     *  @return {boolean} */
+    get isDone() { return this.clip.isDone; }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -1224,7 +1315,7 @@ async function loadTexture(textureIndex, src)
     const image = new Image;
     if (src)
     {
-        await new Promise(resolve =>
+        await engineAddLoad(new Promise(resolve => // startup waits for it
         {
             image.onload = resolve;
             image.onerror = ()=>
@@ -1234,7 +1325,7 @@ async function loadTexture(textureIndex, src)
             };
             image.crossOrigin = 'anonymous';
             image.src = src;
-        });
+        }));
     }
     
     return textureInfos[textureIndex] = new TextureInfo(image);