littlejsengine 1.17.11 → 1.17.15

package/AI.md

@@ -0,0 +1,162 @@
+# LittleJS Project - AI Agent Instructions
+
+These instructions are for making changes in the LittleJS repo safely. Optimize for small diffs, clarity, and ease of use.
+
+## Non-negotiable rules
+
+- **Prefer minimal, local changes.** Do not refactor for style unless asked.
+- **No new runtime dependencies.** Keep LittleJS dependency-free at runtime.
+- **Do not hand-edit generated build artifacts.**
+  - Treat `dist/` as generated output.
+  - Make changes in `src/` (and `plugins/` when appropriate), then run the build.
+- **Match surrounding style.** Follow the conventions in the files you touch.
+- **Avoid breaking public APIs.** If a change could break users, call it out clearly and offer a compatible alternative.
+
+If anything in this doc conflicts with the actual repo behavior, follow the repo behavior and update this doc.
+
+## Key resources
+
+- `README.md` - Overview and getting started
+- `reference.md` - API quick reference
+- `examples/` - Working examples demonstrating engine features
+
+## Architecture overview
+
+LittleJS is a modular HTML5 game engine with:
+
+- **Core engine**: `src/engine*.js` (main loop, objects, rendering, physics, input, etc.)
+- **Plugins**: `plugins/*.js` (optional features like Box2D, post-processing, UI, audio helpers, etc.)
+- **Build system**: `src/engineBuild.mjs` (concatenates modules into distributable bundles)
+
+## Repo structure and file types
+
+### Engine source (`src/*.js`)
+- Modular architecture (one subsystem per file)
+- Concatenated at build time (internal source does not use ES modules)
+- Code is vanilla JavaScript with type info expressed via JSDoc comments
+
+### Build output (`dist/`)
+Common outputs include:
+- `littlejs.js` - Full bundle (debug features included)
+- `littlejs.release.js` - Production bundle (debug stripped)
+- `littlejs.esm.js` - ES module build (import/export)
+- `littlejs.esm.min.js` - Minified ES module
+- `littlejs.d.ts` - TypeScript definitions
+
+Use via script tag or ES module import:
+- `<script src="dist/littlejs.js"></script>`
+- `import * as LJS from './dist/littlejs.esm.js'`
+
+Prefer adding new optional features as plugins when it keeps the core simpler.
+
+### Examples
+- `examples/starter/` - Plain JavaScript global usage via `<script>` (recommended starting point)
+- `examples/module/` - ES module import pattern
+- `examples/typescript/` - TypeScript example usage
+- `examples/shorts/*.js` - Single-file demos loaded by the shorts harness
+
+### Short examples (`examples/shorts/*.js`)
+Short examples are special:
+- Pure JS code file, no HTML
+- No imports, do not use LJS namespace - engine APIs are available globally
+- Override hooks: `gameInit()`, `gameUpdate()`, `gameUpdatePost()`, `gameRender()`, `gameRenderPost()`
+
+## Coding conventions
+
+### Factory functions vs constructors
+Prefer factory functions for core types:
+- `vec2(x, y)` not `new Vector2(x, y)`
+- `rgb(r, g, b, a)` or `hsl(h, s, l, a)` not `new Color(...)`
+- `tile(index, size)` for tile info
+
+Use constructors for game objects and complex types:
+- `new EngineObject(pos, size)`
+- `new ParticleEmitter(...)`
+- `new Sound(zzfxParams)`
+- `new Timer(duration)`
+
+### Naming
+- `camelCase` for variables and functions
+- `PascalCase` for classes
+- `UPPER_CASE` for constants that are truly constant (like `PI`)
+
+### Code style
+- Use JSDoc with `@memberof` grouping (namespaces: Engine, Math, Draw, Input, Audio, Debug, Settings, etc.)
+- Prefer single-line comments: `// comment`
+- Use `ASSERT(condition, 'error message')` for validation (stripped in release)
+- Use `LOG(...)` for debug output (stripped in release)
+
+### Type checking
+Use built-in type helpers for validation:
+```javascript
+isNumber(n)   // true if number and not NaN
+isString(s)   // true if not null/undefined (has toString)
+isArray(a)    // true if array
+isVector2(v)  // true if valid Vector2
+isColor(c)    // true if valid Color
+```
+
+### Global variables
+- Engine time: `time`, `timeReal`, `frame`, `timeDelta`
+- Camera: `cameraPos`, `cameraScale`, `cameraAngle`
+- Input: `mousePos`, `mousePosScreen`, `mouseWheel`
+- State: `paused`, `debug`, `debugOverlay`
+- Settings are in `engineSettings.js` with corresponding setter functions
+
+## Common patterns
+
+### Game structure
+```javascript
+function gameInit() { }       // Called once after engine starts
+function gameUpdate() { }     // Called every frame for game logic
+function gameUpdatePost() { } // Called after physics, even when paused
+function gameRender() { }     // Called before objects render
+function gameRenderPost() { } // Called after objects render
+
+engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost, ['tiles.png']);
+```
+
+### Creating objects
+```javascript
+class Player extends EngineObject {
+    constructor(pos) {
+        super(pos, vec2(1), tile(0, 16));
+        this.setCollision();
+    }
+    update() {
+        super.update();
+        // custom logic
+    }
+}
+```
+
+### Common drawing functions
+```javascript
+drawRect(pos, size, color)              // solid rectangle
+drawTile(pos, size, tileInfo, color)    // sprite from tile sheet
+drawText(text, pos, size, color)        // text rendering
+drawLine(posA, posB, thickness, color)  // line between points
+drawEllipse(pos, size, color)           // filled ellipse
+```
+
+## Common pitfalls
+
+- **ASSERT and LOG are stripped in release builds** - Don't rely on side effects
+- **Don't modify constant colors** - `WHITE`, `BLACK`, `RED`, etc. are frozen; use `.copy()` first
+- **Time variables are global** - `time`, `frame` update automatically each frame
+- **Fixed 60 FPS timestep** - Physics runs at 60 FPS regardless of display refresh rate
+- **WebGL is enabled by default** - Set `glEnable = false` before `engineInit()` for Canvas2D only
+- **Tile coordinates are bottom-left origin** - Y increases upward in world space
+
+## Developer workflows
+
+### Build
+```bash
+npm run build
+```
+
+### Debug features
+- Press `Esc` to toggle debug overlay
+- Number keys toggle visualizations
+- `+`/`-` keys control time scale
+- Debug functions: `debugRect()`, `debugCircle()`, `debugLine()`, `debugText()`

package/README.md

@@ -2,7 +2,7 @@
 
 <div align='center'>
     
-![LittleJS Screenshot](examples/logo.png)
+![LittleJS Logo](examples/logo.png)
 
 [![NPM Package][npm]][npm-url]
 [![Build Size][build-size]][build-size-url]
@@ -12,128 +12,115 @@
 
 </div>
 
-## 🚂 All aboard!
+## 🚂 All Aboard!
 
 LittleJS is a fast, lightweight, and fully open source HTML5 game engine designed for simplicity and performance.
-Its small footprint is packed with a comprehensive feature set including hybrid rendering, physics, particles, sound, and input handling.
-The code is clean and well documented with some fun examples to get you started right away. Choo-Choo!
-
-### 🚀 Join the LittleJS Game Jam
-
-*The Second Annual LittleJS Game Jam will take place From Oct 3 to Nov 3! Unleash your creativity and develop amazing games using the LittleJS game engine. 🕹️🎮 [Sign up today and get more info about the jam on itch.io!](https://itch.io/jam/littlejs-game-jam-2025)*
+Its small footprint is packed with a comprehensive feature set including rendering, physics, particles, sound, and input handling.
+The code is very clean and well documented with many examples to get you started quickly.
 
 <div align='center'>
 
-## [Demos](https://killedbyapixel.github.io/LittleJS/examples) | [Docs](https://killedbyapixel.github.io/LittleJS/docs) | [Trailer](https://youtu.be/chuBzGjv7Ms) | [Discord](https://discord.gg/zb7hcGkyZe) | [Tutorial](https://github.com/KilledByAPixel/LittleJS/blob/main/examples/breakoutTutorial/README.md) | [FAQ](https://github.com/KilledByAPixel/LittleJS/blob/main/FAQ.md)
+## [Demos](https://killedbyapixel.github.io/LittleJS/examples) | [Docs](https://killedbyapixel.github.io/LittleJS/docs) | [Trailer](https://youtu.be/chuBzGjv7Ms) | [Discord](https://discord.gg/zb7hcGkyZe) | [FAQ](https://github.com/KilledByAPixel/LittleJS/blob/main/FAQ.md)
 
 </div>
 
 ![LittleJS Screenshot](examples/screenshot.jpg)
 
-## About LittleJS Engine
-
-LittleJS is a small but powerful game engine with many features and no dependencies.
+## LittleJS Features
 
 ### ✨ Graphics
 
-- Super fast WebGL2 + Canvas2D hybrid rendering
-- 100,000+ sprites at solid 60fps
+- Super fast WebGL2 + Canvas2D hybrid rendering system
 - Apply [Shadertoy](https://www.shadertoy.com) style 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 distance falloff
+- Sound and music with mp3, ogg, or wave files
 - Use [ZzFX](https://killedbyapixel.github.io/ZzFX/) sound effect generator to play sounds without asset files
-- Music and sound with mp3, ogg, wave, or [ZzFXM](https://keithclark.github.io/ZzFXM/)
 
 ### 🎮 Input
 
-- Comprehensive input handling for keyboard, mouse, gamepad, and touch
-- Automatic touch mouse emulation
-- On screen touch gamepad designed for mobile devices
+- Comprehensive input handling for mouse, keyboard, gamepad, and touch
+- Customizable on screen gamepad designed for mobile devices
 
 ### 💥 Physics
 
 - Robust arcade physics system with collision handling
-- Box2d fully integrated for more realistic physics
-- Tilemap collision with raycasting
+- Fast tilemap collision and raycasting
+- Full Box2D integration for realistic physics
 
 ### 🚀 Flexibility
 
-- 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/)
-- Open Source with the [MIT license](https://github.com/KilledByAPixel/LittleJS/blob/main/LICENSE) so it can be used for anything you want forever
+- Compatible with all modern web browsers and mobile devices
+- TypeScript and Module support with example projects for both
+- Great for size coding competitions like [Js13kGames](https://js13kgames.com/)
+- Open Source and [MIT licensed](https://github.com/KilledByAPixel/LittleJS/blob/main/LICENSE)
 
 ### 🛠️ Developer Tools
 
 - Live example browser with code editor
-- Debug primitive rendering system
-- Screenshot and video capture tools
-- Node.js build system
-- Bitmap font rendering and built in engine font
-- Optimized for AI-assisted development
+- Debug overlay and primitive rendering system
 - Medal tracking system with [Newgrounds](https://www.newgrounds.com/) support
+- Node.js build system
 
 ## How To Use LittleJS
 
 To get started download the latest LittleJS package from GitHub or install via npm: ```npm install littlejsengine```
 
-*You need to run a local web server to run LittleJS games during development!* You may see a console error like 'The image element contains cross-origin data.' Don't panic, it's easy to fix! If you are using [Visual Studio Code](https://code.visualstudio.com/) there is a [Live Preview Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.live-server) that will handle this for you automatically. Another option is to setup a simple local web server like [http-server](https://www.npmjs.com/package/http-server) via npm.
-
-- [Watch this GitNation talk](https://youtu.be/_dXKU0WgAj8?si=ZDXLYAFDWp54hrGT) to hear more about LittleJS works and get some tips on how to use it.
-- Learn how to make a simple game from scratch with [The Breakout Tutorial.](https://github.com/KilledByAPixel/LittleJS/tree/main/examples/breakoutTutorial)
-- [Make a ski game with LittleJS](https://eoinmcgrath.com/little-ski/tutorial.html) - Check out this tutorial by eoinmcg that shows how to make a pixel art style game.
-- [LittleJS Engine Quick Reference Sheet](https://github.com/KilledByAPixel/LittleJS/blob/main/reference.md) - This cheat sheet can help you get started.
-- [Check out The Little JS FAQ for more help getting started](https://github.com/KilledByAPixel/LittleJS/blob/main/FAQ.md).
-- Join our vibrant community on [Discord](https://discord.gg/zb7hcGkyZe) to get help, share your projects, and collaborate with others!
-- For Js13k there is a [separate branch that builds to a 7KB zip](https://github.com/KilledByAPixel/LittleJS/tree/js13k)
+- [Making Awesome Games With LittleJS](https://youtu.be/_dXKU0WgAj8?si=ZDXLYAFDWp54hrGT) - A short talk about LittleJS with some tips on how to use it.
+- [Tutorial: Breakout](https://github.com/KilledByAPixel/LittleJS/tree/main/examples/breakoutTutorial) - Learn how to make a simple game from scratch
+- [Tutorial: Make a ski game](https://eoinmcgrath.com/little-ski/tutorial.html) - This tutorial by eoinmcg that shows how to make a pixel art style game.
+- [LittleJS Quick Reference Sheet](https://github.com/KilledByAPixel/LittleJS/blob/main/reference.md) - A reference sheet to help you get started.
+- [Little JS FAQ](https://github.com/KilledByAPixel/LittleJS/blob/main/FAQ.md) - Answers to common questions about LittleJS.
+- [JS13k Branch](https://github.com/KilledByAPixel/LittleJS/tree/js13k) - For size coding events like JS13k there is a special branch that builds to a 7KB zip.
 
 ## Examples
 
-These demos are for both learning and using as starter projects to create your own games.
+LittleJS comes with a several demos both for learning and using as starter projects to create new games.
 
-- [Starter Project](https://killedbyapixel.github.io/LittleJS/examples/starter/) - Clean example with only a few things to get you started
+- [Example Browser](https://killedbyapixel.github.io/LittleJS/examples/) - Live example browser with all examples
 - [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 level data from [Tiled Editor](https://github.com/mapeditor/tiled)
+- [Platformer](https://killedbyapixel.github.io/LittleJS/examples/platformer/) - Platformer/shooter that loads level data from [Tiled Editor](https://github.com/mapeditor/tiled)
 - [Box2D Demo](https://killedbyapixel.github.io/LittleJS/examples/box2d/) - Box2D plugin demonstration and testbed
-- [Stress Test](https://killedbyapixel.github.io/LittleJS/examples/stress/) - Max sprite/object test and music system demo
+- [Stress Test](https://killedbyapixel.github.io/LittleJS/examples/stress/) - Sprite rendering benchmark and music system demo
 - [Particle System Designer](https://killedbyapixel.github.io/LittleJS/examples/particles/) - Particle system editor and visualizer
-- [Example Browser](https://killedbyapixel.github.io/LittleJS/examples/) - Live example browser with all examples
 
 ## Builds
 
-To easily include LittleJS in your game, you can use one of the pre-built js files.
-
-- [littlejs.js](https://github.com/KilledByAPixel/LittleJS/blob/main/dist/littlejs.js) - The full game engine with debug mode available
-- [littlejs.release.js](https://github.com/KilledByAPixel/LittleJS/blob/main/dist/littlejs.release.js) - The engine optimized for release builds
-- [littlejs.min.js](https://github.com/KilledByAPixel/LittleJS/blob/main/dist/littlejs.min.js) - The engine in release mode and minified
-- [littlejs.esm.js](https://github.com/KilledByAPixel/LittleJS/blob/main/dist/littlejs.esm.js) - The engine exported as a module with debug mode available
-- [littlejs.esm.min.js](https://github.com/KilledByAPixel/LittleJS/blob/main/dist/littlejs.esm.min.js) - The engine exported as a minified module in release mode
-
-To rebuild the engine you must first run ```npm install``` to setup the necessary npm dependencies. Then call ```npm run build``` to build the engine.
-
-The starter example project includes a node js file [build.js](https://github.com/KilledByAPixel/LittleJS/blob/main/examples/starter/build.js) that compresses everything into a tiny zip file using Google Closure, UglifyJS, and ECT Zip.
+| File | Mode | Module | Use case |
+|------|------|--------|----------|
+| [littlejs.js](https://github.com/KilledByAPixel/LittleJS/blob/main/dist/littlejs.js) | Debug | No | Debug mode with asserts |
+| [littlejs.release.js](https://github.com/KilledByAPixel/LittleJS/blob/main/dist/littlejs.release.js) | Release | No | Optimized for release |
+| [littlejs.min.js](https://github.com/KilledByAPixel/LittleJS/blob/main/dist/littlejs.min.js) | Release | No | Optimized for release and minified |
+| [littlejs.esm.js](https://github.com/KilledByAPixel/LittleJS/blob/main/dist/littlejs.esm.js) | Debug | ESM | Debug mode with asserts |
+| [littlejs.esm.min.js](https://github.com/KilledByAPixel/LittleJS/blob/main/dist/littlejs.esm.min.js) | Release | ESM | Optimized for release and minified |
 
 ## Games Made With LittleJS
 
 Here are a few of the many amazing games created with LittleJS...
 
-- [Space Huggers](https://www.newgrounds.com/portal/view/819609) - Rogulike platformer shoot-em-up game with procedural levels. by [KilledByAPixel](https://frankforce.com/)
+- [Space Huggers](https://www.newgrounds.com/portal/view/819609) - Roguelike platformer shoot-em-up game with procedural levels. by [KilledByAPixel](https://frankforce.com/)
+- [Black Cat Squadron](https://js13kgames.com/games/black-cat-squadron) - One button shooter based on a WW2 Navy squadron. JS13k 5th place! by [repsej](https://github.com/repsej)
 - [L1ttl3 Paws](https://github.com/KilledByAPixel/JS13K2025) - Cat glider with procedural art and levels for JS13K! by [KilledByAPixel](https://frankforce.com/)
-- [The Way of the Dodo](https://js13kgames.com/2024/games/the-way-of-the-dodo) - Single button platformer. JS13k 5th place winner! by [repsej](https://github.com/repsej)
+- [KleptoKitty](https://js13kgames.com/games/kleptokitty) - Cat themed heist puzzle. JS13K 22nd place. by [eoinmcg](https://eoinmcg.itch.io/)
+- [The Way of the Dodo](https://js13kgames.com/2024/games/the-way-of-the-dodo) - Single button platformer. JS13k 5th place! by [repsej](https://github.com/repsej)
 - [Undergrowth](https://undergrowth.squidband.uk/) - An interactive music videogame for the band Squid. by [KilledByAPixel](https://frankforce.com/)
-- [204Snake!](https://www.newgrounds.com/portal/view/960100) - A puzzle game that combines 2048 with snake. LittleJS Jam 1st place winner! by [Sodoj](https://sodoj.itch.io/) and [Shai-P](https://shai-p.itch.io/)
-- [GATOR](https://www.newgrounds.com/portal/view/960757) - Retro platformer shooter game where you rescue animals. LittleJS Jam 2nd place winner! by [eoinmcg](https://eoinmcg.itch.io/)
-- [A Hedgehog's search](https://willsm1111.itch.io/a-hedgehogs-search) - Adventure game staring a hedgehog. LittleJS Jam 3rd place winner! by [willsm1111](https://willsm1111.itch.io/)
+- [204Snake!](https://www.newgrounds.com/portal/view/960100) - A puzzle game that combines 2048 with snake. LittleJS Jam 1st place! by [Sodoj](https://sodoj.itch.io/) and [Shai-P](https://shai-p.itch.io/)
+- [GATOR](https://www.newgrounds.com/portal/view/960757) - Retro platformer shooter game where you rescue animals. LittleJS Jam 2nd place! by [eoinmcg](https://eoinmcg.itch.io/)
+- [A Hedgehog's Search](https://willsm1111.itch.io/a-hedgehogs-search) - Adventure game starring a hedgehog. LittleJS Jam 3rd place! by [willsm1111](https://willsm1111.itch.io/)
 - [Wendol Village](https://js13kgames.com/2024/games/wendol-village) - Warcraft inspired RTS game. by [sanojian](https://github.com/sanojian)
-- [Dead Again](https://js13kgames.com/entries/dead-again) - Top down survial horror. by [sanojian & repsej](https://github.com/sanojian/js13k_2022)
+- [Dead Again](https://js13kgames.com/entries/dead-again) - Top down survival horror. by [sanojian & repsej](https://github.com/sanojian/js13k_2022)
 - [Isletopia](https://store.steampowered.com/app/1861260/Isletopia) - Relaxing strategy game of greenifying barren islands. by [Gamex Studio](https://x.com/gamesgamex)
 - [Tetrimals](https://nixn.itch.io/tetrimals) - A puzzle game mixing Tetris with animals. by [nixn](https://nixn.itch.io/)
-- [Watch the Pups](https://ma5a.itch.io/watch-the-pups) - The aim of the game is to take care of some puppies. by [masa](https://ma5a.itch.io/)
-- [LittleJS Game Jam Results](https://itch.io/jam/littlejs-game-jam/results) - Check out all the games from the first LittleJS Game Jam!
+- [Bug&Bee](https://itch.io/jam/littlejs-game-jam-2025/results) - Low fi shoot em up with co-op gameplay. LittleJS Jam 1st place! by [eoinmcg](https://eoinmcg.itch.io/)
+- [Little Platformer](https://psemo.itch.io/little-platformer) - Platformer with many mechanics. LittleJS Jam 2st place! by [PSEMO](https://psemo.itch.io/), [Solita666](https://itch.io/profile/solita666), [GabrielRG](https://gabrielrg.itch.io/), [Nate](https://natesassoon.itch.io/)
+- [Rogue Pong](https://itch.io/jam/littlejs-game-jam-2025/rate/4004165) - Roguelike crossed with classic pong gameplay. LittleJS Jam 3rd place! by [webdevbrian](https://webdevbrian.itch.io/)
+- [LittleJS Jam 2024 Results](https://itch.io/jam/littlejs-jam-2024/results) - All the games from the first LittleJS Game Jam.
+- [LittleJS Jam 2025 Results](https://itch.io/jam/littlejs-game-jam-2025/results) - All the games from the second LittleJS Game Jam.
+
+![LittleJS Screenshot](examples/games.jpg)
 
 ![LittleJS Logo](examples/favicon.png)