@origingame/create-game 0.0.0-stage → 0.1.0

package/archetypes/third-person/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/third-person/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/topdown/.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/topdown/LICENSES.md

@@ -0,0 +1,10 @@
+# Asset licences
+
+| File | Licence | Origin |
+|---|---|---|
+| `assets/tiles/dungeon.png`, `assets/tiles/*.ogt` | CC0 1.0 | self-made: the dungeon tileset (the wall terrain's 47 blob shapes, floor, moss, torch, door) drawn pixel by pixel by `tools/make-assets.py` (standard library only, deterministic), with its tileset and import settings |
+| `assets/maps/tomb.tmj` | CC0 1.0 | self-made: the two-room Tiled map, same script |
+| `assets/sprites/*.png`, `assets/sprites/*.ogt` | CC0 1.0 | self-made: the hero, slime, coin and key flipbook sheets, 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 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/topdown/README.md

@@ -0,0 +1,235 @@
+# Tomb Room — the topdown archetype (2D)
+
+A small Zelda-like. Two rooms of a tomb: a slime guards the west room and
+the key in it, coins lie in both, and a locked door stands between them.
+Walk with WASD or the arrows, swing the sword with Space, dash with Shift.
+Take the key to the door and the east room opens.
+
+古墓房间：一个小型俯视角冒险。西边的房间里有史莱姆守着钥匙，两个房间都散落着金币，中间是一扇锁着的门。WASD 或方向键移动，空格挥剑，Shift 冲刺；拿到钥匙走到门前，东边的房间就打开了。
+
+This is a complete Origin Engine project: `og run .` plays it headless,
+`og build .` makes the play page, `og test .` runs its playtests. It shows
+the 2D modules working together: a Tiled map with an auto-tiled, colliding
+wall terrain; flipbook sprites with frame events; y-sorted sprites with
+blob shadows; tweens, hit stop, camera trauma and kick, floating damage
+numbers and afterimages; a 2D follow camera held inside each room by a
+camera zone; and an enemy whose mind is data: a behaviour tree
+(`assets/ai/slime.ogt`, og.ai) walking a grid made from the map's wall
+collision (og.nav).
+
+```sh
+og cook .                    # assets/ into cooked/ (og run and og build cook too)
+og run . --headless --commands "0.2:key_down:KeyD;1.2:key_up:KeyD;1.3:screenshot:play.png;1.4: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
+
+The 2D modules together: a Tiled map with an auto-tiled, colliding wall
+terrain the door opens through `og.tilemap.setTile` and reads back with
+`getTile` (og-game §8), a four-direction flipbook hero on
+og.CharacterController in its top-down mode whose walk steps are heard
+(og-game §13; og-feel §9, §12; og-audio §1), a slime that patrols, chases,
+bites and flees as og.ai data on an og.nav grid from the map (og-ai §1–§5),
+hits felt five ways (hit stop, flash and squash, knockback, shake and kick,
+floating damage and a crit) both ways (og-feel §3–§7), a dash with
+afterimages, sorting by feet (og-feel §10), and a camera that follows with a
+dead zone and scrolls between the rooms by og.CameraZone's scrollTime
+(og-feel §8). `og polish .` (2026-10-19): feel 97 (taste n/a: the HUD is
+screen-space text).
+
+
+## Rules
+
+- **Moving.** WASD or the arrows move the hero at `Tuning.speed` on the
+  tick the keys are read; a diagonal is normalised. The hero faces the
+  stronger axis (a diagonal keeps the old facing when it is one of its keys).
+  The hero's body is `og.CharacterController` in its top-down mode
+  (`gravityScale` 0): a kinematic box the engine slides along the walls,
+  moved by `move` each tick (walk, dash and knockback summed). The slime
+  and the hero pass through each other.
+- **The sword.** Space (or J) swings in the facing direction. The hero is
+  rooted for the swing's 15 ticks. Damage lands on the attack clip's strike
+  frame (its `"hit"` event), within `Tuning.reach` of a point one reach
+  ahead of the chest. Hits deal 12, 12, then a 26 crit: the slime (50 hp)
+  dies on the third.
+- **The dash.** Shift (or K) dashes `Tuning.dashTicks` ticks at
+  `Tuning.dashSpeed` along the keys (or the facing), leaving afterimages;
+  then `Tuning.dashCooldown` ticks before the next.
+- **The slime.** Its behaviour tree, `assets/ai/slime.ogt`, is re-checked
+  every tick, first branch first: under 30 hp, and having seen the hero in
+  the last 3 s, it **flees** to 5 m away; seeing the hero within 0.8 m it
+  **bites** (the game's `bite` command, every 0.5 s at most); seeing the
+  hero it **chases** at `Tuning.slimeSpeed`; having lost the hero in the
+  last 2 s it **searches** where it last saw it; otherwise it **patrols**
+  its beat (four points round the key's corner, 0.6 s at each). It sees all
+  round within `Tuning.slimeSight`, but not through walls (the pillar hides
+  the hero). og.nav walks it on the map's grid around the walls, writing its
+  velocity. A bite costs a heart, knocks the hero away and makes it blink
+  for `Tuning.iframes` ticks; the slime bounces back off the bite.
+- **Pickups.** Coins and the key are taken when the hero's chest touches
+  them. The key is spent opening the door.
+- **The door.** Without the key, walking up to it says "locked". With it,
+  the doorway's four wall cells clear (`og.tilemap.setTile` re-tiles their
+  neighbours and drops their colliders) and the hero walks into room 2.
+- **Falling.** At 0 hearts the hero lies still for 90 ticks, then stands up
+  at the spawn with full hearts. Coins, the key and the door stay as they
+  are.
+
+Everything is deterministic from the project seed: the clock is the fixed
+tick, og.ai and og.nav are deterministic and in snapshots, the hovering is a triangle
+wave, and `tests/replay.og.ts` replays a whole visit to the same hash.
+
+## How a hit feels
+
+Each sword hit does five things at once, all in `hitSlime`
+(`src/systems.ts`):
+
+| Effect | Call | Default |
+|---|---|---|
+| flash and squash | `og.tween.flash`, `og.tween.squash` (their impact holds through the hit stop) | white for 0.14 s; 1.45 × 0.6 recovering in 0.28 s |
+| knockback | the slime's `knockX/knockY`, decaying ×0.82 a tick | `Tuning.knockback` (9 m/s), 16 ticks stunned |
+| hit stop | `og.time.hitStop` | `Tuning.hitStop` (4 ticks), 7 on the crit |
+| camera | `og.camera.shake`, `og.camera.kick` | trauma `Tuning.shake` (0.25, ×1.8 on the crit); a 0.12 m kick away from the hero |
+| damage number | `og.render.floatingText` | white, the crit gold and bigger |
+
+The death is two more tweens: the scale to (1.7, 0) with `backIn` and the
+sprite's opacity to 0; the slime hides 30 ticks later. Pickups pop up,
+stretch and fade, and squash the hero a little.
+
+## The map
+
+`assets/maps/tomb.tmj` is a Tiled map (orthogonal, 40 × 12 cells of
+16 px, uncompressed layers) over the tileset `assets/tiles/dungeon.ogt`
+(Tiled's `../tiles/dungeon.tsx` reference resolves to it). One cell is one
+world unit; the map's bottom-left corner is the world origin, y up.
+
+| Layer | Kind | Holds |
+|---|---|---|
+| `floor` | tiles | three slab variants and moss |
+| `walls` | terrain `wall` (`autotile`), `collision` | the outer walls, the dividing wall at x 19–20, three pillars; blob47 picks each cell's shape and the solid tiles collide |
+| `door` | tiles | the door over the doorway's wall cells |
+| `decor` | tiles, `z` = 15 | the animated torches on the north wall, drawn above the actors |
+| `objects` | objects | `spawn`, `enemy` (the slime), `coin` ×6, `key`, `door` (the doorway's rectangle) and `room` ×2 (each room's rectangle) |
+
+`start` (`src/main.ts`) reads the objects: actors spawn at their points,
+the door's rectangle gives the cells to clear, and each room's rectangle
+becomes an `og.CameraZone`. The hero carries `og.Follow2D` (a small dead
+zone, `smoothTime` 0.12, `lookAhead` 0.15), and the orthographic view is
+12 cells tall: a whole room, as in the old top-down adventures, and the
+view scrolls across to room 2 over the zones' `scrollTime` (0.45 s) when
+the hero crosses the doorway (`tests/door.og.ts` samples og.Camera's zone
+fields through the crossing with `get:og.Camera`).
+
+## State
+
+| Type | Kind | What it holds |
+|---|---|---|
+| `Game` | resource | hearts, coins, the key, the door, the room, the slime's hp and hits, the hero's position and facing for the other systems, the strike of this tick, footsteps, invulnerability, knockback, the spawn, the door's cells, sound requests, the font |
+| `Tuning` | resource | the knobs below |
+| `Hero` | the hero | the swing and dash timers, the dash direction, dashes so far |
+| `Slime` | the slime | hp, knockback, stun, bites, death, its clip indices (it also has `og.NavAgent`, `og.AiAgent` and `og.Perception`; the hero has `og.Perceivable`) |
+| `Pickup` | coins and the key | kind, taken, the resting height |
+| `Sfx` | one entity per sound | its `Sound.*` bit (the entity also has `og.AudioSource`) |
+| `Report` | the hero | the run's facts, copied from `Game` each tick so `dump_entity:hero` shows them |
+
+## Systems (in tick order)
+
+| System | Reads | Writes | Job |
+|---|---|---|---|
+| `Control` | `og.Input`, `Tuning`, `og.FlipbookEvent` | `Game`, `Hero`, `og.Transform`, `og.CharacterController`, `og.Flipbook`, `og.Sprite`, `og.Afterimage` | footsteps and strikes from the hero's frame events; walk, swing, dash, knockback, blinking, falling; the clip and flip |
+| `Slimes` | `Tuning` | `Game`, `Slime`, `og.Transform`, `og.Velocity`, `og.Flipbook`, `og.Sprite`, `og.NavAgent`, `og.AiAgent`, `og.Perception` | take strikes (all five effects), knockback and stun (`NavAgent.drive` off meanwhile), death (the AI stops), sight from `Tuning.slimeSight` |
+| `Pickups` | — | `Game`, `Pickup`, `og.Transform`, `og.Sprite` | hover, take by overlap, pop and fade |
+| `Door` | — | `Game` | the room, "locked", opening the doorway |
+| `Voices` | `Sfx` | `Game`, `og.AudioSource` | plays each requested sound once |
+| `Hud` | `Game` | `Report` | screen text: hearts, coins, the key, the room, the controls for 5 s; the hero's `Report` |
+
+og.ai runs before these systems (the slime's decision for the tick) and
+og.nav after them (moving it). During a hit stop the systems still tick but
+hold their timers, as physics, flipbooks and tweens do.
+
+## Tunables (`Tuning`)
+
+| Field | Default | Range | Unit | What it changes |
+|---|---|---|---|---|
+| `speed` | 4.5 | 1–10 | m/s | walking pace |
+| `dashSpeed` | 13 | 4–24 | m/s | the dash |
+| `dashTicks` | 9 | 2–30 | ticks | the dash's length (dashSpeed × dashTicks / 60 m) |
+| `dashCooldown` | 36 | 0–120 | ticks | ticks between dashes |
+| `reach` | 0.75 | 0.2–2 | m | the sword's reach |
+| `hitStop` | 4 | 0–12 | ticks | the freeze per hit (the crit adds 3) |
+| `shake` | 0.25 | 0–1 | trauma | camera shake per hit |
+| `slimeSpeed` | 1.6 | 0–6 | m/s | the slime's chase and search (the behaviour reads it; it patrols at 0.8) |
+| `slimeSight` | 5 | 0–12 | m | how far the slime sees |
+| `knockback` | 9 | 0–20 | m/s | both ways: the struck slime and the bitten hero |
+| `iframes` | 50 | 0–180 | ticks | the hero's blinking after a bite |
+
+They are the field defaults in `src/components.ts`.
+
+## What a Maker changes first
+
+1. **Feel**: `speed`, `dashSpeed`, `hitStop`, `shake`, `knockback` in
+   `Tuning`, and the damage list `DAMAGE` in `src/systems.ts`.
+2. **The level**: open `assets/maps/tomb.tmj` in Tiled. Paint the `walls`
+   layer with any tile (the terrain picks the shape), move the objects, add
+   coins (`type` coin) or rooms (`type` room). Keep the door's rectangle on
+   wall cells. Or change `map_layout` in `tools/make-assets.py`.
+3. **Enemies**: another `enemy` object needs its own name (the `slime`
+   command addresses `slime`); `Slimes` already loops over every slime.
+   What a slime does is `assets/ai/slime.ogt`: reorder the branches, change
+   the numbers, add a `wander` or a state machine (the nodes are listed in
+   the og-ai skill). `dump_ai:slime` shows the running node, the path to it,
+   the blackboard and what it sees; `dump_nav:slime` its path.
+4. **Look**: the tiles and sprites are drawn in `tools/make-assets.py`;
+   run `python3 tools/make-assets.py && og cook .`. The hero's clip order is
+   fixed (`src/art.ts` checks it).
+5. **Words**: the HUD strings in `Hud`. The font holds Latin-1 only; add
+   characters to `subset_font`'s text and `chars` in `ui.ttf.ogt` first.
+
+## Commands (for scripts and agents)
+
+| Action | Does |
+|---|---|
+| `place:<x>:<y>` | puts the hero's feet at a world point, standing still |
+| `slime:<x>:<y>` | moves the slime |
+| `give:<key\|coin\|door>` | the key, a coin, or the doorway opened |
+| `face:<down\|up\|left\|right>` | turns the hero |
+| `bite:<slime>` | the behaviour's attack (og.ai queues it with the slime's handle): hurts a hero within 0.85 m |
+| `dump_ai:slime[:file]`, `dump_nav:slime[:file]` | the slime's behaviour, running node, blackboard and perception; its path |
+| core actions | `key_down:KeyD`/`key_up:KeyD` walk, `Space` swings, `ShiftLeft` dashes; `dump_entity:hero` shows `Report` |
+
+`facts` (the probe's `state()`) reports `room`, `hp`, `coins`, `hasKey`,
+`enemyHp`, `doorOpen`, `doorWall`, the hero's and slime's positions,
+`facing`, `steps`, `swings`, `hits`, `hurts` and `dashes`.
+
+## Playtests (`og test .`)
+
+| File | Proves |
+|---|---|
+| `tests/walk.og.ts` | one second of D walks 4.5 m; footsteps come from the walk clip's events; up and left stop at the wall terrain's colliders; facing, the side clip and its flip |
+| `tests/ai.og.ts` | out of sight the slime patrols its beat on og.nav's path; the hero 3 m off is seen three ticks later and the patrol gives way to the chase at about 1.6 m/s; the bite lands through the `bite` command |
+| `tests/flee.og.ts` | the pillar hides the hero 4.5 m away; below the pillar it is seen and chased; under 30 hp the slime flees and keeps over 3.5 m away |
+| `tests/combat.og.ts` | a bite costs a heart and knocks the hero back; the hit stop holds the slime still, white and squashed; 12, 12, 26 kill it; it ends hidden and squashed to nothing |
+| `tests/door.og.ts` | the doorway blocks without the key; walking over the key takes it; the door opens (the wall cell cleared), the key is spent, the hero reaches room 2 |
+| `tests/frames.og.ts` | four frames match `references/<tier>/`: the west room at rest, the crit's freeze frame, a dash, the east room through the open doorway (`OG_FX_CAPTURE=1 og test .` records them) |
+| `tests/replay.og.ts` | a whole visit, run twice in fresh processes, ends on the same world hash |
+
+Each one fails when the behaviour it names is broken (checked by halving
+the walk speed, dropping the hit's flash, leaving the doorway's walls in
+place, drawing the map over the actors, and wandering by `Math.random`;
+the AI ones by sight through walls, a bite that never lands and a flee
+threshold of 0; `tests/evidence/E6/break-and-restore.md`).
+
+## Assets
+
+`tools/make-assets.py` regenerates every asset byte for byte: the tileset
+and its blob47 rules, the Tiled map, the flipbook sheets, the sounds and the
+font subset. `LICENSES.md` lists them.
+
+## Known limits (engine gaps, not design)
+
+- The playtests read most of the run through the hero's `Report` copy,
+  which predates `get:` on resources (E7); `set:Tuning.<field>=<value>`
+  now tunes the resource from the command channel.
+- The blob shadows (0.35) barely show on the dark floor.

package/archetypes/topdown/assets/ai/slime.ogt

@@ -0,0 +1,49 @@
+type behaviour
+version 1
+---
+# The slime (crates/og-ai/README.md has every node). og.ai runs it before
+# the game's systems; the first branch that does not fail decides, and the
+# tree is re-checked every tick, so seeing the hero halts the patrol at once.
+name "slime"
+route beat {                       # the west room's middle, round the key's corner
+  point 13.5 6.5 0
+  point 17.5 6.5 0
+  point 17.5 3.5 0
+  point 13.5 3.5 0
+}
+tree {
+  selector {
+    sequence flee {                # hurt and recently threatened: keep away
+      check Slime.hp below 30
+      check sinceSeen below 3
+      flee {
+        speed 2.6
+        distance 5
+      }
+    }
+    sequence attack {              # in reach: bite (the game's `bite` command)
+      check sees
+      check targetDistance below 0.8
+      command bite {
+        cooldown 0.5
+      }
+    }
+    sequence chase {               # in sight (Perception.sight is Tuning.slimeSight)
+      check sees
+      chase {
+        speed Tuning.slimeSpeed
+        reach 0.6
+      }
+    }
+    sequence search {              # lost it: go where it was last seen
+      check sinceSeen below 2
+      move_to lastSeen {
+        speed Tuning.slimeSpeed
+      }
+    }
+    patrol beat {
+      wait 0.6
+      speed 0.8
+    }
+  }
+}

package/archetypes/topdown/assets/audio/step.ogt

@@ -0,0 +1,9 @@
+type sfx
+version 1
+---
+# a short filtered noise tick: og.load.sound(world, "<this file>") plays it.
+preset "footstep"
+seed 0
+pitch 1
+length 1
+volume 1