littlejs-conventions

LittleJS engine conventions

Rules for the LittleJS engine's global API style: call engineInit, vec2, drawTile, etc. directly — no LJS. prefix, no ES-module imports (unless the project already uses the ESM build).

Startup and structure

• engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost, imageSources) starts the engine — define all five callbacks even if some are empty. gameInit may be async; the engine awaits it (put await box2dInit() or a three.js await import(...) at the top).
• Model entities as classes extending EngineObject — the engine updates, moves, collides, and renders them automatically every frame:

class Player extends EngineObject
{
    constructor(pos)
    {
        super(pos, vec2(1), tile(0), 0, CYAN); // pos, size, tileInfo, angle, color
    }
    update()
    {
        this.velocity = keyDirection().scale(.2); // arrows/WASD move the player
        // engine applies physics (velocity, gravity, collision) after update()
        // no super.update() call is needed
    }
}

Spawn once in gameInit with new Player(vec2(0)); it draws itself — no manual draw call. Customize visuals via this.tileInfo / this.color / this.angle, or override render().

• Persisted settings/stats: use readSaveData/writeSaveData (localStorage-backed, JSON-serialized) — don't hand-roll localStorage. Save data is always an object. readSaveData returns {...yourDefault, ...whatWasStored}, so a scalar default spreads to nothing: readSaveData('best', 0) yields {}, not 0, and the next arithmetic on it is NaN with no error. Always pass and read an object — readSaveData('save', {best:0}).best — and write the whole object back with writeSaveData('save', {best:score}).
• three.js 3D (the engine's built-in ThreeJSPlugin / ThreeJSObject): three.js itself is not bundled. Declare let THREE; at top level and THREE = await import(...) at the top of an async gameInit, then new ThreeJSPlugin(THREE) — construct no THREE.* object before that import resolves (no top-level new THREE.Vector3(...)). Never declare let threeJS in game code: the engine owns that global and the plugin constructor assigns it, so redeclaring it throws. Call setGLEnable(false) so the LittleJS canvas draws only Canvas2D content (HUD text, particles) over the 3D scene.