Writing a browser game
A game written in Nish runs in a browser as a WebAssembly module and a page
that calls one function. The module draws into a framebuffer, reads the keys
and the pointer from a queue, and hands the page its sounds as samples. The
page, nish/page/game, does everything a browser needs: it loads the module,
puts the frames on a <canvas> through WebGPU, WebGL 2 or Canvas 2D, turns
keyboard, mouse and touch events into the module's input, and plays its
sounds through Web Audio. Neither side knows much about the other, so the same
game runs on a 60 Hz laptop and a 240 Hz monitor, with or without a GPU.
This page builds a small game from nothing. A complete one, a paddle and a
ball, is
examples/game-starter:
copy that directory to start your own. The rules for module storage and the
wasm32 target are in
LANGUAGE.md;
Calling Nish from other languages covers wasm in a
browser in general.
Install
The page's half comes with the nish package:
$ npm install nish
It is plain JavaScript with no dependencies and no build step, imported as
nish/page/game (its types are nish/page/game's .d.ts). The game's half
is three standard-library modules: nish/host/game (the framebuffer, input
and sound queues the page reads), nish/raster (drawing into the
framebuffer) and nish/synth (making sounds). Building needs clang and
wasm-ld, as for any wasm build (Installing).
The three exports
A game is a module that exports three functions; the page calls them, and nothing else:
-
init(seed: i32): voidruns once, before anything else. It sets the framebuffer's size withgameSetSize(width, height)(at most 960 by 540) and starts the game.seedis the page's clock unless the page passes one. -
step(nowMs: f64): voidadvances the game by one fixed step, 60 times a second unless the page asks for another rate. It reads the input and moves things.nowMsis the step's clock: it grows by exactly one step each call. -
draw(alpha: f64, frameMs: f64): voiddraws one frame intoGAME_FRAME, once per display frame.alpha, from 0 to 1, is how far the display is between the last step and the next;frameMsis the time since the last frame.
Two more are optional. sound(id: i32): i32 makes sound id; the page
calls it for 0, 1, 2, ... before the first step, until it answers 0.
resize(width: i32, height: i32): void hears the canvas's size in CSS
pixels, rounded to whole ones, once at start and whenever the size or the
display's pixel ratio changes, for a game that fits its framebuffer to the
window (with gameSetSize, in framebuffer pixels).
The game's state lives in module storage: typed arrays declared at the top of the module, which keep their values from call to call. This game moves a square with the arrow keys and beeps when space is pressed:
import { GAME_FRAME, gameHeight, gamePlaySound, gameReadInput, gameSetSize, gameWidth, gameWriteSamples } from "nish/host/game"
import { StepInput } from "nish/input"
import { RASTER_SOLID, rasterGradient, rasterRect, rasterText } from "nish/raster"
import { SYNTH_SQUARE, synthSilence, synthTone } from "nish/synth"
import { ACTION_PRESS, ACTION_RELEASE, EVENT_KEY, KEY_LEFT, KEY_RIGHT, KEY_SPACE, KeyState } from "nish/term"
// The square's x now and a step ago, and whether left and right are held.
const STATE = new Float64Array(2)
const HELD = new Int32Array(2)
export const init = (seed: i32): void => {
gameSetSize(320, 180)
STATE[0] = 150.0
STATE[1] = 150.0
}
export const sound = (id: i32): i32 => {
if (id !== 0) {
return 0
}
const beep = synthSilence(0.1, 22050)
synthTone(beep, 22050, 0.0, 0.1, 880.0, 660.0, SYNTH_SQUARE, 0.25, 30.0)
return gameWriteSamples(beep, 22050)
}
export const step = (nowMs: f64): void => {
const input = new StepInput(new KeyState())
gameReadInput(input, nowMs)
for (const e of input.events) {
if (e.type === EVENT_KEY && (e.action === ACTION_PRESS || e.action === ACTION_RELEASE)) {
const down: i32 = e.action === ACTION_PRESS ? 1 : 0
if (e.key === KEY_LEFT) {
HELD[0] = down
} else if (e.key === KEY_RIGHT) {
HELD[1] = down
} else if (e.key === KEY_SPACE && down === 1) {
gamePlaySound(0)
}
}
}
STATE[1] = STATE[0]
STATE[0] = Math.min(Math.max(STATE[0] + toF64(HELD[1] - HELD[0]) * 3.0, 0.0), 300.0)
}
export const draw = (alpha: f64, frameMs: f64): void => {
const w: i32 = gameWidth()
const h: i32 = gameHeight()
rasterGradient(GAME_FRAME, w, h, 0x101830, 0x302040)
const x: i32 = toI32(STATE[1] + (STATE[0] - STATE[1]) * alpha)
rasterRect(GAME_FRAME, w, h, x, 80, x + 20, 100, 0xffd040, RASTER_SOLID)
rasterText(GAME_FRAME, w, h, 6, 6, 1, "arrows move, space beeps", 0xf0f0f0)
}
A game with more than a few numbers of state keeps it in objects instead:
module storage of a class or null is
root storage, and
the world in it, with every array and object it reaches, lasts from init
through every step and draw while memory stays bounded:
class Ball {
x: f64 = 0.0
dx: f64 = 2.0
}
class World {
balls: Ball[]
constructor() {
this.balls = []
}
}
const world = new Array<World | null>(1)
export const init = (seed: i32): void => {
const w = new World()
w.balls.push(new Ball())
world[0] = w
}
export const step = (nowMs: f64): void => {
const w = world[0]
if (w !== null) {
for (const b of w.balls) {
b.x = b.x + b.dx
}
}
}
The sections below take each part in turn.
Drawing: nish/raster
GAME_FRAME is an Int32Array of 0xRRGGBB pixels, row by row, gameWidth()
pixels wide and gameHeight() tall; the page shows that much of it and
scales it to the canvas with sharp, square pixels. nish/raster draws into it.
Each function takes the pixels, the width and the height first, and clips to
them, so a shape half off the screen is drawn half:
-
rasterGradient(pixels, w, h, top, bottom)fills the frame from one colour at the top to another at the bottom; drawing starts from it, or from arasterRectover the whole frame. -
rasterRect(pixels, w, h, x0, y0, x1, y1, colour, alpha)fills a rectangle;RASTER_SOLIDis full opacity, out of 256. -
rasterDisc(pixels, w, h, x, y, radius, colour, alpha)draws an anti-aliased disc at a fractional position. -
rasterText(pixels, w, h, x, y, scale, text, colour)writes text in a built-in 5 by 7 font;rasterTextWidth(text, scale)measures it first, to centre or right-align it. -
rasterGlow,rasterTrailandrasterParticlesdraw a soft glow, a fading trail and a particle pool, for effects.
Draw the whole frame every time draw runs; the page does not clear it.
Input: gameReadInput
The page writes each key, mouse and touch event into a queue in the module's
storage, and gameReadInput(input, nowMs) reads the queue into a StepInput
from nish/input, as a terminal game's input. Its events are TermEvents
from nish/term:
-
A key event has
typeEVENT_KEY,key(KEY_LEFT,KEY_SPACE, ...), andactionACTION_PRESS,ACTION_REPEATorACTION_RELEASE. The page sends a real release for every press, and releases every held key when the window loses focus or is hidden, so a key is never stuck down. -
A mouse event has
typeEVENT_MOUSE, the button, anaction(ACTION_MOVEfor a move) andpx,py: the position in framebuffer pixels, already mapped through the scaling and the black bars around the frame. Moves are merged, so a step sees where the pointer is, not every place it passed. A held button is released when it comes up, even off the canvas, and when a context menu opens, the pointer is cancelled or the window loses focus. -
A touch holds a key down while it stays on a zone of the canvas: by default
the left half holds
ArrowLeftand the right halfArrowRight, and a short tap that does not move presses and releasesEnter. A game written for the keyboard plays on a phone without a change.
The page reads only the keys a game uses — the arrows, space, Enter and
Escape by default — so the browser keeps the rest (a reload, a tab switch).
The page's keys option names others by their KeyboardEvent.key. A key held
with Ctrl, Alt or Meta is the browser's too (Alt+Left goes back), even one the
game reads.
input.isDown(key, 0) answers whether a key is held, from the KeyState the
input was built with. A KeyState cannot live in module storage, so a game
either keeps its own held flags from the events, as the game above does, or
rebuilds a KeyState from them each step, as examples/game-starter does.
Sound: nish/synth
The page asks for every sound before the game starts. sound(id) makes the
samples, hands them over with gameWriteSamples(samples, sampleRate) and
returns what that returns; past its last sound it returns 0. Then any step or
draw plays one with gamePlaySound(id), as often as it likes.
nish/synth makes the samples: synthSilence(seconds, rate) makes a buffer
of silence, and synthTone(buffer, rate, start, length, fromHz, toHz, wave, volume, decay) adds a tone that sweeps from one pitch to another and fades
out, in a SYNTH_SQUARE, SYNTH_TRIANGLE or SYNTH_NOISE wave. Several
tones in one buffer make a chord or a jingle; synthSemitone(hz, n) steps a
pitch by semitones. All the sounds together hold at most 96,000 samples, about
four seconds at 22,050 Hz.
Browsers start sound only after the person presses a key or touches the page,
so the page holds its sounds until then; the game need not care. The game's
muted property on the page turns them off.
Building
Copy examples/game-starter to a directory of your own, install the nish
package there, and build:
$ npm install nish
$ node build.mjs
build.mjs writes dist/, one directory to serve: game.wasm, its loader
game.mjs and the loader's typings game.d.ts, index.html, and, under
dist/nish/, nish/page/game and the two files it imports. It finds the
toolchain in the installed package (node_modules/nish) and the nish
command in node_modules/.bin; --nish <path> names another compiler,
--out <dir> another directory and --memory <MiB> the memory size. The
build empties its output directory first, so --out must name a new or empty
directory, or one an earlier build wrote; any other flag is refused. It runs two commands, which a build of
your own can run instead ($NISH is node_modules/nish):
$ nish game.ts --target wasm32 --emit-dts out/game.d.ts -o ll/
$ $NISH/scripts/build.sh ll/*.ll $NISH/runtime/runtime-wasm.c -o out/game.wasm \
--profile wasm-host --memory 16
--emit-dts writes game.mjs, the loader, next to game.d.ts; the page
imports it from beside the .wasm. --memory 16 fixes the module's memory at
16 MiB, which the framebuffer, the sound samples and a game's own state fit in
with room to spare: a fixed memory never moves, so the page reads the
framebuffer in place every frame without copying it. A game that keeps its
world in root storage needs room on top for the runtime to move it, several
times the world's size when it is many small objects. The worst-case
formula in sizing is
the safe default; to size closer, measure the peak without --memory through
the largest world the game reaches (the peak grows with it) and give about 1.5
times that. The break director's kept heap, the arena's offset after a keep
rather than its live objects alone, reaches 3.26 MB in 3.34 MB of memory.
The page
The page is a canvas and one call:
<canvas id="game" style="width: 100vw; height: 100vh"></canvas>
<script type="module">
import { startGame } from "nish/page/game";
const game = await startGame(document.getElementById("game"), "./game.wasm");
</script>
startGame(canvas, wasmUrl, options?) fetches and compiles the module while
it imports the loader, calls init, gathers the sounds, and starts the loop;
it resolves to the running game, or rejects when an option is malformed, the
start is aborted, or the module cannot be fetched or lacks an export it needs.
The game has:
-
presenter, which draws the frames:presenter.backendis the tier in use andpresenter.canvasthe canvas it draws on; -
module, the module's exports, for a page that reads its storage (a score shown in HTML, say); fpsandrefreshHz, the frames drawn a second and the display's rate;muted, which turns sound off and on;running, false once the game has stopped;stop(), which ends the loop, removes every listener and closes the audio.
The options are all optional: seed (passed to init), keys (the keys the
game reads), touch (its zones and tap, or false), stepsPerSecond (60),
maxStepsPerFrame (8), sound (false, or { muted: true } to start
muted), prefer and onFallback (below), onError (below), signal (an
AbortSignal: aborting it rejects a start still loading, or stops the game),
loader (the loader, imported yourself, for a bundler), loaderUrl (the
loader's URL, when it is not the .mjs beside a .wasm URL) and imports
(passed to the loader, such as onPanic). Without a bundler, an import map lets the browser find
nish/page/game, or the page imports the file by its path, as
examples/game-starter does.
A panic in step or draw, or a frame the presenter cannot show, stops the
game as stop() does and calls onError(error) once; without onError the
error is thrown from the animation frame, where the console shows it.
The canvas's CSS size decides how big the game looks; the page keeps its drawing buffer at the canvas's size in device pixels and fits the frame in it, with black bars to keep its shape.
Serving
Any static server works. Serve the .wasm as application/wasm and the
browser compiles it while it downloads; with another type the page reads it
whole first and compiles that, which is slower to start but works. A page
opened as a file:// URL cannot fetch the module: serve the directory, even
for a quick look:
$ python3 -m http.server --directory dist
Fallback tiers
The page draws with the best the browser offers: WebGPU, then WebGL 2, then
Canvas 2D. A tier that fails to start, or whose GPU is lost while the game
runs, is given up for the next one, and the game goes on without a restart.
A canvas that has had one context cannot take another, so a fallback puts a
fresh canvas in the old one's place, with its listeners moved over; read
game.presenter.canvas again afterwards. onFallback(from, to, reason, canvas) is called each time, for a page that logs it or styles the new
canvas.
prefer starts lower down: prefer: "webgl2" never tries WebGPU, and
prefer: "canvas2d" uses no GPU at all. A query parameter is a handy way to
try each tier:
const prefer = new URLSearchParams(location.search).get("renderer") ?? undefined;
const game = await startGame(canvas, "./game.wasm", {
prefer,
onFallback: (from, to, reason) => console.warn(`${from} -> ${to}: ${reason}`),
});
All three draw the same pixels; Canvas 2D costs more CPU for a large frame.
120 and 240 Hz displays
A game should move at the same speed on every display, and look smooth on a fast one. The page does both by keeping the steps and the frames apart:
-
stepruns at a fixed rate, 60 times a second, whatever the display does. A game's physics count in steps, never in frame times, so the game plays the same everywhere, and a seeded game replays the same. -
drawruns once per display frame: 60 times a second on a 60 Hz display, 240 times on a 240 Hz one. Between two steps it getsalpha, how far the display is between them, and draws each moving thing atlast + (now - last) * alpha. That is why the game above keeps where the square was a step ago: a 240 Hz display then shows four positions between every two steps instead of the same one four times.
A slow frame runs the steps it missed, at most maxStepsPerFrame of them; a
frame over a quarter of a second, a hidden tab or a debugger's pause, counts
as a quarter second, so the game does not race to catch up. game.refreshHz
reads the display's rate and game.fps counts the frames actually drawn.

