Metadata-Version: 2.4
Name: gbc-atlas
Version: 0.2.0
Summary: Deterministic palette-explicit Game Boy Color atlas to C conversion
Requires-Python: >=3.10
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: Pillow (>=12.3,<13)
Requires-Dist: tomli (>=2,<3) ; python_version < "3.11"
Project-URL: Documentation, https://github.com/cliffom/gbc-atlas/blob/v0.2.0/docs/GETTING_STARTED.md
Project-URL: Repository, https://github.com/cliffom/gbc-atlas
Description-Content-Type: text/markdown

# 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](https://github.com/cliffom/gbc-atlas/blob/v0.2.0/docs/GETTING_STARTED.md).
Try the complete synthetic pack first, then author/export your own artwork in
Aseprite, prepare the [manifest](https://github.com/cliffom/gbc-atlas/blob/v0.2.0/src/gbc_atlas/skills/create-atlas/references/format.md),
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](https://github.com/cliffom/gbc-atlas/blob/v0.2.0/docs/GETTING_STARTED.md).
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:

```sh
poetry add gbc-atlas==0.2.0
```

Add project configuration to `pyproject.toml`:

```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`:

```sh
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](https://github.com/cliffom/gbc-atlas/blob/v0.2.0/src/gbc_atlas/skills/create-atlas/references/project.md)
- [Executable consumer example](https://github.com/cliffom/gbc-atlas/blob/v0.2.0/examples/consumer/README.md), tested using the
  installed CLI with synthetic assets and no consumer Python

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

```sh
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

```python
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](https://github.com/cliffom/gbc-atlas/blob/v0.2.0/src/gbc_atlas/skills/create-atlas/SKILL.md)
- [Manifest v1 and C interface](https://github.com/cliffom/gbc-atlas/blob/v0.2.0/src/gbc_atlas/skills/create-atlas/references/format.md)

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

```sh
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](https://semver.org/spec/v2.0.0.html): `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](https://packaging.python.org/en/latest/specifications/version-specifiers/).
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](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
   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.

