js-game-zero 0.0.0-stage → 0.4.0

package/dist/reference/screen.md

@@ -0,0 +1,392 @@
+# Screen And Drawing
+
+`screen` is the global canvas surface. Everything you draw happens inside
+`draw()`, in screen pixels: `[0, 0]` is the top-left corner, x grows right,
+y grows down, and `[WIDTH, HEIGHT]` is the bottom-right corner.
+
+## Short forms
+
+Six short calls draw the most common shapes and text, with each position
+given as separate numbers rather than an `[x, y]` list:
+
+| Call                                                     | Draws                                                   |
+| -------------------------------------------------------- | ------------------------------------------------------- |
+| `screen.circle(x, y, radius, color)`                     | a filled circle centered on `x, y`                      |
+| `screen.rect(x, y, width, height, color)`                | a filled rectangle whose top-left corner is `x, y`      |
+| `screen.roundedRect(x, y, width, height, radius, color)` | the same rectangle with its corners rounded `radius` px |
+| `screen.triangle(x1, y1, x2, y2, x3, y3, color)`         | a filled triangle with those three corners              |
+| `screen.line(x1, y1, x2, y2, color, width = 1)`          | a line from `x1, y1` to `x2, y2`, `width` px thick      |
+| `screen.text(text, x, y, color, size = 24)`              | text whose top-left corner is `x, y`, `size` tall       |
+
+`color` is optional and defaults to `"white"`; it takes any of the
+[colors](#colors) below.
+
+```js
+function draw() {
+  screen.clear();
+  screen.rect(0, 220, 400, 80, "green");
+  screen.roundedRect(280, 20, 100, 40, 12, "purple");
+  screen.circle(200, 150, 25, "gold");
+  screen.triangle(160, 40, 120, 120, 200, 120);
+  screen.line(20, 20, 200, 120, "white", 3);
+  screen.text("Score: " + score, 20, 30);
+}
+```
+
+`screen.text` takes words in quotes or a number. To place text by its
+center, wrap it or give it an outline, use
+[`screen.draw.text`](#screendrawtexttext-pos-options--screendrawtexttext-options).
+
+The short forms fill their shapes. The outline versions, and the versions
+that take `[x, y]` lists, stay under `screen.draw` below. Mind the names:
+**`screen.circle` fills, but `screen.draw.circle` draws only an outline**,
+and the same goes for `screen.rect` and `screen.draw.rect`, and for
+`screen.roundedRect` and `screen.draw.roundedRect`.
+
+A wrong call throws a `TypeError` that says what to change. A list, as in
+`screen.circle([200, 150], 25)`, points to the `screen.draw` method that
+takes lists (here `screen.draw.filledCircle`). A missing or non-number
+argument is named, and an extra one, such as an outline width, points to
+the outline method. `screen.roundedRect` takes its radius before its color,
+as `screen.circle` does, and a color where the radius belongs says so.
+
+## Colors
+
+Every drawing method accepts a `Color`, which is either a CSS color string
+(`"white"`, `"#0f172a"`, `"rgb(20, 30, 40)"`) or an RGB/RGBA tuple of
+integers `0`–`255`: `[249, 115, 22]` or `[249, 115, 22, 128]` (the fourth
+value is alpha out of 255, not a `0`–`1` fraction). Passing anything else
+throws a `TypeError` that says what was wrong:
+
+- A misspelled color name suggests the right one: `"lightblu"` fails with
+  `Did you mean "lightblue"?`. (A canvas would otherwise ignore the color
+  and keep drawing in the previous one.)
+- A hex code needs 3 or 6 hex digits (or 4 or 8, with alpha).
+- A fractional alpha such as `[255, 0, 0, 0.5]` fails with the 0–255 value
+  to use instead (`128`).
+
+Drawing options are checked the same way: an option a method doesn't have,
+such as `{ colour: "red" }`, throws and names the closest real option.
+
+### `rgb(red, green, blue, alpha?)`
+
+Mixes a color from red, green and blue light, each `0`–`255`, with an
+optional alpha out of 255. It returns the matching list, so
+`rgb(255, 140, 105)` is `[255, 140, 105]` and works anywhere a color does.
+It's ready to use in a game file; in import mode, import it from
+`js-game-zero`.
+
+```js
+let coral = rgb(255, 140, 105);
+let glass = rgb(120, 200, 255, 128); // half see-through
+screen.circle(200, 150, 25, coral);
+```
+
+Its numbers are checked like a list's, with the same hints (a fractional
+alpha such as `0.5` names `128` instead), and a missing one is named:
+`rgb(255, 140)` fails with `rgb is missing blue`.
+
+## `screen.clear()`
+
+Resets the whole canvas to opaque black.
+
+```js
+function draw() {
+  screen.clear();
+}
+```
+
+## `screen.fill(color, bottomColor?)`
+
+Fills the canvas with a solid color, or a top-to-bottom gradient when a
+second color is given: `color` at the top fading to `bottomColor` at the
+bottom.
+
+```js
+screen.fill("#0f172a"); // solid
+screen.fill("#0f172a", "#164e63"); // gradient, dark at top to teal at bottom
+```
+
+## `screen.draw.image(image, pos)` / `screen.blit(image, pos)`
+
+`screen.draw.image` and `screen.blit` (Pygame Zero's name) do the same
+thing. Draws an already-loaded image (by asset name, or a `SurfaceLike` you already
+hold) at a position. `pos` is a `[x, y]` point for the image's top-left
+corner, or a rect-like value (its top-left corner is used; blit does not
+scale the image to the rect's size).
+
+```js
+screen.draw.image("player.svg", [40, 40]);
+```
+
+If the named image hasn't finished loading yet, nothing is drawn: it returns
+a `Promise` that resolves once the image has loaded, and the runtime holds
+the frames that follow until then, so the image shows from the next one.
+If it can't be loaded, the promise rejects and the run reports the missing
+image by name, so `draw()` needn't handle the promise itself.
+Images touched while the script starts up load before the first frame (see
+[`docs/reference/runtime.md`](runtime.md#preload-gate)).
+Prefer `Actor` for anything that moves or needs collision — drawing an image
+directly is for background art and tiles.
+
+## `screen.bounds()`
+
+Returns a `ZRect` covering the whole canvas (`[0, 0, WIDTH, HEIGHT]`), handy
+for clamping or collision against the screen edge.
+
+```js
+if (!screen.bounds().contains(player.rect()))
+  player.center = [WIDTH / 2, HEIGHT / 2];
+```
+
+## `PIXEL_DENSITY` and `screen.density`
+
+On a phone, one screen pixel covers several of the device's own pixels.
+The canvas has a pixel for each of them, so text, outlines and SVG pictures
+stay sharp. `screen.density` says how many canvas pixels make up one screen
+pixel along each side: between 2 and 3 on most phones and 1 on a computer
+monitor. Your game's numbers don't change with it: a game 360 pixels wide
+is 360 wide at any density.
+
+Set `PIXEL_DENSITY` next to `WIDTH` and `HEIGHT` to choose the density
+yourself. Without it, the game uses the device's own, up to 3.
+
+```js
+WIDTH = 360;
+HEIGHT = 640;
+PIXEL_DENSITY = 1; // one canvas pixel per screen pixel, even on a phone
+```
+
+See [pixel density](runtime.md#pixel-density) for how hosts size and read
+the canvas.
+
+## `screen.draw.line(start, end, color, width = 1)`
+
+```js
+screen.draw.line([20, 20], [200, 120], "white", 3);
+```
+
+## `screen.draw.circle(pos, radius, color, width = 1)` / `filledCircle(pos, radius, color)`
+
+`screen.draw.circle` draws an outline; `filledCircle` and the short form
+[`screen.circle`](#short-forms) fill.
+
+```js
+screen.draw.circle([160, 90], 40, "#38bdf8", 2); // outline
+screen.draw.filledCircle([160, 90], 40, "#38bdf8"); // filled
+```
+
+## `screen.draw.rect(rect, color, width = 1)` / `filledRect(rect, color)`
+
+`rect` accepts anything geometry accepts: a `Rect`, an `Actor` (via its
+`.rect()` duck type — see [`docs/reference/rect.md`](rect.md)), or a plain
+`[left, top, width, height]` tuple.
+
+```js
+screen.draw.filledRect([40, 40, 120, 60], "#f97316");
+screen.draw.rect(player.rect(), "yellow", 2); // highlight a hitbox
+```
+
+## `screen.draw.roundedRect(rect, radius, color, width = 1)` / `filledRoundedRect(rect, radius, color)`
+
+A rectangle with its corners rounded: each corner is a quarter of a circle
+`radius` pixels round. `rect` takes what `screen.draw.rect` takes, and the
+radius comes before the color, as a circle's does. `roundedRect` draws an
+outline, `width` pixels thick; `filledRoundedRect` and the short form
+[`screen.roundedRect`](#short-forms) fill.
+
+```js
+screen.draw.filledRoundedRect([40, 40, 160, 48], 12, "#f97316"); // a button
+screen.draw.roundedRect([40, 40, 160, 48], 12, "white", 2); // its border
+screen.draw.filledRoundedRect([40, 110, 160, 30], 15, "#22c55e"); // a pill
+```
+
+A radius of `0` gives square corners. A radius bigger than half the
+rectangle's height (or width, if that's shorter) is drawn as that half, so
+its short sides are half circles: a pill, or a circle for a square. A
+negative radius, or a color where the radius belongs, throws a `TypeError`
+that says what to change.
+
+## `screen.draw.polygon(points, color, width = 1)` / `filledPolygon(points, color)`
+
+Needs at least three points.
+
+```js
+screen.draw.filledPolygon(
+  [
+    [238, 40],
+    [292, 64],
+    [270, 126],
+    [214, 118],
+  ],
+  "#f8fafc",
+);
+```
+
+## `screen.draw.text(text, pos?, options?)` / `screen.draw.text(text, options)`
+
+Draws text with a large set of beginner-friendly options — this is a
+JavaScript-native reimplementation of pgzero's `ptext` module, including its
+word-wrapping algorithm and gradient/outline/shadow effects.
+
+```js
+screen.draw.text("Score: 12", [16, 16], {
+  size: 24,
+  color: "white",
+});
+```
+
+When the options say where the text goes (`center`, `topRight`, ...), pass
+them second, in place of the position:
+
+```js
+screen.draw.text("Game Over", { center: [WIDTH / 2, HEIGHT / 2], size: 40 });
+```
+
+Several options have two names: a readable one, and the shorter one Pygame
+Zero uses. Either works, but not both at once:
+
+| Readable name   | Pygame Zero name |
+| --------------- | ---------------- |
+| `size`          | `fontsize`       |
+| `outline`       | `owidth`         |
+| `outlineColor`  | `ocolor`         |
+| `shadowColor`   | `scolor`         |
+| `gradientColor` | `gcolor`         |
+
+### Position options
+
+Give **exactly one** of the following ways to position the text (mixing
+them throws a `TypeError`):
+
+- `pos` (or the second positional argument) — a `[x, y]` point. Combined
+  with `anchor` (default `"topLeft"`) to decide which part of the text box
+  sits at that point.
+- A named anchor point directly: `topLeft`, `topRight`, `bottomLeft`,
+  `bottomRight`, `midTop`, `midLeft`, `midRight`, `midBottom`, `center` —
+  each takes a `[x, y]` point for that corner/edge/center of the text.
+- Scalar axis keywords, combined per-axis: `left`/`centerX`/`right` for the
+  horizontal position, `top`/`centerY`/`bottom` for the vertical position.
+  You can mix one horizontal and one vertical scalar (`{ right: 300, top: 10
+}`), or use just one axis and fall back to `pos` for the other.
+
+```js
+screen.draw.text("Game Over", {
+  center: [WIDTH / 2, HEIGHT / 2],
+  size: 40,
+});
+screen.draw.text("HUD", { right: WIDTH - 10, top: 10 }); // top-right corner, 10px margin
+```
+
+### Font options
+
+- `size` / `fontsize` (default `24`)
+- `fontname` — the stem of a font asset under `fonts/` (e.g. `"pixel"` for
+  `fonts/pixel.ttf`); loads asynchronously the first time it's used.
+- `sysfontname` — a literal CSS font family name instead (e.g. `"Georgia"`).
+  Mutually exclusive with `fontname`.
+- `bold`, `italic`, `underline` — booleans.
+- `color` (default `"white"`), `background` (fills a box behind the text).
+- `gradientColor` / `gcolor` — a second color for a top-to-bottom gradient
+  across the text.
+
+### Layout options
+
+- `width` — wraps text to fit this many pixels; without it, text is only
+  broken at explicit newlines (`\n`). Wrapping is greedy word-wrap: a single
+  word longer than `width` is placed on its own (overflowing) line rather
+  than being cut.
+- `widthem` — like `width`, but expressed as a multiple of `size`.
+- `lineheight` — pixels between lines (default `size * 1.2`).
+- `align` — `"left"` (default), `"center"`, or `"right"`, for multi-line text.
+  A [`textbox`](#screendrawtextboxtext-rect-options) follows its `anchor`
+  instead, so it centers by default.
+- `strip` — trims trailing spaces from each wrapped line (default `true`).
+- `anchor` — overrides which part of the text's bounding box sits at the
+  resolved position; either one of the named anchor strings above, or a
+  `[horizontal, vertical]` pair where each side is `"left"`/`"center"`/`"right"`,
+  `"top"`/`"center"`/`"bottom"`, or a literal pixel-offset number.
+- `angle` — rotates the text counterclockwise around the anchor point, in
+  degrees.
+
+### Effects
+
+- `outline` / `owidth` + `outlineColor` / `ocolor` — an outline stroke
+  around the glyphs, `outline` pixels thick.
+- `shadow` (a number or `[x, y]` offset) + `shadowColor` / `scolor`
+  (default `"black"`) — a drop shadow.
+- `alpha` — overall opacity, `0`–`1` (default `1`).
+
+## `screen.draw.textbox(text, rect, options?)`
+
+Like `draw.text`, but instead of a fixed `size` you give a rectangle and
+`textbox` picks the **largest font size that fits inside it** (shrinking
+down to `minSize`, default `4`, if necessary; `minFontsize` is another name
+for it, but not both at once). Text is centered in the rect by default.
+Pass `anchor` (e.g. `"topLeft"`) to place it elsewhere in the rect; its
+lines line up the same way (on the left for `"topLeft"`) unless you give
+`align`. The rect places the text, so `textbox` takes none of
+`draw.text`'s position options (`pos`, `center`, `topLeft`, `left`, ...)
+and no `width`; giving one throws a `TypeError` that says so.
+
+```js
+screen.draw.textbox("You win!", [40, 60, 240, 80], {
+  color: "white",
+  size: 48, // upper bound; shrinks to fit if "You win!" would overflow
+});
+```
+
+## `screen.measureText(text, options?)`
+
+How big `screen.draw.text` would draw some text. It returns
+`{ width, height, lines }`, in screen pixels, and draws nothing:
+
+- `width` — the widest line's width.
+- `height` — the lines' height together: one `lineheight` (`size * 1.2`
+  unless given) for each line.
+- `lines` — the lines the text breaks into, at each `\n` and, with a
+  `width` option, where it wraps.
+
+It takes the options `screen.draw.text` takes (`size`, `fontname`,
+`sysfontname`, `bold`, `italic`, `width`, `widthem`, `lineheight`,
+`strip`) and measures the text the way `screen.draw.text` lays it out
+with them. Options that only place or color the text (`center`, `color`,
+`outline`, `angle`, ...) are allowed too, and change nothing, so you can
+measure a label with the same options you draw it with. A position before
+the options, as in `screen.draw.text(text, [x, y], options)`, is allowed
+for the same reason.
+
+```js
+let options = { midLeft: [40, 200], size: 20 };
+screen.draw.text("Play again", options);
+let label = screen.measureText("Play again", options);
+// A dot just right of the label, whatever its font and size.
+screen.circle(40 + label.width + 12, 200, 5, "gold");
+```
+
+Measuring a button's label tells you how big to draw the button:
+
+```js
+let size = screen.measureText("Start", { size: 24 });
+let box = [100, 100, size.width + 32, size.height + 16];
+screen.draw.filledRoundedRect(box, 12, "#2563eb");
+screen.draw.text("Start", {
+  center: [100 + box[2] / 2, 100 + box[3] / 2],
+  size: 24,
+});
+```
+
+Without a `width` option, the size it returns is the size of the box
+`screen.draw.text` places, so `center` (or any other anchor) puts the text
+where that size says it goes. With a `width` option, `screen.draw.text`'s
+box is that wide, and the `width` it returns says how much of it the
+lines fill. An outline or shadow draws a little outside the measured size.
+
+Measure where you draw, in `draw()`: a font from `fonts/` measures right
+once it has loaded, and the game holds its frames while it loads.
+
+`text` is words in quotes or a number. A wrong call throws a `TypeError`
+that says what to change: an option `screen.draw.text` doesn't have is
+named with the closest real one, and a number after the text, as in
+`screen.measureText("Score", 32)`, says to give the size as an option,
+`{ size: 32 }`.

package/dist/reference/storage.md

@@ -0,0 +1,90 @@
+# Storage
+
+`storage` is a persistent, dictionary-like object for saving small amounts
+of data between play sessions — high scores, unlocked levels, settings.
+
+```js
+let highScore = storage.get("highScore") ?? 0;
+
+function update() {
+  if (score > highScore) {
+    highScore = score;
+    storage.set("highScore", highScore);
+  }
+}
+```
+
+## Auto-load and auto-save
+
+You don't need to call `save()` or `load()` yourself in normal use:
+
+- **Auto-load**: the default browser adapter has a synchronous `loadSync()`
+  path, so a top-level read like `let score = storage.get("score") ?? 0`
+  sees previously-saved data immediately. So does a custom adapter with a
+  `loadSync()`, or whose `load()` returns its text rather than a Promise. A
+  custom asynchronous adapter is loaded once during startup and delays
+  frames/`handle.ready`, but cannot retroactively change values already
+  copied into top-level variables, and what it loads replaces anything the
+  top level stored before it arrived.
+- **Auto-save**: any mutation (`storage.set(...)`, `storage.score = 5`,
+  `storage.delete(...)`, `storage.clear()`) schedules a save a fraction of a
+  second later, and within a second even while the game keeps changing it
+  every frame; rapid changes coalesce into one write instead of saving on
+  every single mutation. Storage is also flushed immediately when the tab is
+  hidden or closed, and when the game stops, so nothing is lost. A change
+  inside a stored object or list, such as `storage.highScores.push(score)`,
+  is saved too, with the next of those saves; set the key again
+  (`storage.highScores = storage.highScores`) to save it sooner.
+
+## Reading and writing
+
+Two equivalent styles work — plain method calls, or attribute-style access
+through a proxy (closer to pgzero's `storage` object):
+
+```js
+storage.set("score", 10);
+storage.get("score"); // 10
+
+storage.score = 10; // same as storage.set("score", 10)
+storage.score; // 10
+```
+
+| Method                                  | Behavior                                                                                           |
+| --------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `storage.get(key, defaultValue?)`       | Returns the stored value, or `defaultValue` (`undefined` if omitted) if `key` isn't set.           |
+| `storage.set(key, value)`               | Stores `value` under `key`.                                                                        |
+| `storage.setDefault(key, defaultValue)` | Sets `key` to `defaultValue` only if it isn't already set; returns the resulting value either way. |
+| `storage.has(key)`                      | `boolean`.                                                                                         |
+| `storage.delete(key)`                   | Removes `key`; also works as `delete storage.key`. Returns `true` if something was removed.        |
+| `storage.clear()`                       | Removes everything.                                                                                |
+| `storage.keys()`                        | Every stored key, alphabetically sorted.                                                           |
+| `storage.path`                          | The backing location: a scoped `localStorage` key in the browser, or a file path in the sandbox.   |
+
+Values must be JSON-serializable — plain objects, arrays, strings, numbers,
+booleans, and `null`. Storing anything else (a class instance, a function,
+`undefined`, `NaN`, `Infinity`, a circular reference), anywhere inside the
+value, throws a `JsonStorageError` naming the offending path, e.g.
+`NaN is not a JSON value at storage.highScores[2].score`, and stores nothing.
+A value changed inside a stored object or list after it was stored is only
+checked when storage saves: until it's a JSON value again, saving fails,
+with a warning naming its path, and nothing in storage is saved.
+
+## Gotchas
+
+- **Don't shadow method names.** `storage.save`, `storage.load`, `storage.path`
+  and the other method names above are real properties on `storage` itself,
+  not just proxy-forwarded keys — writing `storage.save = 5` overwrites the
+  actual `save` method instead of storing a value, and another spelling of
+  a method, such as `storage.setdefault`, throws naming the method. Pick key
+  names that don't collide with the method list.
+- Storage is scoped per project: in the browser it's namespaced by project
+  id (so two different games on the same site don't share data, as long as
+  each has its own `projectId`; games run without one all share the id
+  `default`); in the sandbox it's a JSON file inside that project's own
+  directory.
+
+## Manual save/load
+
+For advanced cases — forcing an immediate write instead of waiting for the
+debounce, or working outside of `run()` — `storage.save()` and
+`storage.load()` are both available directly and return `Promise<void>`.