@origingame/create-game 0.0.0-stage → 0.1.1

package/archetypes/roguelike/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/roguelike/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/runner/.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/runner/LICENSES.md

@@ -0,0 +1,10 @@
+# Asset licences
+
+| File | Licence | Origin |
+|---|---|---|
+| `assets/sprites/*.png`, `assets/sprites/*.ogt` | CC0 1.0 | self-made: the courier, coin, props and sky are drawn texel by texel by `tools/make-assets.py` (standard library only, deterministic), with their flipbook sheets and import settings |
+| `assets/tiles/city.png`, `assets/tiles/*.ogt` | CC0 1.0 | self-made: the city tileset, same script |
+| `assets/maps/*.ogt` | CC0 1.0 | self-made: the far, near and roof tilemaps, same script |
+| `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` |
+| `references/*/*.png` | CC0 1.0 | frames of this game recorded by `tests/frames.og.ts` |

package/archetypes/runner/README.md

@@ -0,0 +1,225 @@
+# Rooftop Run — the runner archetype (2D)
+
+A courier runs the night roofs on her own; the player decides every jump. A
+tap is a hop that clears a crate, a hold is a full jump that clears a fence,
+and coins hang where the arcs go. The run speeds up until a crash ends it;
+the score is the distance plus the coins.
+
+屋顶快跑：信使在夜晚的屋顶上自己奔跑，每一次起跳由你决定。点按小跳越过木箱，按住高跳越过路障，金币挂在跳跃的弧线上。速度越来越快，直到撞上障碍。
+
+This is a complete Origin Engine project: `og run .` plays it headless,
+`og build .` makes the play page, `og test .` runs its playtests. It
+replaces the platform's Godot Discover runner (Skyline Post) and keeps its
+feel (one thumb, tap for a hop, hold for a jump, pace that ramps), not its
+code, art or route.
+
+```sh
+og cook .                    # assets/ into cooked/ (og run and og build cook too)
+og run . --headless --commands "0.5:key_down:Space;0.55:key_up:Space;3:screenshot:play.png;3.1:quit"
+og test .                    # tests/*.og.ts through og run --headless --commands
+og build .                   # dist/: the play page for the browser
+```
+
+## What it demonstrates, and the skills it exercises
+
+A one-button 2D game end to end: og.PlatformerController with its designer
+units in a `Tuning` resource and its CharacterEvents driving the take-off
+stretch and landing squash (og-game §13; og-feel §5, §12), a scrolling world
+of flipbooks and parallax tile layers (og-game §8; og-feel §9–§11), coins
+with floating text, hit stop, shake and kick on a crash (og-feel §3, §4,
+§7), every action heard through one `Voices` system (og-audio §1), the best
+score and a leaderboard through og.platform's requests answered later
+(og-platform-sdk §1–§4), and playtests for jumps, tuning, records and a
+replay to one hash (og-build §1, §3). `og polish .` (2026-10-19): feel 99
+(taste n/a: the HUD is screen-space text, not og.ui).
+
+
+## Rules
+
+- **Title.** The city scrolls slowly; the first press (Space, ArrowUp, W, a
+  click or a touch) starts the run. That press does not also jump.
+- **Running.** The courier stays at x = −5 and the world scrolls left at the
+  run speed, which starts at `Tuning.speed` and ramps by `Tuning.speedRamp`
+  up to `Tuning.speedMax`. Every `Tuning.spawnInterval` seconds (×0.85–1.25
+  from the dice) a pattern enters from the right: a crate, a crate under an
+  arc of coins, a line of coins, and after 60 m a fence or a fence under a
+  high coin, and after 150 m two crates in a row.
+- **Jumping.** The courier's body is an `og.PlatformerController` that
+  never runs (the world scrolls past it) on a static roof collider: a press
+  jumps to `Tuning.jumpHeight` in `Tuning.timeToApex`, hanging a little at
+  the top (`apexGravity`) and coming down a little faster (`fallGravity`);
+  releasing while rising multiplies gravity by `jumpCut`. A two-tick tap is
+  the shortest hop (1.30 m) and clears a crate (0.7 m); only a full jump
+  (2.12 m) clears a fence (1.55 m). A press up to 0.1 s before landing jumps
+  on landing (the controller's buffer), and one 0.08 s after running off an
+  edge still jumps (its coyote time).
+- **Score.** `floor(distance) + coins × Tuning.coinValue`. Touching a crate or
+  a fence ends the round; the best score is kept for the session.
+- **Game over.** The card holds for 30 ticks, then a press starts the next
+  round at once.
+
+Everything is deterministic from the project seed (`project.ogt`, or
+`og run --seed`): the patterns come from `og.Rng`, the clock is the fixed
+tick, and the feel (tweens, flipbooks, hit stop, shake, floating text,
+afterimages) is engine world state, so the same script gives the same world
+hash on the native and the web host (`tests/replay.og.ts` runs it twice).
+
+## The world
+
+A night city in pixel art: every sheet is drawn texel by texel by
+`tools/make-assets.py`, imported as `kind pixel` (lossless, sampled
+nearest) and outlined in the brand ink `#14161b` so the silhouettes read
+on the dark sky. Layers, back to front:
+
+| Layer | What | Drawn by |
+|---|---|---|
+| −40 | the sky's colour bands | `og.Sprite` over `sprites/sky.png` |
+| −38, −36 | the moon, three clouds (drifting at 0.06 of the speed) | `og.Sprite` + `og.Flipbook` (`sprites/props.ogt`) |
+| −30 | the far skyline, antenna lights blinking | `og.Tilemap` of `maps/far.ogt`, parallax 0.15 |
+| −20 | the near buildings, warm windows (one goes on and off), a neon sign, a water tank | `og.Tilemap` of `maps/near.ogt`, parallax 0.45 |
+| −10 | the roof the courier runs on | `og.Tilemap` of `maps/roofs.ogt`, parallax 1 |
+| 0, 1 | crates and fences; coins (a 6-frame turn) and dust puffs | `og.Sprite` + `og.Flipbook` |
+| 2 | the courier (idle, run, jump, fall, crash) | `og.Sprite` + `og.Flipbook` (`sprites/courier.ogt`) + `og.Afterimage` |
+| 10, 100 | the HUD; "+10" | `og.render.text`; `og.render.floatingText` |
+
+The three city strips are text tilemaps (`.ogt` rows of legend
+characters: the script writes them, a person can edit them by hand) over one
+tileset (`tiles/city.ogt`, with its animated tiles) and draw with `repeat
+x`; the camera stays still, so each strip's entity scrolls left at the run
+speed times its parallax and jumps right by its own width, seamlessly. The
+crates, fences, coins and dust are pools (4, 3, 16 and 4) parked at
+x = −1000 until a pattern or a footfall puts them in play.
+
+| Component | On | What it holds |
+|---|---|---|
+| `Actor` | every row | `kind` (sky, moon, cloud, city, dust, runner, crate, fence, coin), `active` (collides), the hit box `w`×`h`, `parallax` (the share of the run speed a row scrolls at), `wrap` (the span scenery jumps right by), `vy` |
+| `Run` | every row; **the runner's is the authority** | `phase` (0 title, 1 running, 2 over), `phaseTicks`, `speed`, `distance`, `coins`, `score`, `best`, `rounds`, `spawnIn`, and the body's `grounded` (copied from the controller), `startHeld` (the starting press is not a jump) and `kick` (a speed Director or Collide gave the body) |
+| `Tuning` | every row; **the runner's is the authority** | the tunables below |
+| `Hud` | the runner only | the font handle and the visible area the HUD lays out in |
+
+The runner's position is its feet (the sheet's pivot is `0.5 0`), so a
+squash keeps them on the roof; its hit box is centred 0.8125 m above them.
+
+Why `Run` and `Tuning` sit on every row: a system sees exactly one query,
+the AND of what it declares, and inside a system the engine reaches no other
+entity and no game resource yet. So the systems that move obstacles and end
+the round must find the run's state on the same rows as the obstacles. The
+other rows' copies keep their defaults and nothing reads them. When the
+engine lets a system read another entity or a resource, `Run` and `Tuning`
+become a resource or the runner's alone and the systems keep their shape.
+
+## Systems (in tick order)
+
+| System | Reads | Writes | Job |
+|---|---|---|---|
+| `Director` | `og.Input`, `Tuning` | `Run`, `Actor`, `og.Transform`, `og.Sprite` | phases; the speed ramp, distance and score; a new round (pools retired, the courier stood up); a press during the card's hold answered by the hold tick |
+| `Jump` | `og.Input`, `Tuning`, `og.CharacterEvent` | `Run`, `Actor`, `og.PlatformerController` | the controller's jump held while the press is, its tunables from `Tuning`; its take-off (a stretch and the sound) and landing (a squash) events |
+| `Scroll` | `Run` | `Actor`, `og.Transform` | everything left at speed × parallax; scenery wraps by its span; pooled rows retire past x = −13 |
+| `Spawn` | `Tuning` | `og.Rng`, `Run`, `Actor`, `og.Transform`, `og.Sprite` | the next pattern at x = 13 from the dice |
+| `Collide` | `og.Transform`, `Tuning` | `Run`, `Actor` | coins collected ("+10" and the coin's pop), crashes (the crash's feel), the best score |
+| `Dust` | `og.FlipbookEvent`, `Run` | `Actor`, `og.Transform` | a dust puff at the feet on each `step` event of the run clip |
+| `Animate` | `Run`, `Actor`, `Tuning` | `og.Flipbook`, `og.Afterimage` | the courier's clip from the phase and the body, the run clip's pace from the speed, the afterimage near top speed |
+| `Hud` | `Run`, `Hud`, `Tuning` | — | the score line, the title card and the game-over card (`og.render.text`) |
+
+Motion reads `Time.scaledDt`, so a hit stop freezes the world while the
+camera still shakes. Spawning and retiring at fixed x (beyond the widest
+view) keeps the play surface's shape out of the simulation: a phone and a
+desktop see the same obstacles at the same ticks.
+
+## Feel (E4)
+
+| Moment | What happens | Where |
+|---|---|---|
+| running | an 8-frame run at 14 fps, faster with the speed (×0.8–1.6); `step` events on the footfalls kick up dust | `sprites/courier.ogt`, `Animate`, `Dust` |
+| take-off | stretch (0.78, 1.28), then the jump frame | `og.tween.squash` in `Jump` |
+| landing | squash (1.3, 0.72), recovering with `backOut` | `og.tween.squash` in `Jump` |
+| a coin | "+10" pops and rises; the coin grows, lifts and fades | `og.render.floatingText`, `og.tween.parallel` in `Collide` |
+| a crash | 8 ticks of hit stop, shake 0.5, a kick of the view, the courier knocked back 0.9 m and up, flashing red, the crash clip played once | `og.time.hitStop`, `og.camera.shake`/`kick`, tweens in `Collide` |
+| top speed | four mint ghosts trail the courier | `og.Afterimage` in `Animate` |
+
+The numbers are `FEEL` in `src/systems.ts`. None of them changes a rule:
+the playtests below hold with any of them.
+
+## Tunables (`Tuning`, on the runner)
+
+| Field | Default | Range | Unit | What it changes |
+|---|---|---|---|---|
+| `speed` | 6 | 3–12 | m/s | the pace a round starts at |
+| `speedRamp` | 0.12 | 0–1 | m/s² | how fast the pace rises (the cap after 50 s) |
+| `speedMax` | 12 | 4–20 | m/s | the top pace (and where the afterimage shows) |
+| `jumpHeight` | 2 | 0.5–6 | m | a held jump's height |
+| `timeToApex` | 0.333 | 0.15–1 | s | how long it takes to peak (with the height: gravity and take-off speed) |
+| `jumpCut` | 1.8 | 1–6 | × | gravity while rising with the press released: the hop's height |
+| `apexGravity` | 0.75 | 0.2–1 | × | gravity near the top of a held jump: the hang |
+| `fallGravity` | 1.15 | 1–3 | × | gravity on the way down: the landing's snap |
+| `spawnInterval` | 1.3 | 0.5–60 | s | the gap between patterns |
+| `coinValue` | 10 | 0–100 | points | what a coin adds (and the floating text shows) |
+
+They are written in `assets/scenes/main.ogt` (the runner's `Tuning` block)
+and live with `set:runner.Tuning.<field>=<value>` from the command channel
+or Tune. The hop and jump heights above were measured with `get:runner.og.Transform.position`
+through a tap and a hold; `tests/jump.og.ts` holds them against the obstacles.
+
+## What a Maker changes first
+
+1. **Feel**: `jumpHeight`, `timeToApex`, `jumpCut`, `apexGravity` and `fallGravity` in the scene's `Tuning`.
+   Keep the hop below the fence and above the crate (`tests/jump.og.ts`
+   checks exactly that). The juice is `FEEL` in `src/systems.ts`.
+2. **Pace**: `speed`, `speedRamp`, `speedMax`, `spawnInterval`.
+3. **What comes**: `placePattern` and the `top` gate in `Spawn`
+   (`src/systems.ts`): add a pattern, change when fences appear.
+4. **Look**: the pixel art and the city in `tools/make-assets.py`
+   (`courier`, `run_frame`, `tile`, `far_rows`, `near_rows`), then
+   `python3 tools/make-assets.py && og cook .`. A new courier clip goes in
+   `COURIER_OGT` there and `COURIER` in `src/art.ts` (which checks the
+   order). Re-record the reference frames afterwards (below).
+5. **Words**: the HUD strings in `Hud`. A CJK character must be in `CHARS`
+   of `tools/make-assets.py` (it writes `assets/fonts/ui.ttf.ogt`).
+
+## Commands (for scripts and agents)
+
+| Action | Does |
+|---|---|
+| `place:<crate\|fence\|coin>:<x>[:<y>]` | puts a pooled obstacle or coin in play at x (y defaults to its resting height) |
+| core actions | `key_down:Space`/`key_up:Space` (or `touch_start`/`touch_end`) jump; `set:runner.Tuning.<field>=<v>` tunes; `dump_entity:runner` shows `Run` |
+
+`facts` (the probe's `state()`) reports `phase`, `score`, `coins`,
+`distance`, `speed`, `best` and `rounds`.
+
+## Playtests (`og test .`)
+
+| File | Proves |
+|---|---|
+| `tests/flow.og.ts` | title → a press starts → an untouched crate ends the round → the card holds → a press starts round two from zero, best kept; every system matches its rows |
+| `tests/coins.og.ts` | a coin in reach is collected and adds `coinValue`; one hung at 3.2 m passes over a standing runner |
+| `tests/jump.og.ts` | a full jump clears a crate and a fence; a hop clears a crate and crashes into a fence |
+| `tests/tune.og.ts` | `set` writes `Tuning`: the start speed and the jump height follow |
+| `tests/frames.og.ts` | the title, a coin's pickup ("+10", the pop, dust) and the crash inside its hit stop (red flash, shake) match `references/<tier>/frames-*.png` under og-tests' tolerance (`tests/frames.ts`) |
+| `tests/replay.og.ts` | the same script of jumps, coins, a crash and a second round, run twice in fresh processes, ends on one world hash |
+
+Each one fails when the behaviour it names is broken (checked by breaking
+coin collection, the hop's minimum hold, the card's hold, the coin's
+floating text, the crash flash through the hit stop and the determinism of
+the dust). After a deliberate change to the look, re-record the frames:
+`OG_FX_CAPTURE=1 og test .` (a tier without its own references compares
+with `metal` and says so).
+
+## Assets
+
+`tools/make-assets.py` regenerates every asset byte for byte (sheets,
+tileset, maps, sounds, the font subset); `LICENSES.md` lists them. The
+sounds play through one `og.AudioSource` voice each: Director (a round
+starts, and a quiet tick, og sfx's `click` preset in `assets/audio/hold.ogt`,
+for a press while the game-over card holds), Jump and Collide (a coin, a
+crash) set bits of the `Sounds` resource and Voices plays each once
+(`og polish` found the archetype silent, no input answered by a sound;
+tests/sounds.og.ts holds it, and tests/flow.og.ts the held press's tick).
+
+## Known limits
+
+- Systems cannot read other entities (hence `Run` and `Tuning` on every
+  row; a game resource they declare, `Sounds`, they can) and cannot spawn (hence the pools, the dust's
+  included); the camera stays still and the world scrolls.
+- The view's size is read once in `start`; on the web the renderer is not
+  attached yet then, so the layout assumes 16:9 and a portrait phone sees a
+  narrow slice of the roofs.

package/archetypes/runner/assets/audio/hold.ogt

@@ -0,0 +1,9 @@
+type sfx
+version 1
+---
+# a tiny tick: a press while the game-over card holds is heard, not ignored.
+preset "click"
+seed 0
+pitch 1
+length 1
+volume 1

package/archetypes/runner/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.