Skip to content

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

generate2dsprite

Verified

Make game-ready 2D characters, creatures, props, icons and FX as master stills, sprite sheets or animation clips. Plan size, motion and finish; generate the art (image generation is the default, through generate2dmedia route_media.py - the API when a key is configured, else the local Codex or Grok CLI); approve one master still per character; then key, slice, register, scale, palette, QA and export frames for a game engine (Aseprite JSON, Godot SpriteFrames or Sprite3D). HD finish by default, pixel finish on request. Character animation is one image-to-video clip per action from the master (video2dsprite); sheets are for FX, icons and props. Use for sprites, masters, sheets, frame-by-frame animation and packaging frames from any source. Not for maps, tiles or backgrounds (generate2dmap), video clips (video2dsprite), code-drawn art (codeart2d, only on request) or calling an image or video API by itself (generate2dmedia).

FileKindSize
SKILL.mdskill md17.1 KB
agents/openai.yamlconfig529 B
references/action-recipes.mdmarkdown13.8 KB
references/animation-planning.mdmarkdown9.1 KB
references/character-animation.mdmarkdown3.9 KB
references/engine-export.mdmarkdown13.7 KB
references/frames-and-clips.mdmarkdown16.2 KB
references/hibit.mdmarkdown7.1 KB
references/master-still.mdmarkdown15.1 KB
references/modes.mdmarkdown6.1 KB
references/palette-and-pixels.mdmarkdown12.0 KB
references/pixel-looks.mdmarkdown20.5 KB
references/processing.mdmarkdown14.2 KB
references/prompt-rules.mdmarkdown9.8 KB
references/runtime-integration.mdmarkdown10.6 KB
references/schemas/common.schema.jsonconfig12.9 KB
references/schemas/host.schema.jsonconfig18.8 KB
references/schemas/sprite.schema.jsonconfig80.7 KB
references/video-handoff.mdmarkdown7.8 KB
scripts/assemble_frames.pyscript51.9 KB
scripts/build_animation_clips.pyscript73.9 KB
scripts/export_engine.pyscript65.1 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_palette.pyscript70.2 KB
scripts/forge_pixelgrid.pyscript74.0 KB
scripts/fx_pixelfx.pyscript26.0 KB
scripts/generate2dsprite.pyscript135.7 KB
scripts/hibit_fx.pyscript15.8 KB
scripts/make_anchor_layout.pyscript7.3 KB
scripts/make_layout_guide.pyscript6.1 KB
scripts/master_still.pyscript88.0 KB
scripts/palette_tool.pyscript40.6 KB
scripts/pixel_look.pyscript64.9 KB
scripts/pixel_reduce.pyscript15.2 KB
scripts/plan_guide.pyscript32.6 KB
scripts/scale_frames.pyscript37.8 KB
scripts/sheet_qc.pyscript70.3 KB

scripts/make_layout_guide.py

View on GitHub
#!/usr/bin/env python3
"""Create a layout-only guide image for sprite sheet generation.

Each cell gets its border, a blue safe frame inset by the safe margins and
dashed centre lines. Margins must satisfy 0 <= margin < half the cell, so a
safe frame never collapses or spills into a neighbouring cell. The output PNG
must be new; it is published without replacing anything, and a one-line JSON
summary is printed on success.
"""

from __future__ import annotations

import argparse
import json
import os
import sys
import tempfile
from pathlib import Path
from typing import Sequence

from PIL import Image
from PIL import ImageDraw

_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 copy)


def draw_dashed_line(
    draw: ImageDraw.ImageDraw,
    start: tuple[int, int],
    end: tuple[int, int],
    *,
    fill: str,
    width: int,
    dash: int,
    gap: int,
) -> None:
    x1, y1 = start
    x2, y2 = end
    if x1 == x2:
        for y in range(min(y1, y2), max(y1, y2), dash + gap):
            draw.line((x1, y, x2, min(y + dash, max(y1, y2))), fill=fill, width=width)
        return
    if y1 == y2:
        for x in range(min(x1, x2), max(x1, x2), dash + gap):
            draw.line((x, y1, min(x + dash, max(x1, x2)), y2), fill=fill, width=width)
        return
    raise ValueError("draw_dashed_line only supports horizontal or vertical lines")


def validate_layout(rows: int, cols: int, cell_width: int, cell_height: int,
                    safe_margin_x: int, safe_margin_y: int) -> None:
    """Refuse a grid or safe margin that cannot be drawn inside its own cell (S25)."""
    if rows <= 0 or cols <= 0:
        raise ValueError("--rows and --cols must be positive")
    if cell_width <= 0 or cell_height <= 0:
        raise ValueError("--cell-width and --cell-height must be positive")
    for flag, margin, size, axis in (("--safe-margin-x", safe_margin_x, cell_width, "width"),
                                     ("--safe-margin-y", safe_margin_y, cell_height, "height")):
        if not 0 <= 2 * margin < size:
            raise ValueError(f"{flag} must satisfy 0 <= margin < half the cell {axis} ({size} px cells allow "
                             f"0 to {(size - 1) // 2}); got {margin}")


def build_layout_guide(rows: int, cols: int, cell_width: int, cell_height: int, safe_margin_x: int,
                       safe_margin_y: int, label_cells: bool = False) -> Image.Image:
    validate_layout(rows, cols, cell_width, cell_height, safe_margin_x, safe_margin_y)
    width = cols * cell_width
    height = rows * cell_height
    image = Image.new("RGB", (width, height), "#f8f8f8")
    draw = ImageDraw.Draw(image)

    for row in range(rows):
        for col in range(cols):
            left = col * cell_width
            top = row * cell_height
            right = left + cell_width - 1
            bottom = top + cell_height - 1
            safe_left = left + safe_margin_x
            safe_top = top + safe_margin_y
            safe_right = right - safe_margin_x
            safe_bottom = bottom - safe_margin_y

            draw.rectangle((left, top, right, bottom), outline="#111111", width=4)
            draw.rectangle((safe_left, safe_top, safe_right, safe_bottom), outline="#2f80ed", width=3)

            center_x = left + cell_width // 2
            center_y = top + cell_height // 2
            draw_dashed_line(
                draw,
                (center_x, safe_top),
                (center_x, safe_bottom),
                fill="#b8b8b8",
                width=2,
                dash=14,
                gap=16,
            )
            draw_dashed_line(
                draw,
                (safe_left, center_y),
                (safe_right, center_y),
                fill="#b8b8b8",
                width=2,
                dash=14,
                gap=16,
            )

            if label_cells:
                draw.text((left + 12, top + 10), f"{row + 1},{col + 1}", fill="#777777")
    return image


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    parser.add_argument("--rows", type=int, required=True)
    parser.add_argument("--cols", type=int, required=True)
    parser.add_argument("--cell-width", type=int, default=384)
    parser.add_argument("--cell-height", type=int, default=384)
    parser.add_argument("--safe-margin-x", type=int, default=52, help="0 <= margin < half the cell width.")
    parser.add_argument("--safe-margin-y", type=int, default=52, help="0 <= margin < half the cell height.")
    parser.add_argument("--output", type=Path, required=True,
                        help="New .png file; an existing file is never replaced.")
    parser.add_argument(
        "--label-cells",
        action="store_true",
        help="Draw small row,column labels. Leave off for normal imagegen references.",
    )
    return parser


def _run(argv: Sequence[str] | None = None) -> int:
    args = build_parser().parse_args(argv)
    output = args.output.resolve()
    if output.suffix.lower() != ".png":
        raise ValueError(f"--output must be a .png file: {output.name}")
    if os.path.lexists(output):
        raise FileExistsError(f"Refusing to overwrite existing output: {output}")
    image = build_layout_guide(args.rows, args.cols, args.cell_width, args.cell_height,
                               args.safe_margin_x, args.safe_margin_y, args.label_cells)
    output.parent.mkdir(parents=True, exist_ok=True)
    with tempfile.TemporaryDirectory(prefix=f".{output.name}.", dir=output.parent) as temporary:
        staged = Path(temporary) / output.name
        forge_core.save_png(image, staged)
        forge_core.publish_file_no_replace(staged, output)
    print(json.dumps({"output": str(output), "size": list(image.size), "rows": args.rows, "cols": args.cols}))
    return 0


def main(argv: Sequence[str] | None = None) -> int:
    """Usage errors exit 2; other failures print one ``error: ...`` line and exit 1 (D26, D27)."""
    return forge_core.run_cli(_run, argv)


if __name__ == "__main__":
    raise SystemExit(main())
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall