littlejsengine 1.17.11 → 1.17.15

package/src/engineDraw.js

@@ -1,21 +1,22 @@
 /**
  * LittleJS Drawing System
- * - Hybrid system with both Canvas2D and WebGL available
- * - Super fast tile sheet rendering with WebGL
- * - Can apply rotation, mirror, color and additive color
- * - Font rendering system with built in engine font
- * - Many useful utility functions
+ * - Hybrid rendering with both Canvas2D and WebGL support
+ * - Optimized tile sheet sprite rendering using WebGL batching
+ * - Primitive drawing for polygons, ellipses, and lines
+ * - Tile-based rendering with TileInfo and TextureInfo classes
+ * - Text rendering with custom fonts and FontImage support
+ * - Color and additive color blending for effects
+ * - Rotation, mirroring, and scaling transformations
+ * - Camera system with position, scale, and rotation
+ * - Multiple canvas support (main, WebGL, work canvases)
+ * - Gradient fills and outlined shapes
+ * - Image manipulation and color tinting
  *
- * LittleJS uses a hybrid rendering solution with the best of both Canvas2D and WebGL.
- * There are 3 canvas/contexts available to draw to...
- * mainCanvas - 2D background canvas, non WebGL stuff like tile layers are drawn here.
- * glCanvas - Used by the accelerated WebGL batch rendering system.
+ * Rendering Architecture:
+ * - glCanvas: WebGL canvas for accelerated sprite batch rendering
+ * - mainCanvas: Canvas2D overlay for text, UI, and custom drawing
+ * - All draw functions default to WebGL when enabled, can force Canvas2D with useWebGL parameter
  *
- * The WebGL rendering system is very fast with some caveats...
- * - Switching blend modes (additive) or textures causes another draw call which is expensive in excess
- * - Group additive rendering together using renderOrder to mitigate this issue
- *
- * The LittleJS rendering solution is intentionally simple, feel free to adjust it for your needs!
  * @namespace Draw
  */
 
@@ -108,6 +109,7 @@ function tile(index=new Vector2, size=tileDefaultSize, texture=0, padding=tileDe
     // create tile info object
     const textureInfo = typeof texture === 'number' ?
         textureInfos[texture] : texture;
+    ASSERT(textureInfo instanceof TextureInfo, 'tile texture is not loaded');
 
     // get the position of the tile
     const sizePaddedX = size.x + padding*2;

package/src/engineExport.js

@@ -1,5 +1,6 @@
 /**
  * LittleJS Module Export
+ * - Exports all engine modules and functions for external use
  */
 
 export
@@ -168,7 +169,7 @@ export
     nearestPowerOfTwo,
     isOverlapping,
     isIntersecting,
-    wave,
+    oscillate,
 
     // Utilities
     formatTime,

package/src/engineInput.js

@@ -1,10 +1,13 @@
 /**
  * LittleJS Input System
- * - Tracks keyboard down, pressed, and released
- * - Tracks mouse buttons, position, and wheel
- * - Tracks multiple analog gamepads
- * - Touch input is handled as mouse input
- * - Virtual gamepad for touch devices
+ * - Keyboard input with key down, pressed, and released states
+ * - Mouse input with position (world and screen space), buttons, and wheel
+ * - Gamepad support for multiple controllers with analog sticks and buttons
+ * - Touch input mapped to mouse position and buttons
+ * - Virtual on-screen gamepad for mobile devices
+ * - Automatic gamepad vs keyboard/mouse detection
+ * - Input event prevention for canvas focus
+ * - Clipboard copy/paste support
  * @namespace Input
  */
 
@@ -336,7 +339,19 @@ function inputInit()
                 inputData[0][remapKey(e.code)] = 3;
         }
 
-        // prevent arrow key from moving the page
+        // try to prevent default browser handling of input
+        if (!inputPreventDefault || !document.hasFocus() || !e.cancelable) return;
+
+        // don't break browser shortcuts
+        if (e.ctrlKey || e.metaKey || e.altKey) return;
+
+        // don't interfere with user typing into UI fields
+        if (isTextInput(e.target) || isTextInput(document.activeElement)) return;
+
+        // fix browser setting "Search for text when you start typing"
+        const printable = typeof e.key === 'string' && e.key.length === 1;
+
+        // prevent arrow key and other default keys from messing with stuff
         const preventDefaultKeys = 
         [
             'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', // scrolling
@@ -344,9 +359,15 @@ function inputInit()
             'Tab',          // focus navigation
             'Backspace',    // browser back
         ];
-        if (preventDefaultKeys.includes(e.code))
-        if (inputPreventDefault && document.hasFocus() && e.cancelable)
+        if (preventDefaultKeys.includes(e.code) || printable)
             e.preventDefault();
+                    
+        function isTextInput(element)
+        {
+            const tag = element?.tagName;
+            const editable = element?.isContentEditable;
+            return editable || ['INPUT','TEXTAREA','SELECT'].includes(tag);
+        }
     }
     function onKeyUp(e)
     {

package/src/engineMath.js

@@ -1,9 +1,16 @@
 /**
  * LittleJS Math Classes and Functions
- * - General purpose math library
- * - RandomGenerator - seeded random number generator
- * - Vector2 - fast, simple, easy 2D vector class
- * - Color - holds a rgba color with math functions
+ * - Comprehensive math utilities for game development
+ * - Vector2 class for 2D positions, directions, and math operations
+ * - Color class for RGBA colors with interpolation and manipulation
+ * - RandomGenerator for seeded pseudo-random number generation
+ * - Math shortcuts (PI, abs, floor, ceil, min, max, sin, cos, etc.)
+ * - Interpolation functions (lerp, smoothStep, percent)
+ * - Clamping, wrapping, and modulo operations
+ * - Angle utilities with wrap-around support
+ * - Collision detection (overlapping, intersection, line tests)
+ * - Random number generation and seeding
+ * - Type checking utilities
  * @namespace Math
  */
 
@@ -254,10 +261,24 @@ function isIntersecting(start, end, pos, size)
  *  @param {number} [amplitude] - Amplitude (max height) of the wave
  *  @param {number} [t=time]    - Value to use for time of the wave
  *  @param {number} [offset]    - Value to use for time offset of the wave
+ *  @param {number} [type]      - Wave type: 0=sine, 1=triangle, 2=square, 3=sawtooth
  *  @return {number}            - Value waving between 0 and amplitude
  *  @memberof Math */
-function wave(frequency=1, amplitude=1, t=time, offset=0)
-{ return amplitude/2 * (1 - cos(offset + t*frequency*2*PI)); }
+function oscillate(frequency=1, amplitude=1, t=time, offset=0, type=0)
+{
+    const phase = (offset + t*frequency) % 1;
+    let value;
+    
+    if (type === 1) // triangle
+        value = 2 * abs(2 * phase - 1) - 1;
+    else if (type === 2) // square
+        value = phase < .5 ? -1 : 1;
+    else if (type === 3) // sawtooth
+        value = 2 * phase - 1;
+    else // sine
+        value = -cos(phase * 2*PI);
+    return amplitude/2 * (value + 1);
+}
 
 /**
  * Check if object is a valid number, not NaN or undefined, but it may be infinite
@@ -339,15 +360,17 @@ function lineTest(posStart, posEnd, testFunction, normal)
             // set hit point
             const hitPos = vec2(posStart.x + dirX*t, posStart.y + dirY*t);
 
-            // move inside of tile if on positive edge
+            // ensure result is inside the tile
             const e = 1e-9;
-            if (wasX)
-            {
-                if (stepX < 0)
-                    hitPos.x -= e;
-            }
-            else if (stepY < 0)
-                hitPos.y -= e;
+            const hitPosFloor = hitPos.floor();
+            if (hitPosFloor.x < pos.x)
+                hitPos.x = pos.x;
+            else if (hitPosFloor.x > pos.x)
+                hitPos.x = pos.x + 1 - e;
+            if (hitPosFloor.y < pos.y)
+                hitPos.y = pos.y;
+            else if (hitPosFloor.y > pos.y) 
+                hitPos.y = pos.y + 1 - e;
 
             // set normal
             if (normal)
@@ -740,6 +763,15 @@ class Vector2
      * @return {Vector2} */
     floor() { return new Vector2(floor(this.x), floor(this.y)); }
 
+    /** Returns a copy of this vector snapped to a grid
+     *  @param {number} grid - grid size to snap to
+     *  @return {Vector2} */
+    snap(grid)
+    {
+        ASSERT_NUMBER_VALID(grid);
+        return new Vector2(floor(this.x*grid)/grid, floor(this.y*grid)/grid);
+    }
+
     /** Returns new vec2 with modded values
     *  @param {number} [divisor]
     *  @return {Vector2} */

package/src/engineMedals.js

@@ -1,8 +1,11 @@
 /**
  * LittleJS Medal System
- * - Tracks and displays medals
- * - Saves medals to local storage
- * - Newgrounds integration
+ * - Achievement/trophy system for games
+ * - Medal class with name, description, icon, and unlock tracking
+ * - Automatic saving to local storage
+ * - Visual display queue with slide-in notifications
+ * - Newgrounds API integration for online achievements
+ * - Debug mode to unlock/reset medals during development
  * @namespace Medals
  */
 

package/src/engineObject.js

@@ -1,5 +1,12 @@
 /**
  * LittleJS Object System
+ * - EngineObject is the base class for all game objects
+ * - Handles automatic updating, rendering, physics, and collision
+ * - Supports parent-child hierarchies with transform inheritance
+ * - 2D physics with velocity, acceleration, damping, and gravity
+ * - Collision system with tiles and other objects
+ * - Renders sprites from tile sheets with color and rotation
+ * - Objects sorted by renderOrder for layered rendering
  */
 
 'use strict';
@@ -514,12 +521,16 @@ class EngineObject
     {
         if (!debug) return;
 
+        // check if there is anything to show
+        const hasPhysics = this.collideTiles || this.collideSolidObjects || this.isSolid;
+        if (!hasPhysics && !this.parent) return;
+
         // show object info for debugging
         const size = vec2(max(this.size.x, .2), max(this.size.y, .2));
         const color = rgb(this.collideTiles?1:0, this.collideSolidObjects?1:0, this.isSolid?1:0, .5);
-        drawRect(this.pos, size, color, this.angle);
+        debugRect(this.pos, size, color, 0, this.angle, hasPhysics);
         if (this.parent)
-            drawRect(this.pos, size.scale(.8), rgb(1,1,1,.5), this.angle);
-        this.parent && drawLine(this.pos, this.parent.pos, .1, rgb(1,1,1,.5));
+            debugRect(this.pos, size.scale(.8), rgb(1,1,1,.5), 0, this.angle);
+        this.parent && debugLine(this.pos, this.parent.pos, rgb(1,1,1,.5), .5);
     }
 }

package/src/engineParticles.js

@@ -1,8 +1,13 @@
 /**
  * LittleJS Particle System
- * - A simple but fast and flexible particle system
- * - Lightweight Particles are created and managed by ParticleEmitters
- * - The particle design tool can be used to help create emitters
+ * - Fast and flexible particle effects system
+ * - ParticleEmitter spawns and manages lightweight Particle objects
+ * - Particles support color gradients, fading, rotation, and scaling
+ * - Physics simulation with velocity, gravity, and damping
+ * - Collision detection with tile layers
+ * - Additive blending for glowing effects
+ * - Cone-based emission with randomization
+ * - Particle design tool available for easy emitter creation
  * @namespace Particles
  */
 

package/src/engineRelease.js

@@ -1,7 +1,11 @@
 /**
  * LittleJS - Release Mode
- * - This file is used for release builds in place of engineDebug.js
- * - Debug functionality is disabled to reduce size and increase performance
+ * - Replaces engineDebug.js in production builds
+ * - All debug functions are stubbed out as no-ops
+ * - Removes ASSERT and LOG calls to reduce file size
+ * - Disables debug overlay, watermark, and visualizations
+ * - Improves performance by eliminating debug overhead
+ * - Significantly reduces final bundle size
  */
 
 'use strict';

package/src/engineTileLayer.js

@@ -1,9 +1,13 @@
 /**
  * LittleJS Tile Layer System
- * - Caches arrays of tiles to off screen canvas for fast rendering
- * - Unlimited numbers of layers, allocates canvases as needed
- * - Tile layers can be drawn to using their context with canvas2d
- * - Tile layers can also have collision with EngineObjects
+ * - Renders large tile-based levels efficiently using cached canvases
+ * - Unlimited tile layers with automatic canvas allocation
+ * - Layers support both rendering and collision detection
+ * - Direct canvas2d drawing access for custom tile rendering
+ * - TileLayer for rendering, TileCollisionLayer for physics
+ * - Collision callbacks for tile interactions with objects
+ * - Optimized raycast support for tile-based physics
+ * - Integration with Box2D physics via Box2DTileLayer plugin
  * @namespace TileLayers
  */
 

package/src/engineUtilities.js

@@ -1,7 +1,11 @@
 /**
  * LittleJS Utility Classes and Functions
- * - General purpose utilities
- * - Timer - tracks time automatically
+ * - Timer - tracks time automatically with support for pause and real-time modes
+ * - Time formatting helper
+ * - JSON file fetching
+ * - File saving (text, canvas, data URLs)
+ * - Native share dialog support
+ * - Local storage save data management
  * @namespace Utilities
  */
 

package/src/engineWebGL.js

@@ -1,13 +1,16 @@
 /**
  * LittleJS WebGL Interface
- * - All WebGL used by the engine is wrapped up here
- * - Will fall back to 2D canvas rendering if WebGL is not supported
- * - For normal stuff you won't need to see or call anything in this file
- * - For advanced stuff there are helper functions to create shaders, textures, etc
- * - Can be disabled with glEnable to revert to 2D canvas rendering
- * - Batches sprite rendering on GPU for incredibly fast performance
- * - Sprite transform math is done in the shader where possible
- * - Supports shadertoy style post processing shaders via plugin
+ * - WebGL2 rendering engine for high-performance graphics
+ * - Batched sprite rendering for drawing thousands of sprites efficiently
+ * - Instanced rendering using vertex array objects (VAOs)
+ * - Polygon rendering with triangle strip support
+ * - Shader system with custom vertex and fragment shaders
+ * - Texture management with automatic atlas support
+ * - Post-processing effects via framebuffer and shader plugins
+ * - Automatic fallback to Canvas2D if WebGL is unavailable
+ * - Context loss and restoration handling
+ * - Can be disabled with glEnable setting
+ * - Advanced users can create custom shaders and render targets
  * @namespace WebGL
  */
 

package/src/jsconfig.json

@@ -1,7 +1,8 @@
 {
   "compilerOptions": {
     "checkJs": true,
-    "target": "ES6"
+    "target": "ES2020",
+    "module": "esnext"
   },
   "exclude": [
     "engineRelease.js",

package/examples/electron/build.bat

@@ -1,7 +0,0 @@
-rem LittleJS Build Script
-call node build.js
-if %errorlevel% neq 0 (
-    echo Build failed with error level %errorlevel%
-    pause
-    exit /b %errorlevel%
-)

package/examples/module/build.bat

@@ -1,7 +0,0 @@
-rem LittleJS Build Script
-call node build.js
-if %errorlevel% neq 0 (
-    echo Build failed with error level %errorlevel%
-    pause
-    exit /b %errorlevel%
-)

package/examples/typescript/build.bat

@@ -1,5 +0,0 @@
-rem LittleJS Build Script
-call node build.js
-
-@echo off
-if %ERRORLEVEL% neq 0 ( pause )

package/examples/typescript/build.js

@@ -1,31 +0,0 @@
-#!/usr/bin/env node
-
-const PROGRAM_NAME = 'game';
-const BUILD_FOLDER = 'build';
-
-// Define TypeScript source files
-const tsSourceFiles = [
-    'game.ts',
-    // add your TypeScript files here
-];
-
-// Corresponding JS output files
-const jsSourceFiles = tsSourceFiles.map(file => file.replace('.ts', '.js'));
-
-console.log(`Building TypeScript for ${PROGRAM_NAME}...`);
-const startTime = Date.now();
-const fs = require('node:fs');
-const child_process = require('node:child_process');
-
-console.log(`Removing old build folder...`);
-fs.rmSync(BUILD_FOLDER, { recursive: true, force: true });
-
-console.log(`Compiling TypeScript...`);
-// Compile all TypeScript files at once
-const tsFiles = tsSourceFiles.join(' ');
-child_process.execSync(`npx tsc ${tsFiles} --outDir './${BUILD_FOLDER}' --target es2020 --module es2020`, {stdio: 'inherit'});
-console.log(`TypeScript built in ${((Date.now() - startTime)/1e3).toFixed(2)} seconds!`);
-
-console.log(`Moving js files back to root...`);
-for (const file of jsSourceFiles)
-    fs.copyFileSync(`${BUILD_FOLDER}/${file}`, file);