littlejsengine 1.18.23 → 1.18.25

package/README.md

@@ -23,6 +23,8 @@ The code is very clean and well documented with many examples to get you started
 
 *The Third Annual LittleJS Game Jam will take place From Oct 2 to Nov 2! Unleash your creativity and develop amazing games using the LittleJS game engine.*
 
+### 😼👍 [LittleJS + JS13k](https://github.com/KilledByAPixel/LittleJS/tree/js13k) - We made a special branch designed for size coding events like JS13k.
+
 <div align='center' markdown='1'>
 
 ## [Demos](https://killedbyapixel.github.io/LittleJS/examples) | [Arcade](https://killedbyapixel.github.io/LittleJSArcade) | [Docs](https://killedbyapixel.github.io/LittleJS/docs) | [FAQ](https://github.com/KilledByAPixel/LittleJS/blob/main/FAQ.md) | [Trailer](https://youtu.be/chuBzGjv7Ms) | [Discord](https://discord.gg/zb7hcGkyZe)
@@ -38,6 +40,7 @@ The code is very clean and well documented with many examples to get you started
 - Blazing fast WebGL2 + Canvas2D hybrid rendering system
 - Apply [Shadertoy](https://www.shadertoy.com) style shaders for post-processing effects
 - Robust particle effect system and [effect design tool](https://killedbyapixel.github.io/LittleJS/examples/particles/)
+- Load sprites and animations into texture sheets at runtime, or import [TexturePacker](https://www.codeandweb.com/texturepacker) and [Aseprite](https://www.aseprite.org) atlases
 - Optional 3D rendering with the [Three.js](https://threejs.org) plugin
 
 ### 🔊 Audio

package/dist/littlejs.d.ts

@@ -146,6 +146,17 @@ declare module "littlejsengine" {
      *  );
      *  @memberof Engine */
     export function engineInit(gameInit: GameInitCallback, gameUpdate: GameCallback, gameUpdatePost: GameCallback, gameRender: GameCallback, gameRenderPost: GameCallback, imageSources?: Array<string>, rootElement?: HTMLElement): Promise<void>;
+    /** 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 */
+    export function engineStep(frames?: number): void;
     /** 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 */
@@ -417,6 +428,12 @@ declare module "littlejsengine" {
      *  @default
      *  @memberof Settings */
     export let headlessMode: boolean;
+    /** 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 */
+    export let engineManualStep: boolean;
     /** Default size of tiles in pixels
      *  @type {Vector2}
      *  @default Vector2(16,16)
@@ -690,6 +707,11 @@ declare module "littlejsengine" {
      *  @param {boolean} headless
      *  @memberof Settings */
     export function setHeadlessMode(headless: boolean): void;
+    /** Set if the engine only advances when engineStep is called
+     *  Must be set before engineInit
+     *  @param {boolean} [enable]
+     *  @memberof Settings */
+    export function setEngineManualStep(enable?: boolean): void;
     /** Set if WebGL rendering is enabled
      *  @param {boolean} enable
      *  @memberof Settings */
@@ -1087,7 +1109,7 @@ declare module "littlejsengine" {
     export function shareURL(title: string, url: string, callback?: Function): void;
     /** 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 */
     export function readSaveData(saveName: string, defaultSaveData?: any): any;
@@ -5841,15 +5863,15 @@ declare module "littlejsengine" {
          *  @param {Vector2} imageSize - Size of the source image in pixels
          *  @param {Vector2} [frameSize] - Size of each frame, or the whole image if not passed
          *  @param {number} [padding] - How many pixels padding around each frame
-         *  @param {number} [sourcePadding] - How many pixels padding around each frame in the source image
+         *  @param {number|Vector2} [sourcePadding] - How many pixels padding around each frame in the source image
          *  @return {TileInfo} Tile for the packed image, or undefined if the sheet is full */
-        tryAdd(imageSize: Vector2, frameSize?: Vector2, padding?: number, sourcePadding?: number): TileInfo;
+        tryAdd(imageSize: Vector2, frameSize?: Vector2, padding?: number, sourcePadding?: number | Vector2): TileInfo;
         /** Draw an image into this sheet at a tile returned by tryAdd
          *  @param {HTMLImageElement} image - Source image to copy from
          *  @param {TileInfo} tileInfo - Where to put it, from tryAdd
          *  @param {boolean} [update] - Upload to webgl now, pass false when batching
-         *  @param {number} [sourcePadding] - How many pixels padding around each frame in the source image */
-        drawImage(image: HTMLImageElement, tileInfo: TileInfo, update?: boolean, sourcePadding?: number): void;
+         *  @param {number|Vector2} [sourcePadding] - How many pixels padding around each frame in the source image */
+        drawImage(image: HTMLImageElement, tileInfo: TileInfo, update?: boolean, sourcePadding?: number | Vector2): void;
         /** Upload the canvas to webgl if it has changed since the last upload
          *  Only needed after batching, drawImage uploads automatically by default */
         updateTexture(): void;
@@ -5863,13 +5885,13 @@ declare module "littlejsengine" {
      *  @param {string} src - Image source path
      *  @param {Vector2|number} [frameSize] - Size of each animation frame in pixels
      *  @param {number} [padding] - How many pixels padding around each frame
-     *  @param {number} [sourcePadding] - How many pixels padding around each frame in the source image
+     *  @param {number|Vector2} [sourcePadding] - How many pixels padding around each frame in the source image
      *  @return {TileInfo}
      *  @example
      *  const playerTile = loadSprite('player.png');     // a single sprite
      *  const runTile = loadSprite('run.png', vec2(16)); // a 16x16 frame animation
      *  @memberof TextureSheets */
-    export function loadSprite(src: string, frameSize?: Vector2 | number, padding?: number, sourcePadding?: number): TileInfo;
+    export function loadSprite(src: string, frameSize?: Vector2 | number, padding?: number, sourcePadding?: number | Vector2): TileInfo;
     /** Load a pre-packed texture atlas and repack it onto texture sheets
      *  - Supports TexturePacker json (hash and array) and Aseprite json
      *  - Returns an empty object which is filled with TileInfos when loaded

package/dist/littlejs.esm.js

@@ -35,7 +35,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.18.23';
+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 */
@@ -2688,12 +2720,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
@@ -2717,7 +2754,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); }
@@ -2885,6 +2922,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
 
@@ -3235,6 +3279,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 */
@@ -14998,17 +15048,21 @@ class TextureSheet
      *  @param {Vector2} imageSize - Size of the source image in pixels
      *  @param {Vector2} [frameSize] - Size of each frame, or the whole image if not passed
      *  @param {number} [padding] - How many pixels padding around each frame
-     *  @param {number} [sourcePadding] - How many pixels padding around each frame in the source image
+     *  @param {number|Vector2} [sourcePadding] - How many pixels padding around each frame in the source image
      *  @return {TileInfo} Tile for the packed image, or undefined if the sheet is full */
     tryAdd(imageSize, frameSize=imageSize, padding=textureSheetPadding, sourcePadding=0)
     {
         ASSERT(isVector2(imageSize) && isVector2(frameSize), 'sizes must be vec2');
         ASSERT(frameSize.x > 0 && frameSize.y > 0, 'frame size must be positive');
-        ASSERT(isNumber(sourcePadding) && sourcePadding >= 0, 'sourcePadding must be a number >= 0');
+
+        if (isNumber(sourcePadding))
+            sourcePadding = vec2(sourcePadding);
+        ASSERT(isVector2(sourcePadding) && sourcePadding.x >= 0 && sourcePadding.y >= 0,
+            'sourcePadding must be a number or vec2 >= 0');
 
         // the source may have its own padding baked in around each frame
-        const sourceCellWidth = frameSize.x + sourcePadding*2;
-        const sourceCellHeight = frameSize.y + sourcePadding*2;
+        const sourceCellWidth = frameSize.x + sourcePadding.x*2;
+        const sourceCellHeight = frameSize.y + sourcePadding.y*2;
         ASSERT(imageSize.x % sourceCellWidth === 0 && imageSize.y % sourceCellHeight === 0,
             'image size must be a multiple of the padded frame size');
 
@@ -15050,16 +15104,19 @@ class TextureSheet
      *  @param {HTMLImageElement} image - Source image to copy from
      *  @param {TileInfo} tileInfo - Where to put it, from tryAdd
      *  @param {boolean} [update] - Upload to webgl now, pass false when batching
-     *  @param {number} [sourcePadding] - How many pixels padding around each frame in the source image */
+     *  @param {number|Vector2} [sourcePadding] - How many pixels padding around each frame in the source image */
     drawImage(image, tileInfo, update=true, sourcePadding=0)
     {
         ASSERT(!!this.context, 'texture sheet has no canvas');
 
+        if (isNumber(sourcePadding))
+            sourcePadding = vec2(sourcePadding);
+
         // copy frames in order, reading the source left to right, top to bottom
         // the destination wraps at tileInfo.columns which may be narrower than the source
         const frameSize = tileInfo.size;
-        const sourceCellWidth = frameSize.x + sourcePadding*2;
-        const sourceCellHeight = frameSize.y + sourcePadding*2;
+        const sourceCellWidth = frameSize.x + sourcePadding.x*2;
+        const sourceCellHeight = frameSize.y + sourcePadding.y*2;
         const sourceColumns = image.width / sourceCellWidth;
         const frameCount = sourceColumns * (image.height / sourceCellHeight);
         const columns = tileInfo.columns || frameCount;
@@ -15067,8 +15124,8 @@ class TextureSheet
         const cellHeight = frameSize.y + tileInfo.padding*2;
         for (let i = frameCount; i--;)
         {
-            const sourceX = (i % sourceColumns) * sourceCellWidth + sourcePadding;
-            const sourceY = (i / sourceColumns | 0) * sourceCellHeight + sourcePadding;
+            const sourceX = (i % sourceColumns) * sourceCellWidth + sourcePadding.x;
+            const sourceY = (i / sourceColumns | 0) * sourceCellHeight + sourcePadding.y;
             this.context.drawImage(image,
                 sourceX, sourceY, frameSize.x, frameSize.y,
                 tileInfo.pos.x + (i % columns) * cellWidth,
@@ -15102,7 +15159,7 @@ class TextureSheet
  *  @param {string} src - Image source path
  *  @param {Vector2|number} [frameSize] - Size of each animation frame in pixels
  *  @param {number} [padding] - How many pixels padding around each frame
- *  @param {number} [sourcePadding] - How many pixels padding around each frame in the source image
+ *  @param {number|Vector2} [sourcePadding] - How many pixels padding around each frame in the source image
  *  @return {TileInfo}
  *  @example
  *  const playerTile = loadSprite('player.png');     // a single sprite
@@ -15113,6 +15170,7 @@ function loadSprite(src, frameSize, padding=textureSheetPadding, sourcePadding=0
     ASSERT(isStringLike(src), 'image src must be a string');
     ASSERT(!frameSize || isVector2(frameSize) || isNumber(frameSize), 'frameSize must be a vec2 or number');
     ASSERT(isNumber(padding), 'padding must be a number');
+    ASSERT(isNumber(sourcePadding) || isVector2(sourcePadding), 'sourcePadding must be a number or vec2');
 
     if (isNumber(frameSize))
         frameSize = vec2(frameSize);
@@ -16863,6 +16921,7 @@ export
     getPaused,
     setPaused,
     engineInit,
+    engineStep,
     engineObjectsUpdate,
     engineObjectsDestroy,
     engineObjectsCollect,
@@ -16910,6 +16969,7 @@ export
     fontDefault,
     showSplashScreen,
     headlessMode,
+    engineManualStep,
     tileDefaultSize,
     tileDefaultPadding,
     tileDefaultBleed,
@@ -16964,6 +17024,7 @@ export
     setFontDefault,
     setShowSplashScreen,
     setHeadlessMode,
+    setEngineManualStep,
     setGLEnable,
     setTileDefaultSize,
     setTileDefaultPadding,