mapgen: obstacles, bridges-arena, chokepoint-arena + per-scenario authoring

Extend the YAML-referenceable map generator with three new tools so
each scenario pack can have a map tailored to what it measures
instead of all sharing rush-hour-arena.

* `arena` generator: new `obstacles: [{x,y,w,h}, ...]` parameter
paints WATER rectangles inside the playable area (cover, channels,
forced-flank obstacles).
* `bridges-arena` generator: a horizontal or vertical water channel
with N explicit bridge gaps — canonical chokepoint-defense map.
Honours all `arena` knobs plus axis / channel_y or _x /
channel_width / bridges (list of {pos, width}).
* `chokepoint-arena` generator: two open lobes linked by one narrow
corridor through a thick wall — forces the attacker through a
single cell.
* Refactor: extract `_blank_arena()`, `_stamp_rect()`, and
`_default_spawns()` helpers shared across generators.

3 new tests cover obstacle painting, bridge gaps, and corridor-only
routing (9 total now; 6 existing pass unchanged).

`scripts/author_perscenario_maps.py` declares per-pack map specs
for the 12 engine-feature debug packs — each scenario gets a
tailored .oramap (bridges for def-bridge-chokepoint, chokepoint for
spec-thief-steal-cash, small focused arena for spec-tanya-c4-strike,
etc). `--dry-run` materialises the maps without touching YAML
(committing only the infrastructure for now).

Validation found 7/12 packs whose existing actor coords collide
with the proposed map geometry: ~5 econ/spec packs have actors at
x=120 designed for rush-hour's 128 width that fall outside smaller
custom maps, def-bridge-chokepoint has enemy infantry on the vertical
water channel, and spec-spy-infiltrate has a pre-existing bug placing
enemy buildings at y=80-100 (out of bounds for any 40-high map —
silently ignored in rush-hour-arena too). Next wave will either
upsize the maps to fit existing coords, or rewrite per-pack actor
positions to fit tailored maps.

openra_bench/mapgen.py

@@ -40,18 +40,14 @@ def generator(name: str):
     return _reg
 
 
-@generator("arena")
-def _arena(spec: dict):
-    """Open rectangle with a water cordon (generalizes rush-hour-arena
-    and scout-arena). Params: width, height, cordon."""
-    w = int(spec.get("width", 128))
-    h = int(spec.get("height", 40))
-    c = int(spec.get("cordon", spec.get("bounds", 2)))
+def _blank_arena(w: int, h: int, c: int) -> list[list[int]]:
+    """Open arena with a water cordon (the base canvas every generator
+    builds on)."""
     if not (16 <= w <= 512 and 16 <= h <= 512):
         raise ValueError(f"arena size out of range: {w}x{h}")
     if not (0 <= c < min(w, h) // 2):
         raise ValueError(f"arena cordon out of range: {c}")
-    grid = [
+    return [
         [
             WATER
             if (x < c or x >= w - c or y < c or y >= h - c)
@@ -60,15 +56,161 @@ def _arena(spec: dict):
         ]
         for y in range(h)
     ]
-    bounds = (c, c, w - 2 * c, h - 2 * c)
-    # Four playable-corner spawn references.
-    spawns = [
+
+
+def _stamp_rect(grid: list[list[int]], rect: dict, tile: int) -> None:
+    """Paint a rectangle of `tile` onto `grid`. `rect` is {x, y, w, h}
+    in playable-area coords (the cordon is honoured)."""
+    h = len(grid); w = len(grid[0])
+    rx = int(rect["x"]); ry = int(rect["y"])
+    rw = int(rect.get("w", 1)); rh = int(rect.get("h", 1))
+    for y in range(max(0, ry), min(h, ry + rh)):
+        for x in range(max(0, rx), min(w, rx + rw)):
+            grid[y][x] = tile
+
+
+def _default_spawns(w: int, h: int, c: int) -> list[tuple[int, int]]:
+    return [
         (c + 4, c + 4), (w - c - 5, c + 4),
         (c + 4, h - c - 5), (w - c - 5, h - c - 5),
     ]
+
+
+@generator("arena")
+def _arena(spec: dict):
+    """Open rectangle with a water cordon + optional interior obstacles.
+
+    Params:
+      width, height (16..512), cordon (default 2).
+      obstacles: list of {x, y, w, h} rectangles painted as WATER.
+        Each rectangle is in absolute map coords; the cordon is
+        the impassable frame, obstacles paint additional water
+        INSIDE the playable area (forces flanking, cover, etc).
+      spawns: optional list of [x, y] overriding the 4 corner defaults.
+      title: optional human-readable map title.
+    """
+    w = int(spec.get("width", 128))
+    h = int(spec.get("height", 40))
+    c = int(spec.get("cordon", spec.get("bounds", 2)))
+    grid = _blank_arena(w, h, c)
+    for rect in (spec.get("obstacles") or []):
+        _stamp_rect(grid, rect, WATER)
+    spawns = [tuple(s) for s in spec["spawns"]] if spec.get("spawns") \
+        else _default_spawns(w, h, c)
+    bounds = (c, c, w - 2 * c, h - 2 * c)
     return grid, (w, h), bounds, spawns, spec.get("title", f"Arena {w}x{h}")
 
 
+@generator("bridges-arena")
+def _bridges_arena(spec: dict):
+    """Open arena split by a horizontal or vertical water channel with
+    N bridge gaps — the canonical 'chokepoint defense' map.
+
+    Params:
+      width, height, cordon as in `arena`.
+      axis: 'horizontal' (default) splits along y; 'vertical' splits
+        along x.
+      channel_y / channel_x: the cell index of the water row/column
+        (defaults to the map midpoint).
+      channel_width: thickness of the water band (default 2 cells).
+      bridges: list of {pos, width} declaring the cell position of
+        each crossing (along the axis perpendicular to the channel)
+        and how many cells wide the gap is. Default: 3 evenly-spaced
+        2-cell bridges.
+      obstacles: optional extra WATER rectangles, as in `arena`.
+      spawns / title: as in `arena`.
+    """
+    w = int(spec.get("width", 128))
+    h = int(spec.get("height", 40))
+    c = int(spec.get("cordon", 2))
+    grid = _blank_arena(w, h, c)
+    axis = spec.get("axis", "horizontal")
+    cw = int(spec.get("channel_width", 2))
+    bridges = spec.get("bridges")
+    if axis == "horizontal":
+        cy = int(spec.get("channel_y", h // 2))
+        if bridges is None:
+            # 3 evenly-spaced 2-cell bridges
+            third = (w - 2 * c) // 4
+            bridges = [
+                {"pos": c + third, "width": 2},
+                {"pos": c + 2 * third, "width": 2},
+                {"pos": c + 3 * third, "width": 2},
+            ]
+        for dy in range(cy, min(h, cy + cw)):
+            for x in range(c, w - c):
+                grid[dy][x] = WATER
+        for br in bridges:
+            bx = int(br["pos"]); bw = int(br.get("width", 2))
+            for dy in range(cy, min(h, cy + cw)):
+                for x in range(max(c, bx), min(w - c, bx + bw)):
+                    grid[dy][x] = CLEAR
+    elif axis == "vertical":
+        cx = int(spec.get("channel_x", w // 2))
+        if bridges is None:
+            third = (h - 2 * c) // 4
+            bridges = [
+                {"pos": c + third, "width": 2},
+                {"pos": c + 2 * third, "width": 2},
+                {"pos": c + 3 * third, "width": 2},
+            ]
+        for dx in range(cx, min(w, cx + cw)):
+            for y in range(c, h - c):
+                grid[y][dx] = WATER
+        for br in bridges:
+            by = int(br["pos"]); bh = int(br.get("width", 2))
+            for dx in range(cx, min(w, cx + cw)):
+                for y in range(max(c, by), min(h - c, by + bh)):
+                    grid[y][dx] = CLEAR
+    else:
+        raise ValueError(f"bridges-arena axis must be horizontal/vertical, got {axis!r}")
+    for rect in (spec.get("obstacles") or []):
+        _stamp_rect(grid, rect, WATER)
+    spawns = [tuple(s) for s in spec["spawns"]] if spec.get("spawns") \
+        else _default_spawns(w, h, c)
+    bounds = (c, c, w - 2 * c, h - 2 * c)
+    return grid, (w, h), bounds, spawns, spec.get("title", f"Bridges {w}x{h}")
+
+
+@generator("chokepoint-arena")
+def _chokepoint_arena(spec: dict):
+    """Two open lobes linked by a single narrow corridor — the canonical
+    'force the attacker through one cell' map. Defender bias: small army
+    holding the pinch beats a larger army that can't deploy width.
+
+    Params:
+      width, height, cordon as in `arena`.
+      pinch_x: x of the corridor wall (default w//2).
+      pinch_width: thickness of the wall on each side of the corridor
+        (default 6 cells of WATER above + below the corridor).
+      corridor_width: open height of the corridor gap (default 4).
+      corridor_y: y of the corridor centre (default h//2).
+      obstacles / spawns / title: as in `arena`.
+    """
+    w = int(spec.get("width", 96))
+    h = int(spec.get("height", 40))
+    c = int(spec.get("cordon", 2))
+    grid = _blank_arena(w, h, c)
+    px = int(spec.get("pinch_x", w // 2))
+    pw = int(spec.get("pinch_width", 6))      # wall thickness vertical
+    cw = int(spec.get("corridor_width", 4))   # corridor height
+    cy = int(spec.get("corridor_y", h // 2))
+    # Wall above corridor
+    for y in range(c, cy - cw // 2):
+        for x in range(max(c, px - pw // 2), min(w - c, px + pw // 2 + 1)):
+            grid[y][x] = WATER
+    # Wall below corridor
+    for y in range(cy + (cw + 1) // 2, h - c):
+        for x in range(max(c, px - pw // 2), min(w - c, px + pw // 2 + 1)):
+            grid[y][x] = WATER
+    for rect in (spec.get("obstacles") or []):
+        _stamp_rect(grid, rect, WATER)
+    spawns = [tuple(s) for s in spec["spawns"]] if spec.get("spawns") \
+        else [(c + 4, h // 2), (w - c - 5, h // 2)]
+    bounds = (c, c, w - 2 * c, h - 2 * c)
+    return grid, (w, h), bounds, spawns, spec.get("title", f"Chokepoint {w}x{h}")
+
+
 @generator("naval-arena")
 def _naval_arena(spec: dict):
     """Naval-arena: an open rectangle (like `arena`) with a documented

scripts/author_perscenario_maps.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+"""Author per-scenario maps for each scenario pack.
+
+The bench currently shares one 128×40 `rush-hour-arena.oramap` across
+194 of 210 packs. Each scenario should have a map TAILORED to what it
+measures — small focused arenas for short-execution packs (Tanya C4),
+chokepoint maps for defensive packs, multi-zone maps for expansion /
+multi-base packs, bridges for crossing-defense packs.
+
+This script declares a per-pack map spec (one dict per pack id) and:
+
+  --dry-run        : materialize the .oramaps + print a summary;
+                     do NOT edit any pack YAMLs.
+  --apply          : in addition, rewrite each pack's `base_map:`
+                     line to point at the new per-scenario .oramap.
+  --validate       : run a stall-policy smoke through each pack to
+                     confirm the new map loads cleanly (no panic) and
+                     the scenario still terminates.
+
+Authoring rule of thumb (from CLAUDE.md):
+  - small open arena → short-execution packs (Tanya C4, engineer
+    capture easy, spy infiltrate easy).
+  - medium with corridor / chokepoint → packs that need a forced
+    pinch (def-bridge-chokepoint, chokepoint family).
+  - large open arena → search / perception packs (spec-nuke-strike,
+    scout-far-frontier).
+  - bridges-arena → packs whose briefing references bridges
+    (def-bridge-chokepoint).
+  - naval-arena → packs with water + ships (combat-naval-shore-strike).
+
+The 12-pack debug grid is the first wave; the remaining ~198 packs
+follow in subsequent waves once these are validated.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+REPO = HERE.parent
+if str(REPO) not in sys.path:
+    sys.path.insert(0, str(REPO))
+
+from openra_bench.mapgen import materialize  # noqa: E402
+
+# ── per-pack map specs ────────────────────────────────────────────────
+# Each spec is the dict you'd put under `base_map:` in the pack YAML.
+# Generators understand: arena, bridges-arena, chokepoint-arena,
+# naval-arena. `name` slugs become the .oramap filename.
+PER_PACK_MAPS: dict[str, dict] = {
+    # ── special-ability family ────────────────────────────────────────
+    # Short execution; small focused arena keeps the run on the
+    # action, not the navigation.
+    "spec-tanya-c4-strike": {
+        "generator": "arena",
+        "name": "spec-tanya-c4-strike-arena",
+        "title": "Tanya Strike — close-range execution",
+        "width": 80, "height": 32, "cordon": 2,
+    },
+    # Engineer is fragile; one obstacle band creates a north/south
+    # choice that tests path planning under attrition.
+    "spec-engineer-capture": {
+        "generator": "arena",
+        "name": "spec-engineer-capture-arena",
+        "title": "Engineer Capture — escort path",
+        "width": 96, "height": 36, "cordon": 2,
+        "obstacles": [{"x": 44, "y": 14, "w": 8, "h": 8}],
+    },
+    # Spy infiltrates fogged; medium arena with TWO cover clusters
+    # offers a stealth-route choice.
+    "spec-spy-infiltrate": {
+        "generator": "arena",
+        "name": "spec-spy-infiltrate-arena",
+        "title": "Spy Infiltrate — fogged approach",
+        "width": 96, "height": 36, "cordon": 2,
+        "obstacles": [
+            {"x": 30, "y": 8, "w": 6, "h": 4},
+            {"x": 30, "y": 24, "w": 6, "h": 4},
+            {"x": 56, "y": 16, "w": 6, "h": 4},
+        ],
+    },
+    # Thief drains cash from proc/silo. Single corridor approach
+    # tests whether the model finds the only path.
+    "spec-thief-steal-cash": {
+        "generator": "chokepoint-arena",
+        "name": "spec-thief-steal-cash-arena",
+        "title": "Thief — single corridor approach",
+        "width": 80, "height": 32, "cordon": 2,
+        "pinch_x": 40, "pinch_width": 8, "corridor_width": 4,
+        "corridor_y": 16,
+    },
+    # Nuke targets a CLUSTER; the test is spatial commit (find +
+    # aim). Large open arena gives plausible alternative cluster
+    # positions.
+    "spec-nuke-strike": {
+        "generator": "arena",
+        "name": "spec-nuke-strike-arena",
+        "title": "Nuke Strike — large arena, find the cluster",
+        "width": 144, "height": 48, "cordon": 3,
+    },
+
+    # ── economy family ────────────────────────────────────────────────
+    # Pure macro: small open arena, no obstacles, no enemies.
+    "econ-mine-and-grow": {
+        "generator": "arena",
+        "name": "econ-mine-and-grow-arena",
+        "title": "Mine and Grow — pure macro",
+        "width": 72, "height": 32, "cordon": 2,
+    },
+    # Contested patch in the centre; obstacle band between the two
+    # bases forces an approach commitment.
+    "econ-contested-expansion": {
+        "generator": "arena",
+        "name": "econ-contested-expansion-arena",
+        "title": "Contested Expansion — single channel",
+        "width": 112, "height": 36, "cordon": 2,
+        "obstacles": [
+            {"x": 50, "y": 6, "w": 8, "h": 8},
+            {"x": 50, "y": 22, "w": 8, "h": 8},
+        ],
+    },
+    # Multi-patch decision; medium arena with room for 3+ patches.
+    "econ-multi-patch-allocation": {
+        "generator": "arena",
+        "name": "econ-multi-patch-allocation-arena",
+        "title": "Multi-Patch Allocation",
+        "width": 128, "height": 40, "cordon": 2,
+    },
+    # Second-base race; medium arena with clear best vs second-best
+    # placement zones.
+    "econ-second-base-race": {
+        "generator": "arena",
+        "name": "econ-second-base-race-arena",
+        "title": "Second Base Race",
+        "width": 112, "height": 36, "cordon": 2,
+    },
+    # Defend harvester from a raider on a single lane.
+    "econ-harvester-defense-raid": {
+        "generator": "arena",
+        "name": "econ-harvester-defense-raid-arena",
+        "title": "Harvester Defense — single raid lane",
+        "width": 96, "height": 36, "cordon": 2,
+        "obstacles": [
+            {"x": 48, "y": 6, "w": 6, "h": 10},
+            {"x": 48, "y": 22, "w": 6, "h": 10},
+        ],
+    },
+
+    # ── defense / combat family ───────────────────────────────────────
+    # Bridges! Real water channel with 3 crossings — the briefing
+    # finally matches the terrain.
+    "def-bridge-chokepoint": {
+        "generator": "bridges-arena",
+        "name": "def-bridge-chokepoint-arena",
+        "title": "Bridge Chokepoint — 3 crossings",
+        "width": 128, "height": 40, "cordon": 2,
+        "axis": "vertical",
+        "channel_x": 60, "channel_width": 3,
+        "bridges": [
+            {"pos": 8, "width": 3},
+            {"pos": 18, "width": 3},
+            {"pos": 28, "width": 3},
+        ],
+    },
+    # Naval shore strike already uses naval-arena; keep but namespace
+    # to the pack so future tuning is per-scenario.
+    "combat-naval-shore-strike": {
+        "generator": "naval-arena",
+        "name": "combat-naval-shore-strike-arena",
+        "title": "Naval Shore Strike",
+        "width": 96, "height": 40, "cordon": 2,
+    },
+}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--dry-run", action="store_true",
+                    help="materialize maps and print summary; no YAML edits")
+    ap.add_argument("--apply", action="store_true",
+                    help="rewrite each pack's base_map to the per-scenario id")
+    ap.add_argument("--packs", default="all",
+                    help="comma-separated pack ids or 'all'")
+    args = ap.parse_args()
+
+    target = (set(args.packs.split(",")) if args.packs != "all"
+              else set(PER_PACK_MAPS))
+
+    materialized: list[tuple[str, str, Path]] = []
+    for pid, spec in sorted(PER_PACK_MAPS.items()):
+        if pid not in target:
+            continue
+        mid = materialize(spec)
+        out = REPO / "data" / "maps" / f"{mid}.oramap"
+        materialized.append((pid, mid, out))
+        print(f"  {pid:34s} → {mid:42s} ({out.stat().st_size} bytes)")
+    print(f"\nmaterialized {len(materialized)}/{len(target)} pack maps")
+
+    if args.apply:
+        from openra_bench.scenarios.loader import PACKS_DIR
+        edited = 0
+        for pid, mid, _ in materialized:
+            yaml_path = PACKS_DIR / f"{pid}.yaml"
+            if not yaml_path.exists():
+                print(f"  ⚠ pack file missing: {yaml_path}")
+                continue
+            raw = yaml_path.read_text()
+            # Replace the first `base_map: <something>` line with the
+            # new logical id. We use a regex anchored to start-of-line
+            # so we don't touch any documentation that mentions
+            # "base_map:" inside a comment.
+            import re
+            new_raw, n = re.subn(
+                r"^base_map: .*$",
+                f"base_map: {mid}",
+                raw,
+                count=1,
+                flags=re.MULTILINE,
+            )
+            if n == 0:
+                print(f"  ⚠ no base_map: line in {pid}")
+                continue
+            if new_raw != raw:
+                yaml_path.write_text(new_raw)
+                edited += 1
+        print(f"\napplied to {edited} pack YAMLs")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/test_mapgen.py

@@ -67,3 +67,74 @@ def test_pack_with_generator_spec_compiles():
     hard = compile_level(p, "hard")
     assert hard.scenario.base_map == "scout-arena"
     assert hard.map_supported
+
+
+def test_arena_obstacles_paint_interior_water():
+    """Obstacles are WATER rectangles inside the playable area —
+    distinguishable from the cordon by their position."""
+    s = {"generator": "arena", "name": "test-obs-paint",
+         "width": 40, "height": 20, "cordon": 2,
+         "obstacles": [{"x": 10, "y": 8, "w": 4, "h": 2}]}
+    mid = materialize(s)
+    p = resolve_map_path(mid)
+    # Parse map.bin and confirm the (10,8)..(13,9) block is water but
+    # surrounding playable cells are clear.
+    blob = zipfile.ZipFile(p).read("map.bin")
+    w = int.from_bytes(blob[1:3], "little")
+    h = int.from_bytes(blob[3:5], "little")
+    tiles_off = int.from_bytes(blob[5:9], "little")
+    def cell(x, y):
+        idx = tiles_off + 3 * (x * h + y)
+        return int.from_bytes(blob[idx:idx + 2], "little")
+    assert (w, h) == (40, 20)
+    assert cell(10, 8) == 1 and cell(13, 9) == 1, "obstacle painted as water"
+    assert cell(20, 10) == 255, "interior outside obstacle stays clear"
+    assert cell(0, 0) == 1, "cordon corner still water"
+
+
+def test_bridges_arena_channel_with_gaps():
+    """Horizontal water band with explicit bridge gaps."""
+    s = {"generator": "bridges-arena", "name": "test-br-h",
+         "width": 60, "height": 30, "cordon": 2,
+         "channel_y": 14, "channel_width": 2,
+         "bridges": [{"pos": 20, "width": 3}]}
+    mid = materialize(s)
+    p = resolve_map_path(mid)
+    blob = zipfile.ZipFile(p).read("map.bin")
+    w = int.from_bytes(blob[1:3], "little")
+    h = int.from_bytes(blob[3:5], "little")
+    tiles_off = int.from_bytes(blob[5:9], "little")
+    def cell(x, y):
+        idx = tiles_off + 3 * (x * h + y)
+        return int.from_bytes(blob[idx:idx + 2], "little")
+    # Channel row 14 is water on the non-bridge cells
+    assert cell(40, 14) == 1, "off-bridge channel cell is water"
+    # Bridge gap (20..22) is clear
+    assert cell(20, 14) == 255 and cell(22, 14) == 255
+    # Row 13 (above channel) is open
+    assert cell(40, 13) == 255
+
+
+def test_chokepoint_arena_corridor_is_only_route():
+    """One narrow corridor across the wall; everywhere else along the
+    wall x-band is water."""
+    s = {"generator": "chokepoint-arena", "name": "test-chk",
+         "width": 60, "height": 30, "cordon": 2,
+         "pinch_x": 30, "pinch_width": 6, "corridor_width": 4,
+         "corridor_y": 14}
+    mid = materialize(s)
+    p = resolve_map_path(mid)
+    blob = zipfile.ZipFile(p).read("map.bin")
+    h = int.from_bytes(blob[3:5], "little")
+    tiles_off = int.from_bytes(blob[5:9], "little")
+    def cell(x, y):
+        idx = tiles_off + 3 * (x * h + y)
+        return int.from_bytes(blob[idx:idx + 2], "little")
+    # Corridor (y=12..15) clear at the pinch column
+    assert cell(30, 12) == 255 and cell(30, 15) == 255
+    # Above corridor (y=8) at the pinch is water
+    assert cell(30, 8) == 1
+    # Below corridor (y=22) at the pinch is water
+    assert cell(30, 22) == 1
+    # Open areas left/right of the wall still clear
+    assert cell(10, 14) == 255 and cell(50, 14) == 255