LittleJS
The Tiny Javascript Engine That Can
Audio
LittleJS Audio System
- ZzFX Sound Effects - Sound Effect Generator
- ZzFXM Music - 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 wrapper functions
Members
Audio context used by the engine.
Sample rate used for all ZzFX sounds. Default value is 44100.
Methods
Debug
LittleJS Debug System
- Press ~ to show debug overlay with mouse pick
- Number keys toggle debug functions
- +- apply time scale
- Debug primitive rendering
- Save a 2d canvas as an image
Members
True if debug is enabled.
Key code used to toggle debug mode, Esc by default.
Size to render debug points by default.
True if asserts are enaled.
True if god mode is enabled, handle this however you want.
True if watermark with FPS should be shown, false in release builds.
Methods
Draw
LittleJS Drawing System
- Hybrid with both Canvas2D and WebGL available
- Super fast tile sheet rendering with WebGL
- Can apply rotation, mirror, color and additive color
- Many useful utility functions
LittleJS uses a hybrid rendering solution with the best of both Canvas2D and WebGL.
There are 3 canvascontexts available to draw to...
mainCanvas - 2D background canvas, non WebGL stuff like tile layers are drawn here.
glCanvas - Used by the accelerated WebGL batch rendering system.
overlayCanvas - Another 2D canvas that appears on top of the other 2 canvases.
The WebGL rendering system is very fast with some caveats...
- The default setup supports only 1 tile sheet, to support more call glCreateTexture and glSetTexture
- Switching blend modes (additive) or textures causes another draw call which is expensive in excess
- Group additive rendering together using renderOrder to mitigate this issue
The LittleJS rendering solution is intentionally simple, feel free to adjust it for your needs!
Members
The primary 2D canvas visible to the user.
2d context for mainCanvas.
A canvas that appears on top of everything the same size as mainCanvas.
2d context for overlayCanvas.
Tile sheet for batch rendering system.
Methods
Automatically splits new lines into rows.
Automatically splits new lines into rows.
- if calling outside of render, you may need to manually set mainCanvasSize.
- if calling outside of render, you may need to manually set mainCanvasSize.
Engine
LittleJS - The Tiny JavaScript Game Engine That Can!
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!
Members
Name of engine.
Array containing all engine objects.
Array containing only objects that are set to collide with other objects this frame (for optimization).
Version of engine.
Current update frame, used to calculate time.
Frames per second to update objects.
Is the game paused? Causes time and objects to not be updated.
Current engine time since start in seconds, derived from frame.
How many seconds each frame lasts, engine uses a fixed time step. Default value is 160.
Actual clock time since start in seconds (not affected by pause or frame rate clamping).
Methods
Input
LittleJS Input System
- Tracks key down, pressed, and released
- Also tracks mouse buttons, position, and wheel
- Supports multiple gamepads
- Virtual gamepad for touch devices with touchGamepadSize
Members
True if a touch device has been detected.
Returns true if user is using gamepad (has more recently pressed a gamepad button).
Mouse wheel delta this frame.
Prevents input continuing to the default browser handling (false by default).
Methods
Medals
LittleJS Medal System
- Tracks and displays medals
- Saves medals to local storage
- Newgrounds integration
Members
List of all medals.
Methods
- Call this after creating all medals
- Checks if medals are unlocked.
Random
Random global functions
Methods
Settings
LittleJS Engine Settings
Members
Scale of camera in world space.
The max size of the canvas, centered if window is larger. Default value is Vector2(1920,1200).
Disables anti aliasing for pixel art if true.
Enable physics solver for collisions between objects.
Default font used for text rendering.
If true, the dpad input is also routed to the left analog stick (for better accessability).
Should gamepads be allowed.
Enable webgl rendering, webgl can be disabled and removed from build (with some features disabled).
Fixes slow rendering in some browsers by not compositing the WebGL canvas.
How much gravity to apply to objects along the Y axis, negative is down.
If true the WASD keys are also routed to the direction keys (for better accessability).
Size of icon in medal display.
Size of medal display. Default value is Vector2(640,80).
How quickly to slide onoff medals in seconds.
How long to show medals for in seconds.
Set to stop medals from being unlockable (like if cheats are enabled).
How much to slow angular velocity each frame (0 $1).
How much to slow velocity by each frame (0 $1).
How much to bounce when a collision occurs (0 $1).
How much to slow when touching (0 $1).
Default object mass for collison calcuations (how heavy objects are).
Clamp max speed to avoid fast objects missing collisions.
Scales emit rate of particles, useful for low graphics mode (0 disables particle emitters).
Default range where sound no longer plays.
Default range percent to start tapering off sound (0 $1).
All audio code can be disabled and removed from build.
Volume scale to apply to all sound, music and speech.
Prevent tile bleeding from neighbors in pixels.
Default size of tiles in pixels. Default value is Vector2(16,16).
Transparency of touch gamepad overlay.
True if touch gamepad should be analog stick or false to use if 8 way dpad.
True if touch gamepad should appear on mobile devices
- Supports left analog stick, 4 face buttons and start button (button 9)
- Must be set by end of gameInit to be activated.
Size of virutal gamepad for touch devices in pixels.
Allow vibration hardware if it exists.
Methods
- you may also need to set mainCanvasSize if using screen space coords in startup.
TileCollision
LittleJS Tile Layer System
- Caches arrays of tiles to off screen canvas for fast rendering
- Unlimted numbers of layers, allocates canvases as needed
- Interfaces with EngineObject for collision
- Collision layer is separate from visible layers
- It is recommended to have a visible layer that matches the collision
- Tile layers can be drawn to using their context with canvas2d
- Drawn directly to the main canvas without using WebGL
Members
The tile collision layer array, use setTileCollisionData and getTileCollisionData to access.
Methods
Utilities
LittleJS Utility Classes and Functions
- General purpose math library
- Vector2 - fast, simple, easy 2D vector class
- Color - holds a rgba color with some math functions
- Timer - tracks time automatically
Members
A shortcut to get Math.PI. Default value is Math.PI.
Seed used by the randSeeded function.
Methods
WebGL
LittleJS WebGL Interface
- All webgl used by the engine is wrapped up here
- For normal stuff you won't need to see or call anything in this file
- For advanced stuff there are helper functions to create shaders, textures, etc
- Can be disabled with glEnable to revert to 2D canvas rendering
- Batches sprite rendering on GPU for incredibly fast performance
- Sprite transform math is done in the shader where possible
Members
The WebGL canvas which appears above the main canvas and below the overlay canvas.
2d context for glCanvas.
Main tile sheet texture automatically loaded by engine.
Methods
- This may also flush the gl buffer resulting in more draw calls and worse performance.
Color
Color object (red, green, blue, alpha) with some helpful functions
Methods
EngineObject
LittleJS Object Base Object Class
- Base object class used by the engine
- Automatically adds self to object list
- Will be updated and rendered each frame
- Renders as a sprite from a tilesheet by default
- Can have color and addtive color applied
- 2d Physics and collision system
- Sorted by renderOrder
- Objects can have children attached
- Parents are updated before children, and set child transform
- Call destroy() to get rid of objects
The physics system used by objects is simple and fast with some caveats...
- Collision uses the axis aligned size, the object's rotation angle is only for rendering
- Objects are guaranteed to not intersect tile collision from physics
- If an object starts or is moved inside tile collision, it will not collide with that tile
- Collision for objects can be set to be solid to block other objects
- Objects may get pushed into overlapping other solid objects, if so they will push away
- Solid objects are more performance intensive and should be used sparingly
Methods
FontImage
Font Image Object - Draw text on a 2D canvas by using characters in an image
- 96 characters (from space to tilde) are stored in an image
- Uses a default 8x8 font if none is supplied
- You can also use fonts from the main tile sheet
Methods
Medal
Medal Object - Tracks an unlockable medal
Methods
Music
Music Object - Stores a zzfx music track for later use
Create music with the ZzFXM tracker.
Methods
Newgrounds
Newgrounds API wrapper object
Methods
Particle
Particle Object - Created automatically by Particle Emitters
Methods
ParticleEmitter
Particle Emitter - Spawns particles with the given settings
Methods
Sound
Sound Object - Stores a zzfx sound for later use and can be played positionally
Create sounds using the ZzFX Sound Designer.
Methods
TileLayer
Tile layer object - cached rendering system for tile layers
- Each Tile layer is rendered to an off screen canvas
- To allow dynamic modifications, layers are rendered using canvas 2d
- Some devices like mobile phones are limited to 4k texture resolution
- So with 16x16 tiles this limits layers to 256x256 on mobile devices
Methods
- This may be slow in some browsers.
TileLayerData
Tile layer data object stores info about how to render a tile
Methods
Timer
Timer object tracks how long has passed since it was set
Methods
Vector2
2D Vector object with vector math library
- Functions do not change this so they can be chained together