# LittleJS Frequently Asked Questions
Welcome to the LittleJS FAQ!
This document addresses common questions and issues to help developers get started and troubleshoot their projects.
If you don't find an answer here, feel free to ask the community or check the documentation.
**Getting Started**
- [What is LittleJS, and how is it different from other JavaScript game engines?](#what-is-littlejs-and-how-is-it-different-from-other-javascript-game-engines)
- [How do I set up a basic LittleJS project?](#how-do-i-set-up-a-basic-littlejs-project)
- [How do I use LittleJS as an ES module?](#how-do-i-use-littlejs-as-an-es-module)
- [How do I use LittleJS with TypeScript?](#how-do-i-use-littlejs-with-typescript)
- [Why do I see a blank screen when I run my game?](#why-do-i-see-a-blank-screen-when-i-run-my-game)
- [Why does my game say a name "has already been declared"?](#why-does-my-game-say-a-name-has-already-been-declared)
- [Do I need a local server to run LittleJS games, and how do I set one up?](#do-i-need-a-local-server-to-run-littlejs-games-and-how-do-i-set-one-up)
- [Which browsers does LittleJS run in?](#which-browsers-does-littlejs-run-in)
- [How far can my world go, and how long can my game run?](#how-far-can-my-world-go-and-how-long-can-my-game-run)
- [How does the camera and world coordinate systems work?](#how-does-the-camera-and-world-coordinate-systems-work)
- [How do I configure engine settings?](#how-do-i-configure-engine-settings)
- [What plugins ship with LittleJS?](#what-plugins-ship-with-littlejs)
- [How do I use Vite with LittleJS?](#how-do-i-use-vite-with-littlejs)
- [How do I use Box2D with Vite?](#how-do-i-use-box2d-with-vite)
- [How do I build and publish my game?](#how-do-i-build-and-publish-my-game)
- [How do I shrink my game for js13kGames?](#how-do-i-shrink-my-game-for-js13kgames)
**Graphics and Sound**
- [How do I load and add images to my game?](#how-do-i-load-and-add-images-to-my-game)
- [What is the tile function and how do tile indexes work?](#what-is-the-tile-function-and-how-do-tile-indexes-work)
- [Can I add and switch between multiple sprites for a game object?](#can-i-add-and-switch-between-multiple-sprites-for-a-game-object)
- [There are thin lines around my sprites sometimes, how can I fix that?](#there-are-thin-lines-around-my-sprites-sometimes-how-can-i-fix-that)
- [How do I handle animations in LittleJS?](#how-do-i-handle-animations-in-littlejs)
- [How do I control the camera in LittleJS?](#how-do-i-control-the-camera-in-littlejs)
- [How do I use post-processing shaders?](#how-do-i-use-post-processing-shaders)
- [How do I play sounds in LittleJS?](#how-do-i-play-sounds-in-littlejs)
- [How do I play music?](#how-do-i-play-music)
- [Why doesn't my audio play until the user clicks something?](#why-doesnt-my-audio-play-until-the-user-clicks-something)
- [If I load several images, how do I control which is used?](#if-i-load-several-images-how-do-i-control-which-is-used)
- [How can I check if an object is on screen?](#how-can-i-check-if-an-object-is-on-screen)
**Gameplay and Programming**
- [How do I add keyboard or mouse input to my game?](#how-do-i-add-keyboard-or-mouse-input-to-my-game)
- [How does touch input work on mobile?](#how-does-touch-input-work-on-mobile)
- [How do I create and update game objects?](#how-do-i-create-and-update-game-objects)
- [How do I use parent/child objects?](#how-do-i-use-parentchild-objects)
- [How do collisions work?](#how-do-collisions-work)
- [How can I load a 2D level map?](#how-can-i-load-a-2d-level-map)
- [Can I use physics with LittleJS?](#can-i-use-physics-with-littlejs)
- [How do I add particle effects to my game?](#how-do-i-add-particle-effects-to-my-game)
- [How do I use timers?](#how-do-i-use-timers)
- [How do I save and load game state?](#how-do-i-save-and-load-game-state)
- [How do I use the medals (achievements) system?](#how-do-i-use-the-medals-achievements-system)
**Debugging and Development**
- [How do I debug my game in LittleJS?](#how-do-i-debug-my-game-in-littlejs)
- [How do I record a smooth video of my game, like a trailer?](#how-do-i-record-a-smooth-video-of-my-game-like-a-trailer)
---
## Getting Started
### What is LittleJS, and how is it different from other JavaScript game engines?
LittleJS is a lightweight, high-performance JavaScript game engine designed for simplicity and speed.
It offers a hybrid rendering system that combines the advantages of WebGL and 2D Canvas, and [bench/](bench/) runs the same scenes in it and in three.js, PixiJS and Phaser.
Unlike those feature-heavy engines, LittleJS keeps to a comprehensive set of simple, easy to use features, for 2D games first, with a 3D renderer of its own as well.
LittleJS is perfect for developers who want a minimal yet powerful engine to bring their 2D game ideas to life without the complexity of larger frameworks, and it's especially well suited for size-constrained competitions like js13kGames.
### How do I set up a basic LittleJS project?
Clone the LittleJS repository, or use Download ZIP on its GitHub page: the examples are only there, the npm package and the release zip hold the engine alone.
Include one of the LittleJS builds from the dist folder.
Several examples are included for you to build on, and they need a local web server: serve the repository's root, for example with `npx http-server`, and open `http://localhost:8080/examples/empty/` (see [Do I need a local server](#do-i-need-a-local-server-to-run-littlejs-games-and-how-do-i-set-one-up)).
The most basic example is just an empty project. Its `import '../../dist/littlejs.esm.js'` finds the engine from inside the repository, so a copy of the folder somewhere else changes that path to where the engine is.
[Empty Example HTML file:](https://github.com/KilledByAPixel/LittleJS/blob/main/examples/empty/index.html)
```html
LittleJS Hello World Demo
```
[Empty Example JavaScript file:](https://github.com/KilledByAPixel/LittleJS/blob/main/examples/empty/game.js)
```javascript
/*
Little JS Hello World Demo
- Just prints 'Hello World!'
- A good starting point for new projects
*/
'use strict';
// import LittleJS module
import * as LJS from '../../dist/littlejs.esm.js';
const {vec2, hsl} = LJS;
///////////////////////////////////////////////////////////////////////////////
function gameInit()
{
// called once after the engine starts up
// setup the game
}
///////////////////////////////////////////////////////////////////////////////
function gameUpdate()
{
// called every frame at 60 frames per second
// handle input and update the game state
}
///////////////////////////////////////////////////////////////////////////////
function gameUpdatePost()
{
// called after physics and objects are updated
// setup camera and prepare for render
}
///////////////////////////////////////////////////////////////////////////////
function gameRender()
{
// called before objects are rendered
// draw any background effects that appear behind objects
}
///////////////////////////////////////////////////////////////////////////////
function gameRenderPost()
{
// called after objects are rendered
// draw effects or hud that appear above all objects
LJS.drawTextScreen('Hello World!', LJS.mainCanvasSize.scale(.5), 80);
}
///////////////////////////////////////////////////////////////////////////////
// Startup LittleJS Engine
LJS.engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost, ['tiles.png']);
```
The empty example is an ES module, so engine names come from the `LJS` namespace. For a classic setup where the engine is a plain `
```
Vite may print an informational warning during build that the classic script can't be bundled without `type=module` — this is expected and harmless. The classic-script form is exactly what's needed so Emscripten can read `document.currentScript.src` to locate the `.wasm` file.
3. Await `box2dInit()` in `main.js` before `engineInit`:
```javascript
import { box2dInit, engineInit } from 'littlejsengine';
await box2dInit();
engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost, ['tiles.png']);
```
To avoid copying the files by hand on every fresh install, add a `postinstall` script to `package.json`:
```json
"scripts": {
"postinstall": "node -e \"['box2d.wasm.js','box2d.wasm.wasm'].forEach(f=>require('fs').copyFileSync('node_modules/littlejsengine/dist/'+f,'public/'+f))\""
}
```
Then `npm install` keeps `public/box2d.wasm.*` in sync with whatever version of `littlejsengine` you have installed. Add them to `.gitignore` if you don't want the binaries in your repo.
### How do I build and publish my game?
It depends on how your project is set up:
**Plain script-tag projects** (like `examples/starter`) are already deployable as-is. For production, swap the debug bundle for a release build to strip asserts and shrink the file:
```html
```
Then zip up your game folder for itch.io or push to GitHub Pages.
**Vite / module projects** — run `npm run build` and deploy the output `dist/` folder.
**For GitHub Pages**, use relative asset paths (the Vite starter sets `base: './'` in `vite.config.js` for this), and include an empty `.nojekyll` file in your output so files starting with `_` aren't ignored by Jekyll.
**For itch.io**, zip your build output and upload as an HTML5 game. Tick "This file will be played in the browser" in the upload settings.
**For size coding competitions** like js13kGames, see the [js13k branch](https://github.com/KilledByAPixel/LittleJS/tree/js13k) which provides a build that fits in 7KB zipped.
### How do I shrink my game for js13kGames?
LittleJS has a dedicated [js13k branch](https://github.com/KilledByAPixel/LittleJS/tree/js13k) that builds to about 7KB zipped, leaving most of the 13KB budget for your game. A few practical tips for hitting tiny sizes:
- **Use Canvas2D instead of WebGL**: call `setGLEnable(false)` before `engineInit`. Stripping the WebGL renderer saves a significant chunk of bytes, and for most pixel-art and low-sprite-count games the visual difference is imperceptible. A nice side effect: once the jam is over, you can flip WebGL back on with a single setting change for a big performance boost when publishing the game elsewhere.
- **Drop unused plugins**: every plugin is self-contained, so only include what you actually use. Skip `uiSystem.js`, `box2d.js`, `pathFinder.js`, etc. unless you need them.
- **Lean on built-ins to avoid asset files**: `Sound` with ZzFX parameters generates sound effects from a tiny array, and built-in shape drawing avoids shipping image assets.
- **Use a packer**: the js13k branch is set up to compress the final bundle with Roadroller or a similar packer. Check the branch's build script for the current toolchain.
For normal production (non-13KB) builds, the engine ships `dist/littlejs.release.js` (asserts stripped, about 1.6 MB with every plugin and its comments) and `dist/littlejs.min.js` (minified, about 450 KB, about 135 KB gzipped). A bundler like Vite leaves out the plugins a game does not use, which makes a small game far smaller.
---
## Graphics and Sound
### How do I load and add images to my game?
First you need to load an image file. For LittleJS this is typically done on startup via a parameter to engineInit that is a list of images to load. The engine will ensure that all images are loaded before starting. Most modern devices support textures up to 4096x4096 or larger, though some older mobile devices cap out at 2048x2048 — keep that lower limit in mind if you need broad compatibility. Most games only need one texture, but you can load as many as you need.
```javascript
engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost, ['tiles.png']);
```
LittleJS works best when your tile sheet is broken up into grids of tiles because the rendering system can be batched up. To draw a tile from a source image you can call drawTile and pass in TileInfo object. Another common approach is to create an EngineObject and set its tileInfo, it will automatically be rendered.
```javascript
drawTile(vec2(21,5), vec2(4.5), tile(3,128));
```
Once loaded, the underlying images are available via `textureInfos[0].image`, `textureInfos[1].image`, etc. This is useful for tasks like reading pixel data to generate a level — the [Level Editor short](https://killedbyapixel.github.io/LittleJS/examples/?example=Level%20Editor) loads a level from data instead, and [examples/module/game.js](examples/module/game.js) builds one from a string.
### What is the tile function and how do tile indexes work?
The `tile` function returns a `TileInfo` object pointing at a region of a loaded image, ready to pass to `drawTile`, an `EngineObject`, a particle emitter, etc.
```javascript
tile(2) // index 2 at the default tile size (16x16)
tile(5, 8) // index 5 at 8x8 tile size
tile(1, 16, 3) // index 1 of size 16 on texture 3 (multi-image projects)
tile(vec2(4,8), vec2(30,10)) // explicit (x,y) tile position with a 30x10 region
```
When you pass a numeric index, the engine multiplies it by the tile size to get pixel coordinates inside the texture. Indexes count left-to-right, top-to-bottom — so for a 16x16 tile sheet, `tile(0, 16)` is the top-left tile, `tile(1, 16)` is the one to its right, `tile(8, 16)` wraps to the next row if your sheet is 8 tiles wide, etc.
The full signature is `tile(index, size, texture, padding, bleed)`:
- `texture` — which loaded image to read from (index into the array you passed to `engineInit`, default 0)
- `padding` — pixels of padding between tiles in the sheet, if you laid them out with space around each
- `bleed` — shrink the sampled region slightly to avoid edge bleeding (see the tile-bleed entry below)
### Can I add and switch between multiple sprites for a game object?
Yes — there are several ways depending on what you need.
**Set the sprite when creating the object** via the `tileInfo` parameter on `EngineObject`:
```javascript
class Player extends EngineObject {
constructor(pos) {
super(pos, vec2(1), tile(0, 16)); // start with tile index 0
}
}
```
**Swap the sprite at runtime** by assigning a new `TileInfo`:
```javascript
this.tileInfo = tile(3, 16); // now showing tile index 3
```
**For frame-based animation**, store a base `TileInfo` and use `.frame(n)` to offset along the row:
```javascript
const baseSprite = tile(2, 16);
this.tileInfo = baseSprite.frame(animationFrame); // 0, 1, 2... walks to the right
```
**To draw an arbitrary sprite without an object**, call `drawTile` directly:
```javascript
drawTile(pos, vec2(1), tile(5, 16));
```
### There are thin lines around my sprites sometimes, how can I fix that?
That's called tile bleeding — pixels from one tile blend into a neighboring tile when sampling at sub-pixel positions. Two ways to fix it:
1. Call `setTileDefaultBleed(.5)` (or pass a `bleed` parameter to `tile()` / the `TileInfo` constructor). This shrinks each tile slightly when sampling. A value around `.5` usually eliminates the issue with no noticeable visual difference. Smaller values like `.1` are sometimes enough.
2. Add 1 pixel of padding around each sprite in your spritesheet, then pass that padding to `tile(index, size, texture, padding)` so the engine accounts for it.
### How do I handle animations in LittleJS?
Use `SpriteAnimation`, which steps through frames laid out left-to-right on your sprite sheet, and can loop, play once or ping-pong, pausing with the game:
```javascript
const walk = new SpriteAnimation(tile(0, 16), 4, .1); // four frames, a tenth of a second each
const attack = new SpriteAnimation(tile(4, 16), 3, .05).play(); // once, then holds the last frame
// in update()
this.tileInfo = (attack.isDone ? walk : attack).tileInfo;
```
To do it by hand, use the `TileInfo.frame(n)` method to offset along the row of frames from a base sprite:
```javascript
// store the base sprite (the first frame of the animation)
const playerSprite = tile(0, 16);
// inside update(), advance the frame based on time
const animationFrame = Math.floor(time * 10) % 4; // 4-frame loop at 10 FPS
this.tileInfo = playerSprite.frame(animationFrame);
```
`time` is a global updated by the engine each frame (in seconds). The `% 4` keeps the index inside the 4 frames you actually drew on the sheet — adjust to match your animation length.
### How do I control the camera in LittleJS?
LittleJS uses a world space rendering system, so objects can move independently of the camera.
The camera is easy to control using cameraPos and cameraScale, which indicate the world space position and how many pixels is equivalent to one world unit.
The default cameraScale is 32 while the default cameraPos is just the origin.
It is also possible to draw using screen space pixel coordinates by passing in true as the screenSpace parameter to most drawing functions.
```javascript
setCameraPos(vec2(22,5)); // move camera to world position (22,5)
setCameraScale(20); // zoom camera to 20 pixels per world unit
```
### How do I use post-processing shaders?
LittleJS supports Shadertoy-style fragment shaders as a final pass on the rendered output via the post-process plugin. Create the plugin with your shader source in `gameInit`, once `engineInit` has set up WebGL:
```javascript
const shader = `
void mainImage(out vec4 c, vec2 p) {
vec2 uv = p / iResolution.xy;
c = texture(iChannel0, uv);
c.rgb *= 1.0 - distance(uv, vec2(0.5)) * 0.7; // vignette
}`;
function gameInit()
{
new PostProcessPlugin(shader);
}
engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost);
```
The shader gets these uniforms automatically:
- `iChannel0` (`sampler2D`) — the rendered game frame
- `iChannel1` (`sampler2D`) — the shader's own output from the previous frame, when `feedbackTexture` is on
- `iResolution` (`vec3`) — canvas width, height, and `1`
- `iTime` (`float`) — seconds since engine start
The constructor has two optional positional arguments after the shader source:
```javascript
new PostProcessPlugin(shader, includeMainCanvas, feedbackTexture);
```
- `includeMainCanvas` (default `false`) composites the Canvas2D layer (where some debug and text rendering goes) onto the WebGL canvas before the shader runs. Pass `true` if your post-process effect should apply to *everything* on screen, not just the WebGL-rendered objects.
- `feedbackTexture` (default `false`) also passes the shader's own output from the previous frame as `iChannel1`, for effects like motion trails or feedback loops; `iChannel0` is still the frame just drawn. Mutually exclusive with `includeMainCanvas`.
See [plugins/postProcess.js](plugins/postProcess.js) and the [Breakout example](https://killedbyapixel.github.io/LittleJS/examples/breakout/) for working post-process effects.
### How do I play sounds in LittleJS?
Sounds can either be generated on startup using ZzFX or loaded from a wave or mp3 file.
[ZzFX sounds can be created using the sound designer app.](https://killedbyapixel.github.io/ZzFX/)
Once loaded sounds can be played by calling Sound.play with some parameters to control how it is played.
```javascript
const sound_click = new Sound([1,.5]); // create a ZzFX sound
const sound_jump = new Sound('jump.mp3'); // load an mp3 sound
sound_click.play(pos, volume, pitch); // play a sound
```
### How do I play music?
Load an mp3 or ogg file with the regular `Sound` class and play it with `playMusic`, which loops by default.
```javascript
// load an mp3/ogg and loop it
const track = new Sound('music.mp3');
const trackInstance = track.playMusic(1, true); // volume, loop
```
Music pauses automatically when the tab loses focus (audio context suspends) and resumes when it comes back. `playMusic` returns a `SoundInstance`; keep it and call `trackInstance.stop()` to halt playback.
### Why doesn't my audio play until the user clicks something?
Browsers require a user interaction (click, key press, touch) before audio is allowed to play — this is a hard rule from the browser's autoplay policy, not something the engine can bypass. LittleJS handles the actual resume for you: the audio context starts in a suspended state and is automatically resumed on the first input event. You don't need to call `audioContext.resume()` yourself.
A sound played before that, in `gameInit()` or on the first frames, waits and starts once audio runs, so music started in `gameInit()` begins on the player's first click or key press.
### If I load several images, how do I control which is used?
Pass multiple image paths to `engineInit` and select between them with the third argument to `tile()` (the `texture` index):
```javascript
// load two images
engineInit(..., ['tiles.png', 'background.png']);
// later, draw a tile from each
const fgTile = tile(0, 16); // texture 0 → tiles.png
const bgTile = tile(0, 16, 1); // texture 1 → background.png
```
The `texture` argument defaults to `0`, so single-image projects can ignore it. One thing to keep in mind for large games: switching between textures forces WebGL to flush its current render batch, so frequently alternating between textures within a single frame can hurt performance. Group draws by texture where you can.
### How can I check if an object is on screen?
You can use the `isOverlapping` function to check the object against the camera's viewable window. For culling you might want to enlarge the object size slightly to account for attached objects or rotation — I usually do `this.size.scale(2)`.
```javascript
if (!isOverlapping(this.pos, this.size, cameraPos, getCameraSize()))
return;
```
`getCameraSize()` returns the viewable window in world units (canvas pixel size divided by `cameraScale`).
---
## Gameplay and Programming
### How do I add keyboard or mouse input to my game?
LittleJS provides input handling functions for keyboard, mouse, and gamepads. Touch input is also routed to the mouse. There are functions for isDown, wasPressed, and wasReleased. Input can only be checked during the update and should not be called from render functions.
```javascript
if (keyIsDown('ArrowLeft')) // Left arrow key
obj.pos.x -= 5;
if (mouseWasReleased(0)) // Left mouse button
console.log('Mouse clicked at:', mousePos);
if (gamepadWasPressed(0)) // Gamepad button 0
console.log('Gamepad pressed, stick is:', gamepadStick(0));
```
Keyboard keys are identified by `KeyboardEvent.code` strings (e.g. `'KeyA'`, `'Space'`, `'ArrowUp'`, `'Enter'`). See the [MDN code reference](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values) for the full list.
### How does touch input work on mobile?
Touch input is routed to the mouse functions automatically — `mouseIsDown(0)`, `mouseWasPressed(0)`, and `mousePos` all work with a finger tap on the canvas. Games written for mouse usually work on mobile without code changes.
For games that need movement and multiple buttons, enable the built-in on-screen gamepad:
```javascript
setTouchGamepadEnable(true);
```
Once enabled, an analog stick and face buttons appear on touch devices, and the regular gamepad input functions (`gamepadIsDown`, `gamepadStick`) work normally — so the same code can drive both a physical gamepad and the touch overlay. Customization helpers like `setTouchGamepadSize`, `setTouchGamepadAnalog`, `setTouchGamepadButtonCount`, and `setTouchGamepadAlpha` let you tune the appearance.
You can also branch behavior on `isTouchDevice` if you need to detect touch hardware explicitly.
### How do I create and update game objects?
LittleJS can be used as an object oriented system by extending the base class [EngineObject](https://github.com/KilledByAPixel/LittleJS/blob/main/src/engineObject.js) with your own. This lightweight class provides many useful features including physics, collision, parent/child system, and sorted rendering. These objects are added to the global list of objects where they will automatically be updated and rendered until destroyed.
Here is a template you can use to make objects that behave however you want. See the examples for a complete demonstration.
```javascript
class MyObject extends EngineObject
{
constructor(pos, size, tileInfo)
{
super(pos, size, tileInfo);
// setup object
}
update()
{
// custom logic; physics runs separately in updatePhysics
super.update();
}
render()
{
// draw object as a sprite
super.render();
}
}
// spawn one of those objects
const object = new MyObject(pos, size, tileInfo);
```
Common things you'll do on an `EngineObject`:
- `this.setCollision()` — opt in to tile collision and object-object collision
- `this.tileInfo = tile(7, 16)` — swap the sprite at runtime
- `this.velocity = vec2(.1, 0)` — physics is applied automatically each frame
- `this.gravityScale = 0` — disable gravity for this object (e.g. UI or floating objects)
- `this.destroy()` — remove from the world (calls cleanup on children too)
### How do I use parent/child objects?
`EngineObject` supports a parent/child hierarchy with local transforms. Attached children automatically follow their parent's position, angle, and mirror state each frame:
```javascript
const ship = new EngineObject(vec2(10, 5), vec2(2));
const turret = new EngineObject(vec2(), vec2(.5));
ship.addChild(turret, vec2(0, .5)); // turret sits .5 units above the ship in local space
```
`addChild(child, localPos, localAngle)` attaches the child with a local offset; the child's world-space `pos` and `angle` are recomputed each frame from the parent's transform. To detach, call `parent.removeChild(child)` — or just `child.destroy()`, which also detaches it (and destroying a parent destroys all its children).
A few things to know:
- **Mirroring a parent flips children** — a mirrored ship has its turret on the correct side automatically (`localPos.x` and `localAngle` are inverted).
- **Children have no physics of their own** — they follow the parent's transform, so a child's velocity, gravity and collision do nothing while it is attached. Detach it with `removeChild` to let physics move it again.
### How do collisions work?
Opt in to collision on an `EngineObject` by calling `setCollision()` — by default it's off so most objects don't pay the collision cost.
```javascript
class Player extends EngineObject {
constructor(pos) {
super(pos, vec2(1), tile(0, 16));
this.setCollision(); // collide with solid objects and tile map
}
}
```
`setCollision(collideSolidObjects, isSolid, collideLevel, collideRaycast)` — all default to `true`. Pass `false` to opt out of any of them (e.g. a ghost that passes through walls: `setCollision(false, false, false)`).
For custom collision logic, override `collideWithObject(other)` and `collideWithTile(tileData, pos)` on your subclass. Return `true` to actually block the collision, `false` to pass through. Both fire during the physics step, and `collideWithTile` can fire several times a frame for the same tile, including for positions the object only tries, so guard side effects like damage to once a frame:
```javascript
class Bullet extends EngineObject {
collideWithObject(other) {
if (other instanceof Enemy) {
other.damage(1);
this.destroy();
return false; // don't physically bounce off the enemy
}
return true; // solid collision with everything else
}
}
```
For raycasting against the tile collision map (line-of-sight checks, hitscan weapons, etc.), use `tileCollisionRaycast(start, end)` which returns the hit position or `undefined`.
### How can I load a 2D level map?
There are two parts that work together to make 2D level maps in LittleJS.
The tileCollision system is an array of values that correspond to each tile in the map.
The built in physics system can resolve collisions against this tile map very quickly.
For the visual side of things, there is a class called TileLayer which can be used in conjunction with tileCollision.
The TileLayer system works by pre-rendering the entire level to a texture so it can be drawn extremely fast each frame.
It is also possible to have multiple TileLayers for foreground and background layers.
[The platformer example shows a basic example of how to load data that was exported from an external editor.](https://killedbyapixel.github.io/LittleJS/examples/platformer/)
### Can I use physics with LittleJS?
Yes! LittleJS comes with a robust game physics system included and [also a plugin using Box2D.](https://killedbyapixel.github.io/LittleJS/examples/box2d/)
The platformer example includes a character object class that can be used as a starting point for advanced platforming physics.
### How do I add particle effects to my game?
[There is a particle system designer that is useful for experimenting with particle designs.](https://killedbyapixel.github.io/LittleJS/examples/particles/)
You can create a particle system in code using the ParticleEmitter object.
```javascript
// fire particle system
new ParticleEmitter(
pos, 0, // pos, angle
1, .1, 100, PI, // emitSize, emitTime, emitRate, emitCone
undefined, // tileInfo (undefined = untextured)
rgb(1,.5,.1), rgb(1,.1,.1), // colorStartA, colorStartB
rgb(1,.5,.1,0), rgb(1,.1,.1,0), // colorEndA, colorEndB
.7, .8, .2, .2, .05, // time, sizeStart, sizeEnd, speed, angleSpeed
.9, 1, -.2, PI, .05, // damp, angleDamp, gravity, particleCone, fade
.5, 0, 1, 0, 1e9 // randomness, collide, additive, colorLinear, renderOrder
);
```
### How do I use timers?
The `Timer` class is a small but very useful utility for anything that needs to happen *after some time has passed* — cooldowns, animation timing, delayed spawns, fades, etc. It tracks elapsed time automatically, so you don't have to add `timeDelta` to a variable every frame.
```javascript
const cooldown = new Timer(2); // 2-second timer, starts immediately
function gameUpdate() {
if (cooldown.elapsed()) {
fireWeapon();
cooldown.set(2); // restart it
}
}
```
Useful methods:
- `set(seconds)` — start or restart the timer
- `unset()` — disable it (`isSet()` becomes false)
- `active()` / `elapsed()` — boolean checks
- `get()` — seconds elapsed (negative while still counting down)
- `getPercent()` — 0 → 1 progress, handy for easing animations
By default, a timer ticks on **game time** — it pauses when the game is paused and slows down or speeds up with `setTimeScale`. For UI animations, on-screen notifications, or anything that should keep running regardless of game state, use a real-time timer:
```javascript
const uiFade = new Timer(.5, true); // useRealTime = true
```
Real-time timers track `timeReal` instead of `time` — unaffected by pause or time scale. You can also flip an existing timer between modes with `timer.setUseRealTime(true)` while it's unset.
### How do I save and load game state?
LittleJS has built-in helpers for localStorage-backed save data — no need to roll your own JSON serialization:
```javascript
// Read save data, falling back to defaults if nothing is saved yet
const saveData = readSaveData('MyGame', { highScore: 0, level: 1 });
// Write save data
writeSaveData('MyGame', { highScore: 99999, level: 5 });
```
The `saveName` should be unique per game so multiple LittleJS games on the same host don't collide. The data object must be JSON-serializable (no functions, no circular references). Under the hood these are thin wrappers around `localStorage` + `JSON.stringify` / `JSON.parse`.
### How do I use the medals (achievements) system?
LittleJS includes a medals plugin for tracking unlockable achievements with popup notifications:
```javascript
// Create medals — each needs a unique id, optional emoji icon
const medal_firstWin = new Medal(0, 'First Win', 'Win your first match', '🏆');
const medal_perfect = new Medal(1, 'Perfect Score', 'Score 100%', '⭐');
// Initialize medals — saveName persists unlocks to localStorage, a different name from your save data
medalsInit('MyGame medals');
// Unlock a medal (shows a popup, persists across visits)
medal_firstWin.unlock();
```
You can pass an image URL as the fifth argument to `Medal` instead of an emoji icon. The `saveName` you pass to `medalsInit` is used to track which medals have been unlocked in localStorage, so unlocks persist across visits. Give it a name of its own, not the one you pass to `readSaveData` and `writeSaveData`, or the medals and your save data overwrite each other.
The plugin also supports [Newgrounds](https://www.newgrounds.com) scoreboards and medals held on the server through [plugins/newgrounds.js](plugins/newgrounds.js): create each medal as a `NewgroundsMedal` with the id Newgrounds gave it, call `medalsInit` as usual, then `new NewgroundsPlugin(app_id, cipher)`. The "LittleJS Medals & Newgrounds" section of REFERENCE.md has a short example. [plugins/wavedash.js](plugins/wavedash.js) does the same for [Wavedash](https://wavedash.com/) with `WavedashMedal` and `WavedashPlugin`, and both have `cloudSave(slot, data)` and `cloudLoad(slot)` to keep a player's save on the platform.
---
## Debugging and Development
### How do I debug my game in LittleJS?
In addition to your browser's built-in developer tools, LittleJS has its own debug overlay. Press `Esc` to show it — the overlay lists the available toggles and their number-key bindings, so you don't have to memorize them. `+` and `-` adjust the time scale, which is great for slowing tricky moments down or speeding past a slow section.
**Debug draw functions** let you visualize state directly in the world without committing to permanent UI. They're drawn for one frame and only render in debug builds:
```javascript
debugRect(pos, size, color); // outline a rectangle
debugCircle(pos, diameter, color); // outline a circle
debugLine(posA, posB, color); // a line between two points
debugText(string, pos, size, color); // text at a world position
debugPoint(pos, color); // small marker
```
These are perfect for "where exactly is this AI heading?" or "is this hitbox where I think it is?" investigations — drop a call into your update or render code, see the answer, then delete it.
**`ASSERT` and `LOG`** are similar to `console.assert` / `console.log`, but they're *stripped from release builds* (`littlejs.release.js`, `littlejs.min.js`). That means you can leave them in your code with no cost to shipped users. Don't rely on side effects inside the arguments — they won't run in release.
```javascript
ASSERT(player.health > 0, 'player damaged below zero', player);
LOG('spawned enemy at', pos);
```
---
### How do I record a smooth video of my game, like a trailer?
A screen recorder such as OBS, the Xbox Game Bar or the macOS screen recorder is the quickest. For every frame at exactly 60 fps, even on a machine that cannot keep up, step the engine yourself and save each frame as an image: with `setEngineManualStep(true)` the game moves only when `engineStep` is called, one update of 1/60 of a second and its render, however long that takes.
```javascript
// record a number of seconds of the game, one image every 1/60 of a second
function recordFrames(seconds)
{
setEngineManualStep(true); // the engine moves only when engineStep is called
let frame = 0;
const next = ()=>
{
engineStep(1); // one update of 1/60 second, and its render
combineCanvases(); // the WebGL and 2D canvases as one image
saveCanvas(mainCanvas, 'frame' + String(frame).padStart(5, '0'));
if (++frame < seconds * 60)
setTimeout(next, 100); // a moment for the browser to save each one
else
setEngineManualStep(false); // back to real time
};
next();
}
```
The browser asks once to allow many downloads. The game plays slower than real time while it records, so this suits a scripted or replayed scene. Then make the video from the images, with ffmpeg for example: `ffmpeg -framerate 60 -i frame%05d.png -pix_fmt yuv420p trailer.mp4`.
## Contribute to the FAQ
If you have additional questions or think something should be added to this FAQ, please open an issue or pull request on the [LittleJS GitHub repository](https://github.com/KilledByAPixel/LittleJS).
---
Happy coding with LittleJS! 🎮🚂💨