littlejsengine 1.0.14 → 1.1.8

package/engine/engine.js

@@ -1,11 +1,9 @@
 /*
-    LittleJS - The Tiny JavaScript Game Engine That Can
-    MIT License - Copyright 2019 Frank Force
+    LittleJS - The Tiny JavaScript Game Engine That Can!
+    MIT License - Copyright 2021 Frank Force
 
     Engine Features
-    - Engine and debug system are separate from game code
-    - Object oriented with base class engine object
-    - Engine handles core update loop
+    - Object oriented system with base class engine object
     - Base class object handles update, physics, collision, rendering, etc
     - Engine helper classes and functions like Vector2, Color, and Timer
     - Super fast rendering system for tile sheets
@@ -13,30 +11,63 @@
     - Input processing system with gamepad and touchscreen support
     - Tile layer rendering and collision system
     - Particle effect system
-    - Automatically calls gameInit(), gameUpdate(), gameUpdatePost(), gameRender(), gameRenderPost()
+    - Medal system tracks and displays achievements
     - Debug tools and debug rendering system
     - Call engineInit() to start it up!
 */
 
 'use strict';
 
+/** Name of engine */
 const engineName = 'LittleJS';
-const engineVersion = '1.0.14';
-const FPS = 60, timeDelta = 1/FPS; // engine uses a fixed time step
-const tileImage = new Image(); // everything uses the same tile sheet
-
-// core engine variables
-let mainCanvas, mainContext, overlayCanvas, overlayContext, mainCanvasSize=vec2(), 
-    engineObjects=[], engineCollideObjects=[],
-    cameraPos=vec2(), cameraScale=max(defaultTileSize.x, defaultTileSize.y),
-    frame=0, time=0, realTime=0, paused=0, frameTimeLastMS=0, frameTimeBufferMS=0, debugFPS=0, gravity=0, 
-    tileImageSize, tileImageSizeInverse, shrinkTilesX, shrinkTilesY, drawCount;
-
-// call this function to start the engine
+
+/** Version of engine */
+const engineVersion = '1.1.8';
+
+/** Frames per second to update objects
+ *  @default */
+const FPS = 60;
+
+/** How many seconds each frame lasts, engine uses a fixed time step
+ *  @default 1/60 */
+const timeDelta = 1/FPS;
+
+/** Array containing all engine objects */
+let engineObjects = [];
+
+/** Array containing only objects that are set to collide with other objects (for optimization) */
+let engineCollideObjects = [];
+
+/** Current update frame, used to calculate time */
+let frame = 0;
+
+/** Current engine time since start in seconds, derived from frame */
+let time = 0;
+
+/** Actual clock time since start in seconds (not affected by pause or frame rate clamping) */
+let timeReal = 0;
+
+/** Is the game paused? Causes time and objects to not be updated. */
+let paused = 0;
+
+// Engine internal variables not exposed to documentation
+let frameTimeLastMS = 0, frameTimeBufferMS = 0, debugFPS = 0, 
+    shrinkTilesX, shrinkTilesY, drawCount, tileImageSize, tileImageSizeInverse;
+
+///////////////////////////////////////////////////////////////////////////////
+
+/** Start up LittleJS engine with your callback functions
+ *  @param {Function} gameInit        - Called once after the engine starts up, setup the game
+ *  @param {Function} gameUpdate      - Called every frame at 60 frames per second, handle input and update the game state
+ *  @param {Function} gameUpdatePost  - Called after physics and objects are updated, setup camera and prepare for render
+ *  @param {Function} gameRender      - Called before objects are rendered, draw any background effects that appear behind objects
+ *  @param {Function} gameRenderPost  - Called after objects are rendered, draw effects or hud that appear above all objects
+ *  @param {String} [tileImageSource] - Tile image to use, everything starts when the image is finished loading
+ */
 function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost, tileImageSource)
 {
-    // init engine when tiles load
-    tileImage.onload = ()=>
+    // init engine when tiles load or fail to load
+    tileImage.onerror = tileImage.onload = ()=>
     {
         // save tile image info
         tileImageSizeInverse = vec2(1).divide(tileImageSize = vec2(tileImage.width, tileImage.height));
@@ -76,7 +107,7 @@ function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRender
             debugFPS = lerp(.05, 1e3/(frameTimeDeltaMS||1), debugFPS);
         if (debug)
             frameTimeDeltaMS *= keyIsDown(107) ? 5 : keyIsDown(109) ? .2 : 1; // +/- to speed/slow time
-        realTime += frameTimeDeltaMS / 1e3;
+        timeReal += frameTimeDeltaMS / 1e3;
         frameTimeBufferMS = min(frameTimeBufferMS + !paused * frameTimeDeltaMS, 50); // clamp incase of slow framerate
 
         if (paused)
@@ -104,7 +135,7 @@ function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRender
                 // update game and objects
                 inputUpdate();
                 gameUpdate();
-                engineUpdateObjects();
+                engineObjectsUpdate();
 
                 // do post update
                 debugUpdate();
@@ -116,31 +147,28 @@ function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRender
             frameTimeBufferMS += deltaSmooth;
         }
 
-        if (fixedWidth)
+        if (fixedSize.x)
         {
             // clear set fixed size
-            mainCanvas.width  = fixedWidth;
-            mainCanvas.height = fixedHeight;
+            mainCanvas.width  = fixedSize.x;
+            mainCanvas.height = fixedSize.y;
             
-            if (fixedFitToWindow)
+            // fit to window by adding space on top or bottom if necessary
+            const aspect = innerWidth / innerHeight;
+            const fixedAspect = mainCanvas.width / mainCanvas.height;
+            mainCanvas.style.width  = overlayCanvas.style.width  = aspect < fixedAspect ? '100%' : '';
+            mainCanvas.style.height = overlayCanvas.style.height = aspect < fixedAspect ? '' : '100%';
+            if (glCanvas)
             {
-                // fit to window by adding space on top or bottom if necessary
-                const aspect = innerWidth / innerHeight;
-                const fixedAspect = fixedWidth / fixedHeight;
-                mainCanvas.style.width  = overlayCanvas.style.width  = aspect < fixedAspect ? '100%' : '';
-                mainCanvas.style.height = overlayCanvas.style.height = aspect < fixedAspect ? '' : '100%';
-                if (glCanvas)
-                {
-                    glCanvas.style.width  = mainCanvas.style.width;
-                    glCanvas.style.height = mainCanvas.style.height;
-                }
+                glCanvas.style.width  = mainCanvas.style.width;
+                glCanvas.style.height = mainCanvas.style.height;
             }
         }
         else
         {
             // clear and set size to same as window
-            mainCanvas.width  = min(innerWidth,  maxWidth);
-            mainCanvas.height = min(innerHeight, maxHeight);
+            mainCanvas.width  = min(innerWidth,  maxSize.x);
+            mainCanvas.height = min(innerHeight, maxSize.y);
         }
         
         // save canvas size and clear overlay canvas
@@ -178,7 +206,11 @@ function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRender
     tileImageSource ? tileImage.src = tileImageSource : tileImage.onload();
 }
 
-function engineUpdateObjects()
+
+///////////////////////////////////////////////////////////////////////////////
+
+/** Calls update on each engine object (recursively if child), removes destroyed objects, and updated time */
+function engineObjectsUpdate()
 {
     // recursive object update
     const updateObject = (o)=>
@@ -199,4 +231,40 @@ function engineUpdateObjects()
 
     // increment frame and update time
     time = ++frame / FPS;
+}
+
+/** Detroy and remove all objects that are not persistent or descendants of a persistent object */
+function engineObjectsDestroy()
+{
+    for (const o of engineObjects)
+        o.persistent || o.parent || o.destroy();
+    engineObjects = engineObjects.filter(o=>!o.destroyed);
+}
+
+/** Triggers a callback for each object within a given area
+ *  @param {Vector2} [pos] - Center of test area
+ *  @param {Number} [size] - Radius of circle if float, rectangle size if Vector2
+ *  @param {Function} [callbackFunction] - Calls this function on every object that passes the test
+ *  @param {Array} [objects=engineObjects] - List of objects to check */
+function engineObjectsCallback(pos, size, callbackFunction, objects=engineObjects)
+{
+    if (!pos)
+    {
+        // all objects
+        for (const o of objects)
+            callbackFunction(o);
+    }
+    else if (size.x != undefined)
+    {
+        // aabb test
+        for (const o of objects)
+            isOverlapping(pos, size, o.pos, o.size) && callbackFunction(o);
+    }
+    else
+    {
+        // circle test
+        const sizeSquared = size*size;
+        for (const o of objects)
+            pos.distanceSquared(o.pos) < sizeSquared && callbackFunction(o);
+    }
 }

package/engine/engineAudio.js

@@ -1,24 +1,42 @@
-/*
-    LittleJS Audio System
-    - ZzFX Sound Effects and ZzFXM Music
-    - Caches sounds and music for fast playback
-    - Can attenuate and apply stereo panning to sounds
-    - Ability to play mp3, ogg, and wave files
-    - Speech Synthesis wrapper functions
-*/
+/** 
+ *  LittleJS Audio System
+ *  <br> - ZzFX Sound Effects and ZzFXM Music
+ *  <br> - Caches sounds and music for fast playback
+ *  <br> - Can attenuate and apply stereo panning to sounds
+ *  <br> - Ability to play mp3, ogg, and wave files
+ *  <br> - Speech synthesis wrapper functions
+ *  @namespace Audio
+ */
 
 'use strict';
 
+/** 
+ * Sound Object - Stores a zzfx sound for later use and can be played positionally
+ * @example
+ * // create a sound
+ * const sound_example = new Sound([.5,.5]);
+ * 
+ * // play the sound
+ * sound_example.play();
+ */
 class Sound
 {
-    constructor(zzfxSound, range=defaultSoundRange, taper=defaultSoundTaper)
+    /** Create a sound object and cache the zzfx samples for later use
+     *  @param {Array}  zzfxSound - Array of zzfx parameters, ex. [.5,.5]
+     *  @param {Number} [range=soundDefaultRange] - World space max range of sound, will not play if camera is farther away
+     *  @param {Number} [taper=soundDefaultTaper] - At what percentage of range should it start tapering off
+     */
+    constructor(zzfxSound, range=soundDefaultRange, taper=soundDefaultTaper)
     {
         if (!soundEnable) return;
 
+        /** @property {Number} - World space max range of sound, will not play if camera is farther away */
         this.range = range;
+
+        /** @property {Number} - At what percentage of range should it start tapering off */
         this.taper = taper;
 
-        // get randomness from sound to apply when played
+        // get randomness from sound parameters
         this.randomness = zzfxSound[1] || 0;
         zzfxSound[1] = 0;
 
@@ -26,7 +44,14 @@ class Sound
         this.cachedSamples = zzfxG(...zzfxSound);
     }
 
-    play(pos, volumeScale=1, pitchScale=1)
+    /** Play the sound
+     *  @param {Vector2} [pos] - World space position to play the sound, sound is not attenuated if null
+     *  @param {Number}  [volume=1] - How much to scale volume by (in addition to range fade)
+     *  @param {Number}  [pitch=1] - How much to scale pitch by (also adjusted by this.randomness)
+     *  @param {Number}  [randomnessScale=1] - How much to scale randomness
+     *  @return {AudioBufferSourceNode} - The audio, can be used to stop sound later
+     */
+    play(pos, volume=1, pitch=1, randomnessScale=1)
     {
         if (!soundEnable) return;
 
@@ -42,7 +67,7 @@ class Sound
                     return; // out of range
 
                 // attenuate volume by distance
-                volumeScale *= percent(lengthSquared**.5, range*this.taper, range);
+                volume *= percent(lengthSquared**.5, range*this.taper, range);
             }
 
             // get pan from screen space coords
@@ -50,13 +75,57 @@ class Sound
         }
 
         // play the sound
-        const playbackRate = pitchScale + pitchScale * this.randomness*rand(-1,1);
-        return playSamples([this.cachedSamples], volumeScale, playbackRate, pan);
+        const playbackRate = pitch + pitch * this.randomness*randomnessScale*rand(-1,1);
+        return playSamples([this.cachedSamples], volume, playbackRate, pan);
+    }
+
+    /** Play the sound as a note with a semitone offset
+     *  @param {Number}  semitoneOffset - How many semitones to offset pitch
+     *  @param {Vector2} [pos] - World space position to play the sound, sound is not attenuated if null
+     *  @param {Number}  [volume=1] - How much to scale volume by (in addition to range fade)
+     *  @return {AudioBufferSourceNode} - The audio, can be used to stop sound later
+     */
+    playNote(semitoneOffset, pos, volume=1)
+    {
+        if (!soundEnable) return;
+
+        return this.play(pos, volume, 2**(semitoneOffset/12), 0);
     }
 }
 
+/**
+ * Music Object - Stores a zzfx music track for later use
+ * @example
+ * // create some music
+ * const music_example = new Music(
+ * [
+ *     [                         // 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 1, right speaker
+ *                 0, 12, 17, -1 // channel notes
+ *             ]
+ *         ],
+ *     ],
+ *     [0, 0, 0, 0], // sequence, play pattern 0 four times
+ *     90            // BPM
+ * ]);
+ * 
+ * // play the music
+ * music_example.play();
+ */
 class Music
 {
+    /** Create a music object and cache the zzfx music samples for later use
+     *  @param {Array} zzfxMusic - Array of zzfx music parameters
+     */
     constructor(zzfxMusic)
     {
         if (!soundEnable) return;
@@ -64,29 +133,44 @@ class Music
         this.cachedSamples = zzfxM(...zzfxMusic);
     }
 
-    play(volumeScale = 1, loop = 1)
+    /** Play the music
+     *  @param {Number}  [volume=1] - How much to scale volume by
+     *  @param {Boolean} [loop=1] - True if the music should loop when it reaches the end
+     *  @return {AudioBufferSourceNode} - The audio node, can be used to stop sound later
+     */
+    play(volume = 1, loop = 1)
     {
         if (!soundEnable) return;
 
-        return playSamples(this.cachedSamples, volumeScale, 1, 0, loop);
+        return playSamples(this.cachedSamples, volume, 1, 0, loop);
     }
 }
 
-///////////////////////////////////////////////////////////////////////////////
-
-// play mp3 or wav audio from a local file or url
-function playAudioFile(url, volumeScale=1, loop=1)
+/** Play an mp3 or wav audio from a local file or url
+ *  @param {String}  url - Location of sound file to play
+ *  @param {Number}  [volume=1] - How much to scale volume by
+ *  @param {Boolean} [loop=1] - True if the music should loop when it reaches the end
+ *  @return {HTMLAudioElement} - The audio element for this sound
+ *  @memberof Audio */
+function playAudioFile(url, volume=1, loop=1)
 {
     if (!soundEnable) return;
 
     const audio = new Audio(url);
-    audio.volume = audioVolume * volumeScale;
+    audio.volume = soundVolume * volume;
     audio.loop = loop;
     audio.play();
     return audio;
 }
 
-// speak text with passed in settings
+/** Speak text with passed in settings
+ *  @param {String} text - The text to speak
+ *  @param {String} [language] - The language/accent to use (examples: en, it, ru, ja, zh)
+ *  @param {Number} [volume=1] - How much to scale volume by
+ *  @param {Number} [rate=1] - How quickly to speak
+ *  @param {Number} [pitch=1] - How much to change the pitch by
+ *  @return {SpeechSynthesisUtterance} - The utterance that was spoken
+ *  @memberof Audio */
 function speak(text, language='', volume=1, rate=1, pitch=1)
 {
     if (!soundEnable || !speechSynthesis) return;
@@ -98,22 +182,39 @@ function speak(text, language='', volume=1, rate=1, pitch=1)
     // build utterance and speak
     const utterance = new SpeechSynthesisUtterance(text);
     utterance.lang = language;
-    utterance.volume = volume*audioVolume*3;
+    utterance.volume = 2*volume*soundVolume;
     utterance.rate = rate;
     utterance.pitch = pitch;
     speechSynthesis.speak(utterance);
     return utterance;
 }
 
-// stop all queued speech
+/** Stop all queued speech
+ *  @memberof Audio */
 const stopSpeech = ()=> speechSynthesis && speechSynthesis.cancel();
 
-///////////////////////////////////////////////////////////////////////////////
+/** Get frequency of a note on a musical scale
+ *  @param {Number} semitoneOffset - How many semitones away from the root note
+ *  @param {Number} [rootNoteFrequency=220] - Frequency at semitone offset 0
+ *  @return {Number} - The frequency of the note
+ *  @memberof Audio */
+const getNoteFrequency = (semitoneOffset, rootFrequency=220)=> rootFrequency * 2**(semitoneOffset/12); 
 
-let audioContext; // audio context used by the engine
+///////////////////////////////////////////////////////////////////////////////
 
-// play cached samples with given settings
-function playSamples(sampleChannels, volume=1, playbackRate=1, pan=0, loop=0) 
+/** Audio context used by the engine
+ *  @memberof Audio */
+let audioContext;
+
+/** Play cached audio samples with given settings
+ *  @param {Array}   sampleChannels - Array of arrays of samples to play (for stereo playback)
+ *  @param {Number}  [volume=1] - How much to scale volume by
+ *  @param {Number}  [rate=1] - The playback rate to use
+ *  @param {Number}  [pan=0] - How much to apply stereo panning
+ *  @param {Boolean} [loop=0] - True if the sound should loop when it reaches the end
+ *  @return {AudioBufferSourceNode} - The audio node of the sound played
+ *  @memberof Audio */
+function playSamples(sampleChannels, volume=1, rate=1, pan=0, loop=0) 
 {
     if (!soundEnable) return;
 
@@ -128,13 +229,13 @@ function playSamples(sampleChannels, volume=1, playbackRate=1, pan=0, loop=0)
     // copy samples to buffer and setup source
     sampleChannels.forEach((c,i)=> buffer.getChannelData(i).set(c));
     source.buffer = buffer;
-    source.playbackRate.value = playbackRate;
+    source.playbackRate.value = rate;
     source.loop = loop;
 
     // create pan and gain nodes
     source
         .connect(new StereoPannerNode(audioContext, {'pan':clamp(pan, 1, -1)}))
-        .connect(new GainNode(audioContext, {'gain':audioVolume*volume}))
+        .connect(new GainNode(audioContext, {'gain':soundVolume*volume}))
         .connect(audioContext.destination);
 
     // play and return sound
@@ -145,10 +246,20 @@ function playSamples(sampleChannels, volume=1, playbackRate=1, pan=0, loop=0)
 ///////////////////////////////////////////////////////////////////////////////
 // ZzFXMicro - Zuper Zmall Zound Zynth - v1.1.8 by Frank Force
 
-const zzfxR = 44100; // sample rate
-const zzfx = (...z) => playSamples([zzfxG(...z)]); // generate and play sound
+/** Generate and play a ZzFX sound
+ *  @param {Array} zzfxSound - Array of ZzFX parameters, ex. [.5,.5]
+ *  @return {Array} - Array of audio samples
+ *  @memberof Audio */
+const zzfx = (...zzfxSound) => playSamples([zzfxG(...zzfxSound)]);
+
+/** Sample rate used for all ZzFX sounds
+ *  @default 44100
+ *  @memberof Audio */
+const zzfxR = 44100; 
 
-function zzfxG // generate samples
+/** Generate samples for a ZzFX sound
+ *  @memberof Audio */
+function zzfxG
 (
     // parameters
     volume = 1, randomness = .05, frequency = 220, attack = 0, sustain = 0,
@@ -192,7 +303,7 @@ function zzfxG // generate samples
                     1 - tremolo + tremolo*Math.sin(PI2*i/repeatTime) // tremolo
                     : 1) *
                 sign(s)*(abs(s)**shapeCurve) *       // curve 0=square, 2=pointy
-                volume * audioVolume * (                  // envelope
+                volume * soundVolume * (                  // envelope
                 i < attack ? i/attack :                   // attack
                 i < attack + decay ?                      // decay
                 1-((i-attack)/decay)*(1-sustainVolume) :  // decay falloff
@@ -233,6 +344,13 @@ function zzfxG // generate samples
 ///////////////////////////////////////////////////////////////////////////////
 // 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 paramaters
+ *  @param {Array} patterns - Array of pattern data
+ *  @param {Array} sequence - Array of pattern indexes
+ *  @param {Number} [BPM=125] - Playback speed of the song in BPM
+ *  @returns {Array} - Left and right channel sample data
+ *  @memberof Audio */
 function zzfxM(instruments, patterns, sequence, BPM = 125) 
 {
   let instrumentParameters;

package/engine/{build.bat → engineBuild.bat}

@@ -11,11 +11,9 @@ del %OUTPUT_FILENAME%
 rem combine code
 type engineDebug.js >> %OUTPUT_FILENAME%
 echo.>> %OUTPUT_FILENAME%
-type engineUtil.js >> %OUTPUT_FILENAME%
+type engineUtilities.js >> %OUTPUT_FILENAME%
 echo.>> %OUTPUT_FILENAME%
-type engineConfig.js >> %OUTPUT_FILENAME%
-echo.>> %OUTPUT_FILENAME%
-type engine.js >> %OUTPUT_FILENAME%
+type engineSettings.js >> %OUTPUT_FILENAME%
 echo.>> %OUTPUT_FILENAME%
 type engineObject.js >> %OUTPUT_FILENAME%
 echo.>> %OUTPUT_FILENAME%
@@ -27,12 +25,14 @@ type engineAudio.js >> %OUTPUT_FILENAME%
 echo.>> %OUTPUT_FILENAME%
 type engineTileLayer.js >> %OUTPUT_FILENAME%
 echo.>> %OUTPUT_FILENAME%
-type engineParticle.js >> %OUTPUT_FILENAME%
+type engineParticles.js >> %OUTPUT_FILENAME%
 echo.>> %OUTPUT_FILENAME%
-type engineMedal.js >> %OUTPUT_FILENAME%
+type engineMedals.js >> %OUTPUT_FILENAME%
 echo.>> %OUTPUT_FILENAME%
 type engineWebGL.js >> %OUTPUT_FILENAME%
 echo.>> %OUTPUT_FILENAME%
+type engine.js >> %OUTPUT_FILENAME%
+echo.>> %OUTPUT_FILENAME%
 
 rem --- BUILD ENGINE RELEASE ---
 
@@ -44,9 +44,9 @@ del %OUTPUT_FILENAME%
 rem combine code
 type engineRelease.js >> %OUTPUT_FILENAME%
 echo.>> %OUTPUT_FILENAME%
-type engineUtil.js >> %OUTPUT_FILENAME%
+type engineUtilities.js >> %OUTPUT_FILENAME%
 echo.>> %OUTPUT_FILENAME%
-type engineConfig.js >> %OUTPUT_FILENAME%
+type engineSettings.js >> %OUTPUT_FILENAME%
 echo.>> %OUTPUT_FILENAME%
 type engine.js >> %OUTPUT_FILENAME%
 echo.>> %OUTPUT_FILENAME%
@@ -60,9 +60,9 @@ type engineAudio.js >> %OUTPUT_FILENAME%
 echo.>> %OUTPUT_FILENAME%
 type engineTileLayer.js >> %OUTPUT_FILENAME%
 echo.>> %OUTPUT_FILENAME%
-type engineParticle.js >> %OUTPUT_FILENAME%
+type engineParticles.js >> %OUTPUT_FILENAME%
 echo.>> %OUTPUT_FILENAME%
-type engineMedal.js >> %OUTPUT_FILENAME%
+type engineMedals.js >> %OUTPUT_FILENAME%
 echo.>> %OUTPUT_FILENAME%
 type engineWebGL.js >> %OUTPUT_FILENAME%
 echo.>> %OUTPUT_FILENAME%