littlejsengine 1.23.1 → 1.24.0

package/plugins/render3dLevel.js

@@ -84,8 +84,9 @@ function level3DAddMesh(name, mesh, tileInfo, color=WHITE)
  *    are added before its objects are made, one the game added itself keeps its place
  *  - A level may set the scene too, in a scene block beside its objects: sky, three colors for straight up, the
  *    horizon and straight down, ambient, how much of them lights the scene, .5 when not given, sunDirection and
- *    sunColor, fog, its start and end, fogColor, the horizon color when not given, and shadows; what the block
- *    leaves out stays as the game set it, and a level with no block changes nothing
+ *    sunColor, fog, its start and end, fogColor, the horizon color when not given, shadows, and lensFlare, the
+ *    sun's lens flare; what the block leaves out stays as the game set it, and a level with no block changes
+ *    nothing
  *  @param {Object} level - The level, the level editor edits this same object
  *  @return {Array<any>} - What each object's type made, a function that made nothing is left out
  *  @memberof Level3D */
@@ -310,8 +311,25 @@ function level3DSceneApply(scene)
     r.fogColor = color(scene.fogColor) || r.fogColor;
     if (typeof scene.shadows === 'boolean')
         r.shadows = scene.shadows;
+    if (typeof scene.lensFlare === 'boolean')
+        level3DSceneFlare(scene.lensFlare);
 }
 
+// the sun's lens flare as a scene sets it: on makes one unless the sun has a flare already, the game's own or an
+// earlier level's, and off takes away the one a scene made, never the game's
+let level3DSunFlare;
+function level3DSceneFlare(on)
+{
+    if (!on)
+    {
+        level3DSunFlare && !level3DSunFlare.destroyed && level3DSunFlare.destroy();
+        level3DSunFlare = undefined;
+    }
+    else if (!level3DSunHasFlare())
+        level3DSunFlare = new LensFlare3D;
+}
+const level3DSunHasFlare = ()=> engineObjects.some((o)=> o instanceof LensFlare3D && !o.destroyed && !o.light);
+
 // a vec3 of an array of three numbers, as the file has them, or the fallback
 function level3DVector(value, fallback)
 {
@@ -660,7 +678,8 @@ level3DAddType('Cylinder', function(pos, properties)
     { return level3DMakeShape(pos, properties, level3DCylinderMesh ||= buildCylinder()); },
     {color: WHITE, tile: -1, solid: true});
 // a light, a spotlight with a cone: cone is the angle in degrees from its forward out to the edge of its beam, the
-// object's rotation aims it, softness is how much of the cone fades, and shadows makes it the one that casts them
+// object's rotation aims it, softness is how much of the cone fades, shadows makes it the one that casts them, and
+// lensFlare gives it a lens flare; not flare, since a property is also set on the object, where flare is the flare
 level3DAddType('Light', function(pos, properties)
 {
     const light = new Light3D(pos, properties.radius, properties.color, properties.intensity);
@@ -668,5 +687,6 @@ level3DAddType('Light', function(pos, properties)
     light.coneSoftness = properties.softness;
     if (properties.shadows && render3D)
         render3D.shadowLight = light;
+    properties.lensFlare && light.addFlare();
     return light;
-}, {color: WHITE, radius: 5, intensity: 1, cone: 0, softness: .2, shadows: false});
+}, {color: WHITE, radius: 5, intensity: 1, cone: 0, softness: .2, shadows: false, lensFlare: false});

package/src/engine.js

@@ -32,7 +32,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.23.1';
+const engineVersion = '1.24.0';
 
 /** Frames per second to update
  *  @type {number}

package/src/engineAudio.js

@@ -7,7 +7,7 @@
  * - 2D spatial audio based on camera position with distance-based falloff
  * - Sound instance management (pause, resume, stop)
  * - Speech synthesis for text-to-speech
- * - Music playback with ZzFXM support
+ * - Music playback from audio files, looping by default
  * - Web Audio API integration with master gain control
  * - Sounds and the master bus can route through effects, see the audio effects plugin
  * @namespace Audio
@@ -887,7 +887,7 @@ function playAudioBuffer(buffer, volume=1, rate=1, pan=0, loop=false, gainNode,
 }
 
 ///////////////////////////////////////////////////////////////////////////////
-// ZzFXMicro - Zuper Zmall Zound Zynth - v1.4.0 by Frank Force
+// ZzFX - Zuper Zmall Zound Zynth - v1.4.0 by Frank Force
 
 /** Generate and play a ZzFX sound
  *

package/src/engineBuild.mjs

@@ -44,7 +44,6 @@ const enginePluginFiles =
     `${PLUGIN_FOLDER}/newgrounds.js`,
     `${PLUGIN_FOLDER}/postProcess.js`,
     `${PLUGIN_FOLDER}/lightSystem.js`,
-    `${PLUGIN_FOLDER}/zzfxm.js`,
     `${PLUGIN_FOLDER}/audioEffects.js`,
     `${PLUGIN_FOLDER}/uiSystem.js`,
     `${PLUGIN_FOLDER}/box2d.js`,

package/src/engineExport.js

@@ -419,6 +419,7 @@ export
     tileCollisionTest,
     tileCollisionRaycast,
     tileLayersLoad,
+    tileLayersFromLDtk,
     objectLayersAddType,
     objectLayersLoad,
     TileLayerData,

package/src/engineTileLayer.js

@@ -128,6 +128,10 @@ const tileLayersTiledFlips = [[0,0], [3,1], [2,1], [3,0], [0,1], [1,0], [2,0], [
  * Load tile layers from exported data
  * - Tiled maps come in as they are, flipped and turned tiles included, from one tileset image (a second tileset's
  *   tiles continue its numbering), finite maps in the CSV or array layer format; layer offsets and parallax are not read
+ * - A tileset kept in the map with a margin or a spacing, a sheet with gaps between its tiles, is read where its
+ *   tiles are, whatever padding the tile info has; one in a file of its own (a tsx) is not read, pass a tile info
+ *   with its padding
+ * - An LDtk level loads through tileLayersFromLDtk, which makes it a map like these
  * - Group layers are flattened in order, each replaced by the layers inside it, so the layer indices
  *   (collisionLayer and the returned array) count that flattened list; a group's tint, opacity and
  *   visibility carry to the layers inside it
@@ -160,6 +164,18 @@ function tileLayersLoad(tileMapData, tileInfo=tileLayerDefaultTile(), renderOrde
     ASSERT(tileMapData.width && tileMapData.height);
     ASSERT(tileMapData.layers && tileMapData.layers.length);
 
+    // a sheet with a margin around its tiles or a spacing between them: the first tile is at the margin and each
+    // cell is a tile and a spacing, which is a padding of half the spacing counted from there, by the tileset's
+    // own count of columns, since the image's width does not say with a spacing that is not all around
+    const tileset = tileMapData.tilesets?.[0];
+    if (tileInfo && tileset && (tileset.margin > 0 || tileset.spacing > 0))
+    {
+        const margin = tileset.margin || 0, spacing = tileset.spacing || 0, size = tileInfo.size;
+        const width = tileInfo.textureInfo?.size.x || 0;
+        const columns = tileset.columns || max(1, floor((width - margin*2 + spacing) / (size.x + spacing)));
+        tileInfo = new TileInfo(vec2(margin), size, tileInfo.textureInfo, spacing / 2, tileInfo.bleed, columns);
+    }
+
     // flatten group layers in order, a group's color and visibility carry to the layers inside it
     /** @type {Array<{dataLayer: Object, color?: Color, visible?: boolean}>} */
     const layers = [];
@@ -237,6 +253,107 @@ function tileLayersLoad(tileMapData, tileInfo=tileLayerDefaultTile(), renderOrde
 function tileLayersColor(hex)
 { return new Color().setHex(hex.length === 9 ? '#' + hex.slice(3) + hex.slice(1, 3) : hex); }
 
+// the Tiled property type of an LDtk field type, for the ones Tiled has a property for
+const tileLayersLDtkTypes = {Int: 'int', Float: 'float', Bool: 'bool', String: 'string', Multilines: 'string',
+    Color: 'color', FilePath: 'file'};
+
+/**
+ * Make a Tiled map of a level of an LDtk project, to load with tileLayersLoad and objectLayersLoad
+ * - Each Tiles, AutoLayer and IntGrid layer is a tile layer, the bottom one first as in Tiled, so the last layer
+ *   of the LDtk file is layer 0; where LDtk stacks tiles in a cell, an edge over a fill, each tile over another
+ *   goes in a layer of its own just above, named with (2), (3) and so on, so a layer of the first tiles has one
+ *   wherever the LDtk layer has any, which makes it the one for collision
+ * - An IntGrid layer with no tiles is a hidden layer of its values, for collision: pass its index as collisionLayer
+ * - An Entities layer is an object layer: an entity's name is its type for objectLayersAddType, it is placed at
+ *   its middle, and its Int, Float, Bool, String, Color and FilePath fields are its properties (an enum is a string)
+ * - The tileset is the first tile layer's, with its padding and spacing; give tileLayersLoad a tile info of its image
+ * - The level is in the project file (not saved as separate level files), its layers of one grid size; a layer of
+ *   another grid size or another tileset is left out, with a warning in debug builds
+ * - The level editor edits the map this returns, and saves it as a Tiled map
+ * @param {Object} ldtk - The LDtk project, its JSON
+ * @param {number|string} [level] - Which level, by its index or its identifier
+ * @return {Object} - A Tiled map: width, height, tilewidth, tileheight, tilesets and layers
+ * @example
+ * const map = tileLayersFromLDtk(await fetchJSON('world.ldtk'), 'Level_0');
+ * const layers = tileLayersLoad(map, tile(0, 16), 0, 1); // layer 1 is solid
+ * objectLayersLoad(map);
+ * @memberof TileLayers */
+function tileLayersFromLDtk(ldtk, level=0)
+{
+    const levels = ldtk?.levels || [];
+    const data = typeof level === 'string' ? levels.find((l)=> l.identifier === level) : levels[level];
+    ASSERT(data, 'LDtk level not found', level);
+    ASSERT(isArray(data.layerInstances), 'LDtk level has no layers: levels saved as separate files are not read');
+    const instances = data.layerInstances;
+    const tiled = (l)=> l.__type !== 'Entities';
+    const first = instances.find((l)=> tiled(l) && l.__tilesetDefUid != undefined) || instances.find(tiled) || instances[0];
+    const grid = first?.__gridSize || 16;
+    const width = first?.__cWid || ceil(data.pxWid / grid), height = first?.__cHei || ceil(data.pxHei / grid);
+    const map = {width, height, tilewidth: grid, tileheight: grid, orientation: 'orthogonal', renderorder: 'right-down',
+        infinite: false, layers: [], nextlayerid: 1, nextobjectid: 1};
+
+    // the tileset of the first layer that has one, where its tiles are in its image
+    const tileset = (ldtk?.defs?.tilesets || []).find((t)=> t.uid === first?.__tilesetDefUid);
+    if (tileset)
+        map.tilesets = [{firstgid: 1, name: String(tileset.relPath || '').replace(/^.*[\\/]/, '').replace(/\.\w+$/, ''),
+            image: tileset.relPath, imagewidth: tileset.pxWid, imageheight: tileset.pxHei,
+            tilewidth: tileset.tileGridSize, tileheight: tileset.tileGridSize, margin: tileset.padding || 0,
+            spacing: tileset.spacing || 0, columns: tileset.__cWid, tilecount: tileset.__cWid * tileset.__cHei}];
+
+    // LDtk lists the top layer first, Tiled the bottom one
+    for (let i = instances.length; i--;)
+    {
+        const instance = instances[i], name = instance.__identifier, id = map.nextlayerid++;
+        if (!tiled(instance))
+        {
+            const objects = (instance.entityInstances || []).map((entity)=>
+            {
+                // an entity is placed by its pivot, an object here by its middle
+                const [pivotX=0, pivotY=0] = entity.__pivot || [], w = entity.width || 0, h = entity.height || 0;
+                const properties = [];
+                for (const field of entity.fieldInstances || [])
+                {
+                    const type = tileLayersLDtkTypes[field.__type] || (/^(Local|Extern)Enum\./.test(field.__type) && 'string');
+                    type && field.__value != undefined && properties.push({name: field.__identifier, type, value: field.__value});
+                }
+                return {id: map.nextobjectid++, name: '', type: entity.__identifier, x: entity.px[0] + (.5 - pivotX) * w,
+                    y: entity.px[1] + (.5 - pivotY) * h, width: w, height: h, rotation: 0, visible: true, properties};
+            });
+            map.layers.push({id, name, type: 'objectgroup', objects, opacity: 1, visible: true, x: 0, y: 0});
+            continue;
+        }
+        const tiles = [...(instance.autoLayerTiles || []), ...(instance.gridTiles || [])];
+        const usable = instance.__gridSize === grid && instance.__cWid === width && instance.__cHei === height &&
+            (!tiles.length || instance.__tilesetDefUid === tileset?.uid);
+        if (!usable)
+        {
+            debug && console.warn(`tileLayersFromLDtk: layer ${name} has another grid or tileset, left out`);
+            continue;
+        }
+        const empty = ()=> new Array(width * height).fill(0), stacks = [empty()];
+        if (tiles.length)
+        {
+            // a tile's place in pixels, its tile in the sheet, and its flips: bit 0 across, bit 1 down, which are
+            // Tiled's two top bits; LDtk lists them in the order it draws them, so the first in a cell is the
+            // bottom one and each after it goes a layer higher
+            const depth = new Uint16Array(width * height);
+            for (const t of tiles)
+            {
+                const x = floor(t.px[0] / grid), y = floor(t.px[1] / grid), cell = x + y * width;
+                if (x >= 0 && x < width && y >= 0 && y < height)
+                    (stacks[depth[cell]++] ||= empty())[cell] =
+                        (t.t + 1 | (t.f & 1 ? 0x80000000 : 0) | (t.f & 2 ? 0x40000000 : 0)) >>> 0;
+            }
+        }
+        else
+            (instance.intGridCsv || []).forEach((value, k)=> k < stacks[0].length && (stacks[0][k] = value));
+        const visible = instance.__type === 'IntGrid' && !tiles.length ? false : instance.visible !== false;
+        stacks.forEach((data, k)=> map.layers.push({id: k ? map.nextlayerid++ : id, name: k ? `${name} (${k + 1})` : name,
+            type: 'tilelayer', width, height, data, opacity: instance.__opacity ?? 1, visible, x: 0, y: 0}));
+    }
+    return map;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 // Object layers
 

package/plugins/zzfxm.js

@@ -1,162 +0,0 @@
-/**
- * LittleJS ZzFXM Plugin
- * - A port of ZzFXM, the Zuper Zmall Zound Zynth music player, by Keith Clark and Frank Force, MIT licensed,
- *   https://github.com/keithclark/ZzFXM; its notice is in COPYRIGHT.txt
- * @namespace ZzFXM
- */
-
-'use strict';
-
-/**
- * Music Object - Stores a zzfx music track for later use
- * 
- * <a href=https://keithclark.github.io/ZzFXM/>Create music with the ZzFXM tracker.</a>
- * @extends Sound
- * @memberof ZzFXM
- * @example
- * // create some music
- * const music_example = new ZzFXMusic(
- * [
- *     [                         // instruments
- *       [,0,400]                // simple note
- *     ], 
- *     [                         // patterns
- *         [                     // pattern 1
- *             [                 // channel 0
- *                 0, -1,        // instrument 0, left speaker
- *                 1, 0, 9, 1    // channel notes
- *             ], 
- *             [                 // channel 1
- *                 0, 1,         // instrument 0, right speaker
- *                 0, 12, 17, -1 // channel notes
- *             ]
- *         ],
- *     ],
- *     [0, 0, 0, 0], // sequence, play pattern 0 four times
- *     90            // BPM
- * ]);
- * 
- * // play the music on a loop
- * music_example.playMusic();
- */
-class ZzFXMusic extends Sound
-{
-    /** Create a music object and cache the zzfx music samples for later use
-     *  @param {[Array, Array, Array, number?, ...any[]]} zzfxMusic - Array of zzfx music parameters: instruments, patterns, sequence, and an optional BPM; anything after it, like the tracker's metadata, is ignored
-     */
-    constructor(zzfxMusic)
-    {
-        super(undefined);
-
-        if (!soundEnable || headlessMode) return;
-        const [instruments, patterns, sequence, BPM] = zzfxMusic;
-        super.sampleChannels = zzfxM(instruments, patterns, sequence, BPM); // the setter, without declaring a field that hides it in the typings
-        this.buildSampleBuffer(); // hand the samples to an audio buffer now, like a zzfx sound, so the arrays are released
-        this.loadedPercent = 1; // generated in place, so it is loaded like a zzfx sound
-    }
-}
-
-///////////////////////////////////////////////////////////////////////////////
-// ZzFX Music Renderer v2.0.3 by Keith Clark and Frank Force
-
-/** Generate samples for a ZzFM song with given parameters
- *  @param {Array} instruments - Array of ZzFX sound parameters
- *  @param {Array} patterns - Array of pattern data
- *  @param {Array} sequence - Array of pattern indexes
- *  @param {number} [BPM] - Playback speed of the song in BPM
- *  @return {Array} - Left and right channel sample data
- *  @memberof ZzFXM */
-function zzfxM(instruments, patterns, sequence, BPM = 125) 
-{
-  let i, j, k;
-  let instrumentParameters;
-  let note;
-  let sample;
-  let patternChannel;
-  let notFirstBeat;
-  let stop;
-  let instrument;
-  let attenuation;
-  let outSampleOffset;
-  let isSequenceEnd;
-  let sampleOffset = 0;
-  let nextSampleOffset;
-  let sampleBuffer = [];
-  let leftChannelBuffer = [];
-  let rightChannelBuffer = [];
-  let channelIndex = 0;
-  let panning = 0;
-  let hasMore = 1;
-  let sampleCache = {};
-  let beatLength = audioDefaultSampleRate / BPM * 60 >> 2;
-
-  // for each channel in order until there are no more
-  for (; hasMore; channelIndex++) {
-
-    // reset current values
-    sampleBuffer = [hasMore = notFirstBeat = outSampleOffset = 0];
-
-    // for each pattern in sequence
-    sequence.forEach((patternIndex, sequenceIndex)=> {
-      // get pattern for current channel, use empty 1 note pattern if none found
-      patternChannel = patterns[patternIndex][channelIndex] || [0, 0, 0];
-
-      // check if there are more channels
-      hasMore |= patterns[patternIndex][channelIndex]&&1;
-
-      // get next offset, use the length of first channel
-      nextSampleOffset = outSampleOffset + (patterns[patternIndex][0].length - 2 - (notFirstBeat?0:1)) * beatLength;
-      // for each beat in pattern, plus one extra if end of sequence
-      isSequenceEnd = sequenceIndex === sequence.length - 1;
-      for (i = 2, k = outSampleOffset; i < patternChannel.length + isSequenceEnd; notFirstBeat = ++i) {
-
-        // <channel-note>
-        note = patternChannel[i];
-
-        // stop if end, different instrument or new note
-        stop = i === patternChannel.length + isSequenceEnd - 1 && isSequenceEnd ||
-            instrument !== (patternChannel[0] || 0) || note | 0;
-
-        // fill buffer with samples for previous beat, most cpu intensive part
-        for (j = 0; j < beatLength && notFirstBeat;
-
-            // fade off attenuation at end of beat if stopping note, prevents clicking
-            j++ > beatLength - 99 && stop && attenuation < 1? attenuation += 1 / 99 : 0
-        ) {
-          // copy sample to stereo buffers with panning
-          sample = (1 - attenuation) * sampleBuffer[sampleOffset++] / 2 || 0;
-          leftChannelBuffer[k] = (leftChannelBuffer[k] || 0) - sample * panning + sample;
-          rightChannelBuffer[k] = (rightChannelBuffer[k++] || 0) + sample * panning + sample;
-        }
-
-        // set up for next note
-        if (note) {
-          // set attenuation
-          attenuation = note % 1;
-          panning = patternChannel[1] || 0;
-          if (note |= 0) {
-            // get cached sample
-            sampleBuffer = sampleCache[
-              [
-                instrument = patternChannel[sampleOffset = 0] || 0,
-                note
-              ]
-            ] = sampleCache[[instrument, note]] || (
-                // add sample to cache
-                instrumentParameters = [...instruments[instrument]],
-                instrumentParameters[2] = (instrumentParameters[2] || 220) * 2**(note / 12 - 1),
-
-                // allow negative values to stop notes
-                note > 0 ? zzfxG(...instrumentParameters) : []
-            );
-          }
-        }
-      }
-
-      // update the sample offset
-      outSampleOffset = nextSampleOffset;
-    });
-  }
-
-  return [leftChannelBuffer, rightChannelBuffer];
-}