@origingame/create-game 0.0.0-stage → 0.1.1

package/archetypes/idle/tools/oglite.py

@@ -0,0 +1,285 @@
+"""A tiny, standard-library-only sprite kit for Origin Engine archetypes.
+
+It draws antialiased vector shapes into RGBA images (4x4 supersampling),
+writes PNGs, packs sprites into one glTF binary (.glb) of unit quads, one
+mesh and one emissive, alpha-masked material per sprite, and writes 16-bit
+WAV sounds. Everything is a pure function of its inputs, so the assets it
+makes are byte-for-byte reproducible.
+
+A sprite quad lies in the xy plane facing +z, 1 x 1 units, centred on the
+origin, with uv (0,0) at the image's top left. Its material is black base
+colour (alpha from the image, for the mask), roughness 1, and the image as
+the emissive texture: with no light, no environment and tone mapping off,
+the frame shows the image's colours exactly.
+"""
+import json, math, struct, wave, zlib
+
+SS = 4  # supersamples per axis
+
+
+def hex_rgb(h):
+    h = h.lstrip("#")
+    return tuple(int(h[i:i + 2], 16) for i in (0, 2, 4))
+
+
+class Canvas:
+    """An RGBA canvas; shapes are painted in order with coverage antialiasing.
+    Coordinates are in pixels, origin top left, y down."""
+
+    def __init__(self, w, h):
+        self.w, self.h = w, h
+        self.px = [[0.0, 0.0, 0.0, 0.0] for _ in range(w * h)]  # premultiplied
+
+    def _paint(self, inside, bbox, colour, alpha=1.0):
+        r, g, b = (c / 255.0 for c in hex_rgb(colour))
+        x0, y0, x1, y1 = bbox
+        x0 = max(0, int(math.floor(x0))); y0 = max(0, int(math.floor(y0)))
+        x1 = min(self.w, int(math.ceil(x1))); y1 = min(self.h, int(math.ceil(y1)))
+        n = SS * SS
+        for y in range(y0, y1):
+            for x in range(x0, x1):
+                hits = 0
+                for sy in range(SS):
+                    py = y + (sy + 0.5) / SS
+                    for sx in range(SS):
+                        if inside(x + (sx + 0.5) / SS, py):
+                            hits += 1
+                if hits == 0:
+                    continue
+                a = alpha * hits / n
+                p = self.px[y * self.w + x]
+                p[0] = r * a + p[0] * (1 - a)
+                p[1] = g * a + p[1] * (1 - a)
+                p[2] = b * a + p[2] * (1 - a)
+                p[3] = a + p[3] * (1 - a)
+
+    def rect(self, x, y, w, h, colour, radius=0.0, alpha=1.0):
+        rad = min(radius, w / 2, h / 2)
+
+        def inside(px, py):
+            if px < x or px > x + w or py < y or py > y + h:
+                return False
+            if rad <= 0:
+                return True
+            cx = min(max(px, x + rad), x + w - rad)
+            cy = min(max(py, y + rad), y + h - rad)
+            return (px - cx) ** 2 + (py - cy) ** 2 <= rad * rad
+
+        self._paint(inside, (x, y, x + w, y + h), colour, alpha)
+
+    def circle(self, cx, cy, r, colour, alpha=1.0):
+        self.ellipse(cx, cy, r, r, colour, alpha)
+
+    def ellipse(self, cx, cy, rx, ry, colour, alpha=1.0):
+        def inside(px, py):
+            return ((px - cx) / rx) ** 2 + ((py - cy) / ry) ** 2 <= 1.0
+
+        self._paint(inside, (cx - rx, cy - ry, cx + rx, cy + ry), colour, alpha)
+
+    def ring(self, cx, cy, r, width, colour, alpha=1.0):
+        def inside(px, py):
+            d = math.hypot(px - cx, py - cy)
+            return r - width <= d <= r
+
+        self._paint(inside, (cx - r, cy - r, cx + r, cy + r), colour, alpha)
+
+    def poly(self, pts, colour, alpha=1.0):
+        xs = [p[0] for p in pts]; ys = [p[1] for p in pts]
+
+        def inside(px, py):
+            c = False
+            j = len(pts) - 1
+            for i in range(len(pts)):
+                xi, yi = pts[i]; xj, yj = pts[j]
+                if (yi > py) != (yj > py) and px < (xj - xi) * (py - yi) / (yj - yi) + xi:
+                    c = not c
+                j = i
+            return c
+
+        self._paint(inside, (min(xs), min(ys), max(xs), max(ys)), colour, alpha)
+
+    def line(self, x0, y0, x1, y1, width, colour, alpha=1.0):
+        dx, dy = x1 - x0, y1 - y0
+        ln = math.hypot(dx, dy) or 1.0
+        nx, ny = -dy / ln * width / 2, dx / ln * width / 2
+        self.poly([(x0 + nx, y0 + ny), (x1 + nx, y1 + ny), (x1 - nx, y1 - ny), (x0 - nx, y0 - ny)], colour, alpha)
+        self.circle(x0, y0, width / 2, colour, alpha)
+        self.circle(x1, y1, width / 2, colour, alpha)
+
+    def rgba(self):
+        """Straight-alpha RGBA8 rows. Transparent pixels take the colour of
+        the nearest painted pixel (a few dilation passes), so filtering and
+        mips never pull a dark fringe into the edge."""
+        w, h = self.w, self.h
+        col = [None] * (w * h)
+        for i, p in enumerate(self.px):
+            if p[3] > 0:
+                col[i] = (p[0] / p[3], p[1] / p[3], p[2] / p[3])
+        for _ in range(8):
+            nxt = list(col)
+            changed = False
+            for y in range(h):
+                for x in range(w):
+                    i = y * w + x
+                    if col[i] is not None:
+                        continue
+                    for dx, dy in ((1, 0), (-1, 0), (0, 1), (0, -1)):
+                        xx, yy = x + dx, y + dy
+                        if 0 <= xx < w and 0 <= yy < h and col[yy * w + xx] is not None:
+                            nxt[i] = col[yy * w + xx]
+                            changed = True
+                            break
+            col = nxt
+            if not changed:
+                break
+        rows = []
+        for y in range(h):
+            row = bytearray()
+            for x in range(w):
+                i = y * w + x
+                c = col[i] or (0.0, 0.0, 0.0)
+                a = self.px[i][3]
+                row += bytes([round(min(1, max(0, c[0])) * 255), round(min(1, max(0, c[1])) * 255),
+                              round(min(1, max(0, c[2])) * 255), round(min(1, max(0, a)) * 255)])
+            rows.append(bytes(row))
+        return rows
+
+
+def png_bytes(w, h, rows):
+    raw = b"".join(b"\x00" + r for r in rows)
+
+    def chunk(t, d):
+        return struct.pack(">I", len(d)) + t + d + struct.pack(">I", zlib.crc32(t + d) & 0xFFFFFFFF)
+
+    return (b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", struct.pack(">IIBBBBB", w, h, 8, 6, 0, 0, 0))
+            + chunk(b"IDAT", zlib.compress(raw, 9)) + chunk(b"IEND", b""))
+
+
+def write_glb(path, sprites):
+    """sprites: list of (name, png bytes, masked). One quad mesh per sprite,
+    in list order: GltfInfo.geometries[i] and materials[i] are sprite i."""
+    bin_ = bytearray()
+
+    def add(data, align=4):
+        while len(bin_) % align:
+            bin_.append(0)
+        off = len(bin_)
+        bin_.extend(data)
+        return off, len(data)
+
+    pos = struct.pack("<12f", -0.5, -0.5, 0, 0.5, -0.5, 0, 0.5, 0.5, 0, -0.5, 0.5, 0)
+    nrm = struct.pack("<12f", *([0, 0, 1] * 4))
+    uv = struct.pack("<8f", 0, 1, 1, 1, 1, 0, 0, 0)
+    idx = struct.pack("<6H", 0, 1, 2, 0, 2, 3)
+    views, accessors = [], []
+    for data, target in ((pos, 34962), (nrm, 34962), (uv, 34962), (idx, 34963)):
+        o, n = add(data)
+        views.append({"buffer": 0, "byteOffset": o, "byteLength": n, "target": target})
+    accessors = [
+        {"bufferView": 0, "componentType": 5126, "count": 4, "type": "VEC3", "min": [-0.5, -0.5, 0], "max": [0.5, 0.5, 0]},
+        {"bufferView": 1, "componentType": 5126, "count": 4, "type": "VEC3"},
+        {"bufferView": 2, "componentType": 5126, "count": 4, "type": "VEC2"},
+        {"bufferView": 3, "componentType": 5123, "count": 6, "type": "SCALAR"},
+    ]
+    images, textures, materials, meshes, nodes = [], [], [], [], []
+    for i, (name, data, masked) in enumerate(sprites):
+        o, n = add(data)
+        views.append({"buffer": 0, "byteOffset": o, "byteLength": n})
+        images.append({"bufferView": len(views) - 1, "mimeType": "image/png", "name": name})
+        textures.append({"source": i, "sampler": 0})
+        m = {
+            "name": name,
+            "pbrMetallicRoughness": {"baseColorFactor": [0, 0, 0, 1], "baseColorTexture": {"index": i},
+                                     "metallicFactor": 0, "roughnessFactor": 1},
+            "emissiveTexture": {"index": i},
+            "emissiveFactor": [1, 1, 1],
+        }
+        if masked:
+            m["alphaMode"] = "MASK"
+            m["alphaCutoff"] = 0.5
+        materials.append(m)
+        meshes.append({"name": name, "primitives": [{"attributes": {"POSITION": 0, "NORMAL": 1, "TEXCOORD_0": 2},
+                                                     "indices": 3, "material": i}]})
+        nodes.append({"name": name, "mesh": i, "translation": [i * 1.2, 0, 0]})
+    while len(bin_) % 4:
+        bin_.append(0)
+    doc = {
+        "asset": {"version": "2.0", "generator": "oglite.py"},
+        "scene": 0, "scenes": [{"nodes": list(range(len(nodes)))}], "nodes": nodes, "meshes": meshes,
+        "materials": materials, "textures": textures, "images": images,
+        "samplers": [{"magFilter": 9729, "minFilter": 9987, "wrapS": 33071, "wrapT": 33071}],
+        "accessors": accessors, "bufferViews": views, "buffers": [{"byteLength": len(bin_)}],
+    }
+    js = json.dumps(doc, separators=(",", ":")).encode()
+    while len(js) % 4:
+        js += b" "
+    out = struct.pack("<III", 0x46546C67, 2, 12 + 8 + len(js) + 8 + len(bin_))
+    out += struct.pack("<II", len(js), 0x4E4F534A) + js + struct.pack("<II", len(bin_), 0x004E4942) + bytes(bin_)
+    with open(path, "wb") as f:
+        f.write(out)
+
+
+def write_wav(path, samples, rate=22050):
+    """samples: floats in [-1, 1], mono."""
+    with wave.open(path, "wb") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(rate)
+        w.writeframes(b"".join(struct.pack("<h", int(max(-1, min(1, s)) * 32000)) for s in samples))
+
+
+def tone(seconds, f0, f1=None, rate=22050, shape="sine", attack=0.005, decay=None, gain=0.6):
+    """A sweep from f0 to f1 Hz with a short attack and an exponential decay."""
+    f1 = f0 if f1 is None else f1
+    n = int(seconds * rate)
+    out, phase = [], 0.0
+    decay = decay or seconds / 4
+    for i in range(n):
+        t = i / rate
+        f = f0 + (f1 - f0) * (i / max(1, n - 1))
+        phase += 2 * math.pi * f / rate
+        if shape == "square":
+            s = 1.0 if math.sin(phase) >= 0 else -1.0
+            s *= 0.5
+        elif shape == "tri":
+            s = 2 / math.pi * math.asin(math.sin(phase))
+        else:
+            s = math.sin(phase)
+        env = min(1.0, t / attack) * math.exp(-t / decay)
+        out.append(s * env * gain)
+    return out
+
+
+def noise(seconds, rate=22050, decay=0.08, gain=0.5, seed=1):
+    x = seed & 0xFFFFFFFF
+    out = []
+    for i in range(int(seconds * rate)):
+        x ^= (x << 13) & 0xFFFFFFFF; x ^= x >> 17; x ^= (x << 5) & 0xFFFFFFFF
+        out.append(((x / 0xFFFFFFFF) * 2 - 1) * math.exp(-(i / rate) / decay) * gain)
+    return out
+
+
+def mix(*parts):
+    n = max(len(p) for p in parts)
+    return [sum(p[i] for p in parts if i < len(p)) for i in range(n)]
+
+
+def concat(*parts):
+    out = []
+    for p in parts:
+        out.extend(p)
+    return out
+
+
+def subset_font(src, dst, text):
+    """Subset a TTF to Latin-1 plus `text` (needs fontTools)."""
+    from fontTools import subset
+    opts = subset.Options()
+    opts.name_IDs = ["*"]
+    opts.notdef_outline = True
+    opts.layout_features = []
+    font = subset.load_font(src, opts)
+    s = subset.Subsetter(opts)
+    s.populate(text="".join(chr(c) for c in range(0x20, 0x7F)) + "".join(chr(c) for c in range(0xA0, 0x100)) + text)
+    s.subset(font)
+    subset.save_font(font, dst, opts)

package/archetypes/idle/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "types": [],
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noFallthroughCasesInSwitch": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts", "host.d.ts"]
+}

package/archetypes/match3/.origin/setup

@@ -0,0 +1,14 @@
+#!/bin/sh
+# Prepares this Game's cloud sandbox snapshot: Origin runs it once per
+# snapshot build, in the checkout, without a terminal, for at most 20 minutes,
+# and saves the result for new sandboxes of the Game. Keep it idempotent; it
+# never receives credentials. Only ignored output is kept: node_modules/ and
+# cooked/ (og cook is incremental, so a new sandbox starts cooked).
+set -eu
+if [ -f bun.lock ]; then bun install --frozen-lockfile; else bun install; fi
+og="${ORIGIN_OG_BIN:-og}"
+if ! command -v "$og" >/dev/null 2>&1; then
+  echo "no og on this executor class; the first og run cooks instead"
+  exit 0
+fi
+"$og" cook .

package/archetypes/match3/LICENSES.md

@@ -0,0 +1,7 @@
+# Asset licences
+
+| File | Licence | Origin |
+|---|---|---|
+| `assets/sprites/*` | CC0 1.0 | self-made: the gem flipbook, the panel, the backdrop, the frame and the checker tileset and map, drawn from vector shapes by `tools/make-assets.py` (standard library only, deterministic) |
+| `assets/audio/*.wav` | CC0 1.0 | self-made: synthesised tones and noise, same script |
+| `assets/fonts/ui.ttf` | SIL Open Font License 1.1 (`assets/fonts/OFL.txt`) | Noto Sans SC Regular, subset to Latin-1 and the HUD's characters by the same script from the project template's `assets/fonts/NotoSansSC-Regular-subset.ttf` |

package/archetypes/match3/README.md

@@ -0,0 +1,205 @@
+# Tile Swap — the match3 archetype
+
+Swap two neighbouring gems to make a line of three or more of one colour.
+Lines clear, the gems above fall, new gems drop in, and any line the fall
+makes clears again as a cascade worth more. Reach the target score before
+the moves run out.
+
+三消：交换相邻的两块方块，连成三个或更多同色即可消除；上方方块落下、新方块补入，下落时连成的线会再次消除（连锁得分更高）。在步数用完前达到目标分数即胜利。
+
+A complete Origin Engine project: `og run .`, `og test .`, `og build .`.
+It replaces the platform's Godot Discover match3 (Lantern Swap) and keeps
+its feel (one thumb, a swap that makes nothing is free, cascades as the
+reward, a move budget instead of a clock), not its code, art or lanterns.
+
+It is also the engine's 2D and game-feel showcase for a puzzle game:
+
+- **Sprites and flipbooks.** Every gem is an `og.Sprite` playing an
+  `og.Flipbook` clip from one sheet (`assets/sprites/gems.ogt`): an idle
+  loop that holds 2.4 s and then glints, each gem seeked to its own moment,
+  and a `once` burst when it clears.
+- **Nine-slice and a tilemap.** The board's backing is a nine-sliced
+  `og.Sprite` panel; the checker under the gems is a hand-written 7 × 7
+  tilemap (`assets/sprites/board.ogt` over the `cells.ogt` tileset).
+- **Tweens drive the phases.** A swap slides with `cubicInOut` (a refused
+  one goes there and back as one yoyo), cleared gems squash to nothing and
+  fade, gems fall with `bounceOut`, column by column, and squash as they
+  land; new rounds pop in with `backOut`. Each phase waits for its tween
+  group's `og.TweenCompleted` (by tag), not for a tick count.
+- **Feel.** Every cleared group's score floats up from it
+  (`og.render.floatingText`, a gold crit on a cascade), the gems flash
+  before they burst, four or more in a group punch the camera in, a cascade
+  shakes it by its depth, a third cascade holds time for 3 ticks
+  (`og.time.hitStop`), and the selection frame breathes on a looping tween.
+
+```sh
+og run . --headless --commands "0.5:touch_move:640,700;0.5:touch_start;0.55:touch_end;1:screenshot:board.png;1.1:quit"
+og test .
+og build .
+```
+
+## What it demonstrates, and the skills it exercises
+
+A grid puzzle made of tweens: swaps, falls and refills as `og.tween` moves
+and sequences, squash on landing, a flash and floating score on a clear,
+hit stop, shake and punch growing with a cascade (og-feel §3–§7), taps and
+drags read on the tick they land (og-feel §1; og-game §7), a sound for every
+press, swap, clear, cascade, win and loss (og-audio §1), the board as data
+with a deterministic deal from og.Rng (og-core §2), and playtests that drive
+a known board through commands (og-build §1, §3). `og polish .`
+(2026-10-19): feel 100 (taste n/a: the HUD is screen-space text).
+
+
+## Rules
+
+- **Title.** The first tap (or Space/Enter) deals a round: `Tuning.moves`
+  moves, score 0. That tap does not also select.
+- **Swapping.** Tap a tile, then a neighbour; or press a tile and drag at
+  least 0.45 of a cell towards a neighbour. Tapping the selected tile again
+  deselects it; tapping a tile that is not a neighbour selects it instead.
+- **Lines.** After a swap, every horizontal or vertical run of three or more
+  of one colour is marked. No line: the tiles swap back and no move is
+  spent. Lines: one move is spent and the marked tiles fold away over
+  `Tuning.clearTicks`.
+- **Score.** Each cleared tile scores `Tuning.tileScore × chain`, where the
+  chain is 1 for the swap's own lines and rises by one for every cascade.
+- **Fall and refill.** Survivors fall to the bottom of their columns at
+  `Tuning.fallSpeed` cells/s; the cleared tiles come back above the board
+  with colours from the dice and fall in. Lines the fall makes clear again.
+- **End.** When the board settles: score ≥ `Tuning.target` wins; no moves
+  left loses; a board where no swap makes a line is dealt again (colours
+  only, `Match.shuffles` counts it). The end card holds 40 ticks, then a tap
+  deals the next round.
+
+Deals never contain a ready line and always contain a move. Every colour
+draw comes from `og.Rng`, so a seed (`project.ogt`, `og run --seed`) gives
+the same deals, refills and reshuffles on every host.
+
+## The world
+
+| Row | Count | Name | Drawn as |
+|---|---|---|---|
+| backdrop | 1 | `backdrop` | a soft lift of light behind the board (layer −30); around it the camera's background is the brand ink `#14161b` |
+| board | 1 | `board` (from `assets/scenes/main.ogt`) | the nine-sliced panel (layer −20) |
+| tiles | 49 | `tile-0` … `tile-48` (pool rows: a tile's cell is `Piece.col/row`, not its name) | gems: `og.Sprite` + `og.Flipbook` on the gem sheet (layer 0) |
+| selection frame | 1 | `cursor` | a rounded frame (layer 1) |
+
+Those 52 rows have `og.Transform`, `og.Sprite`, `og.Flipbook` (sheet 0, so
+unused, except on the gems) and:
+
+| Component | On | What it holds |
+|---|---|---|
+| `Piece` | every row | `kind`, a tile's `col`/`row` (0,0 is the bottom left), `colour` (−1 empty), `marked` |
+| `Match` | every row; **the board's is the authority** | `phase` (title, idle, swap, swapBack, clear, fall, won, lost), `phaseTicks`, `score`, `best`, `movesLeft`, `chain`, `maxChain`, `cleared`, `lastCleared`, `rounds`, `shuffles`, `selected`, `swapA`/`swapB`, the drag (`dragFrom`, `pressX/Y`), the view (`viewHeight`, `viewCentreY`), the pointer mapping Pick works out each tick (`pxPerM`, `screenX0/Y0`), `wait` (the tag of the tween group the phase waits for) and `font` (for the floating scores) |
+| `Tuning` | every row; **the board's is the authority** | the tunables below |
+| `Hud` | the board only | the font handle and the view's top |
+
+One more entity, `cells`, carries only the `og.Tilemap` of the checker
+(layer −10), placed by its top-left corner at the board's; no system sees
+it.
+
+`Match` and `Tuning` ride on every row for the same reason as in the
+runner: a system sees one query and cannot reach another entity or a game
+resource yet, and the swap, clear and fall need the round's state together
+with the tiles.
+
+`src/board.ts` is pure logic over a colour grid (lines, "is there a move",
+the deal, the board text format); `src/layout.ts` is the geometry. Neither
+touches the world, so systems, commands and playtests share them.
+
+## Systems (in tick order)
+
+| System | Reads | Writes | Job |
+|---|---|---|---|
+| `Flow` | `og.Input`, `Tuning` | `og.Rng`, `Match`, `Piece`, `og.Transform` | the title and end cards; a tap deals a round, the gems popping in on staggered tweens |
+| `Pick` | `og.Input`, `Piece` | `Match` | pointer → cell; tap-tap and drag start a swap; a `swap` command's request |
+| `Resolve` | `Tuning`, `og.TweenCompleted` | `og.Rng`, `Match`, `Piece`, `og.Transform` | starts the swap (or the refused yoyo), clear and fall tween groups and waits for each; marks, scores, collapses and refills; floating scores, flash, punch, shake and hit stop; cascade, win, lose, reshuffle |
+| `Animate` | `Match`, `Piece`, `Tuning` | `og.Sprite`, `og.Flipbook`, `og.Transform` | each gem's clip (idle or burst), visibility and fade-in at the top edge, the selected gem's pulse, the frame's cell; gems hidden on the title and dimmed under the end cards |
+| `Hud` | `Match`, `Hud`, `Tuning` | — | score, moves, target, best; cascade callout; title, win and lose cards |
+
+## Tunables (`Tuning`, on the board)
+
+| Field | Default | Range | Unit | What it changes |
+|---|---|---|---|---|
+| `moves` | 20 | 1–60 | moves | the budget of a round |
+| `target` | 1500 | 10–10000 | points | the score that wins |
+| `colours` | 5 | 3–6 | colours | fewer colours, more lines and cascades |
+| `tileScore` | 10 | 1–100 | points | per cleared tile, times the chain |
+| `swapTicks` | 8 | 1–30 | ticks | the swap tween's length (a refused swap takes it twice) |
+| `clearTicks` | 12 | 1–40 | ticks | the clear tween's length (squash and fade) |
+| `fallSpeed` | 14 | 2–60 | cells/s | a fall tween lasts 0.12 s plus its drop at this speed |
+
+Written in `assets/scenes/main.ogt` (the board's `Tuning` block), live with
+`set:board.Tuning.<field>=<value>` or Tune.
+
+## What a Maker changes first
+
+1. **Difficulty**: `moves`, `target` and `colours` in the scene's `Tuning`.
+2. **Scoring**: the score line in `Resolve`'s clear step (a bonus for lines
+   of four or five, for example).
+3. **The opening**: deal an authored first board with the `deal` command's
+   text format from `start`, so the first move teaches.
+4. **Look**: the gem cuts and colours, the glint and the burst frames in
+   `tools/make-assets.py` (six cuts, so colour is never the only cue), the
+   idle hold in the sheet it writes, then
+   `python3 tools/make-assets.py && og cook .`.
+5. **Feel**: the eases, durations and staggers in `Resolve` (`startClear`,
+   `collapse`), the punch, shake and hit-stop thresholds in `startClear`.
+6. **Size**: `SIZE` in `src/layout.ts` (the pools follow; regenerate the
+   tilemap in `tools/make-assets.py`'s `board_map`).
+
+## Commands (for scripts and agents)
+
+| Action | Does |
+|---|---|
+| `deal:<rows>` | lays out the board: 7 lines of 7 colour digits joined by `/`, the top row first; needs an idle board |
+| `swap:<col>,<row>:<col>,<row>` | swaps two neighbouring cells on the next tick, as two taps would |
+| `viewport:<desktop\|2x>` | reports the play surface as 640×360 CSS px at 2× (a high-DPR screen; the render target stays 1280×720), or the host's again |
+
+`facts` reports `phase`, `score`, `movesLeft`, `cleared`, `maxChain`,
+`best`, `rounds` and the pointer mapping. A cell's CSS pixel is
+`(x0 + x·pxPerM, y0 − y·pxPerM)` with `(x, y)` from `cellCentre` in
+`src/layout.ts`; at 1280×720 that is 60 px per metre around (640, 390).
+
+## Playtests (`og test .`)
+
+| File | Proves |
+|---|---|
+| `tests/swap.og.ts` | on an authored board, real taps: a swap that makes nothing goes back for free; the swap that makes a line clears it, spends a move, scores, and the fall cascades (chain 2, both lines scored); every system matches its rows |
+| `tests/hidpi.og.ts` | on a 2× surface (640×360 CSS px over the 1280×720 target) the pointer mapping is in CSS pixels and a tap lands on its cell |
+| `tests/drag.og.ts` | a drag shorter than half a cell does nothing; past it, the swap happens and clears |
+| `tests/endings.og.ts` | target 30: the first line wins; one move and an unreachable target: that move loses; a tap after the card deals the next round with the tuned moves; best kept |
+| `tests/frames.og.ts` | at 1280×720 the dealt board, the swap's line mid-clear (burst, squash, `+30`) and the cascade mid-clear (gold crit `+60`, shake) match `references/<tier>/` (og-tests' tolerance, `tests/frames.ts`); away from the board the frame is the brand ink |
+| `tests/replay.og.ts` | `runs: 2`: a refused swap and a cascading swap, stopped mid-fall, end on the same world hash in two fresh processes |
+
+Each one fails when its behaviour is broken (checked by charging refused
+swaps, removing cascades, dropping the drag threshold, shrinking the gems
+for the frames and a wall-clock fall delay for the replay). Record a tier's
+reference frames with `OG_FX_CAPTURE=1 og test .` (`references/metal/` is
+recorded; other tiers compare with it until they have their own).
+
+## Assets
+
+`python3 tools/make-assets.py` writes them all, byte for byte
+(`LICENSES.md`): `assets/sprites/gems.png` + `gems.ogt` (six rows of eight
+80 px frames: idle, three glint frames, four burst frames; clip `2c` is
+colour `c`'s idle loop, `2c + 1` its burst), `panel.png` (96 px, 32 px
+nine-slice insets), `backdrop.png`, `ring.png`, `cells.png` +
+`cells.ogt` + `board.ogt` (the tileset and the map, `kind pixel`), the
+sounds and the font subset. Then `og cook .`.
+
+The sounds play through one `og.AudioSource` voice each: Pick (a
+selection) and Resolve (a swap, a refused swap, a clear, a cascade, the win
+and the loss) set bits of the `Sounds` resource and Voices plays each once
+(`og polish` found the archetype silent; tests/sounds.og.ts holds it).
+
+## Known limits (engine gaps, not design)
+
+- Systems cannot read other entities or the camera (a game resource they
+  declare, `Sounds`, they can), so
+  `Match` and `Tuning` ride on every row, and `Pick` maps the pointer from
+  the view it set in `start` over `og.ui.viewport` (the play surface in
+  CSS pixels, as the pointer is).
+- The camera is set once in `start`; on the web the renderer is not
+  attached then, so the view assumes 16:9 and a portrait phone clips the
+  board's sides.

package/archetypes/match3/assets/fonts/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2014-2021 Adobe (http://www.adobe.com/), with Reserved Font Name 'Source'
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/archetypes/match3/assets/fonts/ui.ttf.ogt

@@ -0,0 +1,11 @@
+type import
+version 1
+---
+# Written by tools/make-assets.py: the atlas holds Latin-1 and the HUD's own
+# CJK characters (CHARS there); add a character to CHARS before showing it.
+font {
+  charset latin
+  chars "三消开始游戏点击或拖动交换相邻方块连成同色分数步数目标胜利失败再来一次剩余最高"
+  em_px 48
+  px_range 6
+}