js-game-zero 0.0.0-stage → 0.4.0

package/dist/reference/clock.md

@@ -0,0 +1,150 @@
+# Clock And Animation
+
+## `clock`
+
+`clock` schedules callbacks against the game's own timeline, which only
+advances while your game is running (driven by the frame loop's `dt`, not by
+wall-clock time) — so a scheduled callback never fires while the tab is
+backgrounded and the game is effectively paused.
+
+### `clock.schedule(callback, delay)`
+
+Calls `callback` once, `delay` seconds from now.
+
+```js
+clock.schedule(spawnEnemy, 2); // spawn one enemy, 2 seconds from now
+```
+
+A callback scheduled by another scheduled callback waits for the next tick,
+even with a delay of `0`, so one that schedules itself again with
+`clock.schedule(loop, 0)` runs once a frame.
+
+### `clock.scheduleInterval(callback, interval)`
+
+Calls `callback` repeatedly, every `interval` seconds, until unscheduled.
+`interval` must be greater than `0`.
+
+```js
+clock.scheduleInterval(spawnEnemy, 3); // a new enemy every 3 seconds
+```
+
+Every schedule, and `eachTick`, takes the function itself, without brackets.
+`clock.scheduleInterval(spawnEnemy(), 3)` would call it once right away and
+hand over what it returned, so it throws a `TypeError` that says to drop the
+brackets.
+
+### `clock.scheduleUnique(callback, delay)`
+
+Like `schedule`, but first cancels any existing scheduled call for the same
+`callback` function — useful when an event might restart a timer that's
+already pending and you only want the latest one to count.
+
+### `clock.unschedule(callback)`
+
+Cancels a pending `schedule`, `scheduleInterval`, or `eachTick` callback
+registered with that exact function reference. Safe to call even if nothing
+matching is scheduled.
+
+### `clock.eachTick(callback)`
+
+Calls `callback(dt)` on every single frame, forever (until unscheduled) —
+this is what `animate()` uses internally to advance animations, and it's
+useful directly for continuous per-frame effects that don't fit naturally
+into your top-level `update()`.
+
+### `clock.clear()`
+
+Cancels every scheduled call and every `eachTick` callback at once — handy
+when resetting a level or restarting a game so old timers from the previous
+run don't fire.
+
+### `clock.now()`
+
+Returns the clock's current time in seconds (the running total of every
+`dt` it has been ticked with).
+
+### Error handling
+
+In a game, a scheduled or `eachTick` callback that throws (an animation's
+`onFinished` too) stops the game, as an error in `update()` does: the game
+fails in the `clock` phase (`handle.failure.phase` is `"clock"`), and a
+`runtime-error` diagnostic reports `clock failed: …`. The other callbacks
+due on that tick still run, but `update()` and `draw()` don't.
+
+A `Clock` you make yourself with `new Clock()` keeps going instead: it logs
+the error to the console and unschedules only that callback.
+`new Clock({ onError })` hands the error to `onError` instead of logging it.
+
+## Animation
+
+### `animate(object, options)`
+
+```ts
+function animate<T extends object>(
+  object: T,
+  options: AnimationOptions<T>,
+): Animation<T>;
+```
+
+Smoothly interpolates one or more numeric properties on `object` over time.
+Any key in `options` other than `tween`, `duration`, and `onFinished` is
+treated as a target value for a same-named property that must already exist
+on `object` — animating a property `object` doesn't have throws an error.
+
+```js
+animate(player, { x: 300, y: 120, duration: 0.5, tween: "decelerate" });
+```
+
+- `duration` — seconds, default `1`.
+- `tween` — the easing curve name (see the table below), default
+  `"linear"`. An unknown name throws with a "did you mean ...?" suggestion.
+- `onFinished` — called once, when the animation reaches its target. It
+  isn't called when the animation is stopped, even with `stop(true)`.
+- Each target value must be a finite number, or an array of finite numbers
+  matching the shape of the property's current value (e.g. animating a
+  `[x, y]`-shaped property to another two-number array).
+
+Starting a new `animate()` call for a property that's already mid-animation
+replaces just that property's animation; other properties being animated by
+an earlier call keep running.
+
+`animate()` returns an `Animation` instance:
+
+- `.running: boolean`
+- `.stop(complete = false)` — stops the animation. `stop(true)` jumps the
+  properties to their final values first. Neither calls `onFinished`.
+- `.removeTarget(property)` — stops animating a single property, leaving
+  any others on the same call running.
+
+### Tween names
+
+| Name             | What the motion looks like                                                   |
+| ---------------- | ---------------------------------------------------------------------------- |
+| `linear`         | Constant speed.                                                              |
+| `easeIn`         | Starts slow, speeds up (CSS's name). Same as `accelerate`.                   |
+| `easeOut`        | Starts fast, slows to a stop (CSS's name). Same as `decelerate`.             |
+| `easeInOut`      | Speeds up, then slows down (CSS's name). Same as `accelDecel`.               |
+| `bounce`         | Bounces to a stop at the target, like a dropped ball. Same as `bounceEnd`.   |
+| `spring`         | Shoots past the target, then wobbles back and settles. Same as `outElastic`. |
+| `accelerate`     | Starts slow, speeds up.                                                      |
+| `decelerate`     | Starts fast, eases to a stop.                                                |
+| `accelDecel`     | Eases in, then eases out.                                                    |
+| `inElastic`      | Wobbles around the starting point, then snaps to the target at the end.      |
+| `outElastic`     | Shoots past the target right away, then wobbles back and settles.            |
+| `inOutElastic`   | Wobbles at the start, then again around the target.                          |
+| `bounceEnd`      | Bounces to a stop at the target, like a dropped ball.                        |
+| `bounceStart`    | Bounces around the starting point, then heads for the target.                |
+| `bounceStartEnd` | Bounces at both ends.                                                        |
+| `endElastic`     | Same as `inElastic`: the wobble comes near the end.                          |
+| `startElastic`   | Same as `outElastic`: the wobble comes near the start.                       |
+| `bothElastic`    | Same as `inOutElastic`.                                                      |
+
+That's all 18 names `tween` accepts: Pygame Zero's 10 curves, the five
+plain-language names, and `endElastic`, `startElastic` and `bothElastic`,
+names from Pygame Zero's older docs (`end_elastic` and so on) that its code
+doesn't accept. To check a name in code, import the same list as
+`tweenNames` (`import { tweenNames } from "js-game-zero"`); it isn't a
+global in a game file. Like every other name, they're camelCase:
+`tween: "bounce_end"` throws, suggesting `bounceEnd`. If you're not
+sure which to pick, try `easeOut` for smooth movement, `bounce` for things
+that land, and `spring` for things that pop into place.

package/dist/reference/helpers.md

@@ -0,0 +1,46 @@
+# Helpers
+
+Small functions for things almost every game needs. In a game file they're
+ready to use, like `screen` and `Actor`; in import mode, import them from
+`js-game-zero`.
+
+## `randomInt(min, max)`
+
+A random whole number from `min` to `max`, **including both ends**.
+
+```js
+let roll = randomInt(1, 6); // a die: 1, 2, 3, 4, 5 or 6
+let x = randomInt(20, WIDTH - 20); // somewhere across the screen
+```
+
+Fractional ends are rounded inward (`randomInt(0.5, 3.5)` picks 1, 2 or 3).
+Putting the bigger number first throws an error that says so.
+
+## `randomChoice(list)`
+
+A random item from a list.
+
+```js
+let color = randomChoice(["red", "gold", "skyblue"]);
+ball.vx = randomChoice([-200, 200]); // left or right
+```
+
+An empty list throws, since there's nothing to choose.
+
+## `clamp(value, min, max)`
+
+`value`, moved inside `min`–`max` if it's outside; values already inside
+come back unchanged.
+
+```js
+player.x = clamp(player.x, 0, WIDTH);
+plane.angle = clamp(-plane.vy / 8, -25, 75);
+```
+
+To keep a whole sprite on screen, `player.clampIp(screen.bounds())` (see
+[`actor.md`](actor.md)) uses the sprite's real edges.
+
+## `rgb(red, green, blue, alpha?)`
+
+A color mixed from red, green and blue, each `0`–`255`, as in
+`rgb(255, 140, 105)`. See [Colors](screen.md#colors).

package/dist/reference/hooks.md

@@ -0,0 +1,379 @@
+# Hooks And Input Constants
+
+Your game is a set of top-level functions and settings. The runtime calls the
+functions it recognizes, in zero-boilerplate mode as plain `function`
+declarations and in import mode as properties on the object you pass to
+`run()`. This page documents the settings, every hook, then the `keys`,
+`keymods`, and `mouse` constant tables used by the input hooks.
+
+Hook names are camelCase (`onKeyDown`, `onMouseDown`, ...), and work the
+same way in both modes. (A game made with `defineGame()` is the exception:
+its input hooks receive one event object — see [`runtime.md`](runtime.md).)
+A hook spelled another way, such as Pygame Zero's `on_key_down`, is never
+called; the runtime warns about it with a `hook-typo` diagnostic that names
+the camelCase hook to rename it to.
+
+A hook's arguments are matched **by parameter name** first. The runtime reads
+your function's declared parameter names and passes the value with that name,
+in whatever order you wrote them. That means
+`function onKeyDown(mod, key) {}` receives `mod` and `key` correctly even
+though the "natural" order is `key, mod`.
+
+A parameter with any other name receives the next value in the hook's
+documented order that isn't already taken by name, just like an ordinary
+JavaScript function: `function onKeyDown(k) {}` gets the key, and
+`function onMouseDown(position) {}` gets `pos`. The runtime adds a
+`hook-parameter` warning saying which value such a parameter receives, since
+`onMouseDown(btn)` gets the position, not the button. Name your parameters
+as shown below to avoid the warning.
+
+One name is different: a hook whose only parameter is called `event`
+receives all of its values in one object, as a `defineGame()` hook does, so
+`function onKeyDown(event) {}` reads `event.key` and `event.mod`.
+
+## Settings
+
+Set these at the top of a game, like `WIDTH = 480;`.
+
+| Setting          | What it does                                                                                               | Default                  |
+| ---------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------ |
+| `WIDTH`          | The game's width in pixels, rounded down to a whole number. `screen` and the mouse use it.                 | `800`                    |
+| `HEIGHT`         | The game's height in pixels, rounded down to a whole number.                                               | `600`                    |
+| `TITLE`          | The page's title, shown on its tab.                                                                        | The page's own title     |
+| `ICON`           | The name of an image in `images/`, as `Actor` takes it (`ICON = "ship";`), shown as the page's icon.       | The page's own icon      |
+| `PIXEL_DENSITY`  | How many canvas pixels each game pixel gets. See [`screen.md`](screen.md#pixel_density-and-screendensity). | The device's pixel ratio |
+| `TOUCH_CONTROLS` | On-screen buttons for touch screens. See [Touch controls](#touch-controls).                                | None                     |
+
+A `WIDTH` or `HEIGHT` that isn't a positive number is ignored, with an
+`invalid-config` warning, and so is an `ICON` that isn't an image name. In
+import mode, put the settings on the game module or in `run()`'s options
+(see [`runtime.md`](runtime.md#runoptions)).
+
+## draw()
+
+```ts
+function draw(): void;
+```
+
+Called once per animation frame after `update` and after any pending assets
+have loaded. `draw` must not declare any parameters — `run()` throws a
+`TypeError` at startup if it does, since a `draw(dt)` typo (mixing it up with
+`update`) is a common beginner mistake worth catching immediately.
+
+```js
+function draw() {
+  screen.fill("#0f172a");
+  screen.draw.filledCircle([160, 90], 40, "gold");
+}
+```
+
+## update() / update(dt)
+
+```ts
+function update(): void;
+function update(dt: number): void;
+```
+
+Called once per frame, before `draw`. Declare zero parameters if you don't
+need frame timing, or one parameter (conventionally named `dt`) to receive the
+seconds elapsed since the previous frame — use it to make movement
+frame-rate-independent. When the game runs on its own, `dt` is clamped to at
+most `0.25` seconds so a dropped frame (e.g. the tab was backgrounded) can't
+cause a huge jump. A host stepping the game itself, as `handle.step(dt)` and
+the CLI's `step` do, passes its `dt` through unchanged.
+
+```js
+function update(dt) {
+  if (keyboard.right) player.x += 200 * dt; // 200 px/sec, any frame rate
+}
+```
+
+## onKeyDown(key, mod, unicode, repeat) / onKeyUp(key, mod, unicode, repeat)
+
+```ts
+function onKeyDown(
+  key: number,
+  mod: number,
+  unicode: string,
+  repeat: boolean,
+): void;
+function onKeyUp(
+  key: number,
+  mod: number,
+  unicode: string,
+  repeat: boolean,
+): void;
+```
+
+Fired on `keydown`/`keyup`.
+
+- `key` — **a numeric key constant from `keys`**, not a string. This is the
+  single most common mistake when porting from other frameworks: compare it
+  with `key === keys.LEFT`, never `key === "left"` or `key === "ArrowLeft"`.
+- `mod` — a bitmask of currently-held modifier keys from `keymods` (see
+  below). Test a specific modifier with `mod & keymods.SHIFT`.
+- `unicode` — the typed character as a one-character string (`""` for
+  non-printable keys like arrows or function keys).
+- `repeat` — `true` if this event is an OS-generated key-repeat while the key
+  is held down, rather than the initial press. It's always `false` for
+  `onKeyUp`.
+
+```js
+function onKeyDown(key, mod) {
+  if (key === keys.SPACE) jump();
+  if (key === keys.R && mod & keymods.CTRL) restartLevel();
+}
+```
+
+`keyboard.left`, `keyboard.a`, and similar boolean properties (see below) are
+usually a better fit for continuous movement inside `update`; use
+`onKeyDown`/`onKeyUp` for one-shot actions like jumping or firing.
+
+## Touch controls
+
+Set `TOUCH_CONTROLS` near `WIDTH` and `HEIGHT` to add controls below your
+game on phones, tablets, and computers with touch input. The runtime fits
+the canvas into the space above the controls, preserving its aspect ratio
+and logical `WIDTH`/`HEIGHT`. Keyboard code works with these buttons too:
+
+```js
+TOUCH_CONTROLS = {
+  left: keys.LEFT,
+  right: keys.RIGHT,
+  a: keys.SPACE,
+  start: keys.RETURN,
+};
+```
+
+In portrait mode, the dock places the D-pad on the left and the action
+buttons on the right, with Start/Select beneath them; a game with no A or B
+puts Start/Select on the right instead. A sits above and to the right of B
+in a Game Boy-style diagonal arrangement. Three or four directions join into
+one cross; left and right alone (or up and down) stay two separate keys. The
+dock stays below the canvas in both portrait and landscape layouts, near the
+bottom of the game's viewport. In portrait, the canvas is centered
+vertically with at least 48px above the control dock. On shorter screens it
+moves upward as needed to keep the game and controls visible. Landscape
+keeps a 16px gap. Bottom padding keeps buttons clear of the device's home
+indicator.
+
+Only the buttons you list appear. Supported names are `up`, `down`, `left`,
+`right`, `a`, `b`, `start`, and `select`. Each value must be a numeric
+constant from `keys`; the button's label is independent of its mapped key.
+For example, `a: keys.SPACE` makes A trigger a game's existing Space action.
+Omitting `TOUCH_CONTROLS`, or setting it to `false`, hides the controls.
+
+`TOUCH_CONTROLS = true` enables this full preset:
+
+| Button                   | Mapped key                                           |
+| ------------------------ | ---------------------------------------------------- |
+| Up / Down / Left / Right | `keys.UP` / `keys.DOWN` / `keys.LEFT` / `keys.RIGHT` |
+| A                        | `keys.SPACE`                                         |
+| B                        | `keys.X`                                             |
+| Start                    | `keys.RETURN`                                        |
+| Select                   | `keys.ESCAPE`                                        |
+
+The default `show: "auto"` displays controls when the browser reports touch
+support or a coarse pointing device. Add `show: "always"` to a mapping to
+preview them on desktop. These are native buttons, so mouse clicks and
+Tab followed by Space or Enter work as well.
+
+Holding a button updates `keyboard` and fires `onKeyDown` once; releasing
+it fires `onKeyUp`. Virtual presses have `mod: keymods.NONE`,
+`unicode: ""`, and `repeat: false`; use `update(dt)` for repeated actions.
+Multiple fingers can hold directions and action buttons together. Slide a
+finger across the D-pad to change direction. Each mapped key stays held
+until every touch button and physical key holding it has
+been released. Cancellation, loss of pointer capture, leaving the window,
+and hiding the page clear held inputs. Stopping or reloading a game removes
+its controls and listeners.
+
+A page that hosts a game can restyle the dock by setting these CSS custom
+properties on any element around the canvas, such as `:root`:
+
+| Property                                           | What it sets                                                         | Default                                 |
+| -------------------------------------------------- | -------------------------------------------------------------------- | --------------------------------------- |
+| `--jgz-key-size`                                   | A key's size; the cross is three keys across                         | `clamp(40px, 10vw, 52px)`               |
+| `--jgz-key-fill`, `--jgz-key-ink`                  | A key's fill, and its label and arrow color                          | `#263244`, `#fff`                       |
+| `--jgz-key-line`, `--jgz-key-line-width`           | A key's outline                                                      | `#718096`, `2px`                        |
+| `--jgz-key-pressed-fill`, `--jgz-key-pressed-line` | A held key's fill and outline                                        | `#4267a0`, `#b9d5ff`                    |
+| `--jgz-key-shadow-x`, `-y`, `-color`               | A hard shadow under each key and the cross; a held key moves onto it | `0px`, `0px`, `transparent`             |
+| `--jgz-key-radius`                                 | Separate keys' corners (any `border-radius`)                         | `12px`                                  |
+| `--jgz-dpad-radius`                                | The cross's outer corners                                            | `10px`                                  |
+| `--jgz-dpad-dot`                                   | The dot in the middle of the cross                                   | `rgba(255, 255, 255, 0.16)`             |
+| `--jgz-key-font`, `--jgz-action-font`              | Start/Select labels, and A/B labels (a `font` shorthand)             | `bold 13px` and `bold 18px` `system-ui` |
+| `--jgz-action-line-width`                          | A and B's outline                                                    | `--jgz-key-line-width`                  |
+| `--jgz-system-height`, `--jgz-system-radius`       | Start and Select's height and corners                                | `40px`, `12px`                          |
+| `--jgz-focus-ring`                                 | The keyboard focus outline                                           | `#facc15`                               |
+| `--jgz-dock-gap`                                   | The least space between the canvas and the dock                      | `48px` portrait, `16px` landscape       |
+
+In import mode, put `TOUCH_CONTROLS` on the module returned by `defineGame`,
+on a raw game module, or in the options passed to `run`. TypeScript exports
+`TouchButton`, `TouchControlsConfig`, and `TouchControlsOptions`.
+
+### Tapping and dragging the canvas
+
+Canvas touch and pen input work even without a control dock. A primary
+touch triggers `onMouseDown`, dragging triggers `onMouseMove` with
+`mouse.LEFT` in `buttons`, and releasing or cancelling triggers
+`onMouseUp`. Positions and movement are converted to logical game
+coordinates when the canvas is scaled. The pointer remains captured when
+it leaves the canvas; extra canvas touches are ignored until the first is
+released. Touch buttons do not trigger canvas mouse hooks.
+
+The canvas and control buttons disable native touch panning during play;
+the surrounding page retains its normal gestures. Games can therefore use
+tap-to-flap or drag-to-steer without adding separate touch hooks.
+
+For embedding, give each canvas a parent with a defined height. While the
+dock is visible, the runtime groups the canvas and controls into a column
+that fills the available space, anchors controls at the bottom, and centers
+the portrait canvas when space permits. It accounts for visible siblings,
+padding, and row gaps, and restores the original canvas placement when the
+dock is hidden or the game stops.
+The sandbox preview handles this automatically.
+
+## onMouseDown(pos, button) / onMouseUp(pos, button)
+
+```ts
+function onMouseDown(pos: [number, number], button: number): void;
+function onMouseUp(pos: [number, number], button: number): void;
+```
+
+Fired on `mousedown`/`mouseup`, and also for **wheel scroll**: a wheel event
+is reported as `onMouseDown` with `button` set to `mouse.WHEEL_UP` or
+`mouse.WHEEL_DOWN` (matching pygame's convention of treating the scroll wheel
+as buttons 4 and 5, rather than a separate event). There is no
+`onMouseWheel` hook — check `button` inside `onMouseDown` instead.
+
+```js
+function onMouseDown(pos, button) {
+  if (button === mouse.LEFT) fireAt(pos);
+  if (button === mouse.WHEEL_UP) zoom += 1;
+  if (button === mouse.WHEEL_DOWN) zoom -= 1;
+}
+```
+
+## onMouseMove(pos, rel, buttons)
+
+```ts
+function onMouseMove(
+  pos: [number, number],
+  rel: [number, number],
+  buttons: Set<number>,
+): void;
+```
+
+Fired on `mousemove`. `rel` is the movement since the previous event (from
+the browser's `movementX`/`movementY` when available). `buttons` is a `Set`
+of currently held mouse buttons (`mouse.LEFT`, `mouse.MIDDLE`, `mouse.RIGHT`)
+— check membership with `buttons.has(mouse.LEFT)`.
+
+## onMusicEnd()
+
+```ts
+function onMusicEnd(): void;
+```
+
+Fired once the active `music` track (and any queued tracks) finish playing
+with nothing left to play.
+
+## `keyboard`
+
+`keyboard` is a live object of boolean properties reflecting which keys are
+currently held down, one for each key in `keys` under the same name in any
+capitalization (`keyboard.left`, `keyboard.space`, `keyboard.a`, and
+`keyboard.K_1` for the digit keys). Read it inside `update()` for continuous
+movement:
+
+```js
+function update(dt) {
+  if (keyboard.left) player.x -= 150 * dt;
+  if (keyboard.right) player.x += 150 * dt;
+}
+```
+
+Accessing an attribute that isn't a real key name throws an error (`The key
+"..." does not exist`) instead of silently returning `false` — this catches
+typos like `keyboard.lfet` immediately rather than letting your character
+quietly fail to move. A misspelling says which key it's closest to:
+`keyboard.lfet doesn't exist. Did you mean keyboard.left?`. `keyboard.pressed()` returns a sorted array of every
+currently-held key constant, for debugging.
+
+## `keys`
+
+Numeric key constants, one property per key. The full set includes:
+
+| Category                   | Names                                                                                                                                                                               |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Letters                    | `keys.A` … `keys.Z`                                                                                                                                                                 |
+| Digits                     | `keys.K_0` … `keys.K_9`                                                                                                                                                             |
+| Arrows                     | `keys.UP`, `keys.DOWN`, `keys.LEFT`, `keys.RIGHT`                                                                                                                                   |
+| Editing                    | `keys.BACKSPACE`, `keys.TAB`, `keys.RETURN` (alias `keys.ENTER`), `keys.DELETE`, `keys.ESCAPE`, `keys.SPACE`                                                                        |
+| Function keys              | `keys.F1` … `keys.F15`                                                                                                                                                              |
+| Navigation                 | `keys.HOME`, `keys.END`, `keys.PAGEUP`, `keys.PAGEDOWN`, `keys.INSERT`                                                                                                              |
+| Modifiers (as key presses) | `keys.LSHIFT`, `keys.RSHIFT`, `keys.LCTRL`, `keys.RCTRL`, `keys.LALT`, `keys.RALT`, `keys.LMETA`, `keys.RMETA`                                                                      |
+| Numpad                     | `keys.KP0` … `keys.KP9`, `keys.KP_PERIOD`, `keys.KP_DIVIDE`, `keys.KP_MULTIPLY`, `keys.KP_MINUS`, `keys.KP_PLUS`, `keys.KP_ENTER`, `keys.KP_EQUALS`                                 |
+| Punctuation                | `keys.MINUS`, `keys.EQUALS`, `keys.LEFTBRACKET`, `keys.RIGHTBRACKET`, `keys.BACKSLASH`, `keys.SEMICOLON`, `keys.QUOTE`, `keys.BACKQUOTE`, `keys.COMMA`, `keys.PERIOD`, `keys.SLASH` |
+| Locks                      | `keys.CAPSLOCK`, `keys.NUMLOCK`, `keys.SCROLLOCK`                                                                                                                                   |
+
+The values are arbitrary integers (matching SDL/pygame's numbering) — never
+hardcode them, always compare against the named constant. Constants are
+upper case. In a game file, any other spelling such as `keys.space` or
+`keys.SPCE` throws with a suggestion (`Did you mean keys.SPACE?`) instead of
+quietly comparing against `undefined`. The same goes for `keymods` and
+`mouse`.
+
+## `keymods`
+
+A bitmask of held modifier keys, combined with `|` and tested with `&`:
+
+| Constant                            | Meaning                                   |
+| ----------------------------------- | ----------------------------------------- |
+| `keymods.NONE`                      | No modifier held                          |
+| `keymods.SHIFT`                     | Either Shift key (`LSHIFT \| RSHIFT`)     |
+| `keymods.CTRL`                      | Either Control key (`LCTRL \| RCTRL`)     |
+| `keymods.ALT`                       | Either Alt/Option key (`LALT \| RALT`)    |
+| `keymods.META`                      | Either Cmd/Windows key (`LMETA \| RMETA`) |
+| `keymods.LSHIFT` / `keymods.RSHIFT` | Left/right Shift specifically             |
+| `keymods.LCTRL` / `keymods.RCTRL`   | Left/right Control specifically           |
+| `keymods.LALT` / `keymods.RALT`     | Left/right Alt specifically               |
+| `keymods.LMETA` / `keymods.RMETA`   | Left/right Cmd/Windows specifically       |
+| `keymods.CAPS`                      | Caps Lock is toggled on                   |
+| `keymods.NUM`                       | Num Lock is toggled on                    |
+| `keymods.MODE`                      | AltGr / alternate-graphics modifier       |
+
+```js
+function onKeyDown(key, mod) {
+  if (mod & keymods.SHIFT) console.log("shift-modified key");
+}
+```
+
+## `mouse`
+
+In a game file, `mouse` also says where the mouse is right now, for code in
+`update()` that follows or aims at it — the way `keyboard` does for keys:
+
+| Property        | Meaning                                                                       |
+| --------------- | ----------------------------------------------------------------------------- |
+| `mouse.pos`     | `[x, y]` of the mouse (or a finger) over the game. The center until it moves. |
+| `mouse.x`       | The same `x`.                                                                 |
+| `mouse.y`       | The same `y`.                                                                 |
+| `mouse.buttons` | A `Set` of buttons held now: `mouse.buttons.has(mouse.LEFT)`.                 |
+| `mouse.down`    | `true` while any button, or a finger, is down.                                |
+
+```js
+function update(dt) {
+  ship.angle = ship.angleTo(mouse.pos); // aim at the mouse
+}
+```
+
+Button constants:
+
+| Constant           | Value | Meaning                                              |
+| ------------------ | ----- | ---------------------------------------------------- |
+| `mouse.LEFT`       | 1     | Left mouse button                                    |
+| `mouse.MIDDLE`     | 2     | Middle mouse button (wheel click)                    |
+| `mouse.RIGHT`      | 3     | Right mouse button                                   |
+| `mouse.WHEEL_UP`   | 4     | Scroll wheel moved up (reported via `onMouseDown`)   |
+| `mouse.WHEEL_DOWN` | 5     | Scroll wheel moved down (reported via `onMouseDown`) |

package/dist/reference/index.d.ts

@@ -0,0 +1,2 @@
+/** js-game-zero's API reference: every page's Markdown by its file name, such as "actor.md". */
+export declare const reference: Readonly<Record<string, string>>;