Skip to content

0x0funky/agent-sprite-forge / skills/generate2dmap

generate2dmap

Verified

Plan and build 2D game maps and scenes - top-down and side-scrolling levels, tilemaps, prop packs, parallax backgrounds and HD-2D battle or story plates - with collision, navigation and reachability checks, environment motion, a playable HTML preview and export to Tiled, Godot 4 or LDtk. Map art (terrain, tiles, props, plates, parallax layers) is image generation by default, through generate2dmedia route_media.py (the API when a key is configured, else the local Codex or Grok CLI); map data (layout, collision, exits, spawns) is written as data. Use for any map, level, room, scene, background, terrain or prop-kit request. Not for characters, creatures, items or FX (generate2dsprite), character animation (video2dsprite), code-drawn tiles or maps (codeart2d, only on request) or calling an image or video API by itself (generate2dmedia).

FileKindSize
SKILL.mdskill md12.3 KB
agents/openai.yamlconfig513 B
references/background-scenes.mdmarkdown14.2 KB
references/engine-maps.mdmarkdown14.4 KB
references/hd2d-plates.mdmarkdown11.9 KB
references/hd2d-presentation.mdmarkdown9.8 KB
references/layered-map-contract.mdmarkdown21.3 KB
references/map-presets.mdmarkdown7.9 KB
references/map-strategies.mdmarkdown12.2 KB
references/parallax-backgrounds.mdmarkdown14.0 KB
references/prop-pack-contract.mdmarkdown15.0 KB
references/runtime/map-runtime.mjsscript81.1 KB
references/scene-preview.mdmarkdown14.6 KB
references/schemas/common.schema.jsonconfig12.9 KB
references/schemas/host.schema.jsonconfig18.8 KB
references/schemas/map.schema.jsonconfig134.0 KB
references/side-scroll-scenes.mdmarkdown14.3 KB
scripts/build_motion_mask.pyscript46.3 KB
scripts/build_scene_preview.pyscript93.5 KB
scripts/compose_layered_preview.pyscript92.2 KB
scripts/conform_background.pyscript25.4 KB
scripts/edit_locality_check.pyscript27.1 KB
scripts/export_godot.pyscript85.6 KB
scripts/export_ldtk.pyscript51.4 KB
scripts/export_tiled.pyscript45.5 KB
scripts/extract_platform_strip.pyscript29.4 KB
scripts/extract_prop_pack.pyscript63.2 KB
scripts/extract_scene_lights.pyscript43.3 KB
scripts/extract_terrain_tiles.pyscript54.1 KB
scripts/forge_av.pyscript46.6 KB
scripts/forge_core.pyscript86.4 KB
scripts/forge_hibit.pyscript18.8 KB
scripts/forge_index.pyscript24.8 KB
scripts/forge_matte.pyscript71.6 KB
scripts/forge_nav.pyscript95.5 KB
scripts/forge_schema.pyscript26.1 KB
scripts/hibit_plate.pyscript13.5 KB
scripts/map_bundle.pyscript82.6 KB
scripts/map_nav.pyscript31.9 KB
scripts/scene_layout_guide.pyscript22.1 KB
scripts/scene_motion.pyscript54.5 KB
scripts/validate_chunks.pyscript48.8 KB
scripts/validate_layout.pyscript47.1 KB
scripts/validate_parallax.pyscript29.6 KB
scripts/validate_stage.pyscript62.3 KB

scripts/extract_platform_strip.py

View on GitHub
#!/usr/bin/env python3
"""Extract native rectangular platform pieces (left cap, middle variants, right cap) and measure them.

Pieces are exact source crops: no trim, resize, bbox fit or anchor guess. QC checks the declared
collision band, measures the art's top surface in every collision column against the declared
surface, and measures every join with a normalised seam ratio. The output directory must be new;
work is staged beside it and published only after QC, so a failed run leaves nothing behind. A QA
status of fail is still published for inspection and exits 4; --strict-qc publishes nothing (exit 1).
"""

from __future__ import annotations

import argparse
import json
import math
import os
import re
import sys
from pathlib import Path
from typing import Any

import numpy as np

sys.path.insert(0, str(Path(__file__).resolve().parent))
import forge_core  # noqa: E402  (this skill's vendored copy)
import forge_matte  # noqa: E402


SCHEMA = "generate2dmap.platform_strip.v2"
TOOL_NAME = "extract_platform_strip.py"
TOOL_VERSION = forge_core.FORGE_PACKAGE_VERSION  # D29: QA envelopes carry the package version
MANIFEST_NAME = "platform-strip.json"
PREVIEW_NAME = "strip-preview.png"
ROLES = ("left_cap", "middle", "right_cap")
BACKGROUND_MODES = ("chroma_key", "native_alpha", "opaque")
MAX_MIDDLES = 16
PREVIEW_MIDDLES = 3  # the preview repeats the middle variants up to at least this many
RESERVED_STEMS = {"strip-preview", "platform-strip"}
DEVICE_NAMES = {"CON", "PRN", "AUX", "NUL", *(f"COM{i}" for i in range(1, 10)), *(f"LPT{i}" for i in range(1, 10))}

# The normalised seam ratio (MAP-14) is forge_core.edge_seam_report, the one seam metric (D9): steps are
# premultiplied RGBA mean absolute differences (0-255) between neighbouring columns, and a join is
# compared with the interior steps near it.
NOMINAL_SEAM_RATIO = forge_core.EDGE_SEAM_NOMINAL_RATIO  # verdict label when no --max-seam-ratio gate is set


# --------------------------------------------------------------------------- spec

def integer(value: Any, name: str) -> int:
    if type(value) is not int:
        raise ValueError(f"{name} must be an integer.")
    return value


def validate_spec(data: Any, source_size: tuple[int, int]) -> list[dict[str, Any]]:
    """Return the pieces in strip order: the left cap, the middle variants in spec order, the right cap."""
    if not isinstance(data, dict):
        raise ValueError("Spec must be a JSON object.")
    top = integer(data.get("surface_y_px"), "surface_y_px")
    depth = integer(data.get("collision_depth_px"), "collision_depth_px")
    raw_pieces = data.get("pieces")
    if not isinstance(raw_pieces, list) or not 3 <= len(raw_pieces) <= MAX_MIDDLES + 2:
        raise ValueError(f"Spec requires pieces: one left_cap, 1-{MAX_MIDDLES} middle variants and one right_cap.")
    caps: dict[str, dict[str, Any]] = {}
    middles: list[dict[str, Any]] = []
    ids: set[str] = set()
    for raw in raw_pieces:
        if not isinstance(raw, dict):
            raise ValueError("Each piece must be an object.")
        identity, role, box = raw.get("id"), raw.get("role"), raw.get("source_box")
        if (not isinstance(identity, str) or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_-]*", identity)
                or identity.lower() in ids | RESERVED_STEMS or identity.upper() in DEVICE_NAMES):
            raise ValueError("Piece id must be a unique, portable filename stem, excluding reserved names.")
        if not isinstance(role, str) or role not in ROLES or role in caps:
            raise ValueError("Use exactly one left_cap, one or more middle variants and exactly one right_cap.")
        if not isinstance(box, list) or len(box) != 4:
            raise ValueError("source_box must be [left, top, right, bottom].")
        left, upper, right, bottom = [integer(v, "source_box coordinate") for v in box]
        if not (0 <= left < right <= source_size[0] and 0 <= upper < bottom <= source_size[1]):
            raise ValueError(f"source_box for {identity} lies outside the source or is empty.")
        span = raw.get("collision_span_px", [0, right - left])
        if not isinstance(span, list) or len(span) != 2:
            raise ValueError("collision_span_px must be [x0,x1] in cropped-piece coordinates.")
        x0, x1 = [integer(v, "collision_span_px coordinate") for v in span]
        if not 0 <= x0 < x1 <= right - left:
            raise ValueError("collision_span_px must be nonempty and inside its piece.")
        if (role == "middle" and span != [0, right - left]
                or role == "left_cap" and x1 != right - left
                or role == "right_cap" and x0 != 0):
            raise ValueError("Collision spans must reach every join: middle both sides, left_cap right, right_cap left.")
        ids.add(identity.lower())
        piece = {"id": identity, "role": role, "source_box": box,
                 "size": [right - left, bottom - upper], "collision_span_px": span}
        if role == "middle":
            middles.append(piece)
        else:
            caps[role] = piece
    if set(caps) != {"left_cap", "right_cap"} or not middles:
        raise ValueError("Use exactly one left_cap, one or more middle variants and exactly one right_cap.")
    ordered = [caps["left_cap"], *middles, caps["right_cap"]]
    if len({piece["size"][1] for piece in ordered}) != 1:
        raise ValueError("All native rectangular pieces must have the same height; no resizing is performed.")
    if top < 0 or depth <= 0 or top + depth > ordered[0]["size"][1]:
        raise ValueError("Declared surface_y_px and collision_depth_px must define a nonempty in-canvas band.")
    return ordered


# --------------------------------------------------------------------------- background

def prepare_background(source: Any, args: argparse.Namespace) -> tuple[np.ndarray, dict[str, Any]]:
    """Apply the background mode to the whole RGBA source (Image or array); geometry is never changed."""
    pixels = np.array(source, dtype=np.uint8)
    alpha = pixels[..., 3]
    report: dict[str, Any] = {"background_mode": args.background_mode}
    if args.background_mode == "native_alpha":
        if alpha.min() == 255 or alpha.max() == 0:
            raise ValueError("native_alpha requires visible art and real transparent pixels; "
                             "use --background-mode opaque or chroma_key for this source.")
        return pixels, report
    if args.background_mode == "opaque":
        if alpha.min() != 255:
            raise ValueError("opaque mode cannot discard source transparency; use --background-mode native_alpha.")
        return pixels, report
    keyed = np.array(forge_matte.legacy_hard_key(pixels, args.threshold, args.edge_threshold))
    report.update({"keyer": "forge_matte.legacy_hard_key", "threshold": args.threshold,
                   "edge_threshold": args.edge_threshold})
    if args.despill_radius:
        keyed, despill = forge_matte.despill(keyed, "edge", args.despill_radius)
        report["despill_changed_px"] = despill["changed_px"]
    return keyed, report


# --------------------------------------------------------------------------- measurements

def edge_metrics(left: np.ndarray, right: np.ndarray) -> dict[str, Any]:
    """Compare corresponding edge pixels; ignore hidden RGB when alpha is zero."""
    a = left.astype(np.float64)
    b = right.astype(np.float64)
    jointly_visible = (a[:, 3] > 0) & (b[:, 3] > 0)
    rgb = float(np.abs(a[jointly_visible, :3] - b[jointly_visible, :3]).mean()) if jointly_visible.any() else None
    premultiplied_a = a[:, :3] * a[:, 3:4] / 255.0
    premultiplied_b = b[:, :3] * b[:, 3:4] / 255.0
    return {
        "alpha_mae": round(float(np.abs(a[:, 3] - b[:, 3]).mean()), 6),
        "visible_rgb_mae": round(rgb, 6) if rgb is not None else None,
        "jointly_visible_rows": int(jointly_visible.sum()),
        "premultiplied_rgb_mae": round(float(np.abs(premultiplied_a - premultiplied_b).mean()), 6),
    }


def measure_surface(alpha: np.ndarray, top: int, span: list[int], *, solid: int, tolerance: int,
                    decoration: int, measurable: bool = True) -> dict[str, Any]:
    """Measure the art's top in each collision column against the declared surface (MAP-07).

    The measured top is the first row whose alpha reaches ``solid``; rows of the decoration band
    (``decoration`` rows directly above the surface) are ignored, so grass tips may stand there.
    Art that rises more than ``tolerance`` px above the surface outside that band is a defect:
    actors standing on the declared surface would sink into it. Opaque pieces have no alpha
    silhouette, so ``measurable=False`` records the surface as not measured.
    """
    if not measurable:
        return {"declared_y_px": top, "measured": False,
                "reason": "opaque background mode: every pixel is solid, so the art's top cannot be measured",
                "measured_y_px_by_column": None, "max_rise_px": 0, "columns_above_tolerance": [],
                "decoration_band_px": decoration, "decoration_px": 0}
    x0, x1 = span
    solid_mask = alpha[:, x0:x1] >= solid
    rows = np.arange(alpha.shape[0])[:, None]
    band = (rows >= top - decoration) & (rows < top)
    structural = solid_mask & ~band
    found = structural.any(axis=0)
    first = np.where(found, structural.argmax(axis=0), -1)
    rising = found & (first < top - tolerance)
    measured = [int(value) if ok else None for value, ok in zip(first.tolist(), found.tolist())]
    rise = int((top - first[found]).max()) if found.any() else 0
    return {
        "declared_y_px": top,
        "measured": True,
        "measured_y_px_by_column": measured,
        "max_rise_px": max(0, rise),
        "columns_above_tolerance": (np.flatnonzero(rising) + x0).tolist(),
        "decoration_band_px": decoration,
        "decoration_px": int((solid_mask & band).sum()),
    }


# --------------------------------------------------------------------------- QA

def _check(identifier: str, status: str, value: Any, threshold: Any) -> dict[str, Any]:
    return {"id": identifier, "status": status, "value": value, "threshold": threshold}


def build_checks(pieces: list[dict[str, Any]], joins: list[dict[str, Any]], args: argparse.Namespace) -> list[dict]:
    coverage = {piece["id"]: piece["coverage"]["minimum_column_fraction"] for piece in pieces}
    missing = sum(len(piece["coverage"]["missing_surface_columns"]) for piece in pieces)
    rise = max(piece["surface"]["max_rise_px"] for piece in pieces)
    rising = sum(len(piece["surface"]["columns_above_tolerance"]) for piece in pieces)
    ratio = max(join["seam"]["seam_ratio"] for join in joins)
    seams = sum(join["seam"]["verdict"] == "seam" for join in joins)
    duplicates = sum(join["seam"]["verdict"] == "duplicate_edge" for join in joins)
    gated = args.max_seam_ratio is not None
    measured = all(piece["surface"]["measured"] for piece in pieces)
    checks = [
        _check("collision_band_coverage", "pass" if min(coverage.values()) >= args.min_column_coverage else "fail",
               coverage, args.min_column_coverage),
        _check("surface_row_solid", "pass" if missing == 0 else "fail", missing, 0),
        _check("surface_rise_px", ("pass" if rising == 0 else "fail") if measured else "skipped",
               rise if measured else None, args.surface_tolerance_px),
        _check("seam_ratio", ("fail" if gated else "warn") if seams else "pass", ratio,
               args.max_seam_ratio if gated else NOMINAL_SEAM_RATIO),
        _check("duplicate_edges", ("fail" if gated else "warn") if duplicates else "pass", duplicates, 0),
    ]
    for name, key in (("seam_rgb_mae", "visible_rgb_mae"), ("seam_alpha_mae", "alpha_mae")):
        limit = getattr(args, f"max_{name}")
        values = [join["full_edge"][key] for join in joins if join["full_edge"][key] is not None]
        worst = max(values) if values else None
        if limit is None:
            checks.append(_check(name, "skipped", worst, None))
        else:
            checks.append(_check(name, "fail" if worst is not None and worst > limit else "pass", worst, limit))
    return checks


# --------------------------------------------------------------------------- extraction

def validate_options(args: argparse.Namespace) -> None:
    if not 1 <= args.solid_alpha_threshold <= 255:
        raise ValueError("solid-alpha-threshold must be between 1 and 255.")
    if not math.isfinite(args.min_column_coverage) or not 0 < args.min_column_coverage <= 1:
        raise ValueError("min-column-coverage must be greater than 0 and at most 1.")
    for name in ("max_seam_rgb_mae", "max_seam_alpha_mae"):
        value = getattr(args, name)
        if value is not None and (not math.isfinite(value) or not 0 <= value <= 255):
            raise ValueError(f"{name.replace('_', '-')} must be between 0 and 255.")
    if args.max_seam_ratio is not None and (not math.isfinite(args.max_seam_ratio) or args.max_seam_ratio <= 0):
        raise ValueError("max-seam-ratio must be a positive number.")
    for name in ("threshold", "edge_threshold"):
        if not 0 <= getattr(args, name) <= 442:
            raise ValueError(f"{name.replace('_', '-')} must be between 0 and 442 (RGB Euclidean distance).")
    for name in ("surface_tolerance_px", "decoration_band_px"):
        if getattr(args, name) < 0:
            raise ValueError(f"{name.replace('_', '-')} must be zero or positive.")


def _join_pairs(pieces: list[dict[str, Any]]) -> list[tuple[dict[str, Any], dict[str, Any]]]:
    """Every join a strip can contain: left_cap|middle, middle|middle (all ordered pairs), middle|right_cap."""
    left, *middles, right = pieces
    return ([(left, middle) for middle in middles] + [(a, b) for a in middles for b in middles]
            + [(middle, right) for middle in middles])


def _preview_roles(pieces: list[dict[str, Any]]) -> list[dict[str, Any]]:
    left, *middles, right = pieces
    count = max(PREVIEW_MIDDLES, len(middles))
    return [left, *(middles[index % len(middles)] for index in range(count)), right]


def extract(args: argparse.Namespace) -> dict[str, Any]:
    validate_options(args)
    output = Path(args.output_dir).absolute()
    if os.path.lexists(output):
        raise FileExistsError(f"Output directory already exists: {output}")
    spec_bytes = Path(args.spec).read_bytes()
    try:
        spec = forge_core.parse_json(spec_bytes)  # D28: UTF-8 with an optional BOM
    except ValueError as exc:
        raise ValueError(f"Spec is not valid UTF-8 JSON: {exc}") from exc
    source, info = forge_core.load_rgba(args.input)
    pieces = validate_spec(spec, source.size)
    # Deliberately no trim, edge clean, bbox fit, resizing or anchor estimation.
    prepared, background = prepare_background(source, args)
    top, depth = spec["surface_y_px"], spec["collision_depth_px"]
    arrays: dict[str, np.ndarray] = {}
    issues: list[str] = []
    for piece in pieces:
        left, upper, right, bottom = piece["source_box"]
        pixels = prepared[upper:bottom, left:right].copy()
        pixels[pixels[..., 3] == 0] = 0  # published PNGs carry no RGB under alpha 0
        arrays[piece["id"]] = pixels
        band = pixels[top:top + depth, :, 3] >= args.solid_alpha_threshold
        coverage = band.mean(axis=0)
        x0, x1 = piece["collision_span_px"]
        bad_columns = (np.flatnonzero(coverage[x0:x1] < args.min_column_coverage) + x0).tolist()
        # Missing the declared top is a distinct defect, even if band coverage is relaxed.
        missing_top = (np.flatnonzero(~band[0, x0:x1]) + x0).tolist()
        surface = measure_surface(pixels[..., 3], top, piece["collision_span_px"], solid=args.solid_alpha_threshold,
                                  tolerance=args.surface_tolerance_px, decoration=args.decoration_band_px,
                                  measurable=args.background_mode != "opaque")
        piece.update({
            "path": f"{piece['id']}.png", "anchor_px": [0, top],
            "collision_rect_px": [x0, top, x1 - x0, depth],
            "surface_y_source_px": upper + top,
            "coverage": {
                "solid_fraction_by_column": coverage.tolist(),
                "minimum_column_fraction": float(coverage[x0:x1].min()),
                "insufficient_columns": bad_columns,
                "missing_surface_columns": missing_top,
                "non_solid_band_pixels": int((~band[:, x0:x1]).sum()),
            },
            "surface": surface,
        })
        if bad_columns or missing_top:
            issues.append(f"{piece['id']}: structural coverage fails in {len(bad_columns)} band columns; "
                          f"{len(missing_top)} declared surface columns are not solid.")
        if surface["columns_above_tolerance"]:
            issues.append(f"{piece['id']}: art rises up to {surface['max_rise_px']} px above the declared surface in "
                          f"{len(surface['columns_above_tolerance'])} collision columns (tolerance "
                          f"{args.surface_tolerance_px} px, decoration band {args.decoration_band_px} px); "
                          "actors would sink into it.")
    structural_passed = not issues

    single_middle = len(pieces) == 3
    joins = []
    warnings: list[str] = []
    for left_piece, right_piece in _join_pairs(pieces):
        left_pixels, right_pixels = arrays[left_piece["id"]], arrays[right_piece["id"]]
        left_edge, right_edge = left_pixels[:, -1, :], right_pixels[:, 0, :]
        full = edge_metrics(left_edge, right_edge)
        band_left, band_right = left_edge[top:top + depth], right_edge[top:top + depth]
        contact = ((band_left[:, 3] >= args.solid_alpha_threshold)
                   & (band_right[:, 3] >= args.solid_alpha_threshold))
        label = f"{left_piece['role']}->{right_piece['role']}"
        name = label if single_middle else f"{label} ({left_piece['id']}|{right_piece['id']})"
        seam = forge_core.edge_seam_report(left_pixels, right_pixels, left_start=left_piece["collision_span_px"][0],
                                           right_stop=right_piece["collision_span_px"][1], gate=args.max_seam_ratio)
        joins.append({"join": label, "left": left_piece["id"], "right": right_piece["id"], "full_edge": full,
                      "contact_band": {**edge_metrics(band_left, band_right),
                                       "y_range_px": [top, top + depth],
                                       "solid_contact_by_row": contact.tolist(),
                                       "solid_contact_fraction": float(contact.mean())},
                      "seam": seam})
        if args.max_seam_rgb_mae is not None and full["visible_rgb_mae"] is not None and full["visible_rgb_mae"] > args.max_seam_rgb_mae:
            issues.append(f"{name}: visible RGB edge MAE exceeds reviewed threshold {args.max_seam_rgb_mae}.")
        if args.max_seam_alpha_mae is not None and full["alpha_mae"] > args.max_seam_alpha_mae:
            issues.append(f"{name}: alpha edge MAE exceeds reviewed threshold {args.max_seam_alpha_mae}.")
        if seam["verdict"] == "seam":
            message = (f"{name}: normalised seam ratio {seam['seam_ratio']:.2f} exceeds "
                       f"{args.max_seam_ratio if args.max_seam_ratio is not None else NOMINAL_SEAM_RATIO}; "
                       "the join is sharper than the art around it.")
        elif seam["verdict"] == "duplicate_edge":
            message = (f"{name}: duplicated edge (join step {seam['seam']:.2f} vs neighbouring steps "
                       f"{seam['near_median']:.2f}); the texture stutters at every repeat.")
        else:
            continue
        (issues if args.max_seam_ratio is not None else warnings).append(message)
    if args.strict_qc and issues:
        raise ValueError("Platform strip QC failed:\n- " + "\n- ".join(issues))

    checks = build_checks(pieces, joins, args)
    status = "fail" if any(c["status"] == "fail" for c in checks) else (
        "warn" if any(c["status"] == "warn" for c in checks) else "pass")
    spec_ref = forge_core.file_ref(args.spec, output, sha256=forge_core.sha256_bytes(spec_bytes),
                                   size=len(spec_bytes))
    source_ref = forge_core.file_ref(args.input, output, sha256=info["sha256"], size=info["bytes"])
    payload: dict[str, Any] = {
        "schema": SCHEMA,
        "source": {**source_ref, "size": info["size"], "mode": info["source_mode"],
                   "bit_depth": info["bit_depth"], "conversion": info["conversion"]},
        "spec": {**spec_ref, "content": spec},
        "processing": {**background,
                       "despill_radius": args.despill_radius if args.background_mode == "chroma_key" else 0,
                       "geometry": "explicit_native_rectangles", "resized": False,
                       "trimmed": False, "aligned": False, "transparent_rgb": "zeroed"},
        "surface_y_px": top, "collision_depth_px": depth,
        "coordinate_contract": "Origin at crop top-left; +x right, +y down. Collision rect is [x,y,width,height]. "
                               "At uniform scale s, place crop at (collision_left-s*collision_span_px[0], "
                               "collision_top-s*surface_y_px). anchor_px is the visual left/top-surface anchor, "
                               "not necessarily the collision-left when a cap has outer padding. "
                               "Middle variants are interchangeable: any middle may follow the left cap, any "
                               "other middle or itself, and precede the right cap. "
                               "Collision is declared metadata; alpha coverage does not infer physical geometry.",
        "pieces": pieces, "joins": joins,
        "qc": {"passed": not issues, "structural_passed": structural_passed, "issues": issues,
               "warnings": warnings,
               "solid_alpha_threshold": args.solid_alpha_threshold,
               "min_column_coverage": args.min_column_coverage,
               "surface_tolerance_px": args.surface_tolerance_px,
               "decoration_band_px": args.decoration_band_px,
               "max_seam_ratio": args.max_seam_ratio,
               "max_seam_rgb_mae": args.max_seam_rgb_mae, "max_seam_alpha_mae": args.max_seam_alpha_mae,
               "seam_metrics_note": "seam.seam_ratio compares each join with the interior steps near it: about 1 "
                                    "or less looks like the art, well above 1 is a seam, a join much flatter than "
                                    "its neighbours duplicates an edge. Raw edge MAE values are 0..255 "
                                    "diagnostics; no seam is repaired and no aesthetic seamlessness is certified."},
    }
    with forge_core.staged_output(output) as stage:
        outputs = []
        for piece in pieces:
            forge_core.save_png(arrays[piece["id"]], stage / piece["path"])
            piece["sha256"] = forge_core.sha256_file(stage / piece["path"])
            outputs.append({"path": piece["path"], "sha256": piece["sha256"],
                            "bytes": (stage / piece["path"]).stat().st_size})
        x = 0
        placements = []
        strip = []
        for piece in _preview_roles(pieces):
            strip.append(arrays[piece["id"]])  # placed side by side: native RGBA values, no compositing
            placements.append({"role": piece["role"], "id": piece["id"], "left": x, "top": 0,
                               "size": list(piece["size"])})
            x += piece["size"][0]
        forge_core.save_png(np.concatenate(strip, axis=1), stage / PREVIEW_NAME)
        preview_sha = forge_core.sha256_file(stage / PREVIEW_NAME)
        payload["preview"] = {"path": PREVIEW_NAME, "size": [x, pieces[0]["size"][1]], "sha256": preview_sha,
                              "placements": placements}
        outputs.append({"path": PREVIEW_NAME, "sha256": preview_sha, "bytes": (stage / PREVIEW_NAME).stat().st_size})
        payload["qa"] = {
            "status": status,
            "method": "Exact rectangular crops of the keyed source. Collision band coverage and a solid declared "
                      "surface row per collision column; the first solid row above it (outside the decoration "
                      "band) against the surface tolerance; every join (left cap, each middle variant, right cap) "
                      "by premultiplied column steps normalised by the art's own steps near the join.",
            "notProven": [
                "artistic continuity, lighting or style match at joins (only pixel steps are measured)",
                "runtime behaviour: crossing every join, one-way platforms, slopes and pixel snapping",
                "that the declared collision depth matches the intended physics",
                "chroma keying quality beyond the legacy keyer rules",
            ],
            "checks": checks,
            "inputs": [source_ref, spec_ref],
            "outputs": outputs,
            "tool": {"name": TOOL_NAME, "version": TOOL_VERSION},
        }
        forge_core.write_json(stage / MANIFEST_NAME, payload)
    return payload


# --------------------------------------------------------------------------- CLI

def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    parser.add_argument("--input", required=True, type=Path,
                        help="Platform atlas: RGB(A), palette PNG with transparency, grey or grey+alpha.")
    parser.add_argument("--spec", required=True, type=Path,
                        help="JSON spec: surface_y_px, collision_depth_px and pieces (one left_cap, 1-16 middle "
                             "variants, one right_cap) with source_box and optional collision_span_px.")
    parser.add_argument("--output-dir", required=True, type=Path,
                        help="New directory only; strict QC runs before atomic no-clobber publication.")
    parser.add_argument("--background-mode", choices=BACKGROUND_MODES, default="chroma_key",
                        help="chroma_key removes magenta; native_alpha requires real transparency; opaque requires "
                             "opaque input. All keep the explicit rectangular crop geometry.")
    parser.add_argument("--threshold", type=int, default=100, help="Chroma: clear pixels this close to #FF00FF.")
    parser.add_argument("--edge-threshold", type=int, default=150,
                        help="Chroma: clear border-connected pixels this close to #FF00FF.")
    parser.add_argument("--despill-radius", type=int, choices=range(4), default=0,
                        help="Chroma only: remove magenta excess within this many px of transparency (0-3); "
                             "native_alpha and opaque ignore it. May neutralise legitimate purple at "
                             "transparent boundaries.")
    parser.add_argument("--solid-alpha-threshold", type=int, default=255,
                        help="Alpha required for the declared surface and collision band (1..255).")
    parser.add_argument("--min-column-coverage", type=float, default=1.0,
                        help="Minimum solid fraction in each collision-band column, (0,1]. The declared top row "
                             "must still be solid in every collision column.")
    parser.add_argument("--surface-tolerance-px", type=int, default=0,
                        help="How far the art's top may rise above the declared surface in a collision column.")
    parser.add_argument("--decoration-band-px", type=int, default=0,
                        help="Rows directly above the declared surface that may hold non-structural decoration "
                             "(grass tips); they are ignored when measuring the surface.")
    parser.add_argument("--max-seam-ratio", type=float,
                        help="Gate joins on the normalised seam ratio (try 1.25): a join sharper than the art "
                             "around it, or a duplicated edge, becomes a QC issue. Omitted: diagnostic only.")
    parser.add_argument("--max-seam-rgb-mae", type=float,
                        help="Legacy raw-equality gate: full-edge RGB MAE (0..255) for rows visible on both sides.")
    parser.add_argument("--max-seam-alpha-mae", type=float,
                        help="Legacy raw-equality gate: full-edge alpha MAE (0..255).")
    parser.add_argument("--strict-qc", action="store_true",
                        help="Fail without publishing if structural, surface or explicitly gated seam checks fail.")
    return parser


def _cli(argv: list[str] | None = None) -> int:
    args = build_parser().parse_args(argv)
    try:
        payload = extract(args)
    except (OSError, ValueError) as exc:
        message = f"file not found: {exc.filename}" if isinstance(exc, FileNotFoundError) and exc.filename else exc
        print(f"error: {forge_core.ascii_text(str(message))}", file=sys.stderr)
        return 1
    output = Path(args.output_dir).absolute()
    summary = {"output": str(output), "manifest": str(output / MANIFEST_NAME), "schema": payload["schema"],
               "status": payload["qa"]["status"],
               "qc": {key: payload["qc"][key] for key in ("passed", "structural_passed", "issues", "warnings")}}
    print(json.dumps(summary, ensure_ascii=True))
    if payload["qa"]["status"] == "fail":  # the report is published, and a failed QA status exits 4
        failed = [check["id"] for check in payload["qa"]["checks"] if check["status"] == "fail"]
        print(f"error: published with QA status fail: {', '.join(failed)}", file=sys.stderr)
        return forge_core.EXIT_PUBLISHED_FAIL
    return 0


def main(argv: list[str] | None = None) -> int:
    """The CLI under forge_core.run_cli (D26, D27): usage errors exit 2, runtime errors print
    'error: <message>' and exit 1, and no traceback reaches the user."""
    return forge_core.run_cli(_cli, argv)


if __name__ == "__main__":
    raise SystemExit(main())
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 468kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 319kUpdated Claude CodeCodexVerifiedInstall