godot-asset-pipeline-doctor 0.1.5

CI-friendly PNG and Godot .import checks for pixel-art and mobile asset pipelines.

Godot Asset Pipeline Doctor

CI-friendly PNG and Godot .import checks for pixel-art and mobile asset pipelines.

Use this before merging sprites, UI art, icons, backgrounds, or other PNG-heavy changes. It checks for import settings and texture shapes that commonly cause blurry pixel art, color fringes, or mobile memory surprises.

The tool is designed for generic Godot projects, including private commercial games. Public examples use placeholder project names and do not require publishing project-specific content. It does not need the Godot editor and does not run project scripts.

What It Catches

• Missing Godot .import metadata next to PNG assets.
• Mipmaps enabled on pixel-art profile assets.
• Alpha-border fixing disabled on transparent assets.
• Fully transparent edge pixels that still contain RGB color data.
• Large textures that are risky for Android/mobile memory budgets.
• Very large texture dimensions that may exceed conservative device limits.
• Unexpectedly large palettes in pixel-art folders.
• Sprite manifest dimension mismatches and out-of-bounds anchors.

Install

From a local checkout:

python -m pip install -e .

From PyPI:

python -m pip install godot-asset-pipeline-doctor

Quick Start

Scan a Godot project with the default profile:

godot-asset-doctor C:\Projects\ArcadePrototype

Strict pixel-art check:

godot-asset-doctor C:\Projects\ArcadePrototype --profile pixel-2d --fail-on warning

Android/mobile check with JSON output:

godot-asset-doctor C:\Projects\ArcadePrototype --profile android-mobile --format json --output asset-report.json

Exclude generated or vendor folders:

godot-asset-doctor C:\Projects\ArcadePrototype --exclude "addons/vendor/**" --exclude "assets/generated/**"

Validate a sprite manifest:

godot-asset-doctor manifest check sprite-manifest.json --project C:\Projects\ArcadePrototype --format json --output reports\sprite-manifest.json

Run through Python after installing the package:

python -m godot_asset_doctor examples\tiny-godot-project --fail-on none

Real Workflow: Review New Art Before A Merge

Run a strict pixel-art scan when a pull request changes assets/, sprites/, or ui/:

godot-asset-doctor . --profile pixel-2d --fail-on warning --format json --output reports\asset-doctor.json

Use the findings to catch:

• pixel art imported with mipmaps enabled;
• transparent sprite edges that can show colored fringes;
• missing .import files that mean assets have not been opened by Godot yet;
• unexpectedly large textures before they land in the main branch.
• sprite anchors that fall outside the source PNG bounds.

For Android-focused review, switch profile:

godot-asset-doctor . --profile android-mobile --fail-on error --format sarif --output reports\asset-doctor.sarif

Profiles

Profile	Use Case
default	Balanced local scan; combines pixel and mobile warnings.
pixel-2d	Sprites, UI, icons, tiles, and crisp 2D assets.
android-mobile	Mobile release review, especially large textures and missing import data.

Exit Codes

Flag	Behavior
--fail-on none	Always exits 0 unless the CLI itself errors.
--fail-on error	Exits 1 if any error is found. This is the default.
--fail-on warning	Exits 1 if any warning or error is found. Useful for strict CI.

Config File

Create .godot-asset-doctor.toml in the project root:

profile = "pixel-2d"
format = "json"
fail_on = "warning"
output = "asset-report.json"
exclude = ["addons/vendor/**", "assets/generated/**"]
max_texture_dimension = 4096
large_texture_mb = 16
max_palette_colors = 256

Then run:

godot-asset-doctor C:\Projects\ArcadePrototype

CLI flags override config values. Use these thresholds when your project needs stricter mobile budgets or a looser palette limit for UI art. See docs/CONFIGURATION.md.

Example Output

Godot Asset Pipeline Doctor
Root: C:\Projects\ArcadePrototype
Profile: pixel-2d
Assets: 18 | Issues: 3 | Errors: 0 | Warnings: 3

[WARNING] transparent_edge_rgb: C:\Projects\ArcadePrototype\assets\player.png
  4 fully transparent edge pixel(s) carry non-black RGB values.
  Suggestion: Clean transparent RGB data or enable alpha-border fixing to reduce fringe artifacts.

Documentation

• Rule reference
• Configuration
• Pixel-art workflow
• Mobile texture guide
• Sprite manifests
• CI usage
• Troubleshooting

Tests

python -m unittest discover -s tests -v

CI

The included GitHub Actions workflow installs the package and runs the test suite on Python 3.11, 3.12, and 3.13.

In a project CI job, install from PyPI and keep the report as an artifact:

- run: python -m pip install godot-asset-pipeline-doctor
- run: godot-asset-doctor . --profile android-mobile --format json --output reports/asset-doctor.json

Design Notes

• The scanner does not need a Godot binary.
• The scanner does not execute project scripts.
• The scanner does not upload files or contact external services.
• Default scans ignore common non-asset artifact folders such as docs, logs, and test-results.
• JSON reports can include local paths, so review them before sharing publicly.

License

MIT. See LICENSE.