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_anchor_layout.py

View on GitHub
#!/usr/bin/env python3
"""Repeat an accepted character into a fixed template: magenta RGB by default,
or verified native-alpha RGBA. This is a generation reference, not pose alignment.

The output PNG must be new; it is written beside its destination and published
without replacing anything. Prints a one-line JSON summary on success.
"""

from __future__ import annotations

import argparse
import importlib.util
import json
import os
import sys
import tempfile
from pathlib import Path
from typing import Sequence

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


def sprite_helpers():
    """Resolve the sibling processor without relying on cwd or sys.path."""
    name = "_anchor_layout_sprite_helpers"
    path = Path(__file__).resolve().with_name("generate2dsprite.py")
    cached = sys.modules.get(name)
    if cached is not None and Path(cached.__file__).resolve() == path:
        return cached
    spec = importlib.util.spec_from_file_location(name, path)
    if spec is None or spec.loader is None:
        raise ImportError(f"Cannot load required sprite helpers: {path}")
    module = importlib.util.module_from_spec(spec)
    sys.modules[name] = module
    try:
        spec.loader.exec_module(module)
    except BaseException:
        sys.modules.pop(name, None)
        raise
    return module


def build_anchor_layout(
    source: Image.Image,
    *,
    rows: int,
    cols: int,
    cell_width: int,
    cell_height: int,
    subject_height_ratio: float,
    subject_width_ratio: float,
    feet_ratio: float,
    threshold: int,
    edge_threshold: int,
    background_mode: str = "chroma_key",
    resampler: str = "lanczos",
) -> Image.Image:
    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 dimensions must be positive")
    for name, value in {
        "subject_height_ratio": subject_height_ratio,
        "subject_width_ratio": subject_width_ratio,
        "feet_ratio": feet_ratio,
    }.items():
        if not 0 < value < 1:
            raise ValueError(f"{name} must be between 0 and 1")

    if background_mode == "opaque":
        raise ValueError(
            "opaque is not supported for character anchor templates: an opaque rectangle "
            "does not isolate the subject. Supply verified native alpha or a chroma-key source."
        )
    helpers = sprite_helpers()
    resize_filter = helpers.resampling_filter(resampler)
    cleaned = helpers.prepare_background(source, background_mode, threshold, edge_threshold)
    bbox = cleaned.getchannel("A").getbbox()
    if not bbox:
        raise ValueError("input has no visible subject after background removal")
    subject = cleaned.crop(bbox)

    target_height = cell_height * subject_height_ratio
    target_width = cell_width * subject_width_ratio
    scale = min(target_height / subject.height, target_width / subject.width)
    out_width = max(1, int(round(subject.width * scale)))
    out_height = max(1, int(round(subject.height * scale)))
    subject = subject.resize((out_width, out_height), resize_filter)

    fill = (0, 0, 0, 0) if background_mode == "native_alpha" else (255, 0, 255, 255)
    canvas = Image.new("RGBA", (cols * cell_width, rows * cell_height), fill)
    feet_y = int(round(cell_height * feet_ratio))
    paste_x_in_cell = (cell_width - out_width) // 2
    paste_y_in_cell = feet_y - out_height
    if (paste_x_in_cell < 0 or paste_y_in_cell < 0
            or paste_x_in_cell + out_width > cell_width or paste_y_in_cell + out_height > cell_height):
        raise ValueError("subject ratios place the reference outside the cell")

    for row in range(rows):
        for col in range(cols):
            position = (col * cell_width + paste_x_in_cell, row * cell_height + paste_y_in_cell)
            if background_mode == "native_alpha":
                canvas.paste(subject, position)  # Copy RGBA directly; no alpha squaring or matte.
            else:
                canvas.alpha_composite(subject, position)
    return canvas


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    parser.add_argument("--input", type=Path, required=True)
    parser.add_argument("--rows", type=int, required=True)
    parser.add_argument("--cols", type=int, required=True)
    parser.add_argument("--cell-width", type=int, default=512)
    parser.add_argument("--cell-height", type=int, default=512)
    parser.add_argument("--subject-height-ratio", type=float, default=0.66)
    parser.add_argument("--subject-width-ratio", type=float, default=0.72)
    parser.add_argument("--feet-ratio", type=float, default=0.82)
    parser.add_argument("--threshold", type=int, default=100)
    parser.add_argument("--edge-threshold", type=int, default=150)
    parser.add_argument("--background-mode", choices=("chroma_key", "native_alpha", "opaque"), default="chroma_key",
                        help="Default chroma_key produces a magenta RGB template. native_alpha requires actual transparency and retains RGBA. opaque is explicitly rejected because no isolated subject can be located.")
    parser.add_argument("--resampler", choices=("nearest", "lanczos"), default="lanczos",
                        help="Default lanczos preserves legacy behavior; nearest keeps the pixel-art palette when resizing.")
    parser.add_argument("--output", type=Path, required=True,
                        help="New .png file; an existing file is never replaced.")
    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}")
    source, info = forge_core.load_rgba(args.input)
    layout = build_anchor_layout(
        source,
        rows=args.rows,
        cols=args.cols,
        cell_width=args.cell_width,
        cell_height=args.cell_height,
        subject_height_ratio=args.subject_height_ratio,
        subject_width_ratio=args.subject_width_ratio,
        feet_ratio=args.feet_ratio,
        threshold=args.threshold,
        edge_threshold=args.edge_threshold,
        background_mode=args.background_mode,
        resampler=args.resampler,
    )
    image = layout if args.background_mode == "native_alpha" else layout.convert("RGB")
    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), "mode": image.mode,
                      "background_mode": args.background_mode, "input_sha256": info["sha256"]}))
    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