Documentation

Installation

Install the library from npm:

npm install jsgame

You can also depend on it directly from the repository as a git dependency, or use the bundled file at dist/jsgame.js in a plain <script type="module">.

Getting started

Create a canvas, grab its 2D context with jsgame.init(), then draw and read input. Here is a minimal example:

import { jsgame } from "jsgame";

const surface = jsgame.init();

jsgame.draw.rect(surface, "#FF0000", new jsgame.core.Rect(10, 10, 100, 50));

// Keyboard input
const keys = jsgame.key.getPressed();
if (keys.KeyW) player.moveInPlace(0, -speed);

// Event queue
const events = jsgame.event.get();

The import path depends on how you consume the package: "jsgame" when installed from npm, or "@iainfox/jsgame" when used from this repository (as in the Space Shooter demo).

Top-level jsgame

Status legend:

• ✓ Implemented
• - In progress / partial
• × Unimplemented

• ✓ init(), creates a canvas if one doesn't exist and returns its 2D context
• ✓ quit(close), calls all quit callbacks and optionally closes the window
• ✓ getInit(), returns true if jsgame is currently initialized
• ✓ registerQuit(callback), registers a function to call when the library quits
• × error, getError(), setError(), standard error handling

jsgame.core

Core data types shared across the library. Currently exposes Rect and Color.

Rect

Create one from four numbers, two [x, y] pairs, or an object:

new jsgame.core.Rect(10, 20, 100, 50);            // left, top, width, height
new jsgame.core.Rect([10, 20], [100, 50]);         // [left, top], [width, height]
new jsgame.core.Rect({ x: 10, y: 20, width: 100, height: 50 });

Properties: left, top, width, height, right, bottom.

Methods:

• copy(), returns a new copy
• move(x, y) / moveInPlace(x, y), translate the rect
• inflate(x, y) / inflateInPlace(x, y), grow or shrink
• scaleBy(x, y) / scaleByInPlace(x, y), scale dimensions
• update(...), reassign position and size
• clamp(rect) / clampInPlace(rect), clamp against another rect
• clip(rect), intersection of two rects
• union(rect) / unionInPlace(rect), union of two rects
• unionAll(rects) / unionAllInPlace(rects), union of many rects
• contains(rect), true if fully contained
• collidePoint(x, y), true if the point is inside

Color

Wraps a color string and exposes it as a hex value, used internally by the drawing functions.

jsgame.draw

All drawing functions take the surface (the 2D context from jsgame.init()) first. Pass a positive width to stroke instead of fill.

• ✓ rect(ctx, color, rect, width, borderRadius, ...), draws a rectangle
• ✓ polygon(ctx, color, points, width), draws a polygon from an array of [x, y] points
• ✓ circle(ctx, color, center, radius, width, ...), draws a circle, optionally quarter-by-quarter
• ✓ ellipse(ctx, color, ...), draws an ellipse
• ✓ line(ctx, color, start, end, width), draws a straight line
• ✓ lines(ctx, color, points, width), draws connected line segments
• × aaline / aalines, antialiased lines

jsgame.key

Keyboard input, mirroring pygame.key. The Space Shooter demo uses getPressed() with KeyW, KeyA, KeyS, KeyD and Space.

• ✓ getPressed(), returns the state of all keyboard buttons (keyed by event.code)
• ✓ getMods(), returns the modifier keys currently held
• ✓ name(keyCode), get the name of a key identifier
• ✓ keyCode(name), get the identifier from a key name
• - setMods(), temporarily set which modifiers are pressed
• × getFocused(), setRepeat(), getRepeat(), system focus and key repeat

jsgame.event

Event queue handling, mirroring pygame.event.

• ✓ get(), get events from the queue
• ✓ poll(), get a single event from the queue
• ✓ peek(), test if events are waiting on the queue
• ✓ clear(), remove all events from the queue
• ✓ eventName(), get the string name from an event id
• ✓ setBlocked() / setAllowed() / getBlocked(), control which events are queued
• - setGrab() / getGrab(), control input device sharing
• - post() / customType() / Event, custom events
• × wait(), pump(), blocking wait and internal processing

Play the demo

See the library in action with the Space Shooter demo, a complete game written against jsGame. Thrust, turn, shoot asteroids, and try to top the scoreboard.

Play Space Shooter →