littlejsengine 1.24.1 → 1.24.3

package/CHANGELOG.md

@@ -7,6 +7,79 @@ What changed in each release, newest first. Releases before 1.20.0 are on the
 
 Nothing yet.
 
+## 1.24.3 - 2026-10-03
+
+### Fixes
+
+- TypeScript: the d.ts keeps `undefined` where a value may be missing, so a game in strict mode can write `render3D.shader = undefined` and is told `light.flare`, `levelEditor.edit3D` or `uiSystem.keyInputObject` may be undefined; a game not in strict mode reads the same types as before
+- `box2d.boxCast` and `boxCastAll` say that they test each shape's bounding box, which can find an object near the corner of a turned box or a circle that the box does not touch
+- An image that failed to load gives tiles of no size, which draw nothing, where `tile()` gave NaN places in release builds and stopped debug builds at an assert; a texture slot never given an image still asserts in debug
+- A release build says when a sound, a `loadSprite` or a `loadAtlas` fails to load, as it did for textures and tile sets
+- A `Box2dObject` keeps one `pos` for life, moved in place each step as an EngineObject's is, so a camera holding it follows the body
+- `drawRectGradient` takes no size, as its docs say
+- A release build going on past an error logs each new error, not only the first, and an error every tick no longer runs the game at the screen's refresh rate
+- Under pointer lock a click is a press wherever the locked mouse was left, a letterbox bar too
+- A gamepad with no sticks keeps the one its d-pad stands in for, where its stick count flickered
+- A zzfx `Sound` made in a browser with no audio counts as loaded and plays nothing, where it threw
+- `glCompileShader`, `glCreateProgram` and `glCreateTexture` are typed as giving undefined with no WebGL
+- A release build going on past an error clears that frame's input, where a key press whose action threw was pressed again every frame
+- `loadSprite`, `loadTiles` and `loadAtlas` forget a load whose file failed, so loading it again tries again, where a failure once was kept for the session
+- glTF: a file the model names in subfolders is found when what is in its folder was dropped, not the folder, and a file found by its name alone may have capitals in it, where both said the file was not among those given; the 3D Mesh short keeps a dropped folder's name when other files come with it
+
+## 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 +89,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
@@ -2040,7 +2048,8 @@ box2d.raycast(start, end, includeSensors=false)    // Returns the closest Box2dR
                                                    // are passed through unless includeSensors
 box2d.raycastAll(start, end, includeSensors=false) // Every Box2dRaycastResult along the ray, nearest first
 box2d.boxCast(pos, size, includeSensors=false) / boxCastAll(pos, size, includeSensors=false) // An object, or all
-                               // of them, whose shapes overlap the box; sensors are passed through unless included
+                               // of them, whose shapes' bounding boxes overlap the box, so near the corner of a turned
+                               // box or a circle it can find one the box misses; sensors are passed through unless included
 box2d.circleCast(pos, diameter, includeSensors=false) / circleCastAll(pos, diameter, includeSensors=false) // The
                                // nearest object, or all of them, whose position is in the circle, wherever its shapes
                                // are; objects of only sensors are passed over unless included
@@ -2172,6 +2181,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 +2302,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