littlejsengine 1.23.1 → 1.24.1

package/CHANGELOG.md

@@ -0,0 +1,261 @@
+# LittleJS Changelog
+
+What changed in each release, newest first. Releases before 1.20.0 are on the
+[GitHub releases page](https://github.com/KilledByAPixel/LittleJS/releases).
+
+## Unreleased
+
+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
+
+- [3D Lens Flare](https://killedbyapixel.github.io/LittleJS/examples/?example=3D%20Lens%20Flare) - Now with hexagons, and flares on lamps as well as the sun
+- [Text](https://killedbyapixel.github.io/LittleJS/examples/?example=Text) - What drawText can do: sizes, outlines, alignment, fonts, rows and text placed in pixels
+- [Physics](https://killedbyapixel.github.io/LittleJS/examples/?example=Physics) - The engine's own objects falling, bouncing, sliding and floating, and a sensor
+- [Random](https://killedbyapixel.github.io/LittleJS/examples/?example=Random) - Random numbers, and a seeded generator that gives the same result every time
+
+### New Changes
+
+- Every short example has a write-up in the example browser: what it shows, how its code works, things to try in the editor and where to look next, with links to the docs and to other examples
+- Lens flares on lights: `light.addFlare()` gives a `Light3D` a lens flare of its own and returns it, `light.flare` is the flare, and it goes with the light; a `DirectionalLight3D` can have one too, far away like the sun's
+- 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, 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
+
+### Breaking Changes
+
+- ZzFXM, the tracker music plugin, is removed: it was made for the js13k size limit. A game with a song in that format includes ZzFXM itself and hands its samples to a `Sound`
+- 3D picking hits only the faces that are drawn: a mesh seen from inside is no longer hit unless it is `doubleSided`
+- `LensFlare3D`: `getSunScreenPos` is now `getScreenPos` and `isSunHidden` is now `isHidden`, since a flare may be a light's; `visible` is 0 while the sun is off the screen; a flare pointed at a light is destroyed with it
+- The repository's `dist/` is now the last release, not the latest source: it is committed only for a release, and the site is built from the source
+
+### Fixes
+
+- A lens flare that is off the screen, or of a light that is off, no longer looks for what hides it every frame
+- 3D level editor: an edit of a level's scene, or its undo, no longer takes away a sun lens flare that an earlier level's scene gave the game
+- Shorts: the lander lands upright after a full turn, the maze reaches its top row and works at even sizes, a pocketed cue ball comes back, the 3D Voxels player floats in water, and more that writing them up turned up
+
+## 1.23.1 - 2026-10-02
+
+### New Changes
+
+- 3D sprites are batched: an object with a tile and no mesh, or a `drawBillboard`, that is not transparent is drawn as one instanced batch with the other sprites of its sheet, its clear pixels cut out, so many sprites cost little; transparent and additive sprites still draw sorted, one by one
+- A level's block map works in a game with no images: it shows plain colored blocks, where it used to fail
+- glTF: emission stronger than 1 from Blender is read (`KHR_materials_emissive_strength`), a texture is smooth or pixelated as its sampler says whatever the game's tiles are, and a model with basis textures says they are not read
+- The 2D level editor keeps the last 100 undo steps, as the 3D one does
+- The npm package and the release zip include REFERENCE.md and EDITOR.md
+- EDITOR.md says how to keep a level as a script for a game opened from disk, and what changing the editors' own tools takes
+- The deprecated names from 1.20 are kept until 1.25 at least
+
+### Fixes
+
+- A UI button pressed and released inside one frame was clicked twice
+- `drawRegularPoly`, and circles with `setGLCircleSides`, hung on a side count that was not a whole number
+- 2D level editor: a click on an object no longer rewrites its position with rounding noise and adds an undo step; applying saved edits to a file that gained an object layer leaves that layer alone; a level whose url has a `%20` in it matches its file again
+- 3D level editor: saves of a prefab are written in the order they were asked for when `onSave` is async, a prefab edit that was undone no longer comes back after a reload, and objects a game's tool adds without ids get ids
+- An attached prefab inside another prefab is placed where it belongs, and its collision box follows parts that are turned
+- `levelEditor.onSave` may be an async function in TypeScript too
+- 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
+
+### New Demos
+
+- [3D Prefab Maker](https://killedbyapixel.github.io/LittleJS/examples/?example=3D%20Prefab%20Maker) - Build a prefab in the level editor and save it for a game to place
+- [3D Level Editor](https://killedbyapixel.github.io/LittleJS/examples/?example=3D%20Level%20Editor) - Now makes prefabs, flattens and paints terrain, and fills boxes of blocks
+- [Parallax](https://killedbyapixel.github.io/LittleJS/examples/?example=Parallax) - Rebuilt on the new parallax plugin, with ranges of mountains that repeat as the camera goes by
+
+### New Changes
+
+- 3D prefabs: a prefab is a small level placed many times. `level3DAddPrefab('House', data)` makes it a type, a level places it like a Box, and `level3DSpawn` places one from code; each part is a solid object of its own, or with `attached` the parts move with the instance as one body, for a vehicle or a creature
+- The 3D level editor is the prefab editor too: Ctrl+G makes the selection a prefab, Enter opens one to edit it alone and every instance follows, Ctrl+Shift+G unpacks one, and the panel exports a prefab to a file and loads one from a file; prefabs can hold prefabs, and are saved in the level
+- Make the level editors your own: `levelEditor.addKey`, `addButton` and `addTool` add a key, a panel button and a mouse tool of your game's own, `onOpen`, `onUpdate`, `onDraw`, `onPanel` and `onSave` are called by the editors, and `levelEditor.edit2D` and `edit3D` are the edit functions, each change an undo step. The same calls work in the 2D and the 3D editor
+- Or extend it: `class MyEditor extends LevelEditor` with the hooks as methods, then `setLevelEditor(new MyEditor)`. Release builds take all of it and call none of it, so a game needs no guards
+- New guide, [EDITOR.md](https://github.com/KilledByAPixel/LittleJS/blob/main/EDITOR.md): how to turn the built-in editors into an editor for your own game, written for people and AI assistants, with every example tested
+- Added the Parallax plugin: a `ParallaxLayer` follows the camera by a part of its movement and repeats across the view, so a level of any width has a background; it draws mountains by default, or anything you draw into it
+- Touch has a mouse wheel: a pinch of two fingers turns `mouseWheel`, so what zooms with the wheel zooms with a pinch, and `touchPinch` reads it by itself
+- 3D level editor: the Terrain tool has a flatten brush and a paint brush that colors the ground, the Blocks tool fills a box with a drag and resizes its map, and the Move handles can follow an object's own axes (L)
+- A `LensFlare3D` can be a light's flare: set `flare.light` and it sits at the lamp, in its color, hidden by what is in front of it
+- The example browser has Prev and Next buttons, to go through the examples on a phone
+- `Sound.range` can be set after a sound is made, and 3D sounds use it
+- Size: the full build is about 122 KB gzipped, up from 119 KB; a bundler like Vite leaves out the plugins you don't use
+- Fixes: a `SpriteAnimator` clip that ends and switches clips reads the new clip, glass and water blocks no longer hide the sun's lens flare, 3D particles appear at once like 2D ones, a spotlight that casts shadows lights no wider than its shadow map, the 3D editor's Scene box no longer undoes a field edited just before, and the example browser always shows the example picked last; the test suite grew from 1724 to 1848 tests
+
+### Upgrade Notes
+
+- With two fingers down the touch screen pinches: the second finger lets go of the button the first one pressed. A game that uses two fingers its own way calls `setTouchPinchWheel(false)` to get the old behavior back
+- A `ParticleEmitter3D` makes its first particle at once, where it used to wait one emit interval
+- A spotlight set as `render3D.shadowLight` has its cone capped at 1.35 radians, what its shadow map covers
+- `levelEditor.onRestart`, `onPlayFrom` and `onTile` are set the same way as before, but they are now empty methods when a game has not set them, so `if (levelEditor.onRestart)` is always true; nothing in a game needs to read them
+- The Parallax short moved to the plugins section, and the platformer example uses the plugin for its mountains
+- These names changed in 1.20 and the old ones still work for now: `collideTiles` is now `collideLevel`, and `Box2dWeldJoint.setSpringDampingRatio` is now `setDampingRatio`
+
+## 1.22.0 - 2026-10-01
+
+### New Demos
+
+- [Particle Effects](https://killedbyapixel.github.io/LittleJS/examples/?example=Particle%20Effects) - Every built-in particle effect, one line each
+- [Particle Options](https://killedbyapixel.github.io/LittleJS/examples/?example=Particle%20Options) - One effect, and what each option does to it
+- [3D Lens Flare](https://killedbyapixel.github.io/LittleJS/examples/?example=3D%20Lens%20Flare) - The sun flares across the screen and hides behind pillars
+- [3D First Person](https://killedbyapixel.github.io/LittleJS/examples/?example=3D%20First%20Person) - Now with a night, and a flashlight that casts the shadows
+- [3D Level Editor](https://killedbyapixel.github.io/LittleJS/examples/?example=3D%20Level%20Editor) - Now paints blocks, sculpts terrain and sets the sky, sun and fog
+- [Tween Advanced](https://killedbyapixel.github.io/LittleJS/examples/?example=Tween%20Advanced) - Every tween feature in labeled rows
+- [Particle Designer](https://killedbyapixel.github.io/LittleJS/examples/particles/) - Rebuilt on the effects library, with a 3D preview
+
+### New Changes
+
+- Added the Particle Effects plugin: `particleEffect('fire', pos)` plays one of 24 built-in effects in one line, and `particleEffect3D` plays the same effect in 3D; the options scale it, turn its hue, change its saturation, swap in your own tile, or replace any setting, like `{emitTime: .5}` for a burst
+- The built-in effects are fire, torch, smoke, steam, explosion, sparks, hit, dust, debris, sparkle, magic, heal, poison, portal, rain, snow, leaves, bubbles, fireflies, trail, muzzle, blood, confetti and splash, each sized to fit a one unit object and drawn with shapes the plugin makes itself, so they need no image
+- The Particle Designer is rebuilt on the plugin: the built-in effects are its presets, Save Library writes the file `particleEffectsLoad` reads so a game plays your effects by name, and it previews an effect in 2D or 3D with the same options a game passes
+- `ParticleEmitter` has `scale`, which grows a whole effect, and `gravity`, its own fall; `ParticleEmitter3D` has `gravityScale` and `emitFlat`, which makes its spawn area a disc or a flat sheet
+- 3D level editor: the Blocks tool (B) paints a level's block map, the Terrain tool (T) sculpts its terrain with a brush, and the Scene box sets its sky, sun, fog and shadows; all three are saved in the level's JSON, undo and autosave with the rest, and `level3DLoad` makes them with no game code
+- Spotlights: a `Light3D` with a `coneAngle` shines along its own forward, with `coneSoftness` for where the fade starts, and `render3D.shadowLight` makes one spotlight cast the shadows in place of the sun, for a flashlight in the dark
+- Added `LensFlare3D`, the sun's lens flare: a glow at the sun and a row of discs and rings across the screen, with its size, count, brightness and colors to set, fading out when something hides the sun
+- 2D lights glow like the 3D ones: `light.glow` and `glowFalloff` on a `Light` of the light system
+- Built-in post processing effects: `postProcessEffects` joins scanlines, noise, vignette, curve, chromatic, glow and a 3D outline into one shader, with your own GLSL as a piece too
+- A texture can be smooth or pixelated on its own: `TextureInfo` takes `pixelated`, and `setPixelated` changes it
+- Textures the engine sizes itself, like the shadow maps, fall back to the largest size a device supports; `glClampTextureSize` does the same for your own
+- Faster: particles draw about 30% faster, `InstancedMesh3D` moves many instances with `setTransforms` and uploads less, the 3D draw state is checked with one number per draw, and ZzFX 1.4.0 generates sounds faster
+- `render3D.playSound` hears a sound with no range of its own out to `render3D.soundDefaultRange`, 100 units
+- Added a browser smoke suite, `npm run test:browser`: real WebGL in headless Chrome checks 2D draws, shaders, the 3D pass, spotlights, the lens flare, a lost and restored context, and that every short runs
+- Size: the full build is about 119 KB gzipped, up from 108 KB; a bundler like Vite leaves out the plugins you don't use
+- Fixes: post process feedback keeps the previous frame again, `loadGLTF` follows redirects and takes blob and data urls, overlapping Saves in the level editors write in order, and a scene `leave` that throws no longer blocks later switches; the test suite grew from 1562 to 1724 tests
+
+### Upgrade Notes
+
+- A sound with no range of its own is now heard to 100 units when played with `render3D.playSound`, where it was 40; pass a range to `new Sound`, or set `render3D.soundDefaultRange`, to change it. 2D sounds are unchanged
+- `particleEffect3D` and the particle designer's files use the plugin's effect format; an effect saved by the older designer still loads and keeps its tile
+- The light system writes the sizes it could make back to `shadowMapSize`, `shadowTextureSize` and `textureSize` when a device can not make the size asked for
+- The engine's own soft textures, the light glow and the particle shapes, are smooth even when `tilesPixelated` is on
+- The Tween System and Stress Test full examples are gone, the Tween Advanced short covers tweens
+- These names changed in 1.20 and the old ones still work for now: `collideTiles` is now `collideLevel`, and `Box2dWeldJoint.setSpringDampingRatio` is now `setDampingRatio`
+
+## 1.21.0 - 2026-09-29
+
+### New Demos
+
+- [3D Level Editor](https://killedbyapixel.github.io/LittleJS/examples/?example=3D%20Level%20Editor) - Place boxes, lights and coins, then walk around
+- [3D Materials](https://killedbyapixel.github.io/LittleJS/examples/?example=3D%20Materials) - Bricks from a normal map made in code, a polished ball reflecting the sky, and glowing windows
+- [3D Ambient Occlusion](https://killedbyapixel.github.io/LittleJS/examples/?example=3D%20Ambient%20Occlusion) - Creases and corners darkened from the new depth texture, side by side with plain
+- [3D Water](https://killedbyapixel.github.io/LittleJS/examples/?example=3D%20Water) - Rain on a pool, its waves a cellular automaton, reflecting the sky
+- [Scenes](https://killedbyapixel.github.io/LittleJS/examples/?example=Scenes) - A title, a game with a pause overlay and game over, switched with `setScene`
+- [Animation](https://killedbyapixel.github.io/LittleJS/examples/?example=Animation) - Sprite animation, with clips switched by name
+- [3D Lights](https://killedbyapixel.github.io/LittleJS/examples/?example=3D%20Lights) - The lamps now glow
+
+### New Changes
+
+- Added the 3D Level Editor, in debug builds only: press 0 on the debug overlay in a game that loaded a 3D level to pause it and place, move, rotate and scale its objects with handles, grid and ground snapping, undo, autosave, Save back to the level's JSON file and Reset to file
+- 3D levels: `level3DAddType`, `level3DAddMesh` and `level3DLoad` make a level's objects from plain JSON, with Box, Sphere, Cylinder and Light built in
+- Added a free camera, in debug builds only: press C on the debug overlay to fly around the running game while it reads no keyboard or mouse (`inputCapture`)
+- 3D materials: `normalMap` and `normalScale` bend the surface with no tangents needed, `normalMapFromHeight` makes a normal map in code, `shininess` sets the highlight's size, `reflectivity` reflects the sky with a Fresnel edge, and `emissiveMap` with `emissiveMapColor` makes parts of a surface glow; glTF models bring their normal and emissive textures
+- Turned boxes collide as turned: a box with a `rotation3D` collides as the box you see, so ramps, tilted platforms and turned walls just work, and the 3D box helpers take an optional rotation
+- Standing in 3D: resting on another object sets `groundObject`, and `groundAngle` (45 degrees by default) is the steepest slope an object stands on without sliding
+- The 2D physics settings work in 3D: `damping`, `angleDamping`, `friction` on the ground (a moving platform carries what rides it) and `clampSpeed`
+- Added `render3D.depthTexture`: the post process shader gets the 3D depth as `iChannel2` and reads it with `sceneDepth(uv)`, for ambient occlusion, fog and outlines
+- `Light3D` has a soft hazy `glow`, with `glowFalloff` for how fast it fades
+- 3D particles have the 2D emitter's callbacks, `particleCreateCallback`, `particleUpdateCallback`, `particleCollideCallback` and `particleDestroyCallback`, and `collideLevel` to bounce off height maps and voxel maps
+- Added a loading screen: after the splash, startup waits for the images, `gameInit` and everything loaded while it runs, and shows a loading bar if that takes more than half a second; `setLoadingScreen` draws your own, and `engineAddLoad` adds anything else you load
+- Added the Scene plugin: `setScene` and `getScene` switch between scenes with enter, leave, update and render hooks, clearing all but persistent objects
+- Added `setEngineVariableStep`: one update per display frame with `timeDelta` the frame's time, and frame times are smoothed to whole display frames in both modes
+- `SpriteAnimation.play(onEnd)` calls back when a play ends, and `SpriteAnimator` switches a character's clips by name
+- A mesh with `dynamicDraw` uploads faster, and `levelEditor.paletteTiles` picks the tiles the 2D level editor's palette shows
+- Size: the full build is about 107 KB gzipped, up from 100 KB; a bundler like Vite leaves out the plugins you don't use
+- Fixes: three external review passes and their fixes, and the test suite grew from 1313 to 1562 tests
+
+### Upgrade Notes
+
+- `clampSpeed` now only holds an object to `objectMaxSpeed` (1 unit a frame per axis) while it collides, with solids, or with tiles or the level while it has a mass, in 2D and 3D; something that does not collide, like a bullet you move yourself, now moves at its full speed instead of being slowed
+- In 3D, colliding objects are now held to `objectMaxSpeed`; set `clampSpeed = false` on fast colliding things, as in 2D
+- In 3D, an object standing on something now slows by `friction`, 0.8 by default; set `friction = 1` for none
+- In 3D, `damping` now slows objects with no mass too, and `angleDamping` slows `angleVelocity3D`; both are 1 by default, so nothing changes unless you set them
+- A turned 3D solid now collides as turned, so a spinning solid sweeps what it touches; sprites still collide upright
+- `engineObjectsCollect3D` finds a turned object by its turned box
+- The game loop now starts once `gameInit` and everything loaded while it ran are done, sounds from files included; call `setLoadingScreen()` to turn the loading screen off
+- These names changed in 1.20 and the old ones still work until 1.22: `collideTiles` is now `collideLevel`, and `Box2dWeldJoint.setSpringDampingRatio` is now `setDampingRatio`
+
+## 1.20.0 - 2026-09-28
+
+### New Demos
+
+- [3D Voxels](https://killedbyapixel.github.io/LittleJS/examples/?example=3D%20Voxels) - Walk, jump, dig and build in a little Minecraft style world
+- [3D Mesh Operations](https://killedbyapixel.github.io/LittleJS/examples/?example=3D%20Mesh%20Operations) - Bevels, CSG cuts, mirror and spin
+- [3D Sync 2D](https://killedbyapixel.github.io/LittleJS/examples/?example=3D%20Sync%202D) - A 2D platformer with 2D physics and tile collision, drawn in 3D
+- [3D Mesh](https://killedbyapixel.github.io/LittleJS/examples/?example=3D%20Mesh) - Load an OBJ or glTF model, or drop one in
+- [Level Editor](https://killedbyapixel.github.io/LittleJS/examples/?example=Level%20Editor) - Paint a level and place objects, then play it
+- [Platformer](https://killedbyapixel.github.io/LittleJS/examples/platformer/) - Press Esc then 0 to open the level editor on a real game
+- [Light Shadows](https://killedbyapixel.github.io/LittleJS/examples/?example=Light%20Shadows) - Lights blocked by walls and tinted by glass
+- [Particle Designer](https://killedbyapixel.github.io/LittleJS/examples/particles/) - Reworked, with an effect library, presets and code export
+- [Tweakables](https://killedbyapixel.github.io/LittleJS/examples/?example=Tweakables) - Change values live from a debug panel
+- [UI Tile Slice](https://killedbyapixel.github.io/LittleJS/examples/?example=UI%20Tile%20Slice) - UI styled with nine-slice and tile art
+
+### New Changes
+
+- Added the Level Editor, in debug builds only: press 0 on the debug overlay to pause the game and paint its Tiled tile layers, with stamps, fill, selections, undo and redo, then Escape to play and edit again
+- The level editor places objects too: `objectLayersAddType` names your object classes, `objectLayersLoad` makes them from a Tiled object layer, and their properties are edited in the panel
+- It saves straight back to the level's Tiled JSON file where the browser allows it (Chrome and Edge), autosaves every change, and has `levelEditor` hooks for restart, play from the mouse, resizing and your own tile rules
+- Added the Tweakables plugin: `tweak()` puts any value on a debug panel (press 9) with sliders, checkboxes, colors and buttons
+- Added `VoxelMap`, a grid of blocks drawn in chunks with hidden faces left out, per face tiles, see-through and blending blocks, corner shading, collision and a grid raycast for digging and building
+- Level collision in 3D: objects with `collideLevel` land on and are stopped by height maps and voxel maps, `groundObject` says what they stand on, and `FirstPersonCamera3D` can jump (`jumpSpeed`) and set its `eyeHeight`
+- `HeightMap` is now an object that draws itself, with world space lookups wherever it is placed
+- Mesh operations: bevels and chamfers on the box, cylinder and cone builders, `mirror` and `spin`, and CSG `union`, `subtract` and `intersect`
+- Added the glTF plugin: `loadGLTF` and `parseGLTF` load .gltf and .glb models with textures, node animations, WebP images and glass
+- `InstancedMesh3D` keeps a set of instances on the GPU and draws them as one call, meshes upload as indexed triangle lists, and particles and objects allocate nothing per frame
+- 3D lighting: the sky lights the scene from above and below, and `Light3D` point lights make specular highlights
+- `sync2D` 3D objects start at their 3D position, so a 2D game with 3D looks just works
+- Light System: lights are blocked by shadow casters, colored glass tints what passes through, and `emissive` objects glow in the dark
+- Added `drawScreenSpace`, a setting that makes the draw functions default to screen space, for HUDs or a 3D game's 2D overlay
+- `TileSlice` draws a tile as a nine-slice, three-slice or plain box, and the UI system can style its widgets with tile art
+- Tiled maps keep their flipped and turned tiles, and the debug overlay's new Debug Tiles view (key 8) shows each tile layer's bounds and collision
+- The particle designer was rebuilt with an effect library, presets, grouped settings and code export, and `particleUpdateCallback` runs for each particle
+- The Newgrounds plugin was rewritten: medals unlock on the server, leaderboards work for guests too, and it uses the browser's WebCrypto with no dependencies
+- The example tile sheets now have a 1 pixel border around each tile, with `setTileDefaultPadding(1)`, and the starter builds its level from a string you can edit
+- Release builds no longer evaluate assert arguments, and `RandomGenerator` gives unrelated values for nearby seeds
+- Size: the core engine is about 36 KB gzipped and every build includes the plugins; a bundler like Vite leaves out the ones you don't use, so a small 2D game is about 26 KB and a lit 3D scene about 47 KB
+- Fixes: fifteen review passes fixed hundreds of bugs across the engine and plugins, the engine and plugins type check clean, and the test suite grew from 570 to 1313 tests
+
+### Upgrade Notes
+
+- These names changed in 1.20 and the old ones still work until 1.22:
+  - `collideTiles` is now `collideLevel`
+  - `Box2dWeldJoint.setSpringDampingRatio` and `getSpringDampingRatio` are now `setDampingRatio` and `getDampingRatio`
+  - `NewgroundsPlugin.logView()` does nothing, since the view is logged on start
+  - `drawNineSliceScreen` and `drawThreeSliceScreen` take a color after the start tile, before the border size; a number there still reads the old order
+- `setCollision()` now turns on level collision for 3D objects
+- A `HeightMap` draws itself, so remove any separate object you made to draw its mesh, and `terrain.size` is now `terrain.mapSize`
+- A flat `buildGrid` is flat shaded unless you pass `smooth`
+- The example tile sheets changed layout; if you copied `tiles.png` from an example, use it with `setTileDefaultPadding(1)`

package/COPYRIGHT.txt

@@ -36,30 +36,3 @@ appreciated but is not required.
 2. Altered source versions must be plainly marked as such, and must not be
 misrepresented as being the original software.
 3. This notice may not be removed or altered from any source distribution.
-
--------------------------------------------------------------------------------
-
-ZzFXM License
-
-The ZzFXM plugin (plugins/zzfxm.js) is a port of ZzFXM, the Zuper Zmall Zound Zynth music player.
-https://github.com/keithclark/ZzFXM
-
-Copyright (c) 2020 Keith Clark, Frank Force
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/FAQ.md

@@ -261,7 +261,6 @@ Plugins are self-contained features that live alongside the engine but aren't pa
 | `tweakables.js` | A debug panel to change values live while the game runs, press 9 with the debug overlay open |
 | `medalSystem.js` | Achievement / medal tracking with popup notifications |
 | `newgrounds.js` | Newgrounds.io integration (medals held on the server, scoreboards) |
-| `zzfxm.js` | Procedural chiptune music via the `ZzFXMusic` class |
 | `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 |
 
@@ -365,7 +364,7 @@ LittleJS has a dedicated [js13k branch](https://github.com/KilledByAPixel/Little
 
 - **Use Canvas2D instead of WebGL**: call `setGLEnable(false)` before `engineInit`. Stripping the WebGL renderer saves a significant chunk of bytes, and for most pixel-art and low-sprite-count games the visual difference is imperceptible. A nice side effect: once the jam is over, you can flip WebGL back on with a single setting change for a big performance boost when publishing the game elsewhere.
 - **Drop unused plugins**: every plugin is self-contained, so only include what you actually use. Skip `uiSystem.js`, `box2d.js`, `pathFinder.js`, etc. unless you need them.
-- **Lean on built-ins to avoid asset files**: `Sound` with ZzFX parameters generates sound effects from a tiny array, `ZzFXMusic` makes procedural chiptunes, and built-in shape drawing avoids shipping image assets.
+- **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.
@@ -538,19 +537,15 @@ sound_click.play(pos, volume, pitch); // play a sound
 
 ### How do I play music?
 
-For procedural chiptune music, use the `ZzFXMusic` class from the [ZzFXM plugin](plugins/zzfxm.js). It extends `Sound` and accepts a ZzFXM-format song array — the music is generated on the fly so it adds essentially no bytes to your build. For longer scored music, load an mp3 or ogg file with the regular `Sound` class and play it with `playMusic`, which loops by default.
+Load an mp3 or ogg file with the regular `Sound` class and play it with `playMusic`, which loops by default.
 
 ```javascript
-// procedural ZzFXM music (tiny, generated at runtime)
-const song = new ZzFXMusic(zzfxmSongData);
-const songInstance = song.playMusic();
-
-// or load an mp3/ogg and loop it
+// load an mp3/ogg and loop it
 const track = new Sound('music.mp3');
 const trackInstance = track.playMusic(1, true); // volume, loop
 ```
 
-Both pause automatically when the tab loses focus (audio context suspends) and resume when it comes back. `playMusic` returns a `SoundInstance`; keep it and call `songInstance.stop()` to halt playback.
+Music pauses automatically when the tab loses focus (audio context suspends) and resumes when it comes back. `playMusic` returns a `SoundInstance`; keep it and call `trackInstance.stop()` to halt playback.
 
 ### Why doesn't my audio play until the user clicks something?
 

package/README.md

@@ -25,7 +25,7 @@ The code is very clean and well documented with many examples to get you started
 
 <div align='center' markdown='1'>
 
-## [Demos](https://killedbyapixel.github.io/LittleJS/examples) | [Arcade](https://killedbyapixel.github.io/LittleJSArcade) | [Docs](https://killedbyapixel.github.io/LittleJS/docs) | [FAQ](https://github.com/KilledByAPixel/LittleJS/blob/main/FAQ.md) | [Trailer](https://youtu.be/chuBzGjv7Ms) | [Discord](https://discord.gg/zb7hcGkyZe)  | [AI](https://github.com/KilledByAPixel/LittleJS-AI)
+## [Demos](https://killedbyapixel.github.io/LittleJS/examples) | [Arcade](https://killedbyapixel.github.io/LittleJSArcade) | [Docs](https://killedbyapixel.github.io/LittleJS/docs) | [Reference](https://github.com/KilledByAPixel/LittleJS/blob/main/REFERENCE.md) | [FAQ](https://github.com/KilledByAPixel/LittleJS/blob/main/FAQ.md) | [Trailer](https://youtu.be/chuBzGjv7Ms) | [Discord](https://discord.gg/zb7hcGkyZe)  | [AI](https://github.com/KilledByAPixel/LittleJS-AI)
 
 </div>
 
@@ -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
@@ -140,9 +140,10 @@ engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost);
 - [Making Awesome Games With LittleJS](https://youtu.be/_dXKU0WgAj8) - A short talk about LittleJS with some tips on how to use it
 - [Tutorial: Breakout](https://github.com/KilledByAPixel/LittleJS/tree/main/examples/breakoutTutorial) - Learn how to make a simple game from scratch
 - [Tutorial: Make a ski game](https://eoinmcgrath.com/little-ski/tutorial.html) - A tutorial by eoinmcg that shows how to make a pixel art style game
-- [LittleJS Quick Reference Sheet](https://github.com/KilledByAPixel/LittleJS/blob/main/REFERENCE.md) - A reference sheet to help you get started
+- [LittleJS Quick Reference Sheet](https://github.com/KilledByAPixel/LittleJS/blob/main/REFERENCE.md) - The whole API in one file, made to be read by people and by AI coding tools
 - [Making Your Own Level Editor](https://github.com/KilledByAPixel/LittleJS/blob/main/EDITOR.md) - How to turn the built in 2D and 3D level editors into an editor for your own game
 - [LittleJS FAQ](https://github.com/KilledByAPixel/LittleJS/blob/main/FAQ.md) - Answers to common questions about LittleJS
+- [Changelog](https://github.com/KilledByAPixel/LittleJS/blob/main/CHANGELOG.md) - What changed in each release
 - [JS13k Branch](https://github.com/KilledByAPixel/LittleJS/tree/js13k) - A special branch for size coding events that builds to a 7KB zip
 
 ## Examples

package/REFERENCE.md

@@ -403,7 +403,6 @@ glDraw(x, y, sizeX, sizeY, angle=0, uv0X, uv0Y, uv1X, uv1Y, rgba=-1, rgbaAdditiv
 - Ability to play mp3, ogg, and wave files
 - Route sounds or everything through effects with the audio effects plugin
 - [ZzFX Sound Effect Generator](https://killedbyapixel.github.io/ZzFX)
-- [ZzFXM Music System](https://keithclark.github.io/ZzFXM)
 
 ```javascript
 // Sound Object
@@ -435,10 +434,6 @@ SoundInstance.getDuration()       // Length of the sound, the same at any rate;
 SoundInstance.getSource()         // Get AudioBufferSourceNode
 SoundInstance.onendedCallback     // Called when it plays to its end, not on stop or pause; set it any time
 
-// ZzFXM - Tiny music playing system
-ZzFXMusic(zzfxMusic)                                 // Create a zzfx music object
-ZzFXMusic.playMusic(volume=1, loop=true, paused=false) // Play the music, it is a Sound so play and playLoop work too
-
 // Audio functions
 speak(text, volume=1, rate=1, pitch=1, language='')  // Speak text line
 speakStop()                                          // Stop all queued speech
@@ -722,10 +717,20 @@ 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
+                                                    // hidden layers load with collision but are not drawn; a
+                                                    // tileset in the map with a margin or spacing is read where
+                                                    // 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 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),
                                                     // defaults set on what it made; tileInfo is an editor icon
@@ -1263,8 +1268,9 @@ render3D.screenToRay(screenPos, canvasSize)  // Ray3D under a screen point, alwa
                                      // date for it, so worldToScreen keeps agreeing with them
 render3D.screenToGround(screenPos, groundHeight=0, canvasSize) // where that ray meets a flat ground plane, or
                                                    // undefined; terrain has HeightMap.raycast
-render3D.pick(screenPos or ray, objects)           // {object, distance} of the nearest object hit, the box of its mesh
-                                                   // or a sprite's size3D; a screen position goes through screenToRay
+render3D.pick(screenPos or ray, objects)           // {object, distance} of the nearest object hit, on its mesh's
+                                                   // triangles, the faces that show, both sides when doubleSided,
+                                                   // or a sprite's quad; a screen position goes through screenToRay
 render3D.soundDefaultRange = 100      // how far a sound with no range of its own is heard in 3D, the 2D
                                       // soundDefaultRange is 40; a Sound made with a range keeps it
 render3D.playSound(sound, pos3D, volume, pitch, randomnessScale, loop, paused) // like sound.play(pos): quieter with
@@ -1744,14 +1750,22 @@ new LensFlare3D(size=1, count=7, intensity=1, saturation=1, color) // the sun's
                                   // screen; it fades as the sun leaves the screen or goes behind something
 flare.flareSize = 1.5             // scales every part; count is how many ghosts, intensity how bright, saturation
                                   // how colorful, 0 all its own color; seed picks another arrangement
-flare.elements = [{at: .5, size: .1, color: hsl(.6,1,.6,.3), shape: 'disc'}] // or parts of your own: at 0 the sun,
-                                  // 1 the middle, 2 as far past it; size a part of the screen's height; shape
-                                  // glow, disc or ring
+flare.shapes = ['hex', 'streak']  // what the ghosts are picked from: glow, disc, ring, hex, streak or star; glowSize
+                                  // scales the glow at the sun, 0 for none, and ghostSize the ghosts
+flare.elements = [{at: .5, size: .1, color: hsl(.6,1,.6,.3), shape: 'disc'}] // or parts of your own, each a
+                                  // LensFlareElement: at 0 the sun, 1 the middle, 2 as far past it; size a part of
+                                  // the screen's height, or a vec2 for a wide one; shape one of the six, or
+                                  // 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
-flare.light = lamp                // the flare of a Light3D in place of the sun's: at the light, in its color,
-                                  // smaller from farther than its radius, hidden by what is in front of it; a
-                                  // spotlight's shows from inside its beam only
+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
+                                  // destroy it to take it away; it goes with the light; a level's Light has a
+                                  // lensFlare property
+flare.light = lamp                // the same by hand, a flare made on its own and pointed at a light; it goes when
+                                  // the light does; a DirectionalLight3D's flare is far away, where it shines from
 // Trails - a ribbon through where the object has been, parent it to something that moves
 new Trail3D(pos3D, lifeTime, width, tileInfo, color, colorEnd, additive) // thins and fades from head to tail over
                                                                          // lifeTime seconds; Infinity keeps every
@@ -1856,7 +1870,8 @@ level3DVoxelSetup(tileInfo, (map)=> {})           // The sheet a level's block m
            "sunDirection": [0.5, 1, 0.3], "sunColor": "#ffffff",
            "fog": [25, 70], "fogColor": "#d6ecff",    // start and end, an end of 0 for none; the horizon color
                                                       // when the level has a sky and no fogColor
-           "shadows": true},
+           "shadows": true,
+           "lensFlare": true},                        // the sun's lens flare, a LensFlare3D made for it
  "objects": []}
 
 // A level can hold a map of blocks, made a VoxelMap when it loads: its corner, its size in cells, and its blocks
@@ -1893,14 +1908,15 @@ prefab.originOffset                               // from the prefab's origin to
 // Built-in types and their properties
 Box, Sphere, Cylinder   // color, tile (-1 for none), solid (true); 1 unit across, the scale is the size
 Light                   // color, radius (5), intensity (1); cone (0), degrees from its forward to the edge of
-                        // its beam, makes it a spotlight aimed by its rotation, softness (.2), shadows (false)
+                        // its beam, makes it a spotlight aimed by its rotation, softness (.2), shadows (false);
+                        // lensFlare (false) gives it a lens flare
 ```
 
 ### 3D level editor
 Debug builds only. `0` on the debug overlay opens it for a level loaded with `level3DLoad`, the game pauses under it.
 To make it your own game's editor, with your own types, keys and panel buttons, see [EDITOR.md](EDITOR.md).
 The panel's Scene box edits the level's scene block: "Level sets the scene" starts one from what is on screen, and
-off leaves the sky, sun, fog and shadows to the game.
+off leaves the sky, sun, fog, shadows and lens flare to the game.
 
 ```javascript
 // Tools, the keys Unity, Unreal and Godot use