Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

6.5 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Domain of each pipeline module — the single source for the package taxonomy.

Used at runtime to run a pipeline step as `-m sprite_gen.<domain>.<step>` and by
the reorg tooling. Keep in sync with the physical folder layout.
"""

MODULE_DOMAIN = {
    'guide': 'workflow',
    'preferences': 'workflow',
    'capabilities': 'workflow',
    'runio': 'spec',
    'assets': 'spec',
    'tile': 'background',
    'shadow': 'effects',
    'motion': 'qa',
    'handed': 'qa',
    'holds': 'qa',
    'render': 'scene',
    'inspect_scene': 'scene',
    'model': 'scene',
    'layout': 'spec',
    'migrate_request': 'spec',
    'migrate_breathe': 'spec',
    'video': 'gen',
    'gen_set': 'gen',
    'pixel_draw': 'gen',
    'logo': 'gen',
    'canvas': 'video',
    'frames': 'video',
    'loop': 'video',
    'batch': 'video',
    'align': 'video',
    'follow': 'video',
    'follow_inspect': 'video',
    'sway': 'video',
    'sway_inspect': 'video',
    'set_sheet': 'video',
    'stop': 'video',
    'chain': 'video',
    'compare': 'video',
    'restoration': 'video',
    'source': 'video',
    'rife_install': 'video',
    'clip_prompt': 'video',
    'face_pack': 'video',
    'face_bake': 'video',
    'prepare': 'gen',
    'extract': 'frames',
    'cutout': 'frames',
    'segment': 'frames',
    'slice_sheet': 'frames',
    'logo_matte': 'frames',
    'alpha_floor': 'frames',
    'check_visible_magenta': 'frames',
    'unpack_atlas': 'frames',
    'curation': 'curate',
    'anchor': 'curate',
    'compose_atlas': 'compose',
    'compose_cycle': 'compose',
    'compose_gif': 'compose',
    'export_pngs': 'compose',
    'export_aseprite': 'compose',
    'breathe': 'effects',
    'anatomy': 'effects',
    'recolor': 'effects',
    'interpolate': 'effects',
    'reroll': 'effects',
    'inspect': 'qa',
    'score': 'qa',
    'correction_loop': 'qa',
    'preview': 'qa',
    'serve_curation': 'serve',
    'serve_compose': 'serve',
    'gif_utils': 'util',
    'resample': 'util',
}


# Display order and one-line meaning of each domain — the taxonomy the CLI help and the
# scripts map enumerate from (the docs classification is catalogued in docs/README.md and
# tested against the file set). Adding a module to MODULE_DOMAIN puts it in its group;
# nothing else needs a hand edit.
DOMAINS: list[tuple[str, str]] = [
    ("workflow", "Start here — image or sprite choices, access checks, saved defaults"),
    ("gen", "Generation — prepare a run, generate stills / rows / clips"),
    ("video", "Video → loop — canvas, keyed frames, seamless cycle, batch"),
    ("frames", "Frames — chroma/white removal, row extraction, sheet slicing, atlas unpacking"),
    ("curate", "Curation — direction anchors and the curation sidecar"),
    ("compose", "Compose — runtime atlas, cycles, GIFs, exports"),
    ("background", "Background — repeating painted strips and textures"),
    ("effects", "Post-processing — recolor, breathing, interpolation, projected shadows"),
    ("scene", "Scene — asset placement, camera, lighting, rendering and inspection"),
    ("qa", "QA — motion/contact measurements, inspect, score, preview, bounded correction loop"),
    ("serve", "Webviews — curation and composition canvases"),
    ("spec", "Spec — read-only assets, request migrations and run I/O"),
    ("util", "Utilities"),
]
DOMAIN_ORDER = [d for d, _ in DOMAINS]
DOMAIN_TITLE = dict(DOMAINS)


# Ordered sprite pipelines. Standalone tool groups and scene workflow are separate.
# The CLI help, the docs index and the README
# pipeline table are checked against THIS list; a verb named here must exist as a verb.
PIPELINES: list[dict[str, object]] = [
    {"key": "A", "name": "atlas rows", "verbs": ["prepare", "gen", "gen-set", "extract", "compose-atlas", "curation"],
     "chain": "prepare → gen (or gen-set) → extract → compose-atlas; optional curation and recompose", "doc": "docs/run-contract.md"},
    {"key": "B", "name": "video → loop", "verbs": ["video-canvas", "video", "video-prompt", "video-frames", "video-loop", "video-set", "video-cycle-align", "video-sway", "video-sway-inspect", "video-set-sheet", "video-stop", "handed-check"],
     "chain": "video-canvas → video (or video-prompt + a video MCP) → video-frames → video-loop, or video-set; video-cycle-align across a set; video-sway for a soft part's sway, the Sway layer (video-sway-inspect shows every cell of it and moves nothing; old names video-follow, video-follow-inspect); video-set-sheet lays a set's directions on one sheet on one ground line; video-stop cuts a walk or run's stop from its clip's start played backwards; handed-check for an item on one side", "doc": "docs/video-pipeline.md"},
]

TOOL_GROUPS: list[dict[str, object]] = [
    {"key": "C", "name": "utilities", "verbs": ["cutout", "slice-sheet", "unpack-atlas"],
     "chain": "cutout · slice-sheet · unpack-atlas (each stands alone)", "doc": "docs/sheet-slicing.md"},
    {"key": "D", "name": "post-processing", "verbs": ["recolor", "recolor-palette", "breathe", "export-pngs", "export-aseprite"],
     "chain": "recolor · breathe · export-pngs · export-aseprite", "doc": "docs/recolor.md"},
    {"key": "E", "name": "asset tools", "verbs": ["background-tile", "shadow", "inspect-motion", "inspect-holds"],
     "chain": "background-tile · shadow · inspect-motion · inspect-holds (independent; no generation required)", "doc": "docs/asset-tools.md"},
]

WORKFLOWS: list[dict[str, object]] = [
    {"key": "S", "name": "scene", "verbs": ["scene-render", "scene-inspect"],
     "chain": "existing assets + scene spec → scene-render; scene-inspect for measurements",
     "doc": "docs/scene.md"},
]


def domain_of(module_path: str) -> str:
    """Domain of a fully-qualified module path (`sprite_gen.video.loop` → `video`).

    A domain package itself (`sprite_gen.gen`, whose `run` is the `gen` verb) is its own
    domain. Anything else must be a MODULE_DOMAIN entry — an unknown module is an error,
    not a silent "misc" bucket, so the taxonomy stays a single table.
    """
    parts = module_path.split(".")
    if len(parts) == 2 and parts[0] == "sprite_gen" and parts[1] in DOMAIN_TITLE:
        return parts[1]
    leaf = parts[-1]
    if leaf not in MODULE_DOMAIN:
        raise KeyError(f"{module_path} is not in sprite_gen._modules.MODULE_DOMAIN — add it there (single taxonomy table)")
    return MODULE_DOMAIN[leaf]


def qualified(name: str) -> str:
    """Fully-qualified module path for a pipeline step basename."""
    return f"sprite_gen.{MODULE_DOMAIN[name]}.{name}"