littlejsengine 1.24.1 → 1.24.2

package/CHANGELOG.md

@@ -7,6 +7,60 @@ What changed in each release, newest first. Releases before 1.20.0 are on the
 
 Nothing yet.
 
+## 1.24.2 - 2026-10-03
+
+### New Changes
+
+- Tile sets from separate images: `loadTiles(['grass.png', 'brick.png', 'props.png'], 16)` packs tile images, or several tile sheets, into the texture sheets as one tile set, numbered in the order given, for `tileLayersLoad`, tile layers and the level editor's palette; an image that is not whole tiles gives the whole tiles in it, and a map's tileset margin or spacing does not replace the set
+- Spotlight gels: `light.gel` is a picture the shadow casting spotlight shines through, cast along its beam in its colors, like a slide or stained glass; with none a scene draws exactly as before. The 3D First Person flashlight has one on G
+- Less garbage each frame: objects are sorted only when one is out of render order and the destroyed taken out only when there are some, an object with mass that collides with nothing copies no position, and outlines and regular polygons are made into kept vectors, about 98 fewer for each outlined circle; a 3D pick makes no vectors for an object it misses
+- `Mesh.computeNormals(true)` is 5 to 7 times faster, the same normals to the last bit: a 960 point flag in 0.24 ms where it took 1.8, so a mesh can be bent every frame
+- `loadSprite`, `loadTiles` and `loadAtlas` give back what the first load did when the same image is loaded again with the same settings, packed once
+- A release build goes on past an error in a frame, logging the first, where one error froze the game for good; a debug build stops and shows it as before
+
+### Fixes
+
+- A Tiled property named as a method of the object it is for, like `update`, is left out, where it replaced the method; a debug build says so
+- `noise2D` stays noise however far out y is, where past about 24 million every row was one value; it gives the same values as before everywhere else
+- Medals: the save keeps the unlock of a medal the game has not made this time, and a medal made after `medalsInit` reads its unlock, so a medal made late or behind a flag is never lost; `medalsReset` locks those too
+- Older browsers: the engine starts with no `OffscreenCanvas` (Safari before 16.4), drawing into a canvas element in its place, and so do the textures it makes itself (normal maps from heights, particle shapes, light glows, lens flares, glTF's white texture), and uses neither `Array.prototype.at` nor `Object.hasOwn` (Safari before 15.4); the example browser's markdown has no lookbehind, which Safari before 16.4 could not read
+- On an iPhone the silent switch mutes the game, as it does a ringtone, and the player's music plays on beside it; `setSoundIgnoreSilentSwitch(true)` has the game play through the switch as media does (Safari 16.4 and up)
+- Level editor: the brush, its ghost and the palette read a tile past the end of a sheet as nothing, as the layer draws it, where a collision value picked up with the right button asserted every frame; the palette of a tile set filled in after it was first shown shows its tiles
+- A light's flare looks past four lamps around it to what is behind them, where the fourth counted as hidden
+- A click or tap in the bars around a letterboxed canvas presses nothing, where it pressed whatever was at the canvas edge
+- `showConfirmDialog` while one is open gives the one open, where a second broke UI navigation in release builds
+- The level editor's cut, copy and stamps keep an object's name, size, turn and visibility, where a paste made a bare point; objects moved with a selection or stamped land on their place to the digit, not a hair off
+- The 3D editor's terrain paint rounds no heights, and a sculpt stroke rounds only those it changed
+- A `UISlider` let go in the frame it moves takes that last place
+- A gamepad of fewer buttons put in the slot of another holds none of the other's buttons; a gamepad axis that reads NaN is centered, where it failed an assert in debug builds
+- `UITextInput` takes a keydown with no key, as autofill sends, where it threw
+- `parseOBJ` reads a comment after a face, carriage return line ends and a line carried on with a backslash, and a release build leaves out a face of a vertex the file does not have
+- `tileLayersFromLDtk` keeps a tile layer with no tiles as an empty layer, so a level of one loads and the editor can paint it
+- Level editor: a property set in the box keeps its place and a `file` or `object` property its type; a save leaves out the object layer made for a first object that was undone; a new object layer's id is past every layer's
+- 3D editor: taking a prefab out of the level takes its instances out of the game; a level's parts are saved in one order, so a level reloaded from its autosave saves the same
+- `writeSaveData` asserts its data is an object, which `readSaveData` reads back, and returns whether it was written, false when storage is full or unavailable
+- `parseAtlas` warns of two sprites with one name; `nearestPowerOfTwo` is never less than its value and is 1 for a value of 1 or less; a particle effect's name cut to 60 characters ends with no space
+- A tile layer's raycast toward a point far beyond the layer walks only across the layer, where a ray to a far constant took seconds
+- `debugShowErrors` shows a message as text, so a file name with markup in it can not add elements to the page
+- Canvas2D tints clamp the color to 0 to 1, as WebGL does
+- glTF: the keys of the files given may start with ./ or / or use backslashes, a uri above them is refused, and an accessor that reaches past its buffer is refused before its floats are made
+- A level whose prefab holds itself, several times over, loads at once with that prefab left out where it holds itself, in place of making thousands of objects
+- Small malformed files no longer make a loader run on: an Aseprite tag past its frames keeps to them, a glTF node reached twice and an accessor of millions with no buffer are refused, an LDtk level of millions of cells is refused and a tile or entity with no place is passed by
+- LDtk: an IntGrid layer whose rule tiles are on another tileset keeps its values for collision, its tiles left out with a warning
+- A collision layer named that no layer has says so in release builds too
+- A light's lens flare: its lamp is a mesh around the light that the ray meets near the light and that is thin, so a globe or a lamp post is its own fixture, while a room or a level mesh hides the light, even one close behind its wall
+- VoxelMap: the inside of a doubleSided face is split along the same diagonal as its outside, so it shows no seam
+- glTF: `parseGLTF(data, baseUrl, files)` finds the `.bin` and image files a `.gltf` names among files given, like a drop's, from the model's own folder, or by the file name alone when only one file has it; a file it can not find is named in the error, and an image that can not be read in a warning; the 3D Mesh example takes a `.gltf` dropped with its files or in its folder, and frees the model it replaces
+- Example browser: after the arrow keys move through the list, Enter keeps the example they went to, and Escape in the search clears it without also closing the list
+- 3D levels: a color that is not a string, and a number that is NaN or Infinity (1e999 in JSON), are read as the default, in place of an assert or a NaN
+- `tileLayersLoad` says so when a map is not a whole number of cells across and down, has no layers, or a layer's tiles do not fill it, in release builds too, in place of running on; every layer is checked before any is made. A game that relied on a release build loading such a map anyway now gets the error
+- A tile past the end of a sheet read by its columns draws nothing, as an LDtk IntGrid layer's values past the art did in the level editor, which asserted
+- A tween that loops or ping pongs with a duration of 0 or less, possible in release builds, ends its loops
+
+### New Demos
+
+- [Custom Editor](https://killedbyapixel.github.io/LittleJS/examples/?example=Custom%20Editor) - A level editor made for one game: a class of its own with a tool that lays out rooms by a drag, a button, a key and an overlay
+
 ## 1.24.1 - 2026-10-02
 
 ### New Changes
@@ -16,7 +70,11 @@ Nothing yet.
 - `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
+- 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. A button in the top bar switches between dark and light, the choice shared with the docs site
+
+### Breaking Changes
+
+- LDtk: an IntGrid layer with tiles is now a hidden layer of its values under its own name, its tiles in layers named with tiles over it, so the layer indices and names of such a level move; name the collision layer, `tileLayersLoad(map, tileInfo, 0, 'Collisions')`, in place of an index
 
 ### Fixes
 

package/EDITOR.md

@@ -341,6 +341,8 @@ after a reload.
 
 ## Where the working examples are
 
+- `examples/shorts/customEditor.js`: a 2D editor class of a game's own, with a tool that lays out rooms by a
+  drag, a button, a key and an overlay drawn in `onDraw`.
 - `examples/shorts/render3dLevelEditor.js`: a 3D level with its own Coin and PlayerStart types and both hooks.
 - `examples/shorts/render3dPrefab.js`: the 3D editor used as a prefab maker.
 - `examples/shorts/levelEditor.js` and `examples/platformer/`: the 2D editor with a game's own types, palette

package/FAQ.md

@@ -206,6 +206,10 @@ If you are using [Visual Studio Code](https://code.visualstudio.com/) there is a
 
 Another option is to setup a simple local web server like [http-server](https://www.npmjs.com/package/http-server) via npm.
 
+### Which browsers does LittleJS run in?
+
+Current Chrome, Edge, Firefox and Safari, on desktop and on phones. The oldest it aims to support is Safari 15 (iOS 15) and the other browsers from 2021 on. Where WebGL2 is missing, 2D games fall back to Canvas2D rendering on their own; the 3D plugin needs WebGL2.
+
 ### How does the camera and world coordinate systems work?
 
 LittleJS drawing functions are all handled in world coordinates by default.
@@ -263,6 +267,13 @@ Plugins are self-contained features that live alongside the engine but aren't pa
 | `newgrounds.js` | Newgrounds.io integration (medals held on the server, scoreboards) |
 | `audioEffects.js` | Web Audio effects like filter, reverb, delay, distortion and compressor, for a group of sounds or everything |
 | `drawUtilities.js` | Higher-level drawing helpers like nine-slice and three-slice |
+| `render3dVoxels.js` | `VoxelMap`, a 3D grid of blocks that draws itself and that objects collide with |
+| `render3dLevel.js` | 3D levels as JSON: object types, prefabs, a scene block, block maps and terrain, loaded with `level3DLoad` |
+| `render3dDebug.js` | 3D debug draws (`debugBox3D`, `debugSphere3D`, `debugLine3D`), in debug builds only |
+| `render3dEditor.js` | The free camera and the 3D level editor, in debug builds only |
+| `sceneSystem.js` | Scenes as plain objects, switched with `setScene` |
+| `parallax.js` | `ParallaxLayer`, a background that follows the camera at its own depth and repeats |
+| `particleEffects.js` | A library of ready made particle effects, and their designer's file format |
 
 This self-contained design means the community can also ship plugins independently of the main repo — you can write your own plugin as just a JavaScript file that uses the engine's public API.
 
@@ -367,7 +378,7 @@ LittleJS has a dedicated [js13k branch](https://github.com/KilledByAPixel/Little
 - **Lean on built-ins to avoid asset files**: `Sound` with ZzFX parameters generates sound effects from a tiny array, and built-in shape drawing avoids shipping image assets.
 - **Use a packer**: the js13k branch is set up to compress the final bundle with Roadroller or a similar packer. Check the branch's build script for the current toolchain.
 
-For normal production (non-13KB) builds, the engine ships `dist/littlejs.release.js` (asserts stripped) and `dist/littlejs.min.js` (minified) — both well under 100KB.
+For normal production (non-13KB) builds, the engine ships `dist/littlejs.release.js` (asserts stripped, about 1.5 MB with every plugin and its comments) and `dist/littlejs.min.js` (minified, about 420 KB, about 125 KB gzipped). A bundler like Vite leaves out the plugins a game does not use, which makes a small game far smaller.
 
 ---
 
@@ -387,7 +398,7 @@ LittleJS works best when your tile sheet is broken up into grids of tiles becaus
 drawTile(vec2(21,5), vec2(4.5), tile(3,128));
 ```
 
-Once loaded, the underlying images are available via `textureInfos[0].image`, `textureInfos[1].image`, etc. This is useful for tasks like reading pixel data to generate a level — see [examples/module/game.js](examples/module/game.js) for an example that reads tile data directly from an image.
+Once loaded, the underlying images are available via `textureInfos[0].image`, `textureInfos[1].image`, etc. This is useful for tasks like reading pixel data to generate a level — the [Level Editor short](https://killedbyapixel.github.io/LittleJS/examples/?example=Level%20Editor) loads a level from data instead, and [examples/module/game.js](examples/module/game.js) builds one from a string.
 
 ### What is the tile function and how do tile indexes work?
 

package/README.md

@@ -172,7 +172,7 @@ LittleJS comes with several demos both for learning and using as starter project
 | [littlejs.esm.js](https://github.com/KilledByAPixel/LittleJS/blob/main/dist/littlejs.esm.js) | Debug | ESM | Debug mode with asserts |
 | [littlejs.esm.min.js](https://github.com/KilledByAPixel/LittleJS/blob/main/dist/littlejs.esm.min.js) | Release | ESM | Optimized for release and minified |
 
-Every build includes the plugins. littlejs.min.js is about 100 KB gzipped: the core engine is about 36 KB of that and the 3D plugins about 40 KB. A bundler like Vite leaves out the plugins a game does not use, so a small 2D game comes to about 26 KB gzipped, and a lit 3D scene to about 47 KB.
+Every build includes the plugins. littlejs.min.js is about 125 KB gzipped, and the 3D plugins are a large part of that. A bundler like Vite leaves out the plugins a game does not use, so a small 2D game comes to about 26 KB gzipped, and a lit 3D scene to about 47 KB.
 
 ## Games Made With LittleJS
 

package/REFERENCE.md

@@ -144,7 +144,7 @@ fetchJSON(url)                        // Fetch and parse a JSON file (async)
 shareURL(title, url, callback)        // Share a URL via the navigator share API
 readSaveData(saveName, defaultSaveData) // Read game save data from localStorage, default must be an object
                                       // the result has the default's type in TypeScript
-writeSaveData(saveName, saveData)     // Write game save data to localStorage; give medalsInit a different name
+writeSaveData(saveName, saveData)     // Write a save data object to localStorage, false if it could not; give medalsInit a different name
 
 // Random functions
 rand(valueA=1, valueB=0)             // Random float between values
@@ -441,6 +441,8 @@ getNoteFrequency(semitoneOffset, rootFrequency=220)  // Get frequency for musica
 
 // Audio settings
 soundEnable = true      // Should sound be enabled?
+soundIgnoreSilentSwitch = false // play with an iPhone's silent switch on, as media, pausing the player's music;
+                        // off, the switch mutes the game; setSoundIgnoreSilentSwitch(true)
 soundVolume = .3        // Volume scale to apply to all sound
 soundDefaultRange = 40  // Default range where sound no longer plays
 soundDefaultTaper = .7  // Default range percent to taper off sound (0-1)
@@ -1301,6 +1303,9 @@ light.coneAngle = .5              // a spotlight: the angle in radians from its
                                   // cone, 0 by default for a light that shines every way; it shines along its
                                   // own forward, so rotation3D or what it is attached to aims it
 light.coneSoftness = .2           // how much of the cone is its fading edge: 0 a hard edge, 1 fading from the middle
+light.gel = textureInfo           // or a TileInfo's whole texture: a picture the light shines through, cast along its cone in its colors, upright
+                                  // as the light looks out, like a slide or stained glass; only the spotlight that
+                                  // casts the shadows has one, render3D.shadows on and it as render3D.shadowLight
 light.glow = 1                    // a soft hazy glow over the light this big, like a lamp at night; 0 by default,
                                   // added onto what is behind it, hidden by what is in front
 light.glowFalloff = 1             // how fast the glow fades from its middle, .5 a wide haze, 2 a tight bright core
@@ -1667,8 +1672,9 @@ const map = new VoxelMap(pos3D=vec3(), mapSize=vec3(16), tileInfo=tile()) // a g
         // that objects with collideLevel collide with; pos3D is its corner and a cell is 1 unit, it stays upright
 map.setVoxel(cell, type) / map.getVoxel(cell) // type 1-255 shows that tile on every face, 0 is empty, a cell outside
                                               // the map is ignored and reads 0
-map.setBlockType(type, faces, {seeThrough, transparent}) // faces: a tile, six (+x, -x, +y, -y, +z, -z), or
-        // {top, side, bottom}; seeThrough for holes like leaves, transparent to blend like water, drawn after the rest
+map.setBlockType(type, faces, {seeThrough, transparent, doubleSided}) // faces: a tile, six (+x, -x, +y, -y, +z,
+        // -z), or {top, side, bottom}; seeThrough for holes like leaves, transparent to blend like water, drawn after
+        // the rest; doubleSided for faces seen from inside too, so the surface of water shows from under it
 map.raycast(ray, maxDistance, test)           // {distance, cell, normal, type} of the first block a ray hits, or
                                               // undefined; test(type, cell) says which blocks count
 map.data / map.rebuild()                      // the Uint8Array of types, x + mapSize.x*(y + mapSize.y*z); rebuild
@@ -1683,8 +1689,10 @@ await loadOBJ(url, smooth) // fetch then parse, in an async gameInit; chain .cen
 // glTF models - the glTF plugin, .gltf with its files beside it or .glb in one file; meshes with their node placement,
 // vertex colors, material colors and base color textures, and node animations; no skins or morph targets, and no
 // Draco or meshopt compressed geometry, which throws saying so
-const model = await loadGLTF(url)   // a GLTFModel, in an async gameInit; or await parseGLTF(data, baseUrl) on bytes or
-                                     // JSON you already have
+const model = await loadGLTF(url)   // a GLTFModel, in an async gameInit; or await parseGLTF(data, baseUrl, files) on
+                                     // bytes or JSON you already have; files, a Map of the .bin and image files a
+                                     // .gltf names by their paths, like the files of a drop, in place of fetching,
+                                     // baseUrl then the .gltf's folder among them
 model.parts                          // one GLTFPart per primitive of every node: name, mesh in model space, color,
                                      // textureInfo when the material has one and WebGL is on, transparent for a
                                      // blending material or glass (KHR_materials_transmission), which comes in
@@ -2172,6 +2180,11 @@ getCrescentPoints(pos, size=1, percent=0, angle=0, invert=false, sides=glCircleS
 - See `examples/shorts/textureSheet.js`
 
 ```javascript
+loadTiles(sources, tileSize, padding=1) // Pack tile images, or several tile sheets, into one tile set: each image cut
+                                      // into tiles, numbered from 0 in the order given; give the TileInfo it
+                                      // returns to tileLayersLoad or a TileLayer, and await spritesReady first
+tileInfo.tiles                        // a tile set's tiles, each where it was packed: a tile layer draws tile n
+                                      // from tiles[n], and the level editor's palette offers each
 loadSprite(src, frameSize, padding=1, sourcePadding=0) // Load an image and pack it, returns a TileInfo
 loadAtlas(imageSrc, jsonSrc, padding=1) // Load a TexturePacker or Aseprite atlas, returns name->TileInfo object
 parseAtlas(data)                      // Parse atlas json into named frame groups, used by loadAtlas
@@ -2288,7 +2301,8 @@ debugLine(posA, posB, color, width=.1, time)                // Draw debug line
 debugPoly(pos, points, color=WHITE, time=0, angle=0, fill)  // Draw debug polygon
 debugText(text, pos, size=1, color=WHITE, time=0, angle=0)  // Draw debug text
 debugOverlap(pA, sA, pB, sB, color) // Draw a debug overlap between two boxes
-// each debug draw also takes screenSpace after the params above, defaulting to drawScreenSpace
+// each debug draw also takes screenSpace as its last parameter, defaulting to drawScreenSpace; debugText takes a
+// font before it
 debugClear()                     // Clear all debug primitives
 debugScreenshot()                // Save a screenshot at the end of this frame
 debugShowErrors()                // Show full page error message when an error occurs

package/dist/littlejs.d.ts

@@ -1345,6 +1345,12 @@ declare module "littlejsengine" {
      *  @default
      *  @memberof Settings */
     export let soundEnable: boolean;
+    /** Play sound with an iPhone's silent switch on, as media does; off by default, so the switch mutes the game as it
+     *  does a ringtone, and the player's own music keeps playing beside it; Safari 16.4 and up, elsewhere it does nothing
+     *  @type {boolean}
+     *  @default
+     *  @memberof Settings */
+    export let soundIgnoreSilentSwitch: boolean;
     /** Volume scale to apply to all sound, music and speech
      *  Use setSoundVolume to also update the audio master gain immediately
      *  @type {number}
@@ -1614,6 +1620,10 @@ declare module "littlejsengine" {
      *  @param {boolean} enable
      *  @memberof Settings */
     export function setSoundEnable(enable: boolean): void;
+    /** Set if sound plays with an iPhone's silent switch on, as media does, which also pauses the player's own music
+     *  @param {boolean} ignore
+     *  @memberof Settings */
+    export function setSoundIgnoreSilentSwitch(ignore: boolean): void;
     /** Set volume scale to apply to all sound, music and speech
      *  @param {number} volume
      *  @memberof Settings */
@@ -1806,7 +1816,7 @@ declare module "littlejsengine" {
      *  @return {number}
      *  @memberof Math */
     export function smoothStep(percent: number): number;
-    /** Returns the nearest power of two not less than the value
+    /** Returns the nearest whole power of two not less than the value, 1 for a value of 1 or less
      *  @param {number} value
      *  @return {number}
      *  @memberof Math */
@@ -1899,6 +1909,7 @@ declare module "littlejsengine" {
     export function saveText(text: string, filename?: string, type?: string): void;
     /** Create an offscreen canvas to draw into, and return its 2D context
      *  - The canvas is context.canvas, which is what TextureInfo and the like take
+     *  - A browser with no OffscreenCanvas, Safari before 16.4, gets a canvas element that is not on the page
      *  @param {number} width - In pixels
      *  @param {number} [height] - In pixels, defaults to the width for a square
      *  @param {boolean} [willReadFrequently] - Keep it in software, faster when getImageData is called on it often
@@ -1933,11 +1944,12 @@ declare module "littlejsengine" {
     export function readSaveData<T extends {
         [x: string]: any;
     } = any>(saveName: string, defaultSaveData?: T): T;
-    /** Write save data to local storage
+    /** Write save data to local storage, an object as readSaveData gives it back
      *  @param {string} saveName - unique name for the game/save
      *  @param {object} saveData - object containing data to be saved
+     *  @return {boolean} - Whether it was written, false when storage is unavailable or full
      *  @memberof Utilities */
-    export function writeSaveData(saveName: string, saveData: object): void;
+    export function writeSaveData(saveName: string, saveData: object): boolean;
     /** 1D value noise — returns a smooth value in [0, 1] for any real x.
      *  Integer inputs land on deterministic lattice values; non-integer inputs
      *  are interpolated with smoothStep for C1 continuity.
@@ -2535,6 +2547,10 @@ declare module "littlejsengine" {
         padding: number;
         /** @property {TextureInfo} - The texture info for this tile */
         textureInfo: TextureInfo;
+        /** @property {Array<TileInfo>|undefined} - A tile set's tiles, each wherever it was packed, as loadTiles makes
+         *  them: a tile layer given this tile info draws its tile n from tiles[n] and not from a grid on one sheet
+         *  @type {Array<TileInfo>|undefined} */
+        tiles: Array<TileInfo> | undefined;
         /** @property {number} - Shrinks tile by this many pixels to prevent neighbors bleeding */
         bleed: number;
         /** @property {number} - How many frames per row for frame(), 0 to keep frames on a single row */
@@ -3660,13 +3676,13 @@ declare module "littlejsengine" {
      * @memberof Audio
      * @example
      * // load an audio asset file
-     * const sound_example = new Sound('sound.mp3');
+     * const music = new Sound('sound.mp3');
      *
      * // create a zzfx sound
-     * const sound_example = new Sound([.5,.5]);
+     * const blip = new Sound([.5,.5]);
      *
      * // play a sound
-     * sound_example.play();
+     * blip.play();
      */
     export class Sound {
         /** Create a sound object and cache the audio for later use
@@ -4284,7 +4300,8 @@ declare module "littlejsengine" {
      *  @param {number}   [renderOrder] - Render order of the top layer
      *  @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>}
+     *  @return {Array<TileCollisionLayer>} - It throws for a map that is not whole cells, or a layer whose tiles do not
+     *    fill it, before it makes any layer
      *  @memberof TileLayers */
     export function tileLayersLoad(tileMapData: any, tileInfo?: TileInfo, renderOrder?: number, collisionLayer?: number | string, draw?: boolean): Array<TileCollisionLayer>;
     /**
@@ -4605,7 +4622,7 @@ declare module "littlejsengine" {
      *     rgb(1,1,1,0), rgb(0,0,0,0), // colorEndA, colorEndB
      *     1, .2, .2, .1, .05,  // particleTime, sizeStart, sizeEnd, particleSpeed, particleAngleSpeed
      *     .99, 1, 1, PI, .05,  // damping, angleDamping, gravityScale, particleCone, fadeRate
-     *     .5, 1                // randomness, collide
+     *     .5, true             // randomness, collide
      * );
      */
     export class ParticleEmitter extends EngineObject {
@@ -7681,8 +7698,8 @@ declare module "littlejsengine" {
      *  const path = pf.findPath(player.pos, mousePos);
      *
      *  // Bare grid with custom walkability:
-     *  const pf = new PathFinder(vec2(50, 50));
-     *  pf.isWalkable = (x, y) => myGrid[y*50 + x] === 0;
+     *  const gridFinder = new PathFinder(vec2(50, 50));
+     *  gridFinder.isWalkable = (x, y) => myGrid[y*50 + x] === 0;
      */
     export class PathFinder {
         /** @param {TileCollisionLayer|Vector2} source - Either a TileCollisionLayer
@@ -8503,6 +8520,7 @@ declare module "littlejsengine" {
         viewProjection: Matrix4;
         /** @property {Matrix4} - This frame's light view projection for the shadow map */
         shadowMatrix: Matrix4;
+        gelAxes: number[];
         /** @property {Vector3} - Camera right axis this frame */
         cameraRight: Vector3;
         /** @property {Vector3} - Camera up axis this frame */
@@ -9885,6 +9903,13 @@ declare module "littlejsengine" {
         /** @property {number} - How fast the glow fades from its middle: 1 by default, .5 a wide haze, 2 a tight
          *  bright core */
         glowFalloff: number;
+        /** @property {TextureInfo|TileInfo|undefined} - A gel: a picture the light shines through, like a stained glass
+         *  window or the leaves of a tree, cast along its cone in its colors, upright as the light looks out, the whole
+         *  texture of a TileInfo; only the spotlight that casts the shadows has one, with render3D.shadows on and it
+         *  as render3D.shadowLight, and only on what takes its shadows: an object with receiveShadow off is lit
+         *  without the gel; its alpha is not read, see through panes are dark
+         *  @type {TextureInfo|TileInfo|undefined} */
+        gel: TextureInfo | TileInfo | undefined;
         /** @type {LensFlare3D|undefined} */
         flareObject: LensFlare3D | undefined;
         /** Give the light a lens flare, made with the arguments of LensFlare3D, in place of the one it had
@@ -10219,7 +10244,8 @@ 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 too far off the screen for the flare to show, a third of the screen past its edge, where nothing is tested
+     *   sun is too far off the screen for the flare to show, about a seventh 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
@@ -10262,7 +10288,7 @@ 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 but its lamp, a mesh around it no wider than half its radius, and a spotlight's
+         *  in front of the light but its lamp, a mesh around it whose surface is near it, 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
@@ -10566,11 +10592,24 @@ declare module "littlejsengine" {
         duration: number;
     }
     /** Parse a model from GLB bytes or glTF JSON, fetching the buffers and images it refers to
+     *  - A .gltf names its .bin and image files, which are fetched from baseUrl, or found among files: what a game
+     *    has in hand, like the files dropped on the page, by their paths in the drop; with files, baseUrl is the
+     *    .gltf's own folder among them ('' or 'models/house/'), its names are read from there, and a name found nowhere
+     *    there is taken by its file name alone only when one file of the drop has it; only an http, https or blob uri
+     *    is fetched then
+     *  - A file the model needs that is not found is named in the error, and an image that can not be read is named in
+     *    a warning and left out
      *  @param {ArrayBuffer|Object|string} data - GLB bytes, or the glTF JSON as bytes, text or an object
      *  @param {string} [baseUrl] - Where the .bin and image files are, with its trailing slash; loadGLTF passes the file's folder
+     *  @param {Map<string, Blob>} [files] - The files it refers to, by their paths, in place of fetching them
      *  @return {Promise<GLTFModel>}
+     *  @example
+     *  // the files of a drop, a .gltf with its .bin and textures, by their names
+     *  const files = new Map([...dataTransfer.files].map((file)=> [file.name, file]));
+     *  const gltf = [...files.values()].find((file)=> file.name.endsWith('.gltf'));
+     *  const model = await parseGLTF(await gltf.text(), '', files);
      *  @memberof GLTF */
-    export function parseGLTF(data: ArrayBuffer | any | string, baseUrl?: string): Promise<GLTFModel>;
+    export function parseGLTF(data: ArrayBuffer | any | string, baseUrl?: string, files?: Map<string, Blob>): Promise<GLTFModel>;
     /** Load a glTF or GLB model, the .bin and images of a .gltf from beside it
      *  - A texture only OPAQUE materials use loads with its alpha set to 1, so the 3D pass cuts no holes in it
      *  @param {string} url
@@ -10831,6 +10870,7 @@ declare module "littlejsengine" {
      * - Animation frames keep layout and wrap across rows as needed
      * - WebGL textures upload once per batch of loads
      * - loadAtlas imports pre-packed atlases (TexturePacker and Aseprite json)
+     * - loadTiles packs separate tile images, or several tile sheets, into one tile set for tile layers and maps
      * @namespace TextureSheets
      */
     /** Width and height in pixels of texture sheets created by loadSprite
@@ -10901,6 +10941,7 @@ declare module "littlejsengine" {
      *  - 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
+     *  - The same image loaded again with the same settings gives back what the first load did, packed once
      *  @param {string} src - Image source path
      *  @param {Vector2|number} [frameSize] - Size of each animation frame in pixels, or the whole image less its
      *  source padding if not passed
@@ -10912,6 +10953,28 @@ declare module "littlejsengine" {
      *  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 | Vector2): TileInfo;
+    /** Load tile images and pack them into texture sheets as one tile set, for tile layers and maps
+     *  - Each image is cut into tiles of tileSize, left to right then down, so an image of one tile is one tile and a
+     *    sheet is all of its tiles; the tiles are numbered from 0 in the order the images are given
+     *  - Returns a tile set at once, a TileInfo whose tiles fill in as the images load; wait for them with spritesReady
+     *  - Give it to tileLayersLoad, a TileLayer or a TileCollisionLayer as its tile info: tile n draws tiles[n],
+     *    wherever it was packed, and the level editor's palette offers each of them; frame and index do not read the
+     *    list, use set.tiles[n] for one tile; make the layers after spritesReady, a layer made before draws nothing
+     *  - An image that is not a whole number of tiles gives the whole tiles in it; a sheet with gaps between its tiles
+     *    is not read, cut it into its tiles first
+     *  - An image that fails to load, or that no sheet can hold, adds no tiles and says so in the console, so the tiles
+     *    of the images after it move up
+     *  - The same images loaded again with the same settings give back what the first load did, packed once
+     *  @param {Array<string>} sources - Image source paths
+     *  @param {Vector2|number} [tileSize] - Size of a tile in pixels
+     *  @param {number} [padding] - How many pixels padding around each tile on the sheet
+     *  @return {TileInfo}
+     *  @example
+     *  const tiles = loadTiles(['grass.png', 'dirt.png', 'water.png', 'props.png'], 16);
+     *  await spritesReady();
+     *  tileLayersLoad(map, tiles); // tile 0 is grass, 1 dirt, 2 water, then the tiles of props.png
+     *  @memberof TextureSheets */
+    export function loadTiles(sources: Array<string>, tileSize?: Vector2 | number, padding?: number): 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
@@ -10919,6 +10982,7 @@ declare module "littlejsengine" {
      *  - Aseprite frame tags become animations, so do names like run_0, run_1
      *  - Trimmed frames are restored to their full source size when packed
      *  - Rotated frames are rotated back upright when packed
+     *  - The same atlas loaded again by its paths, with the same padding, gives back what the first load did, packed once
      *  @param {string} imageSrc - Atlas image path
      *  @param {string|Object} jsonSrc - Atlas json path, or already parsed json data
      *  @param {number} [padding] - How many pixels padding around each frame