littlejsengine 1.8.1 → 1.8.4

package/README.md

@@ -8,8 +8,8 @@
 
 ## 🚂 All aboard!
 
-LittleJS is a lightweight open source HTML5 game engine designed for modern web development.
-It's small footprint is packed with a comprehensive feature set, including hybrid rendering, physics, particles, sound effects, music, input handling, and debug tools.
+LittleJS is a lightweight open source HTML5 game engine for modern web development.
+It's small footprint is packed with a comprehensive feature set including hybrid rendering, physics, particles, sound effects, music, and input handling.
 The code is very clean and well documented with some fun examples to get you started. Choo-Choo! 🚂
 
 <div align="center">
@@ -28,27 +28,28 @@ LittleJS is a small but powerful game engine with many features and no dependenc
 
 - Super fast sprite and tile map rendering engine with WebGL
 - Update and render over 10,000 objects at a solid 60fps
-- Apply [Shadertoy](https://www.shadertoy.com) compatible shaders for post processinge effects
+- Apply [Shadertoy](https://www.shadertoy.com) compatible shaders for post-processing effects
 - Robust particle effect system and [effect design tool](https://killedbyapixel.github.io/LittleJS/examples/particles/)
 
 ### 🔊 Audio
 
-- Positional sound effects with wave or [ZzFX](https://killedbyapixel.github.io/ZzFX/)
+- Positional sound effects with wave files or ZzFX
+- Use [ZzFX](https://killedbyapixel.github.io/ZzFX/) sound effect generator to play sounds without asset files
 - Music with mp3, ogg, wave, or [ZzFXM](https://keithclark.github.io/ZzFXM/)
 
 ### 🎮 Input
 
-- Comprehensive system for keyboard, mouse, gamepad, and touch
+- Comprehensive input handling for keyboard, mouse, gamepad, and touch
 - On screen touch gamepad designed for mobile devices
 
 ### 💥 Physics
 
-- 2D physics engine with collision handling for axis aligned boxes
+- Robust 2D physics engine with collision handling for axis aligned boxes
 - Very fast collision and raycasting for tile maps
 
-### 🚀 Flexability
+### 🚀 Flexibility
 
-- Compatible with all modern web bowsers and on mobile devices
+- Compatible with all modern web browsers and on mobile devices
 - Support for TypeScript and Modules with example projects for both
 - Ideal for size coding competitions like [js13kGames](https://js13kgames.com/), [starter project builds to a 7KB zip](https://killedbyapixel.github.io/LittleJS/examples/js13k)
 - Builds to an executable with [Electron](https://www.electronjs.org/) for distribution on Windows, macOS, and Linux
@@ -65,8 +66,10 @@ LittleJS is a small but powerful game engine with many features and no dependenc
 
 ## Demos
 
+These examples are for both learning and using as starter projects to create your own games.
+
 ### [Starter Project](https://killedbyapixel.github.io/LittleJS/examples/starter/) - Clean example with only a few things to get you started
-### [Breakout](https://killedbyapixel.github.io/LittleJS/examples/breakout/) - Breakout game with post processing effect
+### [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 with procedural generation and destruction
 ### [Stress Test](https://killedbyapixel.github.io/LittleJS/examples/stress/) - Max sprite/object test and music system demo
@@ -74,12 +77,14 @@ LittleJS is a small but powerful game engine with many features and no dependenc
 
 ## How to use LittleJS
 
-To use LittleJS download the latest package from GitHub or call ```npm install littlejsengine```.
+To get started download the latest LittleJS package from GitHub or install via npm: ```npm install littlejsengine```.
 
 [The Breakout Tutorial](https://github.com/KilledByAPixel/LittleJS/tree/main/examples/breakoutTutorial) demonstrates how to make a simple game from scratch. [The tutorial is also available on YouTube.](https://youtu.be/tSwDx-NWTXE?si=bkjMa8-7AN2Wg5MO)
 
 [This GitNation talk explains how LittleJS works with some tips on how to use it.](https://youtu.be/_dXKU0WgAj8?si=ZDXLYAFDWp54hrGT)
 
+Join our vibrant community on [Discord](https://discord.gg/zb7hcGkyZe) to get help, share your projects, and collaborate with others.
+
 ## Builds
 
 To easily include LittleJS in your game, you can use one of the pre-built js files.

package/build/littlejs.esm.js

@@ -1558,6 +1558,7 @@ class EngineObject
         // set passed in params
         ASSERT(isVector2(pos) && isVector2(size)); // ensure pos and size are vec2s
         ASSERT(typeof tileInfo !== 'number' || !tileInfo); // prevent old style calls
+        ASSERT(!(renderOrder instanceof Color)); // prevent old style calls
         // to fix old calls, replace with tile(tileIndex, tileSize)
 
         /** @property {Vector2} - World space position of the object */
@@ -2079,16 +2080,18 @@ function worldToScreen(worldPos)
  *  @param {Color}   [additiveColor=Color(0,0,0,0)] - Additive color to be applied
  *  @param {Boolean} [useWebGL=glEnable]            - Use accelerated WebGL rendering
  *  @param {Boolean} [screenSpace=0]                - If true the pos and size are in screen space
+ *  @param {CanvasRenderingContext2D} [context]     - Canvas 2D context to draw to
  *  @memberof Draw */
 function drawTile(pos, size=vec2(1), tileInfo, color=new Color,
-    angle=0, mirror, additiveColor=new Color(0,0,0,0), useWebGL=glEnable, screenSpace)
+    angle=0, mirror, additiveColor=new Color(0,0,0,0), useWebGL=glEnable, screenSpace, context)
 {
+    ASSERT(!context || !useWebGL); // context only supported in canvas 2D mode
     ASSERT(typeof tileInfo !== 'number' || !tileInfo); // prevent old style calls
     // to fix old calls, replace with tile(tileIndex, tileSize)
 
     showWatermark && ++drawCount;
     const textureInfo = tileInfo && tileInfo.getTextureInfo();
-    if (glEnable && useWebGL)
+    if (useWebGL)
     {
         if (screenSpace)
         {
@@ -2139,7 +2142,7 @@ function drawTile(pos, size=vec2(1), tileInfo, color=new Color,
                 context.fillStyle = color;
                 context.fillRect(-.5, -.5, 1, 1);
             }
-        }, undefined, screenSpace);
+        }, screenSpace, context);
     }
 }
 
@@ -2150,28 +2153,36 @@ function drawTile(pos, size=vec2(1), tileInfo, color=new Color,
  *  @param {Number}  [angle=0]
  *  @param {Boolean} [useWebGL=glEnable]
  *  @param {Boolean} [screenSpace=0]
+ *  @param {CanvasRenderingContext2D} [context]
  *  @memberof Draw */
-function drawRect(pos, size, color, angle, useWebGL, screenSpace)
-{ drawTile(pos, size, undefined, color, angle, 0, undefined, useWebGL, screenSpace); }
+function drawRect(pos, size, color, angle, useWebGL, screenSpace, context)
+{ 
+    drawTile(pos, size, undefined, color, angle, 0, undefined, useWebGL, screenSpace, context); 
+}
 
 /** Draw colored polygon using passed in points
  *  @param {Array}   points - Array of Vector2 points
  *  @param {Color}   [color=Color()]
  *  @param {Boolean} [useWebGL=glEnable]
  *  @param {Boolean} [screenSpace=0]
+ *  @param {CanvasRenderingContext2D} [context]
  *  @memberof Draw */
-function drawPoly(points, color=new Color, useWebGL=glEnable, screenSpace)
+function drawPoly(points, color=new Color, useWebGL=glEnable, screenSpace, context)
 {
+    ASSERT(!context || !useWebGL); // context only supported in canvas 2D mode
+
     if (useWebGL)
         glDrawPoints(screenSpace ? points.map(screenToWorld) : points, color.rgbaInt());
     else
     {
         // draw using canvas
-        mainContext.fillStyle = color;
-        mainContext.beginPath();
+        if (!context)
+            context = mainContext;
+        context.fillStyle = color;
+        context.beginPath();
         for (const point of screenSpace ? points : points.map(worldToScreen))
-            mainContext.lineTo(point.x, point.y);
-        mainContext.fill();
+            context.lineTo(point.x, point.y);
+        context.fill();
     }
 }
 
@@ -2182,12 +2193,13 @@ function drawPoly(points, color=new Color, useWebGL=glEnable, screenSpace)
  *  @param {Color}   [color=Color()]
  *  @param {Boolean} [useWebGL=glEnable]
  *  @param {Boolean} [screenSpace=0]
+ *  @param {CanvasRenderingContext2D} [context]
  *  @memberof Draw */
-function drawLine(posA, posB, thickness=.1, color, useWebGL, screenSpace)
+function drawLine(posA, posB, thickness=.1, color, useWebGL, screenSpace, context)
 {
     const halfDelta = vec2((posB.x - posA.x)/2, (posB.y - posA.y)/2);
     const size = vec2(thickness, halfDelta.length()*2);
-    drawRect(posA.add(halfDelta), size, color, halfDelta.angle(), useWebGL, screenSpace);
+    drawRect(posA.add(halfDelta), size, color, halfDelta.angle(), useWebGL, screenSpace, context);
 }
 
 /** Draw directly to a 2d canvas context in world space
@@ -2196,10 +2208,10 @@ function drawLine(posA, posB, thickness=.1, color, useWebGL, screenSpace)
  *  @param {Number}   angle
  *  @param {Boolean}  mirror
  *  @param {Function} drawFunction
- *  @param {CanvasRenderingContext2D} [context=mainContext]
  *  @param {Boolean} [screenSpace=0]
+ *  @param {CanvasRenderingContext2D} [context=mainContext]
  *  @memberof Draw */
-function drawCanvas2D(pos, size, angle, mirror, drawFunction, context = mainContext, screenSpace)
+function drawCanvas2D(pos, size, angle, mirror, drawFunction, screenSpace, context=mainContext)
 {
     if (!screenSpace)
     {
@@ -2218,13 +2230,19 @@ function drawCanvas2D(pos, size, angle, mirror, drawFunction, context = mainCont
 /** Enable normal or additive blend mode
  *  @param {Boolean} [additive=0]
  *  @param {Boolean} [useWebGL=glEnable]
+ *  @param {CanvasRenderingContext2D} [context=mainContext]
  *  @memberof Draw */
-function setBlendMode(additive, useWebGL=glEnable)
+function setBlendMode(additive, useWebGL=glEnable, context)
 {
-    if (glEnable && useWebGL)
-        glSetBlendMode(additive);
+    ASSERT(!context || !useWebGL); // context only supported in canvas 2D mode
+    if (useWebGL)
+        glAdditive = additive;
     else
-        mainContext.globalCompositeOperation = additive ? 'lighter' : 'source-over';
+    {
+        if (!context)
+            context = mainContext;
+        context.globalCompositeOperation = additive ? 'lighter' : 'source-over';
+    }
 }
 
 /** Draw text on overlay canvas in world space
@@ -2876,7 +2894,8 @@ class Sound
         if (zzfxSound)
         {
             // generate zzfx sound now for fast playback
-            this.randomness = zzfxSound[1] || (zzfxSound[1] = 0);
+            this.randomness = zzfxSound[1] || 0;
+            zzfxSound[1] = 0; // generate without randomness
             this.sampleChannels = [zzfxG(...zzfxSound)];
             this.sampleRate = zzfxR;
         }
@@ -4382,21 +4401,20 @@ function glInit()
         '#version 300 es\n' +         // specify GLSL ES version
         'precision highp float;'+     // use highp for better accuracy
         'uniform mat4 m;'+            // transform matrix
-        'in vec2 p,t;'+               // position, uv
-        'in vec4 c,a;'+               // color, additiveColor
+        'in vec4 p,c,a;'+             // position, uv, color, additiveColor
         'out vec4 v,d,e;'+            // return uv, color, additiveColor
         'void main(){'+               // shader entry point
-        'gl_Position=m*vec4(p,1,1);'+ // transform position
-        'v=vec4(t,p);d=c;e=a;'+       // pass stuff to fragment shader
+        'gl_Position=m*vec4(p.xy,1,1);'+ // transform position
+        'v=p;d=c;e=a;'+               // pass stuff to fragment shader
         '}'                           // end of shader
         ,
         '#version 300 es\n' +         // specify GLSL ES version
         'precision highp float;'+     // use highp for better accuracy
-        'in vec4 v,d,e;'+             // uv, color, additiveColor
+        'in vec4 v,d,e;'+             // position, uv, color, additiveColor
         'uniform sampler2D s;'+       // texture
         'out vec4 c;'+                // out color
         'void main(){'+               // shader entry point
-        'c=texture(s,v.xy)*d+e;'+     // modulate texture by color plus additive
+        'c=texture(s,v.zw)*d+e;'+     // modulate texture by color plus additive
         '}'                           // end of shader
     );
 
@@ -4421,7 +4439,7 @@ function glPreRender()
     glContext.bindTexture(gl_TEXTURE_2D, glActiveTexture = textureInfos[0].glTexture);
     glContext.bindBuffer(gl_ARRAY_BUFFER, glArrayBuffer);
     glContext.bufferData(gl_ARRAY_BUFFER, gl_VERTEX_BUFFER_SIZE, gl_DYNAMIC_DRAW);
-    glSetBlendMode();
+    glAdditive = 0;
     
     // set vertex attributes
     let offset = 0;
@@ -4432,33 +4450,25 @@ function glPreRender()
         glContext.vertexAttribPointer(location, size, type, normalize, gl_VERTEX_BYTE_STRIDE, offset);
         offset += size*typeSize;
     }
-    initVertexAttribArray('p', gl_FLOAT, 4, 2);            // position
-    initVertexAttribArray('t', gl_FLOAT, 4, 2);            // texture coords
+    initVertexAttribArray('p', gl_FLOAT, 4, 4);            // position & texture coords
     initVertexAttribArray('c', gl_UNSIGNED_BYTE, 1, 4, 1); // color
     initVertexAttribArray('a', gl_UNSIGNED_BYTE, 1, 4, 1); // additiveColor
 
     // build the transform matrix
     const sx = 2 * cameraScale / mainCanvas.width;
     const sy = 2 * cameraScale / mainCanvas.height;
+    const cx = -1 - sx*cameraPos.x;
+    const cy = -1 - sy*cameraPos.y;
     glContext.uniformMatrix4fv(glContext.getUniformLocation(glShader, 'm'), 0,
         new Float32Array([
-            sx, 0, 0, 0,
-            0, sy, 0, 0,
-            1, 1, -1, 1,
-            -1-sx*cameraPos.x, -1-sy*cameraPos.y, 0, 0
+            sx,  0,  0,  0,
+             0, sy,  0,  0,
+             1,  1, -1,  1,
+            cx, cy,  0,  0
         ])
     );
 }
 
-/** Set the WebGl blend mode, normally you should call setBlendMode instead
- *  @param {Boolean} [additive=0]
- *  @memberof WebGL */
-function glSetBlendMode(additive=0)
-{
-    // setup blending
-    glAdditive = additive;
-}
-
 /** Set the WebGl texture, called automatically if using multiple textures
  *  - This may also flush the gl buffer resulting in more draw calls and worse performance
  *  @param {WebGLTexture} texture
@@ -4694,8 +4704,11 @@ function glRenderPostProcess()
         glFlush(); // clear out the buffer
         mainContext.drawImage(glCanvas, 0, 0); // copy to the main canvas
     }
-    else // set viewport
+    else
+    {
+        // set the viewport
         glContext.viewport(0, 0, glCanvas.width = mainCanvas.width, glCanvas.height = mainCanvas.height);
+    }
 
     if (glPostIncludeOverlay)
     {
@@ -4799,7 +4812,7 @@ const engineName = 'LittleJS';
  *  @type {String}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.8.1';
+const engineVersion = '1.8.4';
 
 /** Frames per second to update objects
  *  @type {Number}
@@ -4860,7 +4873,7 @@ let frameTimeLastMS = 0, frameTimeBufferMS = 0, averageFPS = 0;
  *  @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} [imageSources='tiles.png'] - Image to load
+ *  @param {Array} [imageSources=['tiles.png']] - Image to load
  *  @memberof Engine */
 function engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost, imageSources=['tiles.png'])
 {
@@ -5102,11 +5115,80 @@ function engineObjectsCallback(pos, size, callbackFunction, objects=engineObject
 
 /** 
  * LittleJS Module Export
- * - Export engine as a module with functions where necessary
+ * - Export engine as a module
  */
 
 export {
-	// Setters for global variables
+
+	// Engine
+	engineName,
+	engineVersion,
+	frameRate,
+	timeDelta,
+	engineObjects,
+	frame,
+	time,
+	timeReal,
+	paused,
+	setPaused,
+	engineInit,
+	engineObjectsUpdate,
+	engineObjectsDestroy,
+	engineObjectsCallback,
+	
+	// Globals
+	debug,
+	showWatermark,
+
+	// Debug
+	ASSERT,
+	debugRect,
+	debugCircle,
+	debugPoint,
+	debugLine,
+	debugAABB,
+	debugText,
+	debugClear,
+	debugSaveCanvas,
+
+	// Settings
+	cameraPos,
+	cameraScale,
+	canvasMaxSize,
+	canvasFixedSize,
+	canvasPixelated,
+	fontDefault,
+	tileSizeDefault,
+	tileFixBleedScale,
+	enablePhysicsSolver,
+	objectDefaultMass,
+	objectDefaultDamping,
+	objectDefaultAngleDamping,
+	objectDefaultElasticity,
+	objectDefaultFriction,
+	objectMaxSpeed,
+	gravity,
+	particleEmitRateScale,
+	glEnable,
+	glOverlay,
+	gamepadsEnable,
+	gamepadDirectionEmulateStick,
+	inputWASDEmulateDirection,
+	touchGamepadEnable,
+	touchGamepadAnalog,
+	touchGamepadSize,
+	touchGamepadAlpha,
+	vibrateEnable,
+	soundEnable,
+	soundVolume,
+	soundDefaultRange,
+	soundDefaultTaper,
+	medalDisplayTime,
+	medalDisplaySlideTime,
+	medalDisplaySize,
+	medalDisplayIconSize,
+
+	// Setters for globals
 	setCameraPos,
 	setCameraScale,
 	setCanvasMaxSize,
@@ -5146,58 +5228,6 @@ export {
 	setShowWatermark,
 	setDebugKey,
 
-	// Settings
-	canvasMaxSize,
-	canvasFixedSize,
-	canvasPixelated,
-	fontDefault,
-	tileSizeDefault,
-	tileFixBleedScale,
-	enablePhysicsSolver,
-	objectDefaultMass,
-	objectDefaultDamping,
-	objectDefaultAngleDamping,
-	objectDefaultElasticity,
-	objectDefaultFriction,
-	objectMaxSpeed,
-	gravity,
-	particleEmitRateScale,
-	cameraPos,
-	cameraScale,
-	glEnable,
-	glOverlay,
-	gamepadsEnable,
-	gamepadDirectionEmulateStick,
-	inputWASDEmulateDirection,
-	touchGamepadEnable,
-	touchGamepadAnalog,
-	touchGamepadSize,
-	touchGamepadAlpha,
-	vibrateEnable,
-	soundEnable,
-	soundVolume,
-	soundDefaultRange,
-	soundDefaultTaper,
-	medalDisplayTime,
-	medalDisplaySlideTime,
-	medalDisplaySize,
-	medalDisplayIconSize,
-	
-	// Globals
-	debug,
-	showWatermark,
-
-	// Debug
-	ASSERT,
-	debugRect,
-	debugCircle,
-	debugPoint,
-	debugLine,
-	debugAABB,
-	debugText,
-	debugClear,
-	debugSaveCanvas,
-
 	// Utilities
 	PI,
 	abs,
@@ -5235,9 +5265,6 @@ export {
 	rgb,
 	hsl,
 
-	// Base
-	EngineObject,
-
 	// Draw
 	textureInfos,
 	tile,
@@ -5262,6 +5289,15 @@ export {
 	isFullscreen,
 	toggleFullscreen,
 
+	// WebGL
+	glCanvas,
+	glContext,
+	glSetTexture,
+	glCompileShader,
+	glCreateProgram,
+	glCreateTexture,
+	glInitPostProcess,
+
 	// Input
 	keyIsDown,
 	keyWasPressed,
@@ -5296,6 +5332,9 @@ export {
 	playSamples,
 	zzfx,
 
+	// Base Object
+	EngineObject,
+
 	// Tiles
 	tileCollision,
 	tileCollisionSize,
@@ -5318,30 +5357,4 @@ export {
 	newgroundsInit,
 	Medal,
 	Newgrounds,
-
-	// WebGL
-	glCanvas,
-	glContext,
-	glSetBlendMode,
-	glSetTexture,
-	glCompileShader,
-	glCreateProgram,
-	glCreateTexture,
-	glInitPostProcess,
-
-	// Engine
-	engineName,
-	engineVersion,
-	frameRate,
-	timeDelta,
-	engineObjects,
-	frame,
-	time,
-	timeReal,
-	paused,
-	setPaused,
-	engineInit,
-	engineObjectsUpdate,
-	engineObjectsDestroy,
-	engineObjectsCallback,
 };