littlejsengine 1.18.2 → 1.18.7

package/AI.md

@@ -1,172 +0,0 @@
-# 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
-```
-
-### Testing
-```bash
-npm test
-```
-
-- Tests target `dist/littlejs.esm.js` — rebuild with `npm run build` after changing source.
-- [test/setup.mjs](test/setup.mjs) stubs minimal DOM and enables headless mode. Tests shouldn't call `engineInit`, `render()`, or assume `time` advances.
-- Zero test dependencies — uses Node's built-in `node --test`. Match the style in [test/](test/) when adding new ones.
-- CI runs build + test on every push/PR ([.github/workflows/test.yml](.github/workflows/test.yml)).
-
-### Debug features
-- Press `Esc` to toggle debug overlay
-- Number keys toggle visualizations
-- `+`/`-` keys control time scale
-- Debug functions: `debugRect()`, `debugCircle()`, `debugLine()`, `debugText()`

package/CLAUDE.md

@@ -1 +0,0 @@
-See @AI.md for instructions.

package/examples/box2d/game.js

@@ -1,192 +0,0 @@
-/*
-    Little JS Box2d Demo
-    - Demonstrates how to use Box2D with LittleJS
-    - Several scenes to demonstrate Box2D features
-    - Every type of shape and joint
-    - Contact begin and end callbacks
-    - Raycasting and querying
-    - Collision filtering
-    - User Interaction
-*/
-
-'use strict';
-
-// import LittleJS module
-import * as LJS from '../../dist/littlejs.esm.js';
-import * as GameObjects from './gameObjects.js';
-import * as Scenes from './scenes.js';
-const {vec2, hsl} = LJS;
-
-// use HD textures
-LJS.setCanvasPixelated(false);
-LJS.setTilesPixelated(false);
-
-///////////////////////////////////////////////////////////////////////////////
-// game variables
-
-const sceneCount = 12;
-const startScene = 0;
-export let spriteAtlas, groundObject, mouseJoint, repeatSpawnTimer = new LJS.Timer;
-const sound_click = new LJS.Sound([.2,.1,,,,.01,,,,,,,,,,,,,,,-500]);
-
-///////////////////////////////////////////////////////////////////////////////
-function setScene(scene)
-{
-    // setup
-    LJS.setCameraPos(vec2(20,10));
-    LJS.setGravity(vec2(0,-20));
-
-    // destroy old scene
-    LJS.engineObjectsDestroy();
-    mouseJoint = 0;
-    
-    // create walls
-    groundObject = GameObjects.spawnBox(vec2(0,-4), vec2(1e3,8), hsl(0,0,.2), LJS.box2d.bodyTypeStatic);
-    GameObjects.spawnBox(vec2(-4, 0), vec2(8,1e3), LJS.BLACK, LJS.box2d.bodyTypeStatic);
-    GameObjects.spawnBox(vec2(44, 0), vec2(8,1e3), LJS.BLACK, LJS.box2d.bodyTypeStatic);
-    GameObjects.spawnBox(vec2(0,100), vec2(1e3,8), LJS.BLACK, LJS.box2d.bodyTypeStatic);
-
-    // load the scene
-    Scenes.loadScene(scene);
-}
-
-///////////////////////////////////////////////////////////////////////////////
-async function gameInit()
-{
-    // start up LittleJS Box2D plugin
-    await LJS.box2dInit();
-    //LJS.box2dSetDebug(true); // enable box2d debug draw
-
-    // create a table of all sprites
-    const gameTile = (i)=> LJS.tile(i, 124, 0, 2);
-    spriteAtlas =
-    {
-        circle:         gameTile(0),
-        dot:            gameTile(1),
-        circleOutline:  gameTile(2),
-        squareOutline:  gameTile(3),
-        wheel:          gameTile(4),
-        gear:           gameTile(5),
-        squareOutline2: gameTile(6),
-    };
-
-    // startup the demo
-    LJS.setCanvasClearColor(hsl(0,0,.8));
-    setScene(startScene);
-}
-
-///////////////////////////////////////////////////////////////////////////////
-function gameUpdate()
-{
-    // scale canvas to fit based on 1080p
-    LJS.setCameraScale(LJS.mainCanvasSize.y * 48 / 1080);
-
-    // mouse controls
-    if (mouseJoint)
-    {
-        // update mouse joint
-        mouseJoint.setTarget(LJS.mousePos);
-        if (LJS.mouseWasReleased(0))
-        {
-            // release object
-            sound_click.play(LJS.mousePos, 1, .5);
-            mouseJoint.destroy();
-            mouseJoint = 0;
-        }
-    }
-    else if (LJS.mouseWasPressed(0))
-    {
-        // grab object
-        sound_click.play(LJS.mousePos);
-        const object = LJS.box2d.pointCast(LJS.mousePos);
-        if (object)
-            mouseJoint = new LJS.Box2dTargetJoint(object, groundObject, LJS.mousePos);
-    }
-
-    // controls
-    if (LJS.mouseIsDown(1) || LJS.keyIsDown('KeyZ'))
-    {
-        const isSet = repeatSpawnTimer.isSet();
-        if (!isSet || repeatSpawnTimer.elapsed())
-        {
-            // spawn continuously after a delay
-            isSet || repeatSpawnTimer.set(.5);
-            GameObjects.spawnRandomObject(LJS.mousePos);
-        }
-    }
-    else
-        repeatSpawnTimer.unset();
-    if (LJS.mouseWasPressed(2) || LJS.keyWasPressed('KeyX'))
-        GameObjects.explosion(LJS.mousePos);
-
-    if (LJS.keyWasPressed('KeyR'))
-        setScene(Scenes.scene); // reset scene
-    if (LJS.keyWasPressed('ArrowUp') || LJS.keyWasPressed('ArrowDown'))
-    {
-        // change scene
-        const upPressed = LJS.keyWasPressed('ArrowUp');
-        setScene(LJS.mod(Scenes.scene + (upPressed?1:-1), sceneCount));
-    }
-}
-
-///////////////////////////////////////////////////////////////////////////////
-function gameUpdatePost()
-{
-
-}
-
-///////////////////////////////////////////////////////////////////////////////
-function gameRender()
-{
-    if (Scenes.scene == 5)
-    {
-        // raycast test
-        const count = 100;
-        const distance = 10;
-        for (let i=count;i--;)
-        {
-            const start = LJS.mousePos;
-            const end = start.add(vec2(distance,0).rotate(i/count*LJS.PI*2));
-            const result = LJS.box2d.raycast(start, end);
-            const color = result ? hsl(0,1,.5,.5) : hsl(.5,1,.5,.5);
-            LJS.drawLine(start, result ? result.point : end, .1, color);
-        }
-    }
-}
-
-///////////////////////////////////////////////////////////////////////////////
-function gameRenderPost()
-{
-    if (mouseJoint)
-    {
-        // draw mouse joint
-        const ab = mouseJoint.getAnchorB();
-        LJS.drawTile(ab, vec2(.3), spriteAtlas.circle, LJS.BLACK);
-        LJS.drawLine(LJS.mousePos, ab, .1, LJS.BLACK);
-    }
-
-    // draw demo info
-    const pos = vec2(LJS.mainCanvasSize.x/2, 50);
-    drawText('LittleJS Box2D Demo', 65, 70);
-    drawText(Scenes.sceneName, 50, 100);
-    if (Scenes.scene == 0)
-    {
-        drawText('Mouse Left = Grab');
-        drawText('Mouse Middle or Z = Spawn');
-        drawText('Mouse Right or X = Explode');
-        drawText('Arrows Up/Down = Change Scene');
-    }
-    if (Scenes.scene == 3)
-    {
-        drawText('Right = Accelerate');
-        drawText('Left = Reverse');
-    }
-
-    function drawText(text, size=40, gap=50)
-    { LJS.drawTextScreen(text, pos, size, LJS.WHITE, size*.1); pos.y += gap; }
-}
-
-///////////////////////////////////////////////////////////////////////////////
-// Startup LittleJS Engine with Box2D
-
-LJS.engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost, ['tiles.png']);