littlejsengine 1.18.22 → 1.18.24

package/dist/littlejs.release.js

@@ -35,7 +35,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.18.22';
+const engineVersion = '1.18.24';
 
 /** Frames per second to update
  *  @type {number}
@@ -14307,13 +14307,23 @@ 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|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)
+    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(imageSize.x % frameSize.x === 0 && imageSize.y % frameSize.y === 0,
-            'image size must be a multiple of the frame size');
+
+        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.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');
 
         const cellWidth = frameSize.x + padding*2;
         const cellHeight = frameSize.y + padding*2;
@@ -14322,8 +14332,8 @@ class TextureSheet
 
         // keep the layout of the source image, but narrow it if a row is too wide
         // frames wrap down to the next row, which TileInfo.frame handles via columns
-        const sourceColumns = imageSize.x / frameSize.x;
-        const frameCount = sourceColumns * (imageSize.y / frameSize.y);
+        const sourceColumns = imageSize.x / sourceCellWidth;
+        const frameCount = sourceColumns * (imageSize.y / sourceCellHeight);
         const columns = min(sourceColumns, maxColumns);
         const blockWidth = columns * cellWidth;
         const blockHeight = ceil(frameCount / columns) * cellHeight;
@@ -14352,23 +14362,29 @@ class TextureSheet
     /** 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 */
-    drawImage(image, tileInfo, update=true)
+     *  @param {boolean} [update] - Upload to webgl now, pass false when batching
+     *  @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 sourceColumns = image.width / frameSize.x;
-        const frameCount = sourceColumns * (image.height / frameSize.y);
+        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;
         const cellWidth = frameSize.x + tileInfo.padding*2;
         const cellHeight = frameSize.y + tileInfo.padding*2;
         for (let i = frameCount; i--;)
         {
-            const sourceX = (i % sourceColumns) * frameSize.x;
-            const sourceY = (i / sourceColumns | 0) * frameSize.y;
+            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,
@@ -14398,19 +14414,22 @@ class TextureSheet
  *  - Nothing is visible until it loads, use spritesReady to wait for it
  *  - Pass frameSize for animations, then step through them with TileInfo.frame
  *  - Grid images keep their layout and frames wrap down to the next row
+ *  - Pass sourcePadding if the source image has padding baked in around frames
  *  @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|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 */
-function loadSprite(src, frameSize, padding=textureSheetPadding)
+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);
@@ -14441,9 +14460,9 @@ function loadSprite(src, frameSize, padding=textureSheetPadding)
             // pack onto a sheet, then fill in the tile that was already handed out,
             // copying every field so nothing is missed if TileInfo gains more of them
             const imageSize = vec2(image.width, image.height);
-            const {sheet, tile} = textureSheetAdd(imageSize, frameSize, padding);
+            const {sheet, tile} = textureSheetAdd(imageSize, frameSize, padding, sourcePadding);
             Object.assign(tileInfo, tile);
-            sheet.drawImage(image, tileInfo, false); // upload once per batch below
+            sheet.drawImage(image, tileInfo, false, sourcePadding); // upload once per batch below
         }
         else
         {
@@ -14644,16 +14663,16 @@ function textureSheetCreate()
 }
 
 // use the first sheet with enough space, or make a new one
-function textureSheetAdd(imageSize, frameSize, padding)
+function textureSheetAdd(imageSize, frameSize, padding, sourcePadding)
 {
     let sheet, tile;
     for (sheet of textureSheets)
-        if (tile = sheet.tryAdd(imageSize, frameSize, padding))
+        if (tile = sheet.tryAdd(imageSize, frameSize, padding, sourcePadding))
             break;
     if (!tile)
     {
         sheet = textureSheetCreate();
-        tile = sheet.tryAdd(imageSize, frameSize, padding);
+        tile = sheet.tryAdd(imageSize, frameSize, padding, sourcePadding);
         ASSERT(!!tile, 'image is too large to fit on a texture sheet');
     }
     return {sheet, tile};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "littlejsengine",
-  "version": "1.18.22",
+  "version": "1.18.24",
   "description": "LittleJS - Tiny and Fast HTML5 Game Engine",
   "main": "dist/littlejs.esm.js",
   "types": "dist/littlejs.d.ts",

package/plugins/textureSheet.js

@@ -73,13 +73,23 @@ 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|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)
+    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(imageSize.x % frameSize.x === 0 && imageSize.y % frameSize.y === 0,
-            'image size must be a multiple of the frame size');
+
+        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.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');
 
         const cellWidth = frameSize.x + padding*2;
         const cellHeight = frameSize.y + padding*2;
@@ -88,8 +98,8 @@ class TextureSheet
 
         // keep the layout of the source image, but narrow it if a row is too wide
         // frames wrap down to the next row, which TileInfo.frame handles via columns
-        const sourceColumns = imageSize.x / frameSize.x;
-        const frameCount = sourceColumns * (imageSize.y / frameSize.y);
+        const sourceColumns = imageSize.x / sourceCellWidth;
+        const frameCount = sourceColumns * (imageSize.y / sourceCellHeight);
         const columns = min(sourceColumns, maxColumns);
         const blockWidth = columns * cellWidth;
         const blockHeight = ceil(frameCount / columns) * cellHeight;
@@ -118,23 +128,29 @@ class TextureSheet
     /** 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 */
-    drawImage(image, tileInfo, update=true)
+     *  @param {boolean} [update] - Upload to webgl now, pass false when batching
+     *  @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 sourceColumns = image.width / frameSize.x;
-        const frameCount = sourceColumns * (image.height / frameSize.y);
+        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;
         const cellWidth = frameSize.x + tileInfo.padding*2;
         const cellHeight = frameSize.y + tileInfo.padding*2;
         for (let i = frameCount; i--;)
         {
-            const sourceX = (i % sourceColumns) * frameSize.x;
-            const sourceY = (i / sourceColumns | 0) * frameSize.y;
+            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,
@@ -164,19 +180,22 @@ class TextureSheet
  *  - Nothing is visible until it loads, use spritesReady to wait for it
  *  - Pass frameSize for animations, then step through them with TileInfo.frame
  *  - Grid images keep their layout and frames wrap down to the next row
+ *  - Pass sourcePadding if the source image has padding baked in around frames
  *  @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|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 */
-function loadSprite(src, frameSize, padding=textureSheetPadding)
+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);
@@ -207,9 +226,9 @@ function loadSprite(src, frameSize, padding=textureSheetPadding)
             // pack onto a sheet, then fill in the tile that was already handed out,
             // copying every field so nothing is missed if TileInfo gains more of them
             const imageSize = vec2(image.width, image.height);
-            const {sheet, tile} = textureSheetAdd(imageSize, frameSize, padding);
+            const {sheet, tile} = textureSheetAdd(imageSize, frameSize, padding, sourcePadding);
             Object.assign(tileInfo, tile);
-            sheet.drawImage(image, tileInfo, false); // upload once per batch below
+            sheet.drawImage(image, tileInfo, false, sourcePadding); // upload once per batch below
         }
         else
         {
@@ -410,16 +429,16 @@ function textureSheetCreate()
 }
 
 // use the first sheet with enough space, or make a new one
-function textureSheetAdd(imageSize, frameSize, padding)
+function textureSheetAdd(imageSize, frameSize, padding, sourcePadding)
 {
     let sheet, tile;
     for (sheet of textureSheets)
-        if (tile = sheet.tryAdd(imageSize, frameSize, padding))
+        if (tile = sheet.tryAdd(imageSize, frameSize, padding, sourcePadding))
             break;
     if (!tile)
     {
         sheet = textureSheetCreate();
-        tile = sheet.tryAdd(imageSize, frameSize, padding);
+        tile = sheet.tryAdd(imageSize, frameSize, padding, sourcePadding);
         ASSERT(!!tile, 'image is too large to fit on a texture sheet');
     }
     return {sheet, tile};

package/src/engine.js

@@ -32,7 +32,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.18.22';
+const engineVersion = '1.18.24';
 
 /** Frames per second to update
  *  @type {number}