Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
# 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}"