nish/host/game
The memory a game built for wasm32 shares with the page that runs it: the frame it draws, the input the page feeds it, the sounds it asks for and the samples the page plays them from. Every piece is module storage, so the page reaches it in place through the loader's views().storage (the keys below are the storage's names) and nothing is copied across the boundary in either direction.
import {
GAME_EVENT_WORDS,
GAME_FRAME,
GAME_INFO,
GAME_INFO_HEIGHT,
GAME_INFO_RATE,
GAME_INFO_SAMPLES,
GAME_INFO_WIDTH,
GAME_INPUT,
GAME_INPUT_EVENTS,
GAME_MAX_HEIGHT,
GAME_MAX_WIDTH,
GAME_SAMPLES,
GAME_SAMPLE_LIMIT,
GAME_SOUNDS,
GAME_SOUND_SLOTS,
gameHeight,
gamePlaySound,
gameReadInput,
gameSetSize,
gameWidth,
gameWriteSamples,
} from "nish/host/game";
import { GAME_FRAME, gameHeight, gamePlaySound, gameReadInput, gameSetSize, gameWidth, gameWriteSamples } from "nish/host/game";
import { KeyState } from "nish/term";
import { StepInput } from "nish/input";
import { rasterRect } from "nish/raster";
import { SYNTH_SQUARE, synthSilence, synthTone } from "nish/synth";
const input = new StepInput(new KeyState());
export const start = (): void => gameSetSize(320, 180);
export const sound = (id: i32): i32 => {
const out = synthSilence(0.1, 22050);
synthTone(out, 22050, 0.0, 0.1, 440.0 + toF64(id) * 110.0, 220.0, SYNTH_SQUARE, 0.3, 20.0);
return gameWriteSamples(out, 22050);
};
export const step = (nowMs: f64): void => {
gameReadInput(input, nowMs);
if (input.events.length > 0) gamePlaySound(0);
rasterRect(GAME_FRAME, gameWidth(), gameHeight(), 0, 0, 320, 180, 0x101830, 256);
};
gameHeight
The frame's height, as gameSetSize set it.
gamePlaySound
Ask the page to start a sound: id goes on GAME_SOUNDS, which the page drains after the step.
gameReadInput
Drain the page's input into input: every whole record on GAME_INPUT becomes a TermEvent, and input.events becomes what input.keys.apply makes of them at nowMs, so input.isDown answers for the keys still held.
gameSetSize
Set the frame's size, which the page reads to know how much of GAME_FRAME to show.
gameWidth
The frame's width, as gameSetSize set it.
gameWriteSamples
Hand one sound's samples to the page: each is clipped to -1..1 (NaN is 0) and written to GAME_SAMPLES as an f32, and GAME_INFO records how many and at what rate.
| Storage | Words | Written by | Holds |
|---|---|---|---|
GAME_FRAME |
Int32Array(960 × 540) |
the game | the frame, 0xRRGGBB, row-major, width words a row |
GAME_INFO |
Int32Array(4) |
the game | [width, height, samples, sampleRate] |
GAME_INPUT |
Int32Array(2 + 7 × 64) |
the page | a nish/host/ring of input events, 7 words each |
GAME_SOUNDS |
Int32Array(2 + 32) |
the game | a nish/host/ring of sound ids to start |
GAME_SAMPLES |
Float32Array(96000) |
the game | one sound's samples, -1..1 |
The frame
The game picks its size with gameSetSize (at most
GAME_MAX_WIDTH × GAME_MAX_HEIGHT) and draws into GAME_FRAME, for
instance by lending it to nish/raster with gameWidth() and
gameHeight(). The page reads GAME_INFO[0] and [1] and copies the first
width × height words into its canvas, setting each pixel's alpha to 255
as it does. Storage cannot be returned or aliased, so a program names
GAME_FRAME itself rather than asking a function for it.
Input
The page pushes one record of GAME_EVENT_WORDS words per event
onto GAME_INPUT, and pushes a record only when the ring has room for all
of it. The words are:
| Word | Key event | Pointer event | Focus event |
|---|---|---|---|
| 0 | EVENT_KEY |
EVENT_MOUSE |
EVENT_FOCUS |
| 1 | the KEY_ kind |
the MOUSE_ button, MOUSE_NONE for a move |
1 gained, 0 lost |
| 2 | the code point, for KEY_CHAR |
0 | 0 |
| 3 | the MOD_ bits |
the MOD_ bits |
0 |
| 4 | ACTION_PRESS, ACTION_REPEAT or ACTION_RELEASE |
ACTION_PRESS, ACTION_RELEASE or ACTION_MOVE |
0 |
| 5 | 0 | x, in frame pixels | 0 |
| 6 | 0 | y, in frame pixels | 0 |
The constants are nish/term's, so a step reads the page's keys exactly as
it reads a terminal's. Each step the game calls gameReadInput, which
drains the ring into a nish/input StepInput: its events become this
step's events and its keys (a KeyState) keep which keys are held, for
isDown. A page sees every key go up, so it sends a release for every press
(keyup) and a lost focus on blur, which releases every held key; the
reader turns KeyState's synthetic releases off. A page has no terminal to
quit, so Ctrl-C arrives as an ordinary key press, never EVENT_QUIT. Nor
does the reader make up auto-repeat: a page that wants it sends
ACTION_REPEAT records itself (a keydown with repeat set, say). A
pointer event's x and y are set as both the event's cell (x, y) and its
pixel (px, py).
A record with an unknown kind is dropped, and so is a trailing part-record
a page pushed out of protocol.
Sound
The game names its sounds by small ids and asks for one with
gamePlaySound, which queues the id on GAME_SOUNDS; the page shifts the
ring after each step and starts each id's buffer. To build those buffers,
the page calls an export of the game's once per id at start, which
synthesizes the sound (with nish/synth, say) and hands it to
gameWriteSamples; the page then reads GAME_INFO[2] samples of
GAME_SAMPLES at GAME_INFO[3] Hz into an AudioBuffer.
Building it
A page's game is compiled with --target wasm32 and
linked by scripts/build.sh with --profile wasm-host, which exports the
storage above for the loader's views(), and --memory <MiB>, which pins
the memory so those views never go stale. The
storage alone is about 2.5 MB (GAME_FRAME 2 MB, GAME_SAMPLES 384 KB,
the rings 2 KB), so pin at least 4 MiB, more for what the game itself
allocates. The GAME_* names are the page's keys and are reserved: when
two modules declare storage of one name, the later module's is keyed by its
symbol instead, so a program's own GAME_FRAME could move this module's
off the key the page reads.
The module is ordinary Nish everywhere: a native build has the same
storage, so a test can push records onto GAME_INPUT and read the frame
back without a page. It needs no capability and does no I/O.
Functions
gameHeight
The frame's height, as gameSetSize set it.
const gameHeight: () => i32
returnsi32the height in pixels, held to 0..GAME_MAX_HEIGHT even if the page wrote the word
gamePlaySound
Ask the page to start a sound: id goes on GAME_SOUNDS, which the page
drains after the step. A full queue drops the id, since a sound late by a
frame is worse than one missed.
const gamePlaySound: (id: i32) => boolean
idi32requiredthe sound's id, the one the page fetched its samples by
returnsbooleanwhether the id was queued
gameReadInput
Drain the page's input into input: every whole record on GAME_INPUT
becomes a TermEvent, and input.events becomes what input.keys.apply
makes of them at nowMs, so input.isDown answers for the keys still held.
The page sends real key releases, so the key state's synthetic releases are
turned off, and Ctrl-C is an ordinary key (a page's copy), not a quit. A
trailing part-record is dropped.
const gameReadInput: (input: StepInput, nowMs: f64) => void
inputStepInputrequiredthe step's input, kept by the game from step to step
nowMsf64requiredthe step's clock in milliseconds, for the key state
gameSetSize
Set the frame's size, which the page reads to know how much of GAME_FRAME
to show. Each side is held to 0..GAME_MAX_WIDTH and 0..GAME_MAX_HEIGHT.
The pixels are not touched: the next frame draws over them.
const gameSetSize: (width: i32, height: i32) => void
widthi32requiredthe frame's width in pixels
heighti32requiredthe frame's height in pixels
gameWidth
The frame's width, as gameSetSize set it.
const gameWidth: () => i32
returnsi32the width in pixels, held to 0..GAME_MAX_WIDTH even if the page wrote the word
gameWriteSamples
Hand one sound's samples to the page: each is clipped to -1..1 (NaN is
0) and written to GAME_SAMPLES as an f32, and GAME_INFO records how
many and at what rate. Samples past GAME_SAMPLE_LIMIT are cut off.
const gameWriteSamples: (
samples: f64[],
sampleRate: i32,
) => i32
samplesf64[]requiredthe sound, at sampleRate samples a second
sampleRatei32requiredthe samples' rate in Hz
returnsi32how many samples were written
Constants
7
GAME_EVENT_WORDS: i32
The words of one input record on GAME_INPUT.
GAME_FRAME
GAME_FRAME: Int32Array<ArrayBuffer>
The frame: 0xRRGGBB pixels, row-major, GAME_INFO[GAME_INFO_WIDTH] words a row.
GAME_INFO
GAME_INFO: Int32Array<ArrayBuffer>
The frame's size and the last sound's sample count and rate; see GAME_INFO_WIDTH and the rest.
1
GAME_INFO_HEIGHT: i32
GAME_INFO's word for the frame's height in pixels.
3
GAME_INFO_RATE: i32
GAME_INFO's word for the sample rate of those samples, in Hz.
2
GAME_INFO_SAMPLES: i32
GAME_INFO's word for how many samples gameWriteSamples last wrote.
0
GAME_INFO_WIDTH: i32
GAME_INFO's word for the frame's width in pixels.
GAME_INPUT
GAME_INPUT: Int32Array<ArrayBuffer>
The page's input events: a nish/host/ring of GAME_EVENT_WORDS-word records.
64
GAME_INPUT_EVENTS: i32
The input records GAME_INPUT holds at once.
540
GAME_MAX_HEIGHT: i32
The tallest frame GAME_FRAME holds, in pixels.
960
GAME_MAX_WIDTH: i32
The widest frame GAME_FRAME holds, in pixels.
GAME_SAMPLES
GAME_SAMPLES: Float32Array<ArrayBuffer>
One sound's samples, written by gameWriteSamples for the page to copy.
96,000
GAME_SAMPLE_LIMIT: i32
The samples GAME_SAMPLES holds: two seconds at 48000 Hz.
GAME_SOUNDS
GAME_SOUNDS: Int32Array<ArrayBuffer>
The sound ids the game asked for since the page last looked: a nish/host/ring.
32
GAME_SOUND_SLOTS: i32
The sound ids GAME_SOUNDS holds at once.

