littlejsengine 1.24.0 → 1.24.1

package/CHANGELOG.md

@@ -7,6 +7,28 @@ What changed in each release, newest first. Releases before 1.20.0 are on the
 
 Nothing yet.
 
+## 1.24.1 - 2026-10-02
+
+### New Changes
+
+- A VoxelMap block type can be `doubleSided`, its faces shown from inside the block too, so the surface of water shows from under it
+- 3D Voxels: the player goes under water and walks on the bottom, in place of floating at the surface
+- `tileLayersLoad`'s `collisionLayer` may be a layer's name
+- `light.addFlare` takes the flare's color too
+- LDtk: an IntGrid layer is always a hidden layer of its values under its own name, its rule tiles in layers over it named with tiles, so `tileLayersLoad(map, tileInfo, 0, 'Collisions')` is solid where the values say, whatever the tiles stack or fade; a project of several worlds loads; a project with no tileset entry keeps its tiles
+- The example browser has a new look, in the dark colors of the docs site: a slim top bar in place of the title, the demo at 16:9, and the example list as rows under their headings. A handle between the code and its write-up drags to give one the other's space, by touch and the arrow keys too, and is remembered; a double click puts the quarter back. On a phone the example's name, between Prev and Next, opens a full screen picker with the search. The Screenshot button is gone
+
+### Fixes
+
+- Box2D: `addRegularPoly` with a side count that is not a whole number no longer hangs, as the engine's own polygons do not since 1.23.1
+- The level editor's tile palette no longer asserts on a Tiled tileset with a margin or a spacing
+- LDtk: a see-through tile keeps its opacity, in a layer of its own; a layer whose tileset is another size is left out with a warning, in place of being read as stacks; a missing level says so in release builds too
+- A Tiled tileset's margin and spacing count from where the game's sheet starts, so a sheet inside an atlas keeps its place
+- 2D level editor: applying an autosave of another size leaves an object layer it does not know about as the file has it, and an autosave whose tiles do not fit its size no longer resizes the map
+- A light's lens flare is hidden by a room or a level mesh around it, seen from outside: only a lamp, a mesh around the light no wider than half its radius, is passed by
+- Example browser: Enter on a focused example selects it, a heading named in a write-up is no longer a link that does nothing, blocked or broken saved preferences no longer stop the page, and the handle drags with the main button only
+- 3D level editor: a broken autosave no longer blocks every edit until Drop, and one older than the last edits, which storage had no room for, says so as the 2D editor does
+
 ## 1.24.0 - 2026-10-02
 
 ### New Demos
@@ -23,7 +45,7 @@ Nothing yet.
 - Lens flares in the 3D level editor: a level's Light has a `lensFlare` property, and the Scene box has a Lens flare checkbox for the sun's, saved in the level's scene block
 - Lens flares have three more shapes, `hex`, `streak` and `star`; `flare.shapes` says what the ghosts are picked from, `glowSize` and `ghostSize` scale its parts, and an element may be a tile of the game's own (`tileInfo`), turned (`angle`) and wider than tall
 - 3D picking is triangle accurate: `render3D.pick`, `engineObjectsRaycast3D` and clicks in the 3D level editor hit a mesh on its triangles, not the box around it
-- LDtk levels load: `tileLayersFromLDtk(ldtk, level)` makes a level of an LDtk project a Tiled map for `tileLayersLoad` and `objectLayersLoad`, with its tile, auto and IntGrid layers, its entities as objects and their fields as properties
+- LDtk levels load: `tileLayersFromLDtk(ldtk, level)` makes a level of an LDtk project a Tiled map for `tileLayersLoad` and `objectLayersLoad`, with its tile, auto and IntGrid layers, tiles stacked in a cell and see-through tiles, its entities as objects and their fields as properties
 - A Tiled tileset with a margin or a spacing, a sheet with gaps between its tiles, is read where its tiles are
 - The 3D Example has lens flares, on the sun and on each orb
 - CHANGELOG.md lists what changed in each release, and the site's root goes to the example browser
@@ -64,6 +86,11 @@ Nothing yet.
 - A `Sound` made while sound is off counts as loaded, so a loading screen that waits for sounds finishes
 - A tween callback that throws no longer leaves the tween system allocating on every update
 - The build and the docs build leave `dist/` and `docs/` untouched when a step fails
+- A `Timer` set to a time below zero reads as done
+- `UIVideo` lets go of its video when it is destroyed
+- A texture atlas tag with no frames no longer drops the groups after it
+- `setAdditiveBlendMode` works in headless mode
+- The release build's `levelEditor` has `keys`, `buttons` and `tools`, as the debug one does
 
 ## 1.23.0 - 2026-10-01
 

package/README.md

@@ -105,7 +105,7 @@ The code is very clean and well documented with many examples to get you started
 
 ## How To Use LittleJS
 
-To get started download the latest LittleJS package from GitHub or install via npm: 
+To get started download the latest release from GitHub, the engine's builds and source as npm has them (the examples are in the repository), or install via npm: 
 
 ```
 npm install littlejsengine

package/REFERENCE.md

@@ -717,7 +717,8 @@ tileCollisionRaycast(posStart, posEnd, object, normal, solidOnly=true) // Where
                                                     // or undefined; a normal vec2 passed in is set to the surface's
 tileCollisionLayers                                 // List of all tile collision layers
 tileLayersLoad(tileMapData, tileInfo=tile(), renderOrder=0, collisionLayer, draw=true) // collisionLayer is the index
-                                                    // of the layer that gets collision, no tile when no image is loaded
+                                                    // or the name of the layer that gets collision, no tile when no
+                                                    // image is loaded
                                                     // Load tile layers from exported data, Tiled flips and turns included;
                                                     // groups are flattened and layer indices count that flat list,
                                                     // hidden layers load with collision but are not drawn; a
@@ -725,8 +726,10 @@ tileLayersLoad(tileMapData, tileInfo=tile(), renderOrder=0, collisionLayer, draw
                                                     // its tiles are
 tileLayersFromLDtk(ldtk, level=0)                   // A Tiled map of an LDtk level, by index or identifier, to give
                                                     // tileLayersLoad and objectLayersLoad: its layers bottom first, an
-                                                    // IntGrid layer with no tiles a hidden layer for collision, tiles
-                                                    // stacked in a cell in layers above, named (2), (3); its entities
+                                                    // IntGrid layer a hidden layer of its values under its name, for
+                                                    // collisionLayer, its rule tiles over it as name tiles, tiles
+                                                    // stacked in a cell in layers above, named (2), (3), and a
+                                                    // see-through tile in a layer of its opacity; its entities
                                                     // objects with their fields as properties
 objectLayersAddType(name, make, defaults={}, tileInfo) // Name a type of object in a Tiled map: a class made
                                                     // with new make(pos), or an arrow function called make(pos),
@@ -1755,7 +1758,7 @@ flare.elements = [{at: .5, size: .1, color: hsl(.6,1,.6,.3), shape: 'disc'}] //
                                   // tileInfo for a tile of your own; angle turns it
 flare.visible                     // how much of the sun shows, 0 to 1, eased over fadeTime, to read; what is not
                                   // see through hides it, flare.occlusion = false turns that off
-light.addFlare(size, count, intensity, saturation) // gives a Light3D a flare of its own and returns it: at the
+light.addFlare(size, count, intensity, saturation, color) // gives a Light3D a flare of its own and returns it: at the
                                   // light, in its color, smaller from farther than its radius, hidden by what is
                                   // in front of it, a spotlight's only from inside its beam
 light.flare                       // the light's LensFlare3D, its child, or undefined; set one of your own, and

package/dist/littlejs.d.ts

@@ -4282,30 +4282,35 @@ declare module "littlejsengine" {
      *  @param {Object}   tileMapData - Level data from exported data
      *  @param {TileInfo} [tileInfo] - Default tile info (used for size and texture), tile() by default, none when no image is loaded
      *  @param {number}   [renderOrder] - Render order of the top layer
-     *  @param {number}   [collisionLayer] - Layer to use for collision if any
+     *  @param {number|string} [collisionLayer] - Layer to use for collision if any, by its index or its name
      *  @param {boolean}  [draw] - Should the layer be drawn automatically
      *  @return {Array<TileCollisionLayer>}
      *  @memberof TileLayers */
-    export function tileLayersLoad(tileMapData: any, tileInfo?: TileInfo, renderOrder?: number, collisionLayer?: number, draw?: boolean): Array<TileCollisionLayer>;
+    export function tileLayersLoad(tileMapData: any, tileInfo?: TileInfo, renderOrder?: number, collisionLayer?: number | string, draw?: boolean): Array<TileCollisionLayer>;
     /**
      * Make a Tiled map of a level of an LDtk project, to load with tileLayersLoad and objectLayersLoad
-     * - Each Tiles, AutoLayer and IntGrid layer is a tile layer, the bottom one first as in Tiled, so the last layer
-     *   of the LDtk file is layer 0; where LDtk stacks tiles in a cell, an edge over a fill, each tile over another
-     *   goes in a layer of its own just above, named with (2), (3) and so on, so a layer of the first tiles has one
-     *   wherever the LDtk layer has any, which makes it the one for collision
-     * - An IntGrid layer with no tiles is a hidden layer of its values, for collision: pass its index as collisionLayer
+     * - Each Tiles, AutoLayer and IntGrid layer is a tile layer, the bottom one first as in Tiled; where LDtk stacks
+     *   tiles in a cell, an edge over a fill, each tile over another goes in a layer of its own just above, named with
+     *   (2), (3) and so on, and a tile LDtk draws see-through goes in one of its own with that opacity, times the
+     *   layer's, named with it, like Ground .25
+     * - An IntGrid layer is a hidden layer of its values under its own name, for collision, whatever tiles its rules
+     *   make, which are layers over it named with tiles, like Collisions tiles; pass the name as collisionLayer, since
+     *   the stacked and see-through layers change the indices from level to level:
+     *   tileLayersLoad(map, tile(0, 16), 0, 'Collisions')
      * - An Entities layer is an object layer: an entity's name is its type for objectLayersAddType, it is placed at
      *   its middle, and its Int, Float, Bool, String, Color and FilePath fields are its properties (an enum is a string)
      * - The tileset is the first tile layer's, with its padding and spacing; give tileLayersLoad a tile info of its image
      * - The level is in the project file (not saved as separate level files), its layers of one grid size; a layer of
-     *   another grid size or another tileset is left out, with a warning in debug builds
+     *   another grid size or another tileset is left out, with a warning in debug builds, and a project with no tileset
+     *   keeps its tiles for the tile info the game gives; a project of several worlds has its levels counted in order
+     * - Layer offsets are not read
      * - The level editor edits the map this returns, and saves it as a Tiled map
      * @param {Object} ldtk - The LDtk project, its JSON
      * @param {number|string} [level] - Which level, by its index or its identifier
      * @return {Object} - A Tiled map: width, height, tilewidth, tileheight, tilesets and layers
      * @example
      * const map = tileLayersFromLDtk(await fetchJSON('world.ldtk'), 'Level_0');
-     * const layers = tileLayersLoad(map, tile(0, 16), 0, 1); // layer 1 is solid
+     * const layers = tileLayersLoad(map, tile(0, 16), 0, 'Collisions'); // its IntGrid layer is solid
      * objectLayersLoad(map);
      * @memberof TileLayers */
     export function tileLayersFromLDtk(ldtk: any, level?: number | string): any;
@@ -9721,11 +9726,12 @@ declare module "littlejsengine" {
         /** @type {Array<Vector3>} */
         chunkCenters: Array<Vector3>;
         chunksChanged: Set<any>;
-        /** @type {Array<{faces: Array<number>, seeThrough: boolean, transparent: boolean}|undefined>} */
+        /** @type {Array<{faces: Array<number>, seeThrough: boolean, transparent: boolean, doubleSided: boolean}|undefined>} */
         blockTypes: Array<{
             faces: Array<number>;
             seeThrough: boolean;
             transparent: boolean;
+            doubleSided: boolean;
         } | undefined>;
         tiles: Map<any, any>;
         /** The block type at a cell, 0 for empty or outside the map
@@ -9753,25 +9759,28 @@ declare module "littlejsengine" {
          *  @param {number} type - 1 to 255
          *  @param {number|Array<number>|{top?: number, side: number, bottom?: number}} faces - A tile index for every face,
          *    six in the order +x, -x, +y, -y, +z, -z, or the side's with the top and bottom's, which default to the side's
-         *  @param {{seeThrough?: boolean, transparent?: boolean}} [options] - seeThrough for holes in its texture, like
-         *    leaves, so the blocks beside it keep their faces; transparent to blend, like glass or water, drawn in the
-         *    transparent stage, and see-through too */
+         *  @param {{seeThrough?: boolean, transparent?: boolean, doubleSided?: boolean}} [options] - seeThrough for holes
+         *    in its texture, like leaves, so the blocks beside it keep their faces; transparent to blend, like glass or
+         *    water, drawn in the transparent stage, and see-through too; doubleSided for faces seen from inside the
+         *    block as well, like water, whose surface then shows from under it */
         setBlockType(type: number, faces: number | Array<number> | {
             top?: number;
             side: number;
             bottom?: number;
-        }, { seeThrough, transparent }?: {
+        }, { seeThrough, transparent, doubleSided }?: {
             seeThrough?: boolean;
             transparent?: boolean;
+            doubleSided?: boolean;
         }): void;
         /** A block type's faces and how it is seen through
          *  @param {number} type
-         *  @return {{faces: Array<number>, seeThrough: boolean, transparent: boolean}}
+         *  @return {{faces: Array<number>, seeThrough: boolean, transparent: boolean, doubleSided: boolean}}
          *  @ignore */
         blockType(type: number): {
             faces: Array<number>;
             seeThrough: boolean;
             transparent: boolean;
+            doubleSided: boolean;
         };
         /** Build every chunk again, after changing data directly or ambientOcclusion */
         rebuild(): void;
@@ -9883,8 +9892,9 @@ declare module "littlejsengine" {
          *  @param {number} [count] - How many ghosts there are, besides the glow at the light
          *  @param {number} [intensity] - How bright it is
          *  @param {number} [saturation] - How colorful the ghosts are
+         *  @param {Color} [color] - Tints the flare, with the light's own color
          *  @return {LensFlare3D} - The flare, to change: light.addFlare().shapes = ['hex'] */
-        addFlare(size?: number, count?: number, intensity?: number, saturation?: number): LensFlare3D;
+        addFlare(size?: number, count?: number, intensity?: number, saturation?: number, color?: Color): LensFlare3D;
         set flare(arg: LensFlare3D);
         /** The light's lens flare, undefined for none: addFlare makes it, or set a LensFlare3D of your own, and
          *  destroying the flare takes it away
@@ -10209,7 +10219,7 @@ declare module "littlejsengine" {
      *   with the sun's own color; shapes says what its ghosts are, glowSize and ghostSize how big its parts are; or
      *   give it elements of your own, which may be tiles of the game's
      * - visible is how much of the sun shows, 0 to 1, eased over fadeTime, there for a game to read; it is 0 while the
-     *   sun is off the screen, where nothing is tested
+     *   sun is too far off the screen for the flare to show, a third of the screen past its edge, where nothing is tested
      * - What hides the sun is found with a ray from the camera, against the level and every object that is not see
      *   through, each on the triangles of its mesh, see render3D.pick; turn it off with occlusion
      * - It needs WebGL, and it draws nothing in the shadow of renderAfter2D
@@ -10252,7 +10262,8 @@ declare module "littlejsengine" {
         elements: Array<LensFlareElement> | undefined;
         /** @property {Light3D|undefined} - A light the flare is of in place of the sun, a lamp or a spotlight: the
          *  flare is at the light and in its color, smaller from farther than the light reaches, hidden by what is
-         *  in front of the light, and a spotlight's shows from inside its beam only; a DirectionalLight3D's is far
+         *  in front of the light but its lamp, a mesh around it no wider than half its radius, and a spotlight's
+         *  shows from inside its beam only; a DirectionalLight3D's is far
          *  away where it shines from, like the sun's; the flare is destroyed when its light is; light.addFlare
          *  sets this
          *  @type {Light3D|undefined} */

package/dist/littlejs.esm.js

@@ -35,7 +35,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.24.0';
+const engineVersion = '1.24.1';
 
 /** Frames per second to update
  *  @type {number}
@@ -4084,7 +4084,11 @@ function setGLEnable(enable)
 /** Set how many sided polygons to use when drawing circles and ellipses with WebGL
  *  @param {number} sides
  *  @memberof Settings */
-function setGLCircleSides(sides) { glCircleSides = sides; }
+function setGLCircleSides(sides)
+{
+    ASSERT(isNumber(sides) && sides >= 3, 'circles need at least 3 sides');
+    glCircleSides = sides;
+}
 
 /** Set default size of tiles in pixels
  *  @param {Vector2} size
@@ -9606,7 +9610,7 @@ const tileLayersTiledFlips = [[0,0], [3,1], [2,1], [3,0], [0,1], [1,0], [2,0], [
  *  @param {Object}   tileMapData - Level data from exported data
  *  @param {TileInfo} [tileInfo] - Default tile info (used for size and texture), tile() by default, none when no image is loaded
  *  @param {number}   [renderOrder] - Render order of the top layer
- *  @param {number}   [collisionLayer] - Layer to use for collision if any
+ *  @param {number|string} [collisionLayer] - Layer to use for collision if any, by its index or its name
  *  @param {boolean}  [draw] - Should the layer be drawn automatically
  *  @return {Array<TileCollisionLayer>}
  *  @memberof TileLayers */
@@ -9638,7 +9642,8 @@ function tileLayersLoad(tileMapData, tileInfo=tileLayerDefaultTile(), renderOrde
         const margin = tileset.margin || 0, spacing = tileset.spacing || 0, size = tileInfo.size;
         const width = tileInfo.textureInfo?.size.x || 0;
         const columns = tileset.columns || max(1, floor((width - margin*2 + spacing) / (size.x + spacing)));
-        tileInfo = new TileInfo(vec2(margin), size, tileInfo.textureInfo, spacing / 2, tileInfo.bleed, columns);
+        const origin = tileInfo.pos.subtract(vec2(tileInfo.padding)); // where the sheet starts, in an atlas too
+        tileInfo = new TileInfo(origin.add(vec2(margin)), size, tileInfo.textureInfo, spacing / 2, tileInfo.bleed, columns);
     }
 
     // flatten group layers in order, a group's color and visibility carry to the layers inside it
@@ -9669,6 +9674,14 @@ function tileLayersLoad(tileMapData, tileInfo=tileLayerDefaultTile(), renderOrde
     };
     addLayers(tileMapData.layers, WHITE, true);
 
+    // a layer named for collision is the first tile layer of that name, which stays the same when layers are added
+    if (typeof collisionLayer === 'string')
+    {
+        const name = collisionLayer;
+        collisionLayer = layers.findIndex((l)=> l.color && l.dataLayer.name === name);
+        ASSERT(collisionLayer >= 0, 'no tile layer named ' + name);
+    }
+
     // create tile layers and fill with data
     const tileLayers = [];
     const levelSize = vec2(tileMapData.width, tileMapData.height);
@@ -9724,31 +9737,38 @@ const tileLayersLDtkTypes = {Int: 'int', Float: 'float', Bool: 'bool', String: '
 
 /**
  * Make a Tiled map of a level of an LDtk project, to load with tileLayersLoad and objectLayersLoad
- * - Each Tiles, AutoLayer and IntGrid layer is a tile layer, the bottom one first as in Tiled, so the last layer
- *   of the LDtk file is layer 0; where LDtk stacks tiles in a cell, an edge over a fill, each tile over another
- *   goes in a layer of its own just above, named with (2), (3) and so on, so a layer of the first tiles has one
- *   wherever the LDtk layer has any, which makes it the one for collision
- * - An IntGrid layer with no tiles is a hidden layer of its values, for collision: pass its index as collisionLayer
+ * - Each Tiles, AutoLayer and IntGrid layer is a tile layer, the bottom one first as in Tiled; where LDtk stacks
+ *   tiles in a cell, an edge over a fill, each tile over another goes in a layer of its own just above, named with
+ *   (2), (3) and so on, and a tile LDtk draws see-through goes in one of its own with that opacity, times the
+ *   layer's, named with it, like Ground .25
+ * - An IntGrid layer is a hidden layer of its values under its own name, for collision, whatever tiles its rules
+ *   make, which are layers over it named with tiles, like Collisions tiles; pass the name as collisionLayer, since
+ *   the stacked and see-through layers change the indices from level to level:
+ *   tileLayersLoad(map, tile(0, 16), 0, 'Collisions')
  * - An Entities layer is an object layer: an entity's name is its type for objectLayersAddType, it is placed at
  *   its middle, and its Int, Float, Bool, String, Color and FilePath fields are its properties (an enum is a string)
  * - The tileset is the first tile layer's, with its padding and spacing; give tileLayersLoad a tile info of its image
  * - The level is in the project file (not saved as separate level files), its layers of one grid size; a layer of
- *   another grid size or another tileset is left out, with a warning in debug builds
+ *   another grid size or another tileset is left out, with a warning in debug builds, and a project with no tileset
+ *   keeps its tiles for the tile info the game gives; a project of several worlds has its levels counted in order
+ * - Layer offsets are not read
  * - The level editor edits the map this returns, and saves it as a Tiled map
  * @param {Object} ldtk - The LDtk project, its JSON
  * @param {number|string} [level] - Which level, by its index or its identifier
  * @return {Object} - A Tiled map: width, height, tilewidth, tileheight, tilesets and layers
  * @example
  * const map = tileLayersFromLDtk(await fetchJSON('world.ldtk'), 'Level_0');
- * const layers = tileLayersLoad(map, tile(0, 16), 0, 1); // layer 1 is solid
+ * const layers = tileLayersLoad(map, tile(0, 16), 0, 'Collisions'); // its IntGrid layer is solid
  * objectLayersLoad(map);
  * @memberof TileLayers */
 function tileLayersFromLDtk(ldtk, level=0)
 {
-    const levels = ldtk?.levels || [];
+    const levels = ldtk?.levels?.length ? ldtk.levels : (ldtk?.worlds || []).flatMap((w)=> w.levels || []);
     const data = typeof level === 'string' ? levels.find((l)=> l.identifier === level) : levels[level];
-    ASSERT(data, 'LDtk level not found', level);
-    ASSERT(isArray(data.layerInstances), 'LDtk level has no layers: levels saved as separate files are not read');
+    if (!data)
+        throw new Error('tileLayersFromLDtk: no level ' + level);
+    if (!isArray(data.layerInstances))
+        throw new Error('tileLayersFromLDtk: level ' + data.identifier + ' has no layers, levels saved as separate files are not read');
     const instances = data.layerInstances;
     const tiled = (l)=> l.__type !== 'Entities';
     const first = instances.find((l)=> tiled(l) && l.__tilesetDefUid != undefined) || instances.find(tiled) || instances[0];
@@ -9788,33 +9808,53 @@ function tileLayersFromLDtk(ldtk, level=0)
             continue;
         }
         const tiles = [...(instance.autoLayerTiles || []), ...(instance.gridTiles || [])];
-        const usable = instance.__gridSize === grid && instance.__cWid === width && instance.__cHei === height &&
-            (!tiles.length || instance.__tilesetDefUid === tileset?.uid);
-        if (!usable)
+        const ownTiles = !tiles.length || !tileset ||
+            instance.__tilesetDefUid === tileset.uid && tileset.tileGridSize === grid;
+        if (instance.__gridSize !== grid || instance.__cWid !== width || instance.__cHei !== height || !ownTiles)
         {
             debug && console.warn(`tileLayersFromLDtk: layer ${name} has another grid or tileset, left out`);
             continue;
         }
-        const empty = ()=> new Array(width * height).fill(0), stacks = [empty()];
-        if (tiles.length)
+        // an IntGrid layer's values, hidden, under its own name, for collision whatever its tiles do
+        const empty = ()=> new Array(width * height).fill(0), opacity = instance.__opacity ?? 1;
+        const values = instance.__type === 'IntGrid';
+        if (values)
+        {
+            const data = empty();
+            (instance.intGridCsv || []).forEach((value, k)=> k < data.length && (data[k] = value));
+            map.layers.push({id, name, type: 'tilelayer', width, height, data, opacity, visible: false, x: 0, y: 0});
+            if (!tiles.length) continue;
+        }
+
+        // a layer for each depth in a cell and each opacity, the first tiles drawn solid first
+        const tilesName = values ? name + ' tiles' : name;
+        const stacks = [{depth: 0, alpha: 1, data: empty()}], stack = (depth, alpha)=>
+        {
+            let s = stacks.find((s)=> s.depth === depth && s.alpha === alpha);
+            s || stacks.push(s = {depth, alpha, data: empty()});
+            return s.data;
+        };
         {
-            // a tile's place in pixels, its tile in the sheet, and its flips: bit 0 across, bit 1 down, which are
-            // Tiled's two top bits; LDtk lists them in the order it draws them, so the first in a cell is the
-            // bottom one and each after it goes a layer higher
+            // a tile's place in pixels, its tile in the sheet, its flips, bit 0 across and bit 1 down, which are
+            // Tiled's two top bits, and its opacity; LDtk lists them in the order it draws them, so the first in a
+            // cell is the bottom one and each after it goes a layer higher
             const depth = new Uint16Array(width * height);
             for (const t of tiles)
             {
                 const x = floor(t.px[0] / grid), y = floor(t.px[1] / grid), cell = x + y * width;
                 if (x >= 0 && x < width && y >= 0 && y < height)
-                    (stacks[depth[cell]++] ||= empty())[cell] =
+                    stack(depth[cell]++, round(clamp(t.a ?? 1) * 1e3) / 1e3)[cell] =
                         (t.t + 1 | (t.f & 1 ? 0x80000000 : 0) | (t.f & 2 ? 0x40000000 : 0)) >>> 0;
             }
         }
-        else
-            (instance.intGridCsv || []).forEach((value, k)=> k < stacks[0].length && (stacks[0][k] = value));
-        const visible = instance.__type === 'IntGrid' && !tiles.length ? false : instance.visible !== false;
-        stacks.forEach((data, k)=> map.layers.push({id: k ? map.nextlayerid++ : id, name: k ? `${name} (${k + 1})` : name,
-            type: 'tilelayer', width, height, data, opacity: instance.__opacity ?? 1, visible, x: 0, y: 0}));
+        const visible = instance.visible !== false;
+        stacks.sort((a, b)=> a.depth - b.depth || b.alpha - a.alpha);
+        for (const {depth, alpha, data} of stacks)
+        {
+            const layerName = tilesName + (depth ? ` (${depth + 1})` : '') + (alpha < 1 ? ' ' + String(alpha).replace(/^0/, '') : '');
+            map.layers.push({id: values || depth || alpha < 1 ? map.nextlayerid++ : id, name: layerName, type: 'tilelayer',
+                width, height, data, opacity: opacity * alpha, visible, x: 0, y: 0});
+        }
     }
     return map;
 }
@@ -17375,7 +17415,7 @@ class Box2dObject extends EngineObject
 
         const points = [];
         const radius = diameter/2;
-        for (let i=sides; i--;)
+        for (let i=sides; i-- > 0;) // a count that is not a whole number still ends
             points.push(vec2(radius,0).rotate((i+.5)/sides*PI*2));
         return this.addPoly(points, density, friction, restitution, isSensor);
     }
@@ -27843,10 +27883,11 @@ class Light3D extends EngineObject3D
      *  @param {number} [count] - How many ghosts there are, besides the glow at the light
      *  @param {number} [intensity] - How bright it is
      *  @param {number} [saturation] - How colorful the ghosts are
+     *  @param {Color} [color] - Tints the flare, with the light's own color
      *  @return {LensFlare3D} - The flare, to change: light.addFlare().shapes = ['hex'] */
-    addFlare(size, count, intensity, saturation)
+    addFlare(size, count, intensity, saturation, color)
     {
-        const flare = new LensFlare3D(size, count, intensity, saturation);
+        const flare = new LensFlare3D(size, count, intensity, saturation, color);
         this.flare = flare;
         return flare;
     }
@@ -29494,7 +29535,7 @@ function render3DFlareTile(shape)
  *   with the sun's own color; shapes says what its ghosts are, glowSize and ghostSize how big its parts are; or
  *   give it elements of your own, which may be tiles of the game's
  * - visible is how much of the sun shows, 0 to 1, eased over fadeTime, there for a game to read; it is 0 while the
- *   sun is off the screen, where nothing is tested
+ *   sun is too far off the screen for the flare to show, a third of the screen past its edge, where nothing is tested
  * - What hides the sun is found with a ray from the camera, against the level and every object that is not see
  *   through, each on the triangles of its mesh, see render3D.pick; turn it off with occlusion
  * - It needs WebGL, and it draws nothing in the shadow of renderAfter2D
@@ -29541,7 +29582,8 @@ class LensFlare3D extends EngineObject3D
         this.elements = undefined;
         /** @property {Light3D|undefined} - A light the flare is of in place of the sun, a lamp or a spotlight: the
          *  flare is at the light and in its color, smaller from farther than the light reaches, hidden by what is
-         *  in front of the light, and a spotlight's shows from inside its beam only; a DirectionalLight3D's is far
+         *  in front of the light but its lamp, a mesh around it no wider than half its radius, and a spotlight's
+         *  shows from inside its beam only; a DirectionalLight3D's is far
          *  away where it shines from, like the sun's; the flare is destroyed when its light is; light.addFlare
          *  sets this
          *  @type {Light3D|undefined} */
@@ -29681,13 +29723,15 @@ class LensFlare3D extends EngineObject3D
             if (map.raycast(ray, reach, (type)=> !map.blockType(type).seeThrough))
                 return true;
         // a light's lamp, the mesh the light is inside, does not hide it: one whose box, in its own space, the light
-        // is in
+        // is in, and no wider than half the light's reach, since a room or a whole level has a box around its lights
+        // too, and its walls do hide them from outside
         const lamp = (o)=>
         {
             if (!this.light || reach === Infinity || !o.mesh || o instanceof HeightMap) return false;
-            const matrix = render3DObjectMatrix(o);
-            if (!matrix.determinant()) return false;
-            const p = matrix.copy().invert().transformPoint(source.pos), b = o.mesh.bounds || o.mesh.getBounds();
+            const matrix = render3DObjectMatrix(o), b = o.mesh.bounds || o.mesh.getBounds();
+            const side = max(b.max.x - b.min.x, b.max.y - b.min.y, b.max.z - b.min.z) * render3DMaxStretch(matrix.m);
+            if (!matrix.determinant() || side > this.light.radius / 2) return false;
+            const p = matrix.copy().invert().transformPoint(source.pos);
             return p.x >= b.min.x && p.x <= b.max.x && p.y >= b.min.y && p.y <= b.max.y &&
                 p.z >= b.min.z && p.z <= b.max.z;
         };
@@ -30324,7 +30368,7 @@ class VoxelMap extends EngineObject3D
         /** @type {Array<Vector3>} */
         this.chunkCenters = []; // a chunk mesh's points are around its center, which it is drawn at
         this.chunksChanged = new Set;
-        /** @type {Array<{faces: Array<number>, seeThrough: boolean, transparent: boolean}|undefined>} */
+        /** @type {Array<{faces: Array<number>, seeThrough: boolean, transparent: boolean, doubleSided: boolean}|undefined>} */
         this.blockTypes = [];
         this.tiles = new Map; // tile index to the uvs of its corners
 
@@ -30396,27 +30440,29 @@ class VoxelMap extends EngineObject3D
      *  @param {number} type - 1 to 255
      *  @param {number|Array<number>|{top?: number, side: number, bottom?: number}} faces - A tile index for every face,
      *    six in the order +x, -x, +y, -y, +z, -z, or the side's with the top and bottom's, which default to the side's
-     *  @param {{seeThrough?: boolean, transparent?: boolean}} [options] - seeThrough for holes in its texture, like
-     *    leaves, so the blocks beside it keep their faces; transparent to blend, like glass or water, drawn in the
-     *    transparent stage, and see-through too */
-    setBlockType(type, faces, {seeThrough=false, transparent=false}={})
+     *  @param {{seeThrough?: boolean, transparent?: boolean, doubleSided?: boolean}} [options] - seeThrough for holes
+     *    in its texture, like leaves, so the blocks beside it keep their faces; transparent to blend, like glass or
+     *    water, drawn in the transparent stage, and see-through too; doubleSided for faces seen from inside the
+     *    block as well, like water, whose surface then shows from under it */
+    setBlockType(type, faces, {seeThrough=false, transparent=false, doubleSided=false}={})
     {
         ASSERT(type >= 1 && type <= 255 && type % 1 === 0, 'a block type is a whole number from 1 to 255', type);
         const f = /** @type {any} */ (faces);
         const list = isNumber(f) ? [f, f, f, f, f, f] : isArray(f) ? f :
             [f.side, f.side, f.top ?? f.side, f.bottom ?? f.side, f.side, f.side];
         ASSERT(list.length === 6 && list.every(isNumber), 'faces is a tile index, six of them, or {top, side, bottom}');
-        this.blockTypes[type] = {faces: list, seeThrough: seeThrough || transparent, transparent};
+        this.blockTypes[type] = {faces: list, seeThrough: seeThrough || transparent, transparent, doubleSided};
         this.rebuild();
     }
 
     /** A block type's faces and how it is seen through
      *  @param {number} type
-     *  @return {{faces: Array<number>, seeThrough: boolean, transparent: boolean}}
+     *  @return {{faces: Array<number>, seeThrough: boolean, transparent: boolean, doubleSided: boolean}}
      *  @ignore */
     blockType(type)
     {
-        return this.blockTypes[type] ||= {faces: [type, type, type, type, type, type], seeThrough: false, transparent: false};
+        return this.blockTypes[type] ||= {faces: [type, type, type, type, type, type], seeThrough: false, transparent: false,
+            doubleSided: false};
     }
 
     /** Build every chunk again, after changing data directly or ambientOcclusion */
@@ -30486,6 +30532,11 @@ class VoxelMap extends EngineObject3D
                     colors[k] = ao ? RENDER3D_VOXEL_SHADES[shade[i]] : WHITE;
                 }
                 mesh.addStrip(points, normal, uvs, colors);
+
+                // a double sided block shows the face from inside too, its corners the other way round
+                if (block.doubleSided)
+                    mesh.addStrip([points[1], points[0], points[3], points[2]], normal.scale(-1),
+                        [uvs[1], uvs[0], uvs[3], uvs[2]], [colors[1], colors[0], colors[3], colors[2]]);
             }
         }
         this.chunkMeshes[index]?.dispose();
@@ -34276,8 +34327,8 @@ function editorMapRestore(map)
     if ((saved.width ?? map.width) === map.width && (saved.height ?? map.height) === map.height &&
         editorSameData(saved.layers, data) && editorSameData(saved.objects ?? [], objects))
         editorDiscardPending(record);
-    else if (!sameFile || !editorResizeMap(map, saved.width ?? map.width, saved.height ?? map.height) ||
-        !editorCopyData(data, saved.layers))
+    else if (!sameFile || !editorSavedFits(saved, data.length, saved.width ?? map.width, saved.height ?? map.height) ||
+        !editorResizeMap(map, saved.width ?? map.width, saved.height ?? map.height) || !editorCopyData(data, saved.layers))
     {
         record.pending = saved;
         console.warn(`LittleJS editor: ${record.fileName} changed since its autosaved edits, ` +
@@ -34576,6 +34627,11 @@ function editorCopyData(data, saved)
     return true;
 }
 
+// are an autosave's tiles a layer for each of the map's, each of its own size, so the map is resized only for tiles
+// that fit it
+const editorSavedFits = (saved, count, width, height)=> isArray(saved.layers) && saved.layers.length === count &&
+    saved.layers.every((layer)=> isArray(layer) && layer.length === width * height);
+
 // remember a map's tile data and objects, or forget them when they are back to the file
 function editorAutosave(record)
 {
@@ -34604,7 +34660,7 @@ function editorPaintData(record, data, objects, width=record.map.width, height=r
     {
         if (!editorHas('onRestart')) return;
         const before = editorMapSnapshot(record);
-        editorSetMapSnapshot(record, {width, height, layers: data, objects});
+        editorSetMapSnapshot(record, {width, height, layers: data, objects}, keepUnknown);
         editorMapChanged(record, before);
         return;
     }
@@ -34721,13 +34777,15 @@ function editorMapSnapshot(record)
     return editorObjectsCopy({width: map.width, height: map.height, layers: editorTileLayerData(map.layers), objects});
 }
 
-// give a map a size, tiles and objects, the game's Restart hook makes its layers again
-function editorSetMapSnapshot(record, snapshot)
+// give a map a size, tiles and objects, the game's Restart hook makes its layers again; keepUnknown leaves an object
+// layer past the snapshot's as it is, as applying an autosave from before the file had it does
+function editorSetMapSnapshot(record, snapshot, keepUnknown=false)
 {
     const map = record.map;
     editorResizeMap(map, snapshot.width, snapshot.height);
     editorCopyData(editorTileLayerData(map.layers), snapshot.layers);
     editorRestoreObjects(map, snapshot);
+    if (!keepUnknown)
     for (const group of editorObjectGroups(map.layers).slice(snapshot.objects.length))
         group.objects = []; // an Objects layer the editor made since
     editorClearSelections();
@@ -35887,9 +35945,13 @@ function editorPaletteTiles(layer)
     if (!image) return [];
     if (layer.palette?.image === image) return layer.palette.tiles;
 
-    const tiles = [];
+    // a sheet read by its columns, a tileset with a margin or a spacing, is read with frame(), which asserts the
+    // frame is inside the image, so a row past the image's end is found before its frame is made
+    const tiles = [], base = live.tileInfo, columns = base.columns;
     for (let i = 0; i < 4096; ++i)
     {
+        if (columns && base.pos.y + (i / columns | 0) * (base.size.y + base.padding*2) + base.size.y > image.height)
+            break;
         const t = editorTileInfo(live, i);
         if (t.pos.x + t.size.x > image.width || t.pos.y + t.size.y > image.height) break;
         tiles.push({tile: i, tileInfo: t});
@@ -37178,9 +37240,11 @@ function editor3DLevelLoaded(level)
         level.objects = editor3DCopy(saved.objects);
         for (const name of editor3DLevelPartNames)
             parts[name] ? level[name] = editor3DCopy(parts[name]) : delete level[name];
+        saved.stale && console.warn(`LittleJS editor: the edits brought back to ${record.fileName} are older than ` +
+            'the last ones, which storage had no room for');
     }
-    else if (saved)
-        record.pending = saved;
+    else if (saved && isArray(saved.objects))
+        record.pending = saved; // one that is broken is passed by, and the next autosave writes over it
 }
 
 // called by level3DLoad for each object, with what its type made