English · 한국어 · Version 0.7.0 · Apache License 2.0
Audit the grid, colors, and transparency of static PNG pixel art.
Pixelwright checks actual image pixels against a declared quality profile and produces a JSON verdict and visual diagnostics. Use it to review characters, items, and UI icons, or to apply the same acceptance rules to a batch of assets. Its Python tools also work through the shared AI skill for GPT-powered hosts and Claude.
Static PNG inspection is the main feature. Game contracts keep a whole game on one pixel size and style, from 1× assets to screenshots of the running game. Generation, repair, palette editing, layers, and animation workflows are currently presented as features in development.
| Check | What it verifies |
|---|---|
| Dimensions and grid | The PNG matches the logical canvas multiplied by one integer scale on both axes, with the origin at (0, 0). |
| Square cells | Every sample within each declared cell has exactly the same RGBA value. |
| Palette | The actual visible RGB count stays within the budget; an optional palette constrains exact RGBA values. |
| Transparency | Alpha follows the declared policy, including how hidden RGB under transparent pixels is handled. |
| Evidence | A JSON report, source/profile hashes, grid previews, and complete invalid-cell masks record the result. |
| Batch and CI | Multiple PNGs share one profile, with exit codes for acceptance, QA failures, and execution errors. |
Inspection preserves the input. Declare the intended grid before checking it. A technical PASS applies to those rules; silhouette, readability, and artistic quality still need visual review. Input must be a static PNG decodable into RGBA8. See the full quality contract for format limits and output details.
Requires Python 3.12+, Pillow, and NumPy. Run from the repository root:
git clone https://github.com/arden-deq/pixelwright.git
cd pixelwright
python -m venv .venvActivate the environment:
# macOS / Linux
source .venv/bin/activate# Windows PowerShell
.\.venv\Scripts\Activate.ps1Install the dependencies and inspect the included knight PNG:
python -m pip install -r pixelwright/requirements.txt
python pixelwright/scripts/pixelwright.py inspect docs/examples/knight/4px/rendered.png --profile docs/examples/knight/4px/profile.json --out-dir runs/knight-4px-audit-v1This checks an existing 1024×1536 PNG against a 256×384 logical canvas at 4× scale, with 31 visible colors plus transparency. It does not generate or repair an image. Open report.json and grid_overlay.png in the output directory alongside the input PNG. Output directories must be new or empty; use a different name for each run.
Both PNGs are 1024×1536 and use the same 32 RGBA colors including transparency. These are measured results from the saved images:
| Example | Logical canvas | Cell size | Uniform cells | Result |
|---|---|---|---|---|
| Fine dots | 256×384 | 4×4 px | 98,304 / 98,304 | PASS report |
| Larger dots | 128×192 | 8×8 px | 24,576 / 24,576 | PASS report |
Both inspections found zero nonuniform cells, partially transparent pixels, or samples outside the declared palette. Independent 4 px and 8 px records also confirm exact nearest-neighbor enlargement of the native images.
View the complete 4 px grid or 8 px grid. Grid lines are separate diagnostic overlays; use the underlying PNG's report for exact color measurements. The example files preserve the profiles, source/derived images, and verification records. These results certify the inspected technical constraints, not automatic artistic acceptance.
Save the intended rules as profile.json:
{
"schema_version": 1,
"name": "24px game items",
"logical_size": "24x24",
"scale": 8,
"max_colors": 10,
"alpha": "binary",
"transparent_rgb": "exact"
}This requires a 192×192 PNG with 8×8 px cells, at most 10 visible RGB colors, and alpha values of 0 or 255. Strict profiles require a scale of at least 2. transparent_rgb: "exact" checks hidden RGB too; choose "visible" explicitly to normalize alpha-zero RGB during inspection. Optional allowed_palette restricts complete RGBA values. Adjacent cells can share a color and form irregular shapes.
Inspect one image or a batch under the same profile:
python pixelwright/scripts/pixelwright.py inspect input.png --profile profile.json --out-dir runs/audit-v1
python pixelwright/scripts/pixelwright.py batch item-a.png item-b.png --profile profile.json --out-dir runs/batch-v1| Exit code | Meaning |
|---|---|
0 |
All declared technical checks PASS. |
2 |
At least one QA result is FAIL or REVIEW. |
1 |
An input, profile, or execution error occurred. |
Geometry failures stop cell-color acceptance. Inspect the status, exact violation counts, and previews together. Each single-image audit writes report.json and grid diagnostics; a batch adds batch.json and separate numbered directories. Full artifact descriptions are in the quality contract.
New in 0.7.0. A profile checks one PNG; a game contract (game.json) declares the shared grid, palette, sizes and style brief for a whole game. Technical checks and visual art review have separate results.
Full-size PNG: 2304×1728, 6×. Wide screens use a 2× preview and narrower screens use 1×; all exports preserve the same native dots.
The production sizes and layout were fixed before drawing: 32×32 tiles, 32×64 characters (1×2 tiles), a 192×128 castle (6×4 tiles), and a 384×288 map (12×9 tiles). Every asset is authored directly as native indexed cells using one 64-color palette plus transparency. Eyes, highlights, eyebrows and mouths are designed at their final game resolution. Editable sources and validation record document the native workflow.
The character close-up enlarges the same native cells by 6× (4×, 3× or 2× in smaller windows). Independent assets · Actual checker grid.
These face crops preserve the authored 20×18 facial regions, 4×6 eyes and 5×3 mouth layouts. The expression preservation check compares authored cells, native PNGs, the composed map and actual browser pixels. It does not score artistic quality. This production path uses no high-resolution raster reduction or automatic palette remapping; the previous generated concepts remain historical references.
Thirteen independent 1× PNGs compose the 384×288 field: three characters, a 192×128 castle, eight 32×32 terrain variants and a 28×6 contact shadow. The final 4× assets, 6× character close-up and 2× field preview are also audited as enlarged PNGs. Visual review evaluates readability and coherence separately from technical PASS.
Run python -m http.server 8000 from the repository root and open the SD field demo. Arrow keys translate the static knight sprite; R resets and F toggles fullscreen. This is a composition example without walking animation frames. The browser verification covers asset loading, movement, collision, depth ordering and integer scaling. The actual browser image matches the independent native composition and passes the screen check.
The contract fixes:
- Screen: one base resolution (384×288 here), enlarged by whole numbers, with letterbox bars filling the rest of the window.
- Pixel size: every sprite, tile, effect, UI element and font drawn at 1×, so one image pixel is one game pixel.
- Colors and sizes: palette ramps, color budget, transparency and a canvas per kind of asset.
- Style brief: perspective, light direction, shading, outline, dithering, anti-aliasing, mood and reference assets. Artistic execution still needs visual review.
- Runtime: font size, animation rate, rotation policy, effect blending and engine.
brief turns the contract into rules for artists and image-generation prompts. The example game declares every field.
python pixelwright/scripts/pixel_game.py brief --contract pixelwright/examples/demon-castle-sd/game.json
python pixelwright/scripts/pixel_game.py asset pixelwright/examples/demon-castle-sd/build/knight.png --category character --contract pixelwright/examples/demon-castle-sd/game.json --out-dir runs/knight-v1
python pixelwright/scripts/pixel_game.py intake new_enemy.png --category character --contract pixelwright/examples/demon-castle-sd/game.json --out-dir runs/intake-v1
python pixelwright/scripts/pixel_game.py screen capture.png --contract pixelwright/examples/demon-castle-sd/game.json --out-dir runs/screen-v1Before adding an asset, intake places it beside native references. The enlarged-knight comparison deliberately supplies a 2× export instead of a 1× asset; it fails with COARSE_PIXELS, PIXEL_SIZE_DIFFERS and CATEGORY_SIZE.
In the running game, screen checks a lossless screenshot against the base-resolution grid. The representative field above is clean artwork. Its actual grid diagnostic is a separate image.
Intentional failure example: what the red character means
?fault=1 deliberately draws a duplicate knight two screen pixels off the grid and adds a 50%-transparent rectangle. The checker overlay fills nonuniform cells red and marks out-of-palette pixels magenta. The red character is a diagnostic highlight, not part of the clean artwork. See the negative audit.
| What the game got wrong | Code |
|---|---|
| An asset exported enlarged, or stretched in one direction | COARSE_PIXELS |
| Part of an asset, or a sprite, font or UI element on screen, drawn at 2× or more | COARSE_REGION (review) |
| Sub-pixel positions or camera, runtime rotation, linear filtering, mipmaps, fractional scaling | CELL_NOT_UNIFORM |
| Translucent or additive effects, tinting, color grading | COLOR_OUTSIDE_PALETTE |
| Bars that are not the letterbox color | LETTERBOX_NOT_UNIFORM |
| Colors, transparency, category size, dithering or outline against the style | COLOR_OUTSIDE_PALETTE, PARTIAL_ALPHA, CATEGORY_SIZE, DITHERING_FOUND, OUTLINE_* |
viewport prints the whole-number scale and bars for any window size. The game contract reference lists every field and code. Engine settings covers Unity, Godot 4, Phaser 3, PixiJS, web canvas, LÖVE and GameMaker. Dot size is measured from color edges, so plain 1× art with only a few edges is reported for review rather than failed. Light, shading quality and mood are not measured; judge them from the side-by-side image.
Install the entire pixelwright/ folder, including scripts, references, and examples:
| Host | Personal skill directory | Invocation |
|---|---|---|
| Codex | ~/.agents/skills/pixelwright/ |
$pixelwright |
| Claude Code | ~/.claude/skills/pixelwright/ |
/pixelwright |
The host needs access to the original PNG and a Python environment with the dependencies installed. After loading the skill, a review request can be:
Inspect this PNG as 24×24 logical pixels at 8× scale, with at most 10 visible colors and binary transparency. Show the original, grid overlay, and actual PASS/FAIL report.
For a game, start with the style:
We're making a 384×288 SD RPG Maker-style field, with 32×32 tiles, 32×64 two-head characters and selective 1-pixel dark contours. Fix the final sizes before drawing and design expressions in native cells. Use the SD demon-castle game's shared palette and references. Show me the brief, then inspect a new 1× enemy beside the knight, princess and demon king.
Without the original file and a successful checker run, the result remains unverified. See SKILL.md and the platform compatibility guide for installation and execution details.
The following workflows remain in development. This README introduces them briefly; documents not yet on main link to the codex/design-first-sprites development branch.
| Feature | Development focus | Details |
|---|---|---|
| Pixel-art generation and grid repair | Logical-canvas rendering and derived correction candidates that require reinspection. | Creation · Repair |
| Palette editing | Reusable palettes, extraction, shading ramps, and remapping. | Palettes |
| Layer composition | Shared-grid composition with per-layer and final checks. | Layers |
| External sprite-sheet validation | Palette, margin, and silhouette-size checks from sprite-gen PNGs and manifests. | Atlas contract · Validation record |
| Animation and motion validation | Selected 2D designs, observed parts, frame consistency, and optional 3D pose guides. | 2D workflow · 3D workflow · Progress |
The sprite-sheet integration follows sprite-gen's output contract. The upstream declaration on the development branch records its repository, license, tested version/commit, and data_format relationship with runtime_required: false. These development features do not imply production acceptance of generated artwork or natural motion. The sprite-sheet and 2D motion work is tracked on the development branch; the v0.7.0 archive contains only what is on main.
python -m unittest discover -s pixelwright/tests -v
python tools/package_skill.py --out-dir dist
python tools/package_skill.py --verify dist/pixelwright-v0.7.0.zipPackaging produces an installation ZIP and a development-kit ZIP. The package verifier checks archive layout and SHA-256 coverage. The v0.7.0 validation record covers this release, earlier validation records document square-grid diagnostics, and the design notes explain the implementation.
Pixelwright is licensed under Apache License 2.0. See LICENSE, NOTICE, and SECURITY.md. The repository includes CI, CodeQL, and dependency update configuration.