littlejsengine 1.17.11 → 1.17.15

package/examples/typescript/tsconfig.json

@@ -3,6 +3,15 @@
     "allowJs": true,
     "module": "es2020",
     "target": "es2020",
-    "outDir": "build"
-  }
+    "outDir": "build",
+    "moduleResolution": "bundler",
+    "skipLibCheck": true
+  },
+  "include": [
+    "*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "build"
+  ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "littlejsengine",
-  "version": "1.17.11",
+  "version": "1.17.15",
   "description": "LittleJS - Tiny and Fast HTML5 Game Engine",
   "main": "dist/littlejs.esm.js",
   "types": "dist/littlejs.d.ts",
@@ -30,7 +30,7 @@
   },
   "homepage": "https://github.com/KilledByAPixel/LittleJS",
   "scripts": {
-    "build": "node src/engineBuild.js"
+    "build": "node src/engineBuild.mjs"
   },
   "devDependencies": {
     "bestzip": "^2.2.1",

package/plugins/pluginExport.js

@@ -23,6 +23,7 @@ export
     UISystemPlugin,
     UIObject,
     UIText,
+    UITextInput,
     UITile,
     UIButton,
     UICheckbox,

package/plugins/uiSystem.js

@@ -118,9 +118,16 @@ class UISystemPlugin
         this.lastHoverObject = undefined;
         /** @property {UIObject} - Current confirm menu being shown */
         this.confirmDialog = undefined;
+        /** @property {UIObject} - Object to send keyboard input to */
+        this.keyInputObject = undefined;
 
         engineAddPlugin(uiUpdate, uiRender);
 
+        // key down handler
+        function onKeyDown(e)
+        { uiSystem.keyInputObject?.onKeyDown(e); }
+        document.addEventListener('keydown', onKeyDown);
+
         // set object position in parent space
         function updateTransforms(o)
         {
@@ -139,9 +146,18 @@ class UISystemPlugin
             // reset hover object at start of update
             uiSystem.lastHoverObject = uiSystem.hoverObject;
             uiSystem.hoverObject = undefined;
-
+            
             if (mouseWasPressed(0))
             {
+                // exit navigation mode on mouse press
+                uiSystem.navigationMode = false;
+                uiSystem.navigationObject = undefined;
+            }
+            if (uiSystem.keyInputObject)
+            {
+                // handle text input
+                uiSystem.activeObject = uiSystem.keyInputObject;
+                uiSystem.hoverObject = uiSystem.keyInputObject;
                 uiSystem.navigationMode = false;
                 uiSystem.navigationObject = undefined;
             }
@@ -150,7 +166,7 @@ class UISystemPlugin
             const navigableObjects = uiSystem.getNavigableObjects();
             if (!navigableObjects.length)
                 uiSystem.navigationObject = undefined;
-            else
+            else if (!uiSystem.keyInputObject)
             {
                 // unselect object if it is no longer navigable
                 if (!navigableObjects.includes(uiSystem.navigationObject))
@@ -463,6 +479,7 @@ class UISystemPlugin
         this.activeObject = undefined;
         this.hoverObject = undefined;
         this.lastHoverObject = undefined;
+        this.keyInputObject = undefined;
     }
 
     /** Get all navigable UI objects sorted by navigationIndex
@@ -743,7 +760,7 @@ class UIObject
         }
     }
 
-    /** Check if the mouse is overlapping a box in screen space
+    /** Check if the mouse is overlapping this ui object
      *  @return {boolean} - True if overlapping */
     isMouseOverlapping()
     {
@@ -762,8 +779,16 @@ class UIObject
         this.onUpdate();
 
         // unset active if disabled
-        if (this.disabled && this === uiSystem.activeObject)
-            uiSystem.activeObject = undefined;
+        if (this.disabled)
+        {
+            if (this === uiSystem.activeObject)
+                uiSystem.activeObject = undefined;
+            if (this === uiSystem.keyInputObject)
+                uiSystem.keyInputObject = undefined;
+        }
+
+        if (uiSystem.keyInputObject)
+            return;
 
         const wasHover = uiSystem.lastHoverObject === this;
         const isActive = this.isActiveObject();
@@ -790,19 +815,12 @@ class UIObject
                         uiSystem.activeObject = this;
 
                         if (uiSystem.activateOnPress)
-                        {
-                            this.onClick();
-                            if (!this.soundPress && this.soundClick)
-                                this.soundClick.play();
-                        }
+                            this.click(!this.soundPress);
                     }
                 }
                 if (!uiSystem.activateOnPress)
                 if (!mouseDown && this.isActiveObject() && this.interactive)
-                {
-                    this.onClick();
-                    this.soundClick && this.soundClick.play();
-                }
+                    this.click();
             }
 
             // clear mouse was pressed state even when disabled
@@ -854,11 +872,7 @@ class UIObject
     }
 
     /** Called when the navigation button is pressed on this object */
-    navigatePressed()
-    {
-        this.onClick();
-        this.soundClick && this.soundClick.play();
-    }
+    navigatePressed() { this.click(); }
 
     /** @return {boolean} - Is the mouse hovering over this element */
     isHoverObject() { return uiSystem.hoverObject === this; }
@@ -869,6 +883,9 @@ class UIObject
     /** @return {boolean} - Is the gamepad or keyboard navigation object */
     isNavigationObject() { return uiSystem.navigationObject === this; }
 
+    /** @return {boolean} - Is this object in keyboard input mode */
+    isKeyInputObject() { return uiSystem.keyInputObject === this; }
+
     /** @return {boolean} - Can it be interacted with */
     isInteractive() { return this.interactive && this.visible && !this.disabled;}
 
@@ -905,6 +922,15 @@ class UIObject
         uiSystem.drawRect(this.pos, this.size, CLEAR_BLACK, 4, color);
     }
 
+    /** Internal function called when object is clicked
+     *  @param {boolean} [playSound] */
+    click(playSound)
+    {
+        this.onClick(); 
+        if (playSound && this.soundClick)
+            this.soundClick.play();
+    }
+
     /** Called each frame before object updates */
     onUpdate() {}
 
@@ -980,6 +1006,102 @@ class UIText extends UIObject
     }
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/** 
+ * UITextInput - An editable text input field
+ * - A simple text entry field that supports basic editing
+ * - Suitable for short text input like names or numbers
+ * @extends UIObject
+ * @memberof UISystem
+ */
+class UITextInput extends UIObject
+{
+    /** Create a UITextInput object
+     *  @param {Vector2} [pos]
+     *  @param {Vector2} [size]
+     *  @param {string}  [text]
+     */
+    constructor(pos, size, text='')
+    {
+        super(pos, size);
+
+        ASSERT(isString(text), 'ui text must be a string');
+
+        /** @property {number} - Max length of input (0 = no limit) */
+        this.maxLength = 0;
+
+        // set properties
+        this.text = text;
+        this.interactive = true;
+        this.canBeHover = true;
+    }
+
+    click()
+    {
+        // start editing the text
+        uiSystem.keyInputObject = this;
+        this.onClick();
+    }
+
+    /** Stop editing the text edited */
+    stopEditing()
+    {
+        if (!this.isKeyInputObject())
+            return;
+
+        if (this.soundRelease)
+            this.soundRelease.play();
+        uiSystem.activeObject = undefined;
+        uiSystem.keyInputObject = undefined;
+        this.onChange();
+    }
+
+    /** Key down event handler if this object is being edited
+     *  @param {KeyboardEvent} [e] */
+    onKeyDown(e)
+    {
+        const code = e.code, key = e.key
+        if (code === 'Backspace')
+            this.text = this.text.slice(0, -1);
+        else if (code === 'Enter' || code === 'Escape')
+            this.stopEditing();
+        else if (key.length === 1) // printable characters
+        {
+            if (!this.maxLength || this.text.length < this.maxLength)
+                this.text += key;
+        }
+    }
+
+    update()
+    {
+        super.update();
+
+        if (!this.isKeyInputObject())
+            return;
+
+        // click off object to stop editing
+        if (mouseWasPressed(0) && !this.isMouseOverlapping() ||
+            gamepadWasPressed(0, gamepadPrimary))
+        {
+            this.stopEditing();
+            inputClearKey(0,0);
+        }
+    }
+
+    render()
+    {
+        super.render();
+
+        // draw the text scaled to fit
+        const textSize = this.getTextSize();
+        let text = this.text;
+        if (this.isKeyInputObject()) // add a cursor to end of text
+            text += timeReal%1 < .5 ?  '█' : '░';
+        uiSystem.drawText(text, this.pos, textSize, 
+            this.textColor, this.textLineWidth, this.textLineColor, this.align, this.font, this.fontStyle, true, this.textShadow);
+    }
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /** 
  * UITile - A UI object that displays a tile image
@@ -1091,9 +1213,10 @@ class UICheckbox extends UIObject
         this.color = color.copy();
         this.interactive = true;
     }
-    onClick()
+    click()
     {
         this.checked = !this.checked;
+        this.onClick();
         this.onChange();
     }
     render()

package/reference.md

@@ -49,7 +49,6 @@ smoothStep(percent)                           // Applies smoothstep function
 nearestPowerOfTwo(value)                      // Returns the nearest power of two
 isOverlapping(pointA, sizeA, pointB, sizeB)   // Checks if bounding boxes overlap
 isIntersecting(start, end, pos, size)         // Checks if ray intersects box
-wave(frequency=1, amplitude=1, t=time)        // Returns oscillating wave
 formatTime(t)                                 // Formats seconds for display 
 
 // Random functions

package/src/engine.js

@@ -3,18 +3,20 @@
  * 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
- * - Engine helper classes and functions like Vector2, Color, and Timer
- * - Super fast rendering system for tile sheets
- * - Sound effects audio with zzfx and music with zzfxm
- * - Input processing system with gamepad and touchscreen support
- * - Tile layer rendering and collision system
- * - Particle effect system
- * - Medal system tracks and displays achievements
- * - Debug tools and debug rendering system
- * - Post processing effects
- * - Call engineInit() to start it up!
+ * - Object oriented system with EngineObject base class
+ * - Automatic object lifecycle (update, physics, collision, rendering)
+ * - Engine helper classes: Vector2, Color, Timer, RandomGenerator
+ * - Hybrid rendering with WebGL batching and Canvas2D fallback
+ * - Audio system with wave, mp3, or ZzFX sound effects
+ * - Input system with keyboard, mouse, gamepad, and touch support
+ * - Tile layer rendering and collision detection
+ * - Particle effect system with emitters
+ * - Medal/achievement system with local storage
+ * - Comprehensive debug tools and visualizations
+ * - Fixed 60 FPS timestep with configurable time scale
+ * - Raycast and spatial query utilities
+ * - Plugin system for extending engine functionality
+ * - Start with engineInit() and provide your game callbacks
  * @namespace Engine
  */
 
@@ -30,7 +32,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.17.11';
+const engineVersion = '1.17.15';
 
 /** Frames per second to update
  *  @type {number}
@@ -604,7 +606,7 @@ function drawEngineLogo(t)
     const color = (c,l)=> l?`hsl(${[.95,.56,.13][c%3]*360} 99%${[0,50,75][l]}%`:'#000';
 
     // center and fit tos screen
-    const alpha = wave(1,1,t);
+    const alpha = oscillate(1,1,t);
     const p = percent(alpha, .1, .5);
     const size = min(6, min(w,h)/99);
     x.translate(w/2,h/2);

package/src/engineAudio.js

@@ -1,11 +1,14 @@
 /**
  * LittleJS Audio System
- * - <a href=https://killedbyapixel.github.io/ZzFX/>ZzFX Sound Effects</a> - ZzFX Sound Effect Generator
- * - <a href=https://keithclark.github.io/ZzFXM/>ZzFXM Music</a> - ZzFXM Music System
- * - 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 functions
+ * - Play audio files (mp3, ogg, wave) and generate sounds with ZzFX
+ * - ZzFX sound generator integration: <a href=https://killedbyapixel.github.io/ZzFX/>ZzFX</a>
+ * - Sound caching for fast playback and memory efficiency
+ * - Volume control with attenuation and stereo panning
+ * - 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
+ * - Web Audio API integration with master gain control
  * @namespace Audio
  */
 

package/src/{engineBuild.js → engineBuild.mjs}

@@ -1,19 +1,27 @@
-#!/usr/bin/env node
-
 /**
  * LittleJS Build System
- * - Combine input files
- * - Run custom build steps
- * - Check for errors
- * - Output to build folder
+ * - Concatenates engine source files into distributable bundles
+ * - Generates multiple output formats (standard, ES6 module, minified)
+ * - Creates debug and release builds (with/without debug code)
+ * - Produces TypeScript definition file (.d.ts)
+ * - Includes plugin files in builds
+ * - Validates code and checks for errors
+ * - Outputs to dist/ folder
  */
 
-'use strict';
+import fs from 'node:fs';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ROOT_DIR = join(__dirname, '..');
 
 const ENGINE_NAME = 'littlejs';
-const BUILD_FOLDER = 'dist';
-const SOURCE_FOLDER = 'src';
-const PLUGIN_FOLDER = 'plugins';
+const BUILD_FOLDER = join(ROOT_DIR, 'dist');
+const SOURCE_FOLDER = join(ROOT_DIR, 'src');
+const PLUGIN_FOLDER = join(ROOT_DIR, 'plugins');
 const engineSourceFiles =
 [
     `${SOURCE_FOLDER}/engineMath.js`,
@@ -53,10 +61,8 @@ const license = '// LittleJS Engine - MIT License - Copyright 2021 Frank Force\n
                 '// https://github.com/KilledByAPixel/LittleJS\n\n';
 
 console.log(asciiArt);
-console.log('Choo Choo... Building LittleJS Engine!\n');
+console.log('🚂 Choo Choo... Building LittleJS Engine!');
 const startTime = Date.now();
-const fs = require('node:fs');
-const child_process = require('node:child_process');
 
 try
 {
@@ -71,71 +77,82 @@ try
 }
 catch (e) { handleError(e, 'Failed to create build folder!'); }
 
-Build
-(
-    'Build Engine -- all',
-    `${BUILD_FOLDER}/${ENGINE_NAME}.js`,
-    [
-        `${SOURCE_FOLDER}/engine.js`,
-        `${SOURCE_FOLDER}/engineDebug.js`,
-        ...engineSourceFiles,
-        ...enginePluginFiles
-    ],
-    [], true
-);
-
-Build
-(
-    'Build Engine -- release',
-    `${BUILD_FOLDER}/${ENGINE_NAME}.release.js`,
-    [
-        `${SOURCE_FOLDER}/engine.js`,
-        `${SOURCE_FOLDER}/engineRelease.js`,
-        ...engineSourceFiles,
-        ...enginePluginFiles
-    ],
-    [], true
-);
-
-Build
-(
-    'Build Engine -- minified',
-    `${BUILD_FOLDER}/${ENGINE_NAME}.min.js`,
-    [`${BUILD_FOLDER}/${ENGINE_NAME}.release.js`],
-    [closureCompilerStep, uglifyBuildStep, addLicenseStep]
-);
-
-Build
-(
-    'Build Engine -- ESM',
-    `${BUILD_FOLDER}/${ENGINE_NAME}.esm.js`,
-    [
-        `${BUILD_FOLDER}/${ENGINE_NAME}.js`,
-        `${SOURCE_FOLDER}/engineExport.js`,
-        `${PLUGIN_FOLDER}/pluginExport.js`
-    ],
-    [typeScriptBuildStep]
-);
-
-Build
-(
-    'Build Engine -- ESM minified release',
-    `${BUILD_FOLDER}/${ENGINE_NAME}.esm.min.js`,
-    [
-        `${BUILD_FOLDER}/${ENGINE_NAME}.release.js`,
-        `${SOURCE_FOLDER}/engineExport.js`,
-        `${PLUGIN_FOLDER}/pluginExport.js`
-    ],
-    [uglifyBuildStep, addLicenseStep]
-);
-
-console.log(`Engine built in ${((Date.now() - startTime)/1e3).toFixed(2)} seconds!`);
+// Build all versions
+await buildAll();
+
+console.log(`Engine built in ${((Date.now() - startTime)/1e3).toFixed(2)} seconds! ✨`);
+
+///////////////////////////////////////////////////////////////////////////////
+
+async function buildAll()
+{
+    // Build independent base versions in parallel
+    await Promise.all([
+        Build
+        (
+            'Build Engine -- all',
+            `${BUILD_FOLDER}/${ENGINE_NAME}.js`,
+            [
+                `${SOURCE_FOLDER}/engine.js`,
+                `${SOURCE_FOLDER}/engineDebug.js`,
+                ...engineSourceFiles,
+                ...enginePluginFiles
+            ],
+            [], true
+        ),
+        Build
+        (
+            'Build Engine -- release',
+            `${BUILD_FOLDER}/${ENGINE_NAME}.release.js`,
+            [
+                `${SOURCE_FOLDER}/engine.js`,
+                `${SOURCE_FOLDER}/engineRelease.js`,
+                ...engineSourceFiles,
+                ...enginePluginFiles
+            ],
+            [], true
+        )
+    ]);
+
+    // Build dependent versions in parallel
+    await Promise.all([
+        Build
+        (
+            'Build Engine -- minified',
+            `${BUILD_FOLDER}/${ENGINE_NAME}.min.js`,
+            [`${BUILD_FOLDER}/${ENGINE_NAME}.release.js`],
+            [closureCompilerStep, uglifyBuildStep, addLicenseStep]
+        ),
+        Build
+        (
+            'Build Engine -- ESM',
+            `${BUILD_FOLDER}/${ENGINE_NAME}.esm.js`,
+            [
+                `${BUILD_FOLDER}/${ENGINE_NAME}.js`,
+                `${SOURCE_FOLDER}/engineExport.js`,
+                `${PLUGIN_FOLDER}/pluginExport.js`
+            ],
+            [typeScriptBuildStep]
+        ),
+        Build
+        (
+            'Build Engine -- ESM minified release',
+            `${BUILD_FOLDER}/${ENGINE_NAME}.esm.min.js`,
+            [
+                `${BUILD_FOLDER}/${ENGINE_NAME}.release.js`,
+                `${SOURCE_FOLDER}/engineExport.js`,
+                `${PLUGIN_FOLDER}/pluginExport.js`
+            ],
+            [uglifyBuildStep, addLicenseStep]
+        )
+    ]);
+}
 
 ///////////////////////////////////////////////////////////////////////////////
 
 // A single build with its own source files, build steps, and output file
 // - each build step is a callback that accepts a single filename
-function Build(message, outputFile, files=[], buildSteps=[], isPrimaryBuild)
+async function Build(message, outputFile, files=[], buildSteps=[], isPrimaryBuild)
 {
     console.log(message);
 
@@ -176,18 +193,18 @@ function closureCompilerStep(filename)
     fs.copyFileSync(filename, filenameTemp);
     try
     {
-        child_process.execSync(`npx google-closure-compiler --js=${filenameTemp} --js_output_file=${filename} --warning_level=VERBOSE --jscomp_off=*`);
+        execSync(`npx google-closure-compiler --js=${filenameTemp} --js_output_file=${filename} --warning_level=VERBOSE --jscomp_off=*`);
         fs.rmSync(filenameTemp);
     }
     catch (e) { handleError(e, 'Failed to run Closure Compiler step!'); }
-};
+}
 
 // Process with Uglify to minify
 function uglifyBuildStep(filename)
 {
     try
     {
-        child_process.execSync(`npx uglifyjs ${filename} -o ${filename}`);
+        execSync(`npx uglifyjs ${filename} -o ${filename}`);
     }
     catch (e) { handleError(e,'Failed to run Uglify minification step!'); }
 };
@@ -210,8 +227,8 @@ function typeScriptBuildStep(filename)
 {
     try
     {
-        const tsFilename = `${BUILD_FOLDER}/${ENGINE_NAME}.d.ts`
-        child_process.execSync(`npx tsc ${filename} --declaration --allowJs --emitDeclarationOnly --outFile ${tsFilename}`);
+        const tsFilename = join(BUILD_FOLDER, `${ENGINE_NAME}.d.ts`);
+        execSync(`npx -p typescript tsc ${filename} --declaration --allowJs --emitDeclarationOnly --outFile ${tsFilename}`);
 
         // Make declare module part use the package name littlejsengine
         let fileContent = fs.readFileSync(tsFilename, 'utf8');

package/src/engineDebug.js

@@ -1,10 +1,13 @@
 /**
  * LittleJS Debug System
- * - Press Esc to show debug overlay with mouse pick
- * - Number keys toggle debug functions
- * - +/- apply time scale
- * - Debug primitive rendering
- * - Save a 2d canvas as a png image
+ * - Press Esc to toggle debug overlay with object picking
+ * - Number keys toggle debug visualizations (physics, particles, etc.)
+ * - +/- keys control time scale for slow motion/fast forward
+ * - ASSERT and LOG macros for development (removed in release builds)
+ * - Debug primitive rendering (rectangles, circles, lines, points, text)
+ * - Screenshot and video capture support
+ * - FPS counter and performance watermark
+ * - Debug overlay shows mouse position and picked objects
  * @namespace Debug
  */