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/hibit_plate.py

View on GitHub
#!/usr/bin/env python3
"""Turn a flat painted background into a hi-bit pixel-art plate (forge_hibit, the hi-bit studio recipe).

The image model paints the scene as clean flat art (lineless shapes, at most 3 tones per material; never
ask it for "pixel art"). This tool makes the pixels:

  1. crop the painting to the plate aspect (--focus FX,FY places the window on the axis with room),
  2. one palette of --colors (default 14) colours, k-means++ on luminance-weighted RGB of the painting
     (or --palette, a palette file to share across the plates of one game),
  3. every plate pixel takes the palette colour covering most of its cell (a majority vote, never a blend),
  4. lone pixels take their neighbours' majority unless they contrast strongly (lights, stars and eyes stay),
  5. --smooth 3x3 majority passes (default 1) merge specks into the big shapes: the paper-cut look.

It writes a new --output-dir with plate.png (native size, default 480x270, opaque), plate-x<k>.png (a nearest
preview, default x4), palette.json (generate2dsprite.palette.v1), shade-maps.json (per colour the in-palette
colour one step darker and one step lighter, so a game can light and flash without new colours) and
plate.json (crop, palette, QA). Success prints one ASCII JSON line; errors print "error: ..." and exit 1; a plate published with QA status
fail exits 4.
Draw the plate with nearest sampling at whole-number zoom (480x270 x4 = 1920x1080).
"""
from __future__ import annotations

import argparse
import json
import math
import re
import sys
from pathlib import Path
from typing import Any, Sequence

import numpy as np
from PIL import Image

_HERE = str(Path(__file__).resolve().parent)
if _HERE not in sys.path:
    sys.path.insert(0, _HERE)
import forge_core  # noqa: E402  (this skill's vendored copies)
import forge_hibit as fh  # noqa: E402

PLATE_SCHEMA = "generate2dmap.hibit_plate.v1"
PALETTE_SCHEMA = "generate2dsprite.palette.v1"
SHADES_SCHEMA = "generate2dmap.hibit_shades.v1"
TOOL = {"name": "hibit_plate", "version": forge_core.FORGE_PACKAGE_VERSION}
DEFAULT_SIZE = (480, 270)
MIN_REDUCTION = 2.0      # a plate reduced less than 2x has too little to vote with; warn
NOT_PROVEN = [
    "That the painting reads as the intended scene at the plate size (look at plate-x4.png at gameplay scale).",
    "That characters and FX read against it: finish the sprites with their own palettes and look at a mock-up.",
    "Where the walkable ground is: the tool does not find the floor line in the art.",
]
METHOD = ("hibit_plate v1 (forge_hibit, the hi-bit studio recipe): cover crop of the painting to the plate aspect; "
          "one palette (k-means++ on luminance-weighted RGB, or a given palette); every source pixel indexed to its "
          "nearest palette colour and every plate pixel the colour covering most of its cell (majority, never a "
          "blend); forge_hibit.clean_isolated (lone pixels take the 4-neighbour majority unless 90 apart in "
          "luminance-weighted RGB); 3x3 majority smoothing passes; opaque; nearest preview only for review")


def _size(text: str) -> tuple[int, int]:
    match = re.fullmatch(r"\s*(\d+)\s*[xX,]\s*(\d+)\s*", text)
    if not match or min(int(match.group(1)), int(match.group(2))) < 8:
        raise argparse.ArgumentTypeError("use WIDTHxHEIGHT of at least 8 px, for example 480x270")
    return int(match.group(1)), int(match.group(2))


def _focus(text: str) -> tuple[float, float]:
    try:
        values = tuple(float(part) for part in text.split(","))
    except ValueError:
        values = ()
    if len(values) != 2 or not all(math.isfinite(v) and 0 <= v <= 1 for v in values):
        raise argparse.ArgumentTypeError("use FX,FY with both in 0..1, for example 0.5,0.7")
    return values


def read_palette_colours(path: Path) -> np.ndarray:
    """Colours of a palette.v1 JSON ({"colors": [{"hex": ...} | "#rrggbb", ...]}) or a .hex file (one per line);
    a colour named "outline" (a hibit character palette) is skipped."""
    if path.suffix.lower() == ".json":
        data = forge_core.read_json(path)
        entries = data.get("colors") if isinstance(data, dict) else data
        if not isinstance(entries, list):
            raise ValueError(f"{path.name} has no colour list")
        colours = []
        for entry in entries:
            if isinstance(entry, dict):
                if entry.get("name") == "outline":
                    continue
                entry = entry.get("hex")
            colours.append(fh.parse_hex(str(entry)))
    else:
        colours = [fh.parse_hex(line) for line in path.read_text(encoding="utf-8-sig").splitlines()
                   if line.strip() and not line.strip().startswith(";")]
    if not 2 <= len(colours) <= 254:
        raise ValueError(f"{path.name} needs 2..254 colours; it has {len(colours)}")
    return np.array(colours, np.uint8)


def palette_document(palette: np.ndarray, source: str) -> dict[str, Any]:
    return {"schema": PALETTE_SCHEMA, "colors": [{"hex": fh.hex_of(colour)} for colour in palette],
            "transparent_index": 255, "locked": False, "source": source}


def plate_qa(idx: np.ndarray, size: tuple[int, int], colors: int, reduction: float) -> list[dict[str, Any]]:
    height, width = idx.shape
    used = int(np.unique(idx).size)
    padded = np.pad(idx, 1, mode="edge")
    lone = ((padded[1:-1, 2:] != idx) & (padded[1:-1, :-2] != idx) & (padded[2:, 1:-1] != idx)
            & (padded[:-2, 1:-1] != idx))
    checks = [
        {"id": "size", "status": "pass" if (width, height) == tuple(size) else "fail", "value": [width, height],
         "threshold": list(size)},
        {"id": "opaque", "status": "pass" if bool((idx >= 0).all()) else "fail",
         "value": int((idx < 0).sum()), "threshold": 0},
        {"id": "colours", "status": "pass" if used <= colors else "fail", "value": used, "threshold": colors},
        {"id": "lone-pixels", "status": "skipped", "value": round(float(lone.mean()), 5), "threshold": None,
         "note": "share of plate pixels with no 4-neighbour of their colour (kept features: lights, stars, eyes)"},
        {"id": "reduction", "status": "pass" if reduction >= MIN_REDUCTION else "warn", "value": round(reduction, 3),
         "threshold": MIN_REDUCTION, "note": "painting px per plate px; under 2x the majority has little to vote"},
    ]
    return checks


def cmd_plate(args: argparse.Namespace) -> dict[str, Any]:
    if args.colors is not None and args.palette is not None:
        raise ValueError("--colors learns a palette; drop it when --palette is given")
    colors = fh.PLATE_COLORS if args.colors is None else int(args.colors)
    if not 2 <= colors <= 254:
        raise ValueError("--colors must be 2..254")
    if not 0 <= args.smooth <= 4:
        raise ValueError("--smooth must be 0..4 passes")
    if not 1 <= args.preview_scale <= 8:
        raise ValueError("--preview-scale must be 1..8")
    image, info = forge_core.load_rgba(args.input)
    rgba = np.asarray(image)
    warnings = []
    if (rgba[..., 3] < 255).any():
        warnings.append("the painting has transparent pixels; they are read as their RGB (a plate is opaque)")
    out_w, out_h = args.size
    crop = fh.plate_crop(rgba.shape[1], rgba.shape[0], out_w, out_h, args.focus[0], args.focus[1])
    given = None if args.palette is None else read_palette_colours(args.palette)
    idx, palette = fh.pixelize_plate(rgba[..., :3], out_w, out_h, colors=colors, smooth=args.smooth, seed=args.seed,
                                     x_frac=args.focus[0], y_frac=args.focus[1], palette=given)
    used = np.unique(idx)
    if given is None:   # drop learned colours the plate does not use, keep the dark -> light order
        remap = np.full(len(palette), -1, np.int64)
        remap[used] = np.arange(len(used))
        idx, palette = remap[idx].astype(np.int32), palette[used]
    rendered = fh.render(idx, palette)[..., :3]
    dark, light = fh.shade_maps(palette)
    reduction = (crop[2] - crop[0]) / out_w
    checks = plate_qa(idx, (out_w, out_h), len(palette) if given is not None else colors, reduction)
    for check in checks:
        if check["status"] == "warn":
            warnings.append(f"{check['id']}: {check['value']} (threshold {check['threshold']})")
    final = Path(args.output_dir)
    source_text = (f"hibit_plate: k-means++ on luminance-weighted RGB of {args.input.name}, {colors} colours, seed "
                   f"{args.seed}" if given is None else f"hibit_plate: the colours of {args.palette.name}")
    with forge_core.staged_output(final) as stage:
        forge_core.save_png(Image.fromarray(rendered, "RGB").convert("RGBA"), stage / "plate.png")
        preview_name = f"plate-x{args.preview_scale}.png"
        zoomed = np.repeat(np.repeat(rendered, args.preview_scale, axis=0), args.preview_scale, axis=1)
        forge_core.save_png(Image.fromarray(zoomed, "RGB").convert("RGBA"), stage / preview_name)
        forge_core.write_json(stage / "palette.json", palette_document(palette, source_text))
        shades = {"schema": SHADES_SCHEMA, "colors": [fh.hex_of(c) for c in palette],
                  "dark": dark.tolist(), "light": light.tolist(),
                  "note": "dark[i] / light[i]: the palette index one step darker / lighter than colour i "
                          "(itself when none is close); light a plate or flash a sprite without new colours"}
        forge_core.write_json(stage / "shade-maps.json", shades)
        outputs = [forge_core.file_ref(stage / name, stage)
                   for name in ("plate.png", preview_name, "palette.json", "shade-maps.json")]
        inputs = [forge_core.file_ref(args.input, final, sha256=info["sha256"])]
        if args.palette is not None:
            inputs.append(forge_core.file_ref(args.palette, final))
        status = "fail" if any(c["status"] == "fail" for c in checks) else "needs-visual-review"
        record = {
            "schema": PLATE_SCHEMA, "tool": dict(TOOL), "hibit": fh.SCHEMA,
            "source": {**inputs[0], "size": [int(rgba.shape[1]), int(rgba.shape[0])]},
            "size": [out_w, out_h], "crop": list(crop), "focus": list(args.focus),
            "colors": int(len(palette)), "palette": [fh.hex_of(c) for c in palette], "paletteGiven": given is not None,
            "seed": args.seed, "smooth": args.smooth, "previewScale": args.preview_scale,
            "engine": {"sampling": "nearest", "pixelArt": True,
                       "note": "draw at whole-number zoom (480x270 x4 = 1920x1080); never filter the plate"},
            "warnings": warnings,
            "qa": {"status": status, "method": METHOD, "notProven": NOT_PROVEN, "checks": checks,
                   "inputs": inputs, "outputs": outputs, "tool": dict(TOOL)},
        }
        forge_core.write_json(stage / "plate.json", record)
    final = final.resolve()
    return {"status": status, "output": str(final), "plate": str(final / "plate.png"),
            "preview": str(final / preview_name), "palette": str(final / "palette.json"),
            "metadata": str(final / "plate.json"), "size": [out_w, out_h], "colors": int(len(palette)),
            "crop": list(crop), "_warnings": warnings}


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(prog="hibit_plate.py", description=__doc__,
                                     formatter_class=argparse.RawDescriptionHelpFormatter)
    verbs = parser.add_subparsers(dest="verb", required=True)
    plate = verbs.add_parser("plate", help="a flat painting -> a hi-bit pixel-art plate (480x270 by default)",
                             description="Crop, palette, majority downsample, cleanup and paper-cut smoothing of a "
                                         "flat painted background; writes plate.png, a preview, palette.json, "
                                         "shade-maps.json and plate.json into a new folder.")
    plate.add_argument("--input", type=Path, required=True, help="the flat painted background (PNG, JPEG or WebP)")
    plate.add_argument("--output-dir", type=Path, required=True, help="new folder for the plate (must not exist)")
    plate.add_argument("--size", type=_size, default=DEFAULT_SIZE, metavar="WxH",
                       help="native plate size (default 480x270; x4 = 1920x1080)")
    plate.add_argument("--colors", type=int, help=f"palette size learned from the painting (default {fh.PLATE_COLORS})")
    plate.add_argument("--palette", type=Path, help="palette file (palette.v1 .json or .hex) shared by a game's plates")
    plate.add_argument("--focus", type=_focus, default=(0.5, 0.5), metavar="FX,FY",
                       help="where the crop window sits on the axis with room, 0..1 (default 0.5,0.5; 0.5,1 keeps "
                            "the bottom of a tall painting)")
    plate.add_argument("--smooth", type=int, default=1, help="3x3 majority passes, the paper-cut look (default 1)")
    plate.add_argument("--seed", type=int, default=0, help="k-means++ seed (default 0)")
    plate.add_argument("--preview-scale", type=int, default=4, help="nearest preview zoom (default 4)")
    plate.set_defaults(func=cmd_plate)
    return parser


def _cli(argv: Sequence[str] | None = None) -> int:
    args = build_parser().parse_args(argv)
    summary = args.func(args)
    for warning in summary.pop("_warnings"):
        print(f"warning: {forge_core.ascii_text(warning)}", file=sys.stderr)
    print(json.dumps(summary, ensure_ascii=True))
    return forge_core.EXIT_PUBLISHED_FAIL if summary["status"] == "fail" else 0


def main(argv: Sequence[str] | None = None) -> int:
    """The CLI under forge_core.run_cli (D26, D27)."""
    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: 469kUpdated Claude CodeCodexVerifiedInstall
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: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated 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: 321kUpdated Claude CodeCodexVerifiedInstall