A well-constructed JavaScript main loop useful for games and other animated applications.
npm install mainloop.js 
MainLoop.js provides a well-constructed main loop useful for JavaScript
games and other animated or time-dependent applications.
The main loop is a core part of any application in which state changes over
time. In games, it is typically responsible for computing physics and AI as
well as drawing the result on the screen.
Main loops are
difficult to write correctly
due to timing issues. **The vast majority of main loops found online are
written incorrectly**, resulting in applications that speed up or slow down
depending on the frame rate. This can cause unfortunate behavior like
characters running through walls or being unable to jump over obstacles. These
main loops can also result in applications that are non-deterministic. This
project solves these problems.
- Example
(source code)
- API documentation
- MainLoop.js source code
(heavily documented to explain how it works - the source is about 75% docs)
- How it works
and a detailed walkthrough of what problems this project solves
You can download the script normally, install it with Bower (bower install), or install it with npm (
mainloopnpm install mainloop.js). To include it
on a page client-side without a module loader:
``html
`
You then have access to the MainLoop global.
MainLoop.js is also compatible with CommonJS (e.g. with node.js, io.js, or
browserify) and AMD (e.g. with RequireJS). This means that if you are using
a module loader or want to use MainLoop server-side you can call
require('mainloop') to get the MainLoop object or include 'mainloop' indefine()
the dependencies you pass to a call.
For TypeScript users, there are
typings
available. Install them with typings install dt~mainloop.js --global --save.
MainLoop works by running functions you define every time the browser is
ready to update the screen (up to about 60 times per second on most monitors).
There are four such functions, all of which are optional. You can set them
using the following methods:
- MainLoop.setBegin(): the begin function runs at the beginning of eachMainLoop.setUpdate()
frame and is typically used to process input.
- : the update function runs zero or more times perMainLoop.setDraw()
frame depending on the frame rate. It is used to compute anything affected
by time - typically physics and AI movements.
- : the draw function should update the screen, usuallyMainLoop.setEnd()
by changing the DOM or painting a canvas.
- : the end function runs at the end of each frame and is
typically used for cleanup tasks such as adjusting the visual quality based
on the frame rate.
The update function receives a delta parameter which holds the amount ofobj
time in milliseconds that should be simulated. This should be used to calculate
movement. For example, if an object has an x-axis velocity of 100 unitsupdate
per second (0.1 units per millisecond), the function might look like
this:
`javascript`
function update(delta) {
obj.x += 0.1 * delta;
}
This structure will ensure that your application behaves regardless of the
frame rate.
To start the application, simply call MainLoop.start(). For example, to start
the application for the first time, you might write:
`javascript`
MainLoop.setUpdate(update).setDraw(draw).start();
You can call MainLoop.stop() to stop the application.
For more detail about the API, check out the
documentation.
You can also check out a
usage example
(source code).
This project is
MIT-licensed.
Compatible with all modern browsers (IE9+) including mobile browsers, as well
as node.js and io.js. There are no dependencies.
Contributions are welcome. To get started contributing, run npm install ingrunt` before submitting a pull request to
the project's directory, then run
update the minified script and the docs as well as to perform a style check.
The library is < 1KB minified and gzipped.
Isaac Sukin
(@IceCreamYou) is the author of this
project. I'd love to hear about what you make! Special thanks to
Ian Langworth for reviewing a version of this I
wrote for my
book about making 3D browser games
and for some tips about web workers.