@origingame/create-game 0.0.0-stage → 0.1.0

package/archetypes/topdown/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/topdown/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/tower-defense/.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/tower-defense/LICENSES.md

@@ -0,0 +1,15 @@
+# Asset licences
+
+| File | Licence | Origin |
+|---|---|---|
+| `assets/tiles/garden.png`, `assets/tiles/*.ogt` | CC0 1.0 | self-made: the night garden's tileset (grass, hedge, stone, gate, doorstep, pads, flowers) drawn with antialiased shapes by `tools/make-assets.py` (standard library only, deterministic), with its tileset and import settings |
+| `assets/maps/garden.ogt` | CC0 1.0 | self-made: the 9 × 13 field, same script |
+| `assets/sprites/*.png`, `assets/sprites/*.ogt` | CC0 1.0 | self-made: the visitors, plants, lantern, shots and cursor sheet, the range ring, the spark and the glow, same script |
+| `assets/fx/*.ogt` | CC0 1.0 | self-made: the pop and fireflies emitters, same script |
+| `assets/ai/plant.ogt` | CC0 1.0 | self-made: the plants' behaviour |
+| `assets/audio/*.wav` | CC0 1.0 | self-made: synthesised tones, noise and the night music loop, same script |
+| `assets/audio/*.ogt` | CC0 1.0 | `og sfx` presets (click, select, back, error, levelup) that `og cook` synthesises, written by the same script |
+| `assets/strings/*.ogt` | CC0 1.0 | self-made: the English and Chinese string tables |
+| `assets/fonts/NotoSansSC-subset.ttf` | SIL Open Font License 1.1 (`assets/fonts/OFL.txt`) | Noto Sans SC Regular, subset to Latin-1 and the characters of `assets/strings/zh-CN.ogt` by the same script from the project template's `assets/fonts/NotoSansSC-Regular-subset.ttf` |
+| `assets/skins/pathguard/*` | CC0 1.0 art, SIL OFL 1.1 fonts | the engine's cartoon style pack (`templates/ui-kit/assets/skins/cartoon`, `assets/skins/pathguard/LICENSES.md`) with this game's palette |
+| `references/*/*.png` | CC0 1.0 | frames of this game recorded by `tests/frames.og.ts` |

package/archetypes/tower-defense/README.md

@@ -0,0 +1,240 @@
+# Path Guard — the tower-defense archetype (2D)
+
+A night garden. Visitors (beetles, moths, snails) come through the gate in
+the hedge and walk to the lantern on the doorstep; you set plants on the
+lawn to turn them away. Thorns shoot, frost lilies slow, hedges only block,
+and every plant re-routes the visitors, who always take the shortest way
+round what stands on the lawn. Five waves; the lantern's light is gone
+after ten visitors get through.
+
+小径守卫：夜里的花园，甲虫、飞蛾和蜗牛从树篱的门进来，走向门口台阶上的灯笼。在草地上种植物把它们劝走：荆棘射击，霜百合减速，树篱只挡路；每种下一株，来客都会绕开它重新找最短的路。五波来客，有十个走到门口，灯就灭了。
+
+This is a complete Origin Engine project: `og run .` plays it headless,
+`og build .` makes the play page, `og test .` runs its playtests and
+`og polish .` scores them. It rebuilds the platform's retired Discover
+prototype *Bloomguard* (花园守夜人) on the engine: its night garden, its
+three plant roles (one shoots, one supports, one walls) and its lesson that
+a kill's time must scale with the walk's, but as a mazing defence on a
+flow field rather than lanes, and none of its code or art.
+
+```sh
+og cook .                    # assets/ into cooked/ (og run and og build cook too)
+og run . --headless --commands "0.3:begin;0.5:plant:thorn:3:4;0.5:plant:hedge:4:4;6:screenshot:wave.png;6.1:quit"
+og test .                    # tests/*.og.ts through og run --headless --commands
+og polish .                  # the playtests scored against og-taste and og-feel
+og build . --publish         # dist/: the play page as it ships
+```
+
+## What it demonstrates, and the skills it exercises
+
+- **Crowds on a flow field** (og-ai §1, §2): one `og.nav.flowField` over a
+  grid made from the map's colliding layer (`og.nav.gridFromTilemap`)
+  serves every visitor; each `og.NavAgent` follows it to the doorstep with
+  `faceMovement` turning the sprite. A plant is `og.nav.setCost(…, 0)` on
+  its cell and the field rebuilds; a plant that would close the path for
+  the gate or any visitor on the lawn is found with `og.nav.findPath` and
+  refused before it costs anything.
+- **Targeting as data** (og-ai §3, §4): a shooting plant is an `og.AiAgent`
+  running `assets/ai/plant.ogt` (set, reloaded, sees a visitor → the
+  game's `fire` command) with an `og.Perception` of its range all round;
+  the visitors are `og.Perceivable`. Damage, frost and the shot stay in the
+  game (`fire` in `src/systems.ts`).
+- **Towers on a tilemap** (og-game §8): `assets/maps/garden.ogt` is a
+  hand-written tilemap whose `walls` layer collides; the `pads` layer starts
+  empty and `og.tilemap.setTile` writes the plant's pad on its cell, so the
+  map itself remembers what grows where.
+- **Waves and an economy**: five waves of visitors in data (`WAVES`), a
+  break between them that an early call (N, Y, or the Next wave button)
+  turns into coins, bounties, a wave bonus, prices in `Tuning`.
+- **Shots on tweens** (og-feel §6): a shot is a pooled sprite on an
+  `og.tween.sequence` whose `tag` names the target's pool slot and the
+  plant's kind; the hit lands on the tick `og.TweenCompleted` reports it.
+- **Feel** (og-feel §3–§7): a pop is a coin count (`og.render.floatingText`),
+  a burst of petals (`og.ParticleSystem` with `startTick`), a pitch-varied
+  sound and a light hit stop at most every 10 ticks; a visitor at the
+  doorstep is a red number, a 6-tick hit stop, trauma and a kick, the
+  lantern flashing red and squashing. Plants pop up when set and squash
+  when they shoot.
+- **Screens on og.ui with a skin** (og-ui §2–§6, og-taste §1–§7): the
+  engine's cartoon pack recoloured as `assets/skins/pathguard` (cream
+  panels on the night lawn, the lantern's orange as the one accent); the
+  title (`og.ui.mainMenu`), the HUD as capsules in the corners with
+  counting numbers (`og.ui.counter`), the plant tray (right on a wide
+  screen, along the bottom on a phone), `og.ui.pauseMenu`, a settings
+  dialog and the end card built from widgets (stars landing with
+  `og.ui.burst`, the score counting up), an iris between screens (a fade
+  with reduced motion), a refused plant shaking the purse with the error
+  sound (`og.ui.shake`).
+- **Sound** (og-audio §1–§5): a voice per event, the UI's sounds from
+  `og sfx` presets, a night music loop on the music bus ducked under the
+  effects (`og.AudioBusFx`).
+- **Languages** (og-i18n §1–§5): every string is a key of
+  `assets/strings/en.ogt` and `zh-CN.ogt`; the settings switch with
+  `og.i18n.setLocale`; the Chinese font is Noto Sans SC subset to exactly
+  the table's characters.
+- **The platform** (og-platform-sdk §1–§4): settings through
+  `loadSettings`/`saveSettings`, the best score read on tick 0 and written
+  at the revision read, the board and a `round.over` event.
+
+`og polish .` (2026-10-19, og and the native addon built release from
+this checkout, load 16–18): taste 99, feel 100, in
+`tests/evidence/P2/archetypes/tower-defense/` of the engine repository.
+The same playtests at load 25–50 scored feel 80–89, frame time's p95
+following the machine's load (`tests/evidence/P2/archetypes/frame-time.md`).
+
+## Rules
+
+- **Plants.** Pick one on the tray (or 1, 2, 3; the pad's X cycles), then
+  tap a lawn cell (or move the cursor with the arrows, WASD or the d-pad
+  and press Space, Enter or A). It costs its price at once and stands
+  until the round ends.
+
+  | Plant | Price | Does |
+  |---|---|---|
+  | Thorn | 50 | shoots the nearest visitor within 2.8 m: 14 every 30 ticks |
+  | Frost lily | 70 | shoots the nearest within 2.2 m: 5 every 60 ticks, and frosts it to half speed for 2 s |
+  | Hedge | 10 | blocks the cell: the maze's wall |
+
+- **Refusals.** A cell inside the hedge that is not a stone and holds no
+  plant and no visitor takes a plant, if the purse covers it and the gate
+  and every visitor can still reach the doorstep. Otherwise nothing is
+  spent; a red line says why and the purse shakes.
+- **Visitors.** They walk the flow field to the doorstep. Beetles (34 hp,
+  1.3 m/s, 6 coins), moths (22 hp, 2.1 m/s, 5 coins), snails (140 hp,
+  0.75 m/s, 20 coins, three lights). Each wave's are 20 % tougher than the
+  last's.
+- **Waves.** The first comes 3 s after Play; then a wave comes after the
+  last one's visitors are all gone and an 8 s break. Calling it early pays
+  2 coins a second saved. A wave cleared pays 20 + 5 × its number.
+- **The end.** Ten lights gone ends the round lost; the fifth wave cleared
+  ends it won, with one to three stars by the light left. The score is
+  kills × 10 + light × 50 + coins left.
+
+Everything is deterministic from the project seed: the clock is the fixed
+tick, og.nav, og.ai, tweens and particles are deterministic and in
+snapshots, and `tests/replay.og.ts` replays a round to the same hash.
+
+## How it feels
+
+| Moment | What happens | Where |
+|---|---|---|
+| a plant set | it pops up (squash 0.6 × 1.5 over 0.25 s), a wooden thunk on the ui bus | `Plants`, `place` |
+| a refusal | a red line over the cell, the purse shakes with the error sound | `place`, `hud` |
+| a shot | the plant's shooting frame and a 1.15 × 0.85 squash, a pitch-varied pluck or chime | `fire` |
+| a hit | the visitor flashes white for 0.08 s; frost tints it blue and slows its legs | `Visitors` |
+| a pop | `+6` in gold rising, a burst of petals, a pop, a 2-tick hit stop (at most one per 10 ticks) | `pop` |
+| a leak | `-1` in red at the lantern, a 6-tick hit stop, trauma 0.4 and a kick down, the lantern flashes red and squashes, a low bell | `leak` |
+| a wave | `Wave 3` over the gate, a horn; cleared: `Wave cleared +35` and an arpeggio | `startWave`, `Visitors` |
+| the end | an iris to the end card, stars landing one by one with bursts, the score counting up | `endCard` |
+
+## State
+
+| Type | Kind | What it holds |
+|---|---|---|
+| `Game` | resource | the phase, the light, the purse, the wave clock, the counts (kills, leaks, plants, refusals, shots), the cursor, the score and the best, the cells visitors stand on, sound requests, the grid, field and map handles |
+| `Tuning` | resource | the knobs below |
+| `Prefs` | resource | the volumes, the language, reduced motion, the settings request |
+| `Bed` | one row per lawn cell | whether a plant stands there, its kind, its reload, its shots |
+| `Visitor` | the 24 pooled visitors | slot, kind, health, speed, frost, the pop |
+| `Shot` | the 24 pooled shots | the tween carrying it |
+| `Cursor` | the cursor | its moves |
+| `Sfx` | one row per sound | its `Sound.*` bit, its plays |
+
+## Systems (in tick order)
+
+| System | Job |
+|---|---|
+| `Control` | the cursor, the tray keys, placements by key, pad and tap, the next wave, pause; draws the cursor and the range |
+| `Plants` | switches on the rows of cells planted this tick (the pads tile names the plant), reloads, sight from `Tuning`, the shooting clip back to the sway; clears the rows for a new round |
+| `Visitors` | the wave clock and the gate, shots landing (`og.TweenCompleted`), frost, health bars, pops, leaks, the cells visitors stand on, the end of a wave and of the round |
+| `Ui` | the screens, the camera framed for the surface, the buses, the platform's answers |
+| `Voices` | plays each requested sound once |
+
+og.ai runs before them (the plants' decisions, whose `fire` commands run
+before the next tick) and og.nav after them (walking the visitors).
+
+## Tunables (`Tuning`)
+
+| Field | Default | What it changes |
+|---|---|---|
+| `startGold`, `startLives` | 150, 10 | the purse and the light at Play |
+| `waveBreak`, `spawnGap` | 8 s, 1 s | the break between waves, the gap between visitors |
+| `hpGrowth` | 0.2 | how much tougher each wave's visitors are |
+| `thornCost`, `thornDamage`, `thornReload`, `thornRange` | 50, 14, 30 ticks, 2.8 m | the thorn |
+| `frostCost`, `frostDamage`, `frostReload`, `frostRange`, `frostSlow`, `frostTicks` | 70, 5, 60 ticks, 2.2 m, 0.5, 120 ticks | the frost lily |
+| `hedgeCost` | 10 | the hedge |
+| `shotSpeed` | 11 m/s | how fast shots fly (so how far they lead their targets) |
+| `killStop`, `leakStop`, `leakShake` | 2, 6 ticks, 0.4 | the weight of a pop and of a leak |
+
+The visitors' numbers are `KINDS` and the waves `WAVES` in `src/systems.ts`.
+
+## What a Maker changes first
+
+1. **The waves**: `WAVES` (one letter per visitor: b, m, s) and `KINDS`.
+2. **The plants**: their numbers in `Tuning`; a fourth plant is a clip in
+   `tools/make-assets.py`, a pad tile, a `PLANTS` entry and a case in
+   `fire`.
+3. **The field**: `MAP` in `tools/make-assets.py` (H hedge, R stone, G the
+   gate, D the doorstep), then `python3 tools/make-assets.py && og cook .`.
+4. **The look**: `assets/skins/pathguard/skin.ogt`'s palette and the art
+   in `tools/make-assets.py`.
+5. **Words**: `assets/strings/*.ogt`; a new Chinese string needs the
+   script run again to subset the font.
+
+## Commands (for scripts and agents)
+
+| Action | Does |
+|---|---|
+| `begin` | starts a round, as Play does |
+| `plant:<thorn\|frost\|hedge>:<x>:<y>` | sets a plant on a map cell (column, row from the top) as a placement does, refusals included |
+| `gold:<n>` | sets the purse |
+| `wave:<n>` | skips to the break before wave n |
+| `lose`, `win` | puts the lantern out; ends the round won |
+| `viewport:<desktop\|phone>` | lays the UI out for a phone in portrait (390 × 844 at 3×) |
+| `language:<en\|zh-CN>` | switches the language |
+| `fire:<plant>` | the plants' behaviour command (og.ai sends it) |
+| core actions | `touch_move_to:play`, `Plant#1/Pick`, `Next`, `Pause`, `Retry`, `Menu`; keys `1`–`3`, arrows, `Space`, `N`, `Escape`; `gamepad:a` … |
+
+`facts` (the probe's `state()`) reports the phase, the wave, the light
+(`lives`), the purse, `kills`, `leaks`, `placed`, `refused` and why, `shots`,
+the visitors walking, the selected plant, the cursor, the score and the
+best, and the language. The playtests read the same values from the `Game`
+resource with `get:Game`.
+
+## Playtests (`og test .`)
+
+| File | Proves |
+|---|---|
+| `tests/flow.og.ts` | Play by tap; a hedge picked on the tray and tapped onto the lawn; two thorns set by keys; the first wave walks the field at a beetle's pace, is shot and pays its bounties |
+| `tests/maze.og.ts` | a row of hedges leaves one gap and the first visitor crosses through it only; a hedge closing the gap, a stone, a taken cell and an empty purse are refused and cost nothing |
+| `tests/lose.og.ts` | unguarded, visitors reach the doorstep, the light runs out, the end card, Play again starts round two with the light back |
+| `tests/win.og.ts` | a stand holds the last wave called early with N; the win, the score, the best written at the revision read, the board, the telemetry, Title |
+| `tests/pause.og.ts` | Escape holds the garden (time scale 0); settings switch to 简体中文 and move the music; Done saves through og.platform; Resume |
+| `tests/pad.og.ts` | a gamepad alone starts, moves, plants, picks, calls, pauses and resumes |
+| `tests/phone.og.ts` | 390 × 844 at 3×: the tray along the bottom with touch-sized buttons inside the safe area, the pause button below the notch |
+| `tests/frames.og.ts` | the title, a wave in a small maze and the end card match `references/<tier>/` (`OG_FX_CAPTURE=1 og test .` records them) |
+| `tests/replay.og.ts` | a round with taps, keys, shots, frost and pops, run twice, ends on one hash |
+
+Each one fails when the behaviour it names is broken (one was broken on
+purpose and restored: `tests/evidence/P2/archetypes/break-and-restore.md`
+in the engine repository).
+
+## Assets
+
+`tools/make-assets.py` regenerates every asset byte for byte (two runs
+give the same bytes): the tileset, the map, the sprite sheet, the glow and
+particle textures and emitters, the sounds and the music, the `og sfx`
+preset files of the UI's sounds, and the font subset. `LICENSES.md` lists
+them; the skin's are in `assets/skins/pathguard/LICENSES.md`.
+
+## Known limits (engine gaps, not design)
+
+- og.ui's `settingsScreen` and `resultsScreen` carried English labels of
+  their own ("Master", "Done", "Best", "New best") when this game was
+  written, so it builds its settings dialog and its end card from widgets to
+  keep every string in its tables (both now take a field for each of their
+  words: og-i18n §2).
+- A system may only `world.get`/`world.set` the components its query
+  declares, and declaring one narrows the query, so a placement is written
+  to the map's pads layer and the `Plants` system, which owns the plant
+  rows, switches the row on in the same tick.

package/archetypes/tower-defense/assets/ai/plant.ogt

@@ -0,0 +1,16 @@
+type behaviour
+version 1
+---
+# A shooting plant's mind (og.ai): when it is set, reloaded and sees a
+# visitor (og.Perception: the nearest within its range), it raises the
+# game's `fire` command with its own handle. Damage, frost and the shot are
+# the game's (src/systems.ts `fire`); the reload is the plant's Bed.cool.
+name "plant"
+tree {
+  sequence shoot {
+    check Bed.planted
+    check Bed.cool atMost 0
+    check sees
+    command fire
+  }
+}

package/archetypes/tower-defense/assets/audio/ui-close.ogt

@@ -0,0 +1,9 @@
+type sfx
+version 1
+---
+# og sfx's "back" preset, synthesised by og cook (the UI's close sound).
+preset "back"
+seed 0
+pitch 1
+length 1
+volume 0.8

package/archetypes/tower-defense/assets/audio/ui-error.ogt

@@ -0,0 +1,9 @@
+type sfx
+version 1
+---
+# og sfx's "error" preset, synthesised by og cook (the UI's error sound).
+preset "error"
+seed 0
+pitch 1
+length 1
+volume 0.8

package/archetypes/tower-defense/assets/audio/ui-open.ogt

@@ -0,0 +1,9 @@
+type sfx
+version 1
+---
+# og sfx's "select" preset, synthesised by og cook (the UI's open sound).
+preset "select"
+seed 0
+pitch 1
+length 1
+volume 0.8

package/archetypes/tower-defense/assets/audio/ui-press.ogt

@@ -0,0 +1,9 @@
+type sfx
+version 1
+---
+# og sfx's "click" preset, synthesised by og cook (the UI's press sound).
+preset "click"
+seed 0
+pitch 1
+length 1
+volume 0.8

package/archetypes/tower-defense/assets/audio/ui-success.ogt

@@ -0,0 +1,9 @@
+type sfx
+version 1
+---
+# og sfx's "levelup" preset, synthesised by og cook (the UI's success sound).
+preset "levelup"
+seed 0
+pitch 1
+length 1
+volume 0.8