GitHub - cochranblock/pixel-forge: Pixel art sprite generator. Three diffusion models (1M-17M params). Pure Rust, Metal/CUDA/CPU. No Python, no cloud.

This repo is part of CochranBlock — Unlicense Rust repositories. All source code is public domain.

Ships with Proof of Artifacts and a Timeline of Invention documenting what was built and when.

Pixel Forge v0.6.0

Pixel art sprite generator. Three diffusion models. Pure Rust. No cloud.

Train and run Gaussian diffusion models that generate 32x32 pixel art sprites. Runs locally on CPU, Metal (Apple Silicon), or CUDA (NVIDIA). No Python. No cloud APIs.

Status: In active development. Output quality is improving but not yet game-ready. Training and inference work; sprite fidelity is the current focus.

What Exists Today

• Three model architectures — Cinder (1.09M params, [32,64,64]), Quench (5.83M params, [64,128,128]), Anvil (16.9M params, [96,192,192]). Param counts verified at device_cap.rs:492.
• Training loop (src/train.rs) — Gaussian noise, clean prediction, cosine schedule, min-SNR weighting (gamma=5), CFG dropout (10%), per-epoch checkpoints, --resume for fine-tuning
• Augmentation — palette swap, horizontal flip, 90/180/270 rotation, brightness jitter (50% chance, ×[0.8,1.2])
• 108 class directories mapped via hybrid conditioning (10 super-categories + 12 binary tags, lookup table)
• 7 color palettes — load_palette, quantize
• f16 quantization — quantize_f32_to_f16
• GUI — egui app with class picker, palette selector, generation
• CLI — clap command definitions
• Distributed generation — cluster module distributes work across 4 SSH nodes
• NanoSign model integrity — BLAKE3 signing on all model saves, verification on all loads. Tampered files rejected. Spec.
• 11 governance documents baked into binary via include_str! (govdocs/)
• Android build scaffold — android/ builds AAB, not yet published to Play Store

What's In Progress

• Output quality — models generate recognizable but rough sprites; not yet usable as game art
• Anvil v7 training — fine-tuning from v6 with rotation augmentation on worker node
• MoE cascade — Cinder→Quench pipeline code exists, expert heads designed but not validated at quality
• any-gpu backend — wgpu/Vulkan tensor engine with 31 ops (conv2d, group_norm, attention, etc.). Planned as future training backend for AMD GPUs (bt's 5700 XT). Needs autograd + optimizer.
• Tiered pipeline — planned: palette specialist (50K) → silhouette generator (200K) → detail painter (Anvil-class), each specialist trained separately

What's Not Done

• iOS app — scaffold only, not buildable
• Web/PWA — HTML scaffold only, WASM target not functional
• Community sprite sharing — planned, not implemented
• GitHub Releases — binaries built locally but not published as GitHub releases yet

Quick Start

# Build (Metal GPU on macOS, CPU fallback)
cargo build --release

# Build with CUDA (NVIDIA GPU on Linux)
cargo build --release --features cuda --no-default-features

# Launch GUI
cargo run --release

# Generate (requires a trained model)
cargo run --release -- anvil character --count 4 --steps 40 --palette stardew

# List palettes
cargo run --release -- palettes

Training

Dataset: ~20K balanced tiles in data_v3_32/. See data/SOURCES.md for sources and licensing.

# Train Anvil (~12 min/epoch on CPU, ~42 hrs for 200 epochs)
cargo run --release -- train --data data_v3_32 --anvil --epochs 200 \
  --lr 2e-4 --warmup 10 --batch-size 16 --no-ema --checkpoint-every 1

# Fine-tune from existing checkpoint
cargo run --release -- train --data data_v3_32 --anvil --epochs 100 \
  --lr 5e-5 --batch-size 8 --resume pixel-forge-anvil-v6.safetensors \
  -o pixel-forge-anvil-v7.safetensors

# Train Cinder (fast, ~1.5 min/epoch)
cargo run --release -- train --data data_v3_32 --epochs 500 \
  --lr 2e-4 --batch-size 128 --no-ema

Known Issues (Bug History)

The diffusion models produced blobs for weeks. Root causes found and fixed:

1. Uniform [0,1] noise — signal and noise occupied the same range. Fixed: Gaussian N(0,1) noise in corruption. Commit 541720cd.
2. CFG scale — inverted outputs at high scale. Now set to 3.0 with proper unconditional path. Commit 68f2183a.
3. Noise distribution mismatch — sampling started from uniform noise while training used Gaussian. Fixed: all sampling paths now use seeded_noise (Gaussian). Commit 68f2183a.

Commands

Model Tiers

Training Data

19,876 balanced tiles (capped 2K/class, 68 active class directories). Dataset loader: train::preprocess. Tile count printed at train.rs:320.

~70% of the balanced training set is AI-generated (Gemini). These sprites were generated via text prompts, sliced from grids, background-removed, and quality-checked. They fill classes that had <50 artist-made samples. See data/SOURCES.md.

Built-In Palettes

Platforms

Device auto-detection: pipeline::best_device. Feature flags: Cargo.toml:19.

Tech Stack

~12,458 lines of Rust across 31 .rs files. Zero Python. Zero JavaScript.

Governance Documents

11 compliance-oriented documents embedded via include_str! (self-assessed, not independently audited). Source files in govdocs/.

pixel-forge govdocs              # list all docs
pixel-forge govdocs sbom         # Software Bill of Materials
pixel-forge govdocs security     # security posture

Attribution

See ATTRIBUTION.md for full credits.

License

Unlicense (public domain). See LICENSE.

Built by The Cochran Block. Powered by KOVA.