gbc-atlas

gbc-atlas converts a native PNG atlas and JSON manifest into Game Boy Color 2bpp tiles, palette/cell maps, region and animation metadata, and C headers. It validates the approved pack, generates reproducible output, and can preserve unreferenced artifacts in configured recovery storage.

You can use it directly from a terminal or with an agent's assistance. Conversion requires neither an agent nor a running editor. It reads exact palette matches; it does not paint, resize, quantize, or repair artwork.

Requires Python 3.10+. The generated code uses standard fixed-width C types and is suitable for GBDK-2020. Pillow handles image reading; Python 3.10 also uses Tomli for TOML configuration.

Choose your starting path

Working without an agent: follow the getting-started guide. Try the complete synthetic pack first, then author/export your own artwork in Aseprite, prepare the manifest, review the revision, and record approval. No skill installation or MCP connection is required for this direct workflow.

Working with an agent: use the same installation and project configuration. Run gbc-atlas skill-path (or poetry run gbc-atlas skill-path) and have the agent read that directory's SKILL.md and referenced documents. Give it the project's art direction, asset brief, draft location, and runtime constraints. The bundled skill requires Aseprite MCP for agent drawing and editor review, plus approval of the concrete revision before production handoff. Load the installed skill directly or copy its entire directory into your client's skill location.

Both routes end with an approved pack and the same gbc-atlas handoff / check commands. Configure paths in [tool.gbc-atlas]; no consumer Python wrapper is needed. The game compiles the generated C and owns runtime loading, resource allocation, and gameplay tests.

Install and use

For a fresh C game project, follow the getting-started guide. It covers virtual environments or Poetry, a runnable synthetic pack, native C compilation, real artwork approval, Make/pre-commit integration, and recovery.

Install the package in your project's environment:

poetry add gbc-atlas==0.2.0

Add project configuration to pyproject.toml:

[tool.gbc-atlas]
manifests = ["assets/art/*/*.atlas.json"]
output = "src/generated"
types-header = "include/asset_types.h"

[tool.gbc-atlas.retention]
roots = ["assets/art", "assets/review"]
retire-to = "build/review/retired"

Then use the shared handoff directly, without a custom assets.py:

poetry run gbc-atlas validate assets/art/prop/prop.atlas.json
poetry run gbc-atlas handoff
poetry run gbc-atlas check

All paths resolve relative to the configuration file. Pass --config path/to/pyproject.toml when running elsewhere. Handoff validates every pack's recorded approval and output destinations before writes. With retention configured, it moves unreferenced artifacts into a unique recovery directory, preserving bytes and project-relative paths. The manifest and its declared files are retained; .gitkeep is preserved. Keep recovery storage ignored and inspect the printed path. Removing that storage discards its recovery copies. Omit the retention table to disable retirement entirely.

Check is read-only and verifies arrays, the type header, and configured retention. Use dedicated generated/managed directories. Symlinks, path escapes, overlapping managed/output/retirement directories, duplicate IDs, missing manifests, stale approval, and orphan generated C/headers fail before moving/writing files. Interrupted I/O can still leave a partial handoff; recovery files are not deleted. Handoff does not promote drafts or grant human approval.

• Complete project configuration
• Executable consumer example, tested using the installed CLI with synthetic assets and no consumer Python

For simple explicit-input conversion, the original commands remain available:

gbc-atlas generate --input assets/art --output src/generated
gbc-atlas check --input assets/art --output src/generated

These do not use project configuration or retire artwork. --input accepts one manifest or a recursively searched directory. Configured generate is also supported but refuses extras that require retirement; use handoff for those. Do not mix --config with explicit input/output arguments.

Python API

from pathlib import Path
from gbc_atlas import load_atlas, render_c, render_types, verify_approval

atlas = load_atlas(Path("assets/art/prop/prop.atlas.json"))
verify_approval(atlas)
outputs = render_c(atlas)  # dict[str, str], no writes
outputs["asset_types.h"] = render_types()

Atlas exposes manifest, digest, tiles, cell_tiles, palettes, regions, and dimensions (columns, rows). load_atlas performs technical validation and encoding; it does not require approval. render_c is also available for technical fixtures. Production workflows call verify_approval before rendering. The CLI enforces that gate. For Python-based integrations, load_project, plan_project, and apply_handoff expose the same configured handoff: apply_handoff(plan_project(load_project()), "handoff"). The command can also be generate or check. Treat a plan as a snapshot and do not modify inputs between planning and application. Do not mutate a loaded result before verifying/rendering it; reload after source or metadata changes. Invalid contracts raise ValueError.

The shared asset_types.h defines the C interface version 1. Generate or check it with the same package release as the arrays; do not maintain a divergent copy. Consumers with an existing type header may write render_types() to their include directory instead. render_c(..., generator_label="tools/assets.py") lets consumers preserve existing provenance comments when adopting the package.

Authoring skill and format

Run gbc-atlas skill-path to locate the release's bundled create-atlas skill. Copy that whole directory into your client's skill directory, or load its SKILL.md directly if supported. Reinstall it when upgrading the converter. A project-local adapter should identify art direction, paths, checks, budgets, and handoff policy. No global skill installation is performed automatically.

• Shared skill
• Manifest v1 and C interface

Package version, manifest version, and C interface version are separate contracts. The initial extraction preserves manifest v1's digest algorithm and encoding, including custom metadata and bound editable/review files. Digests detect drift; they cannot prove human approval or that the PNG matches the editable document. The converter currently limits each atlas to 256 cells and eight local palettes; these are converter ceilings, not whole-scene VRAM, palette, or OAM allocations.

Development

poetry install
poetry run ruff check .
poetry run ruff format --check .
poetry run python -m unittest discover -s tests -v
poetry build

Tests use synthetic artwork, exact 2bpp round trips, known digest/output fixtures, and native C compilation. Game-specific ROM and emulator tests remain in the consuming project. A C compiler is required for the compile test. Test an installed wheel too, so the C header and skill resources are verified as shipped.

Releases

Publishing a GitHub release runs .github/workflows/publish.yml. It validates the tag and package version, runs the reusable check workflow on Python 3.10 and 3.14, and publishes the tested wheel and source distribution to PyPI. Draft releases and tag pushes alone do not publish. A failed check blocks publishing.

Use Semantic Versioning: vMAJOR.MINOR.PATCH tags must match [project].version in pyproject.toml. Increment major for incompatible public API changes, minor for compatible features, and patch for compatible fixes. While the major version is zero, signal breaking changes with a minor bump. The public contract includes the documented Python API, CLI, manifest/digest rules, and generated C interface; format versions remain separate.

Prerelease tags use v1.2.3-alpha.1, v1.2.3-beta.1, or v1.2.3-rc.1 and must be marked as prereleases in GitHub. Their Python versions are 1.2.3a1, 1.2.3b1, and 1.2.3rc1, respectively. This supported SemVer subset maps directly to Python package versions. Other prerelease labels, build metadata, and leading zeros are rejected. Stable tags must not be marked as prereleases.

One-time setup before the first release:

1. Create a GitHub environment named pypi in cliffom/gbc-atlas.
2. Configure a PyPI pending trusted publisher for project gbc-atlas, owner cliffom, repository gbc-atlas, workflow publish.yml, and environment pypi. For an existing project, add the same configuration as a normal trusted publisher. Publishing uses OIDC, with no API-token secret. The separate publish job has id-token: write and receives only the already-tested distribution artifacts.

For each release, update the version and documentation/example/hook release pins (for example, poetry version 0.1.0), run the development checks above, commit the change, and publish the GitHub release for the matching tag (v0.1.0). For a release candidate use poetry version 0.2.0rc1 and a prerelease tagged v0.2.0-rc.1. Released versions are immutable; fixes get a new version. The workflow validates consistency but cannot determine whether a code change deserves a major, minor, or patch bump.