littlejsengine 1.23.0 → 1.23.1

package/COPYRIGHT.txt

@@ -1,38 +1,65 @@
-LittleJS Notices and Third-Party Licenses
-=========================================
-
-This repository is licensed under the MIT License. See the file LICENSE.
-
-This file collects copyright notices and third-party license texts for
-software included with or used by this repository. If you redistribute
-LittleJS with third-party components, keep the relevant notices below.
-
--------------------------------------------------------------------------------
-
-LittleJS Engine License
-
-Copyright (c) 2021 Frank Force
-http://www.frankforce.com
-Licensed under the MIT License. See LICENSE.
-
--------------------------------------------------------------------------------
-
-Box2D License
-
-Copyright (c) 2006-2013 Erin Catto http://www.gphysics.com
-
-This software is provided 'as-is', without any express or implied
-warranty.  In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-1. The origin of this software must not be misrepresented; you must not
-claim that you wrote the original software. If you use this software
-in a product, an acknowledgment in the product documentation would be
-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.
+LittleJS Notices and Third-Party Licenses
+=========================================
+
+This repository is licensed under the MIT License. See the file LICENSE.
+
+This file collects copyright notices and third-party license texts for
+software included with or used by this repository. If you redistribute
+LittleJS with third-party components, keep the relevant notices below.
+
+-------------------------------------------------------------------------------
+
+LittleJS Engine License
+
+Copyright (c) 2021 Frank Force
+http://www.frankforce.com
+Licensed under the MIT License. See LICENSE.
+
+-------------------------------------------------------------------------------
+
+Box2D License
+
+Copyright (c) 2006-2013 Erin Catto http://www.gphysics.com
+
+This software is provided 'as-is', without any express or implied
+warranty.  In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not
+claim that you wrote the original software. If you use this software
+in a product, an acknowledgment in the product documentation would be
+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/EDITOR.md

@@ -0,0 +1,359 @@
+# Making your own level editor with LittleJS
+
+LittleJS has two level editors built in, one for 2D tile maps and one for 3D levels. They are meant to be a
+starting point: a game adds its own object types, properties, keys, buttons and tools, and ends up with an
+editor made for that one game. Everything goes through one object, `levelEditor`, and the same calls work in
+both editors.
+
+This page is written to be followed by a person or by an AI coding assistant. Every code block marked "tested"
+is run by `test/editorCustom.test.mjs` straight from this file, so it works as written.
+
+## The rules
+
+1. **Everything is on `levelEditor`**, or on a class of your own that extends `LevelEditor`. It is exported
+   from every build, script tag and ES module alike.
+2. **No guards are needed.** In release builds `LevelEditor` is a stub: it takes what you add and never calls
+   it. The editor's code is only in the debug builds (`dist/littlejs.js`, `dist/littlejs.esm.js`).
+3. **The level data is the source of truth.** The editor changes the level object (3D) or the Tiled map (2D) the
+   game loaded, and brings the game's objects in line. Change the level through `edit3D` or `edit2D`, never the
+   game's objects.
+4. **An edit is a stroke.** Make changes with `edit3D.change(...)`, `edit3D.place(...)`, `edit2D.paint(...)` or
+   `edit2D.changeObjects(...)`, then call `strokeEnd()`: that is one undo step, autosaved. A tool's press, drag
+   and release are ended for you.
+5. **A type is named by a string**, never by its class, because minified builds rename classes.
+6. **Use `levelEditor.edit3D` and `levelEditor.edit2D` only inside what the editor calls**: a key's action, a
+   button's click, a tool's callbacks, `onUpdate`, `onDraw`. In a release build they are undefined, and none of
+   those are ever called.
+7. **`levelEditor.is3D`** says which editor is in use, for a game that has both kinds of level.
+
+## The hooks
+
+```javascript
+levelEditor.open();                    // start in the editor; close() plays on with the changes
+levelEditor.isOpen;                    // true while editing
+levelEditor.onRestart = ()=> buildLevel();         // adds a Restart button: load the level again
+levelEditor.onPlayFrom = (pos)=> player.pos = pos; // adds "Play from mouse": put the player at the mouse
+levelEditor.onOpen = ()=> {};          // the editor opened
+levelEditor.onClose = ()=> {};         // it closed, the game plays on
+levelEditor.onUpdate = ()=> {};        // each frame while it is open
+levelEditor.onDraw = ()=> {};          // while it draws the level, for overlays of your own
+levelEditor.onPanel = (box)=> {};      // once, when the panel is made: a box in it for your own controls
+levelEditor.onSave = (text, name)=> false;     // Save: return true when you kept the file yourself
+levelEditor.use3D = true;              // force the 3D editor (false, the 2D one); undefined picks by the level
+levelEditor.onTile = (layer, pos, tile)=> {};  // 2D: a tile was painted, tile undefined when erased
+levelEditor.paletteTiles = [0, 1, 10]; // 2D: the tiles the palette shows, undefined for the whole sheet
+```
+
+Without code, `0` on the debug overlay (`Esc`) opens the editor, and `Esc` then switches between editing and
+playing.
+
+## Your own object types, and their properties as panel inputs
+
+A type is a name, something to make, and default properties. The editor lists the type to place, and shows an
+input for each default whose value is a number, a true or false, a string, a `Color` or a vector. What the
+level designer sets is saved in the level and set on the object when the level loads.
+
+3D, tested:
+
+<!-- test:type3d -->
+```javascript
+class Spawner extends EngineObject3D
+{
+    // a level type's class is made with (pos3D, properties)
+    constructor(pos, properties)
+    {
+        super(pos, render3D.boxMesh, undefined, properties.color);
+    }
+}
+level3DAddType('Spawner', Spawner, {rate: 2, enemy: 'bat', color: hsl(0, 1, .5), active: true});
+level3DAddType('PlayerStart', (pos)=> playerStart = pos); // a function, for what is not an object
+```
+
+2D, tested:
+
+<!-- test:type2d -->
+```javascript
+class Coin extends EngineObject
+{
+    constructor(pos) { super(pos, vec2(1)); }
+}
+objectLayersAddType('Coin', Coin, {value: 1});
+```
+
+- In 3D a class needs its own constructor that takes the position: one that passes every argument on to
+  `EngineObject3D` would pass the properties as its mesh.
+- `level3DAddMesh('Tree', mesh, tileInfo)` is a 3D type with no class: a static prop with `color` and `solid`.
+- Changing a 3D object's property in the editor makes the object again, since its constructor takes them.
+- 3D prefabs, small levels placed many times, are types too: see "Prefabs" in [REFERENCE.md](REFERENCE.md). The
+  panel's Load prefab button adds one from a file to the level being edited.
+
+## A key of your own
+
+`addKey(key, action, helpLine)`. The key is a letter or digit (`'k'`), a key's name in any case (`'Delete'`,
+`'F2'`, `'Enter'`, `'Space'`), or either with `'ctrl+'` in front. The action is called with whether Shift is
+held. Return `false` when it did nothing.
+
+- A key the editor already uses is replaced by yours, with a warning in the console when the editor opens. The
+  two editors use different keys, so check the `?` help of the one your game uses.
+- `Escape` and `0` are the editor's own, to play and to exit, and are not taken.
+- Ctrl is the one modifier. For Shift, read the argument the action is given.
+
+3D, tested:
+
+<!-- test:key3d -->
+```javascript
+// K lifts every selected object one unit, as one undo
+levelEditor.addKey('k', ()=>
+{
+    const edit = levelEditor.edit3D;
+    const changed = edit.change((list)=>
+    {
+        for (const object of list)
+            if (edit.selection.has(object.id))
+                edit.setTransform(object, edit.pos(object).add(vec3(0, 1, 0)));
+    });
+    edit.strokeEnd();
+    return changed; // false when nothing was selected
+}, 'K: lift the selection one unit');
+```
+
+2D, tested:
+
+<!-- test:key2d -->
+```javascript
+// T paints tile 5 under the mouse on the selected tile layer, as one undo
+levelEditor.addKey('t', ()=>
+{
+    const edit = levelEditor.edit2D;
+    if (!edit.hover) return false; // the mouse is over no cell
+    edit.paint(edit.hover, 5);
+    edit.strokeEnd();
+}, 'T: paint tile 5 under the mouse');
+```
+
+## A panel button of your own
+
+`addButton(label, onClick, title)`. Tested:
+
+<!-- test:button3d -->
+```javascript
+levelEditor.addButton('Scatter 5 spawners', ()=>
+{
+    const edit = levelEditor.edit3D;
+    for (let i = 0; i < 5; ++i)
+        edit.place('Spawner', vec3(rand(-8, 8), .5, rand(-8, 8)));
+    edit.strokeEnd(); // the five are one undo
+}, 'Put five spawners at random places');
+```
+
+For anything more than a button, `onPanel` gives you a box in the panel to fill with your own HTML.
+
+## A tool of your own
+
+`addTool(name, tool)` adds a tool beside the editor's own: a button in the panel by its name, and a key if you
+give one. While it is on, the left button in the level is your tool's. Each callback is given
+`{pos, cell, ray, shift, ctrl}`:
+
+- `pos`: where the mouse is in the level. In 3D a `Vector3` on the level or the ground, in 2D a `Vector2`.
+- `cell`: 2D, the tile cell under the mouse on the selected tile layer, or undefined.
+- `ray`: 3D, the mouse's ray.
+
+What the callbacks change is one undo: the editor ends the stroke at the release, and takes it back when the
+right button or Escape ends the press. Do not call `strokeEnd` in a tool.
+
+3D, a tool that lays a row of posts along a drag, tested:
+
+<!-- test:tool3d -->
+```javascript
+let lastPost;
+levelEditor.addTool('Posts',
+{
+    key: 'o',
+    hint: 'Posts: drag along the ground to lay a row',
+    onPress(at)
+    {
+        if (!at.pos) return false; // not on the level
+        levelEditor.edit3D.place('Cylinder', lastPost = at.pos.add(vec3(0, .5, 0)));
+    },
+    onDrag(at)
+    {
+        // another post each 2 units along the drag
+        if (at.pos && at.pos.distance(lastPost) >= 2)
+            levelEditor.edit3D.place('Cylinder', lastPost = at.pos.add(vec3(0, .5, 0)));
+    },
+});
+```
+
+2D, a tool that paints a tile wherever it is dragged, Shift erasing, tested:
+
+<!-- test:tool2d -->
+```javascript
+levelEditor.addTool('Water',
+{
+    key: 'w',
+    hint: 'Water: drag to fill cells · Shift erases',
+    onPress(at) { at.cell && levelEditor.edit2D.paint(at.cell, at.shift ? -1 : 7); },
+    onDrag(at)  { at.cell && levelEditor.edit2D.paint(at.cell, at.shift ? -1 : 7); },
+    onDraw(at)
+    {
+        // a cell is counted from its layer's corner, which is at the layer's pos in the world
+        const corner = levelEditor.edit2D.layer.pos;
+        at.cell && drawRect(corner.add(at.cell).add(vec2(.5)), vec2(1), hsl(.55, 1, .5, .4));
+    },
+});
+```
+
+A tool is put down by its key or button again, or by picking one of the editor's own tools, layers or types.
+`levelEditor.tool` is the name of the one that is on.
+
+`onDraw`, a tool's and the editor's, draws in the level as the editor does: in the 2D editor with the 2D draws
+(`drawRect`, `drawLine`), and in the 3D editor inside the 3D pass, with `render3D.drawBox`, `render3D.drawLine`
+and the rest.
+
+## An editor class of your own
+
+Everything above can be a class instead, with the hooks as methods. Tested:
+
+<!-- test:class -->
+```javascript
+class MyEditor extends LevelEditor
+{
+    constructor()
+    {
+        super();
+        this.showZones = true;
+        this.addKey('z', ()=> { this.showZones = !this.showZones; }, 'Z: show the spawn zones');
+        this.addButton('Clear spawners', ()=> this.clearSpawners());
+    }
+
+    // the hooks are methods
+    onRestart() { restarts++; }
+    onDraw() { this.showZones && drawnZones++; }
+
+    clearSpawners()
+    {
+        const edit = this.edit3D;
+        edit.change((list)=>
+        {
+            for (let i = list.length; i--;)
+                list[i].type === 'Spawner' && list.splice(i, 1);
+        });
+        edit.strokeEnd();
+    }
+}
+setLevelEditor(new MyEditor);
+```
+
+- Call `setLevelEditor` before the editor opens, and use `levelEditor` itself afterwards, not a copy of it
+  taken earlier.
+- `keys`, `buttons`, `tools` and `tool` are fields the class keeps what you added in: do not name your own
+  fields those.
+- A method of your class is a hook the same as one you set: defining `onRestart` shows the Restart button.
+
+## The edit functions
+
+### `levelEditor.edit3D`
+
+| Member | What it is |
+| --- | --- |
+| `level` | The level object being edited |
+| `objects` | Its objects, the list in the level: read it, edit through `change` |
+| `selection` | A `Set` of the selected objects' ids, yours to add to and delete from |
+| `selected()` | The selected objects |
+| `made(id)` | What the game made for an object |
+| `change((list)=> {...})` | Edit a copy of the object list; false when nothing changed |
+| `changePart(name, (part)=> newPart)` | Edit the level's `scene`, `voxels`, `terrain` or `prefabs` block |
+| `strokeEnd()` | End the edit: one undo step, and the autosave |
+| `strokeCancel()` | Take the edit being made back |
+| `place(type, pos3D)` | Add an object of a type, selected; its id, or undefined when there is no such type or the level can not be edited |
+| `setTransform(object, pos3D, rotation, scale3D)` | Inside `change`, on an object of its list: write a place, a rotation in degrees and a scale; leave one out to keep it |
+| `setProperty(object, name, value)` | Inside `change`, on an object of its list: write a property, left out of the file when it is the type's default |
+| `pos(object)`, `rotation(object)`, `scale(object)` | Read them as vectors, the rotation in degrees |
+| `mousePoint()` | Where the mouse is on the level or the ground, undefined while it is over the panel |
+| `undo(redo)` | Undo, or redo with true |
+| `toJSON()` | The level as the text Save writes |
+
+### `levelEditor.edit2D`
+
+| Member | What it is |
+| --- | --- |
+| `map` | The Tiled map of the selected layer |
+| `layer` | The selected tile layer, a `TileLayer`, undefined on an object layer |
+| `objects` | A copy of the selected object layer's objects, as Tiled has them |
+| `hover` | The cell under the mouse on the selected tile layer |
+| `selection` | A `Set` of the selected objects' ids |
+| `paint(cell, tile, direction, mirror)` | Set a cell of the selected tile layer to a tile index, -1 erases; false off the layer |
+| `changeObjects((list)=> {...})` | Edit a copy of the selected object layer's objects |
+| `strokeEnd()` | End the edit: one undo step, and the autosave |
+| `strokeCancel()` | Take the edit being made back |
+| `bulk(()=> {...})` | Many `paint` calls with one redraw a layer |
+| `undo(redo)` | Undo, or redo with true |
+| `toJSON()` | The map as the text Save writes |
+
+## The files
+
+- 3D: plain JSON, `{littlejs3D: 1, scene, voxels, terrain, prefabs, objects: [{id, type, pos, rotation, scale,
+  properties}]}`. Load with `level3DLoad(await fetchJSON('level.json'))`.
+- 2D: Tiled JSON. Load with `tileLayersLoad(map)` and `objectLayersLoad(map)`. Tiled itself can open the file.
+- A game that loads the same level object again, as a restart does, gets the edits.
+- A 3D level's block map shows the tiles of the sheet given to `level3DVoxelSetup`, or of the game's first image;
+  a game that has loaded no image gets plain colored blocks.
+- To keep levels somewhere of your own, a server or your own format, use `onSave`:
+
+```javascript
+levelEditor.onSave = (text, fileName)=>
+{
+    fetch('/levels/' + fileName, {method: 'PUT', body: text});
+    return true; // kept, the editor writes no file
+};
+```
+
+`onSave` may be an async function. In the 3D editor it is asked for a prefab too, when Save is pressed inside one.
+
+### A game opened from disk
+
+A page opened straight from a folder, with no server, can not `fetch` a JSON file. Keep the level as a script
+instead: a file that sets a variable, loaded with a script tag before the game. `onSave` writes it. Tested:
+
+<!-- test:disklevel -->
+```javascript
+// index.html has <script src="level.js"></script> before the game's own script, and level.js is one line:
+// var level = {"littlejs3D": 1, "objects": [...]};
+levelEditor.onSave = (text, fileName)=>
+{
+    saveText('var level = ' + text.trim() + ';\n', 'level.js', 'text/javascript');
+    return true; // kept, the editor writes no JSON file
+};
+level3DLoad(level); // the same object the script made, so the editor's changes are the game's
+```
+
+Save then downloads `level.js`, to put in place of the old one. The autosave still brings unsaved edits back
+after a reload.
+
+## A checklist for a custom editor
+
+1. Register the game's types with their defaults, before the level loads.
+2. Set `onRestart` and `onPlayFrom`, so Restart and Play from mouse work.
+3. Add keys and buttons for what the game's designers do most, each ending its stroke.
+4. Add a tool for what is done with the mouse in the level: paths, zones, links between objects.
+5. Draw what the level does not show by itself in `onDraw`: zones, ranges, links.
+6. Ship the release build: the editor and everything you added to it are gone.
+
+## Where the working examples are
+
+- `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
+  and hooks.
+
+## What it does not do
+
+- **It does not replace the editor's own tools.** Your keys, buttons and tools are added beside them; how the
+  built-in Move tool snaps, or how painting works, is not something a game changes. That takes an engine build
+  of your own: get the LittleJS source at the version you use, edit `src/engineEditor.js` or
+  `plugins/render3dEditor.js`, run `npm run build`, and use the `dist/littlejs.js` it makes. A changed copy
+  of the file can not be loaded beside the engine, the debug build has the editor in it already, and a build of
+  your own has to be made again for each engine update.
+- **A tool has no handles of its own.** It has the press, the drag and the release, and it can draw.
+- **The editors' inner functions**, the ones named `editor...` and `editor3D...`, are not part of this. They can
+  be reached in a script-tag debug build, but they change between versions.

package/README.md

@@ -40,7 +40,8 @@ The code is very clean and well documented with many examples to get you started
 - Blazing fast WebGL2 + Canvas2D hybrid rendering system
 - Apply [Shadertoy](https://www.shadertoy.com) style shaders for post-processing effects, or on any object or draw
 - 2D lights with soft shadows, tinted glass and emissive objects
-- Robust particle effect system and [effect design tool](https://killedbyapixel.github.io/LittleJS/examples/particles/)
+- Robust particle effect system with a library of ready made effects and an [effect design tool](https://killedbyapixel.github.io/LittleJS/examples/particles/)
+- Parallax background layers that repeat across a level of any size
 - Load sprites and animations into texture sheets at runtime, or import [TexturePacker](https://www.codeandweb.com/texturepacker) and [Aseprite](https://www.aseprite.org) atlases
 
 ### 🧊 LittleJS 3D
@@ -48,8 +49,9 @@ The code is very clean and well documented with many examples to get you started
 - Built-in 3D renderer that shares the canvas with your 2D game
 - 3D objects with the same physics, children and timers as 2D
 - Shape builders, extruded sprites and text, and OBJ and glTF model loading
-- Height map terrain with collision and raycasts
-- Shadow maps, colored lights, specular, emissive glow and fog
+- Height map terrain and voxel maps with collision and raycasts
+- 3D levels and prefabs, built in the 3D level editor and loaded with one call
+- Shadow maps, colored lights, spotlights, lens flares, specular, emissive glow and fog
 - Particles, trails, billboards and instanced drawing
 - Orbit, chase and first person cameras with mouse picking
 - Custom shaders on any object
@@ -66,6 +68,7 @@ The code is very clean and well documented with many examples to get you started
 
 - Comprehensive input handling for mouse, keyboard, gamepad, and touch
 - Customizable on screen gamepad designed for mobile devices
+- Pinch to zoom on touch screens, read the same way as the mouse wheel
 
 ### 💥 Physics
 
@@ -85,9 +88,11 @@ The code is very clean and well documented with many examples to get you started
 ### 🛠️ Developer Tools
 
 - Live example browser with code editor
-- Import level editor data from [Tiled](https://github.com/mapeditor/tiled) or other JSON
+- Built-in 2D and 3D level editors that edit your game while it runs, with undo, autosave and prefabs
+- Make the editors your own with your game's own object types, keys, buttons and tools, see the [editor guide](https://github.com/KilledByAPixel/LittleJS/blob/main/EDITOR.md)
+- 2D levels load and save as [Tiled](https://github.com/mapeditor/tiled) JSON, so Tiled can edit them too
 - UI system with buttons, sliders, text input and nine-slice skins
-- Tween system with easing curves
+- Tween system with easing curves, and a scene system for titles, menus and game states
 - Debug overlay and primitive rendering system
 - Medal tracking system with [Newgrounds](https://www.newgrounds.com/) support
 - Node.js build system
@@ -146,7 +151,7 @@ LittleJS comes with several demos both for learning and using as starter project
 
 - [Example Browser](https://killedbyapixel.github.io/LittleJS/examples/) - Live example browser with all examples and editable source
 - [LittleJS Arcade](https://killedbyapixel.github.io/LittleJSArcade/) - Over 50 example games you can use as starter projects
-- [Short Examples](https://github.com/KilledByAPixel/LittleJS/tree/main/examples/shorts) - 80+ single-file demos showing off individual engine features
+- [Short Examples](https://github.com/KilledByAPixel/LittleJS/tree/main/examples/shorts) - 100+ single-file demos showing off individual engine features
 - [Breakout](https://killedbyapixel.github.io/LittleJS/examples/breakout/) - Block breaking game with post-processing effects
 - [Puzzle Game](https://killedbyapixel.github.io/LittleJS/examples/puzzle/) - Match 3 puzzle game with HD rendering and high score tracking
 - [Platformer](https://killedbyapixel.github.io/LittleJS/examples/platformer/) - Platformer/shooter demo that loads level data