littlejsengine 1.13.4 → 1.14.4

package/reference.md

@@ -13,7 +13,7 @@ To start LittleJS, you need to create a few functions and pass them to engineIni
 
 ```javascript
 // Start up LittleJS engine with your callback functions
-engineInit(init, update, updatePost, render, renderPost, imageSources=[]);
+engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost, imageSources=[], rootElement=document.body)
 ```
 
 ## LittleJS Utilities Classes and Functions
@@ -33,13 +33,14 @@ tile(pos, size=(16,16), texture=0, padding=0) // Create a tile info object
 
 // Helper functions 
 abs(value)                                    // Get absolute value
-min(valueA, valueB)                           // Get lowest of values
-max(valueA, valueB)                           // Get highest of values
+min(...values)                                // Get lowest of values
+max(...values)                                // Get highest of values
 sign(value)                                   // Get the sign of value
 mod(dividend, divisor=1)                      // Get remainder of division
 clamp(value, min=0, max=1)                    // Clamps between values
 percent(value, valueA, valueB)                // Get percentage between values
 lerp(valueA, valueB, percent)                 // Linearly interpolates between values
+percentLerp(value, percentA, percentB, lerpA, lerpB) // Lerp that remaps the percent
 distanceWrap(valueA, valueB, wrapSize=1)      // Signed wrapped distance between values
 lerpWrap(valueA, valueB, percent, wrapSize=1) // Linearly interpolates with wrapping
 distanceAngle(angleA, angleB)                 // Signed wrapped distance between angles
@@ -54,7 +55,8 @@ formatTime(t)                                 // Formats seconds for display
 // Random functions
 rand(valueA=1, valueB=0)             // Random float between values
 randInt(valueA, valueB=0)            // Random integer between values
-randSign()                           // Randomly bool either -1 or 1
+randBool(chance=.5)                  // Random boolean with given chance (0 to 1)
+randSign()                           // Randomly either -1 or 1
 randVec2(length=1)                   // Random Vector2 with the passed in length
 randInCircle(radius=1, minRadius=0)  // Random Vector2 within a circle
 randColor(colorA, colorB, linear)    // Random color between values
@@ -111,16 +113,16 @@ RandomGenerator.int(valueA, valueB=0)     // Random integer between values
 RandomGenerator.sign()                    // Randomly either -1 or 1
 
 // Time tracking system
-Timer(timeLeft)        // Create a timer object
-Timer.set(timeLeft=0)  // Set the timer with seconds passed in
-Timer.unset()          // Unset the timer
-Timer.isSet()          // Returns true if set
-Timer.active()         // Returns true if set and has not elapsed
-Timer.elapsed()        // Returns true if set and elapsed
-Timer.get()            // Get how long since elapsed, 0 if not set
-Timer.getPercent()     // Get percent elapsed, 0 if not set
-Timer.toString()       // Get this timer expressed as a string
-Timer.valueOf()        // Get how long since elapsed, 0 if not set
+Timer(timeLeft)       // Create a timer object
+Timer.set(timeLeft=0) // Set the timer with seconds passed in
+Timer.unset()         // Unset the timer
+Timer.isSet()         // Returns true if set
+Timer.active()        // Returns true if set and has not elapsed
+Timer.elapsed()       // Returns true if set and elapsed
+Timer.get()           // Get how long since elapsed, 0 if not set
+Timer.getPercent()    // Get percent elapsed, 0 if not set
+Timer.toString()      // Get this timer expressed as a string
+Timer.valueOf()       // Get how long since elapsed, 0 if not set
 ```
 
 ## LittleJS Drawing System
@@ -131,35 +133,48 @@ Timer.valueOf()        // Get how long since elapsed, 0 if not set
 
 ```javascript
 // Drawing functions
-drawTile(pos, size=(1,1), tileInfo, color=WHITE, angle=0, mirror, additiveColor)
-drawRect(pos, size=(1,1), color=WHITE, angle=0)
-drawLine(posA, posB, thickness=.1, color=WHITE)
-drawCanvas2D(pos, size, angle, mirror, drawFunction)
-drawText(text, pos, size=1, color=WHITE, lineWidth, lineColor)
-drawTextScreen(text, pos, size=1, color=WHITE, lineWidth, lineColor)
+drawTile(pos, size, tileInfo, color=WHITE, angle=0, mirror, additiveColor)
+drawRect(pos, size, color=WHITE, angle=0)
+drawRectGradient(pos, size, colorTop=WHITE, colorBottom=BLACK, angle=0)
+drawLine(posA, posB, width=.1, color=WHITE, pos=(0,0), angle=0)
+drawLineList(points, width=.1, color, wrap=false, pos=(0,0), angle=0)
+drawPoly(points, color=WHITE, lineWidth=0, lineColor=BLACK, pos, angle=0)
+drawRegularPoly(pos, size=(1,1), sides=3, color=WHITE, lineWidth=0, lineColor=BLACK, angle=0)
+drawEllipse(pos, size=(1,1), color=WHITE, angle=0, lineWidth=0, lineColor=BLACK)
+drawCircle(pos, size=1, color=WHITE, lineWidth=0, lineColor=BLACK)
+drawCanvas2D(pos, size, angle=0, mirror, drawFunction, screenSpace, context)
+
+// Text functions
+drawText(text, pos, size=1, color=WHITE, lineWidth=0, lineColor=BLACK)
+drawTextOverlay(text, pos, size=1, color=WHITE, lineWidth=0, lineColor=BLACK)
+drawTextScreen(text, pos, size=1, color=WHITE, lineWidth=0, lineColor=BLACK)
+
+// Utility drawing functions
 setBlendMode(additive)
-toggleFullscreen()
 isFullscreen()
+toggleFullscreen()
 
 // Tile Info Object
-TileInfo(pos=(0,0), size, textureIndex=0) // Create a tile info object
-TileInfo.pos              // Top left corner of tile in pixels
-TileInfo.size             // Size of tile in pixels
-TileInfo.textureIndex     // Texture index to use
-TileInfo.offset(offset)   // Offset this tile by a certain amount in pixels
-TileInfo.frame(frame)     // Offset this tile by a number of animation frames
-TileInfo.textureInfo      // The texture info for this tile
+TileInfo(pos, size, textureIndex=0, padding=0) // Create a tile info object
+TileInfo.pos            // Top left corner of tile in pixels
+TileInfo.size           // Size of tile in pixels
+TileInfo.textureIndex   // Texture index to use
+TileInfo.padding        // How many pixels padding around tiles
+TileInfo.offset(offset) // Offset this tile by a certain amount in pixels
+TileInfo.frame(frame)   // Offset this tile by a number of animation frames
+TileInfo.textureInfo    // The texture info for this tile
 
 // Texture Info Object
-TextureInfo(image)       // Created automatically for each image
-TextureInfo.image        // Image source
-TextureInfo.size         // Size of the image
-TextureInfo.glTexture    // WebGL texture
+TextureInfo(image)      // Created automatically for each image
+TextureInfo.image       // Image source
+TextureInfo.size        // Size of the image
+TextureInfo.glTexture   // WebGL texture
 
 // Font Image Object draws text using characters in an image
 FontImage(image, tileSize=(8,8), paddingSize=(0,1)) // Create an image font
 FontImage.drawText(text, pos, scale, center)        // Draw text in world space
 FontImage.drawTextScreen(text, pos, scale, center)  // Draw text in screen space
+FontImage.drawTextOverlay(text, pos, scale, center) // Draw text to overlay canvas
 
 // Camera settings
 cameraPos = (0,0)        // Position of camera in world space
@@ -183,31 +198,45 @@ tileFixBleedScale = .3     // How much smaller to draw tiles to prevent bleeding
 ```
 
 ## LittleJS Audio System
-- Caches sounds and music for fast playback
+- Caches sounds and music for fast playback with frame-spread loading
+- Individual sound instance control with pause/resume capabilities
 - Can attenuate and apply stereo panning to sounds
-- Ability to play mp3, ogg, and wave file
+- Ability to play mp3, ogg, and wave files with loading progress tracking
 - [ZzFX Sound Effect Generator](https://killedbyapixel.github.io/ZzFX)
 - [ZzFXM Music System](https://keithclark.github.io/ZzFXM)
 
 ```javascript
 // Sound Object
-Sound(zzfxSound)                                        // Create a zzfx sound
-SoundWave(filename, randomness=0)                       // Load a wave, mp3, and ogg
-Sound.play(pos, volume=1, pitch=1, randomness=1, loop)  // Play a sound
-Sound.playNote(semitoneOffset, pos, volume=1)           // Play as note with a semitone offset
-Sound.stop()                                            // Stop the last instance that was played
-Sound.getSource()                                       // Get source of most recent instance
-Sound.getDuration()                                     // Get length of sound in seconds
-Sound.isLoading()                                       // Check if sound is loading
-
-// ZzFXM - A tiny music system
-Music(..zzfxMusic)                                      // Create a zzfx music object
-Music.playMusic(volume, loop=false)                     // Play the music
+Sound(zzfxSound, range, taper)                         // Create a zzfx sound
+SoundWave(filename, randomness=0, range, taper)        // Load a wave, mp3, or ogg
+Sound.play(pos, volume=1, pitch=1, randomness=1, loop) // Play a sound, returns SoundInstance
+Sound.playMusic(volume=1, loop=true)                   // Play as music with looping
+Sound.playNote(semitoneOffset, pos, volume=1)          // Play as note with a semitone offset
+Sound.getDuration()                                    // Get length of sound in seconds
+Sound.isLoaded()                                       // Check if sound is currently loading
+Sound.loadedPercent                                    // Get loading progress (0 to 1)
+
+// SoundInstance
+SoundInstance.start()             // Start playing the sound
+SoundInstance.setVolume(volume)   // Change volume during playback
+SoundInstance.stop(fadeTime=0)    // Stop with optional fade out
+SoundInstance.pause()             // Pause the sound
+SoundInstance.unpause()           // Resume paused sound
+SoundInstance.isPlaying()         // Check if currently playing
+SoundInstance.isPaused()          // Check if paused
+SoundInstance.isStopped()         // Check if stopped
+SoundInstance.getCurrentTime()    // Get current playback position
+SoundInstance.getDuration()       // Get total duration
+SoundInstance.getSource()         // Get AudioBufferSourceNode
+
+// ZzFXM - Tiny music playing system
+Music(..zzfxMusic)                                   // Create a zzfx music object
+Music.playMusic(volume=1, loop=true)                // Play the music
 
 // Audio functions
-playAudioFile(filename, volume=1, loop=false)           // Play an audio file or url
-speak(text, language='', volume=1, rate=1, pitch=1)     // Speak text line
-speakStop()                                             // Stop all queued speech
+speak(text, language='', volume=1, rate=1, pitch=1)  // Speak text line
+speakStop()                                          // Stop all queued speech
+getNoteFrequency(semitoneOffset, rootFrequency=220)  // Get frequency for musical notes
 
 // Audio settings
 soundEnable = true      // Should sound be enabled?
@@ -228,11 +257,13 @@ soundDefaultTaper = .7  // Default range percent to taper off sound (0-1)
 keyIsDown(key)                        // Is key down?
 keyWasPressed(key)                    // Was key pressed this frame?
 keyWasReleased(key)                   // Was key released this frame?
-keyDirection(up, down, left, right)                        // Get input vector from arrow keys or wasd
+keyDirection(up, down, left, right)   // Get input vector from arrow keys or wasd
 
 // Mouse / Touch
 mousePos                              // World space mouse position
 mousePosScreen                        // Screen space mouse position
+mouseDelta                            // World space mouse movement delta
+mouseDeltaScreen                      // Screen space mouse movement delta
 mouseWheel                            // Delta mouse wheel this frame    
 mouseIsDown(button)                   // Is mouse button down?
 mouseWasPressed(button)               // Was mouse button pressed this frame?
@@ -286,7 +317,7 @@ EngineObject.render()                              // Render object, called auto
 EngineObject.destroy()                             // Destroy this object and children
 EngineObject.collideWithTile(tileData, pos)        // Tile collision resolve check
 EngineObject.collideWithObject(object)             // Object collision resolve check
-EngineObject.getAliveTime(object)                  // How long since object was created
+EngineObject.getAliveTime()                        // How long since object was created
 EngineObject.applyAcceleration(acceleration)       // Apply acceleration
 EngineObject.applyForce(force)                     // Apply force
 EngineObject.getMirrorSign()                       // Get mirror direction (1 or -1)
@@ -324,7 +355,7 @@ objectMaxSpeed = 1            // Clamp max speed to avoid fast objects missing c
 gravity = (0,0)               // How much gravity to apply to objects
 
 // Engine Object functions
-engineObjectsCollect(pos, size, objects=engineObjects)k
+engineObjectsCollect(pos, size, objects=engineObjects)
 engineObjectsCallback(pos, size, callbackFunction, objects=engineObjects)
 engineObjectsRaycast(start, end, objects=engineObjects)
 engineObjectsDestroy()
@@ -341,6 +372,13 @@ engineObjectsDestroy()
 
 ```javascript
 
+// Canvas Layer
+CanvasLayer(position, size) // Create a canvas layer object
+CanvasLayer.canvas          // The canvas used by this layer
+CanvasLayer.context         // The 2D context of the canvas
+CanvasLayer.getImageData()  // Get image data from canvas
+CanvasLayer.useWebGL()      // Creates or updates WebGL texture
+
 // LittleJS Layer System
 TileLayer(position, size, tileInfo, scale)     // Create a tile layer object
 TileLayer.setData(layerPos, data, redraw)      // Set data at position
@@ -353,7 +391,7 @@ TileLayer.drawCanvas2D(pos, size, angle, mirror, drawFunction)      // Draw to 2
 
 // Tile Layer Data Object
 TileLayerData(tile, direction=0, mirror=false, color=WHITE) // Create tile data object
-TileLayerData.clear()      // Clear this tile data
+TileLayerData.clear()                                       // Clear this tile data
 
 // Tile Collision Layer
 TileCollisionLayer(position, size, tileInfo=tile()) // Create a tile collision layer object
@@ -387,10 +425,10 @@ particleEmitRateScale = 1 // Scales particles emit rate
 
 ```javascript
 ASSERT(assert, output) // Asserts if the expression is false
-debugRect(pos, size, color='#fff', time=0, angle=0, fill)   // Draw debug rectangle
-debugCircle(pos, radius, color='#fff', time=0, fill)        // Draw debug circle
+debugRect(pos, size, color='#fff', time=0, angle=0, fill) // Draw debug rectangle
+debugCircle(pos, radius, color='#fff', time=0, fill)      // Draw debug circle
 debugPoint(pos, color, time, angle)                         // Draw debug point
-debugLine(posA, posB, color, thickness=.1, time)            // Draw debug line
+debugLine(posA, posB, color, width=.1, time)                // Draw debug line
 debugText(text, pos, size=1, color='#fff', time=0, angle=0) // Draw debug text
 debugAABB(pA, sA, pB, sB, color)     // Draw a debug axis aligned box
 debugClear()                         // Clear all debug primitives

package/src/engine.js

@@ -1,7 +1,7 @@
-/** 
+/**
  * LittleJS - The Tiny Fast JavaScript Game Engine
  * MIT License - Copyright 2021 Frank Force
- * 
+ *
  * Engine Features
  * - Object oriented system with base class engine object
  * - Base class object handles update, physics, collision, rendering, etc
@@ -30,7 +30,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.13.4';
+const engineVersion = '1.14.4';
 
 /** Frames per second to update
  *  @type {number}
@@ -120,7 +120,7 @@ function engineAddPlugin(updateFunction, renderFunction)
  *  // Basic engine startup
  *  engineInit(
  *    () => { console.log('Game initialized!'); },  // gameInit
- *    () => { updatePlayer(); },                    // gameUpdate  
+ *    () => { updateGameLogic(); },                 // gameUpdate
  *    () => { updateUI(); },                        // gameUpdatePost
  *    () => { drawBackground(); },                  // gameRender
  *    () => { drawHUD(); },                         // gameRenderPost
@@ -146,7 +146,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         mainCanvasSize = vec2(mainCanvas.width, mainCanvas.height);
 
         // disable smoothing for pixel art
-        overlayContext.imageSmoothingEnabled = 
+        overlayContext.imageSmoothingEnabled =
             mainContext.imageSmoothingEnabled = !tilesPixelated;
 
         // setup gl rendering if enabled
@@ -194,7 +194,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
                 deltaSmooth = frameTimeBufferMS;
                 frameTimeBufferMS = 0;
             }
-            
+
             // update multiple frames if necessary in case of slow framerate
             for (;frameTimeBufferMS >= 0; frameTimeBufferMS -= 1e3 / frameRate)
             {
@@ -239,15 +239,14 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
                 overlayContext.textBaseline = 'top';
                 overlayContext.font = '1em monospace';
                 overlayContext.fillStyle = '#000';
-                const text = engineName + ' ' + 'v' + engineVersion + ' / ' 
+                const text = engineName + ' ' + 'v' + engineVersion + ' / '
                     + drawCount + ' / ' + engineObjects.length + ' / ' + averageFPS.toFixed(1)
                     + (glEnable ? ' GL' : ' 2D') ;
                 overlayContext.fillText(text, mainCanvas.width-3, 3);
                 overlayContext.fillStyle = '#fff';
                 overlayContext.fillText(text, mainCanvas.width-2, 2);
             }
-            if (debug || showWatermark)
-                drawCount = 0;
+            drawCount = 0;
         }
         requestAnimationFrame(engineUpdate);
     }
@@ -255,13 +254,13 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     function updateCanvas()
     {
         if (headlessMode) return;
-        
+
         if (canvasFixedSize.x)
         {
             // clear canvas and set fixed size
             mainCanvas.width  = canvasFixedSize.x;
             mainCanvas.height = canvasFixedSize.y;
-            
+
             // fit to window by adding space on top or bottom if necessary
             const aspect = innerWidth / innerHeight;
             const fixedAspect = mainCanvas.width / mainCanvas.height;
@@ -271,16 +270,21 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         else
         {
             // clear canvas and set size to same as window
-            mainCanvas.width  = min(innerWidth,  canvasMaxSize.x);
+            mainCanvas.width = min(innerWidth, canvasMaxSize.x);
             mainCanvas.height = min(innerHeight, canvasMaxSize.y);
         }
-        
+
         // clear overlay canvas and set size
         overlayCanvas.width  = mainCanvas.width;
         overlayCanvas.height = mainCanvas.height;
 
         // save canvas size
         mainCanvasSize = vec2(mainCanvas.width, mainCanvas.height);
+
+        // set default line join and cap
+        const lineJoin = 'round', lineCap = 'round';
+        mainContext.lineJoin = overlayContext.lineJoin = lineJoin;
+        mainContext.lineCap  = overlayContext.lineCap  = lineCap;
     }
 
     // wait for gameInit to load
@@ -293,15 +297,14 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
         return startEngine();
 
     // setup html
-    const styleRoot = 
+    const styleRoot =
         'margin:0;' +                 // fill the window
         'overflow:hidden;' +          // no scroll bars
         'background:#000;' +          // set background color
         'user-select:none;' +         // prevent hold to select
         '-webkit-user-select:none;' + // compatibility for ios
-        (!touchInputEnable ? '' :     // no touch css settings
         'touch-action:none;' +        // prevent mobile pinch to resize
-        '-webkit-touch-callout:none');// compatibility for ios
+        '-webkit-touch-callout:none';// compatibility for ios
     rootElement.style.cssText = styleRoot;
     drawCanvas = mainCanvas = document.createElement('canvas');
     rootElement.appendChild(mainCanvas);
@@ -318,7 +321,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     rootElement.appendChild(overlayCanvas);
     overlayContext = overlayCanvas.getContext('2d');
 
-    // set canvas style
+    // set canvases
     const styleCanvas = 'position:absolute;'+ // allow canvases to overlap
         'top:50%;left:50%;transform:translate(-50%,-50%)'; // center on screen
     mainCanvas.style.cssText = overlayCanvas.style.cssText = styleCanvas;
@@ -327,17 +330,18 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     setCanvasPixelated(canvasPixelated);
     setOverlayCanvasPixelated(overlayCanvasPixelated);
     updateCanvas();
+    glPreRender();
 
     // create offscreen canvas for image processing
     workCanvas = new OffscreenCanvas(256, 256);
     workContext = workCanvas.getContext('2d', { willReadFrequently: true });
-    
+
     // create promises for loading images
     const promises = imageSources.map((src, textureIndex)=>
-        new Promise(resolve => 
+        new Promise(resolve =>
         {
             const image = new Image;
-            image.onerror = image.onload = ()=> 
+            image.onerror = image.onload = ()=>
             {
                 const textureInfo = new TextureInfo(image);
                 textureInfo.createWebGLTexture();
@@ -352,7 +356,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     if (!imageSources.length)
     {
         // no images to load
-        promises.push(new Promise(resolve => 
+        promises.push(new Promise(resolve =>
         {
             const textureInfo = new TextureInfo(new Image);
             textureInfos[0] = textureInfo;
@@ -364,7 +368,7 @@ async function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, game
     if (showSplashScreen)
     {
         // draw splash screen
-        promises.push(new Promise(resolve => 
+        promises.push(new Promise(resolve =>
         {
             let t = 0;
             console.log(`${engineName} Engine v${engineVersion}`);
@@ -596,7 +600,7 @@ function drawEngineSplashScreen(t)
     line(36,20,60,20);
 
     // engine front light
-    circle(60,30,4,PI,3*PI,color(3,2)); 
+    circle(60,30,4,PI,3*PI,color(3,2));
     circle(60,30,4,PI,2*PI,color(3,3));
     circle(60,30,4,PI,3*PI);
 
@@ -645,6 +649,6 @@ function drawEngineSplashScreen(t)
         x[j?'strokeText':'fillText'](s[i],X+w/2,55.5,17*p);
         X += w;
     }
-    
+
     x.restore();
 }