Noteblock Texture Generator

Cross-platform GUI tool (Windows / macOS / Linux) that turns a single base noteblock texture into a complete Minecraft Java Edition resource pack with per-blockstate textures:

• Per-instrument colors — assign a color to each noteblock instrument; the tool shifts the base texture's hue/lightness/chroma automatically (OKLCH).
• Note gradient (0–24) — tint each note along an editable gradient (draggable stops), or assign 25 individual colors, or none. Gradients can be anchored to each instrument's color, so every instrument gets its own gradient for free.
• Powered glow — when a noteblock is powered, show a different texture:
  • LabPBR emissive (_s.png alpha channel) — real light emission with shader packs (Iris + BSL/Complementary). Gotcha: alpha 255 = emission OFF, 254 = max.
  • Vanilla-visible variant — brightness boost / glow border / tint that works without shaders.

Status

All milestones implemented:

Milestone	State
M1 scaffold + base texture + per-instrument colors + preview	✅
M2 note gradient + preview grid + gradient editor	✅
M3 powered modes + LabPBR _s/_n generation	✅
M4 pack generation + zip + project save/load + validate	✅
M5 polish + CI + docs	✅

Remaining known work: pin the instrument introduction versions against decompiled vanilla sources (VERIFY banners in instruments.rs / versions.rs), palette tuning, and a full in-game pass of the checklist below.

Frontend redesign in progress. The GUI has been redesigned as a minimalist single-window preview (no sidebar) and is currently a mock-backed prototype — frontend/js/api.js delegates to a client-side mock backend so interactions and animations can be iterated in a plain browser with no build step. The real Rust/Tauri IPC will be re-wired into api.js once the UI settles; the Rust core and its tests are unaffected and remain green.

Build & run

Requires Rust and the Tauri CLI (no Node toolchain):

cargo install tauri-cli --version "^2.0.0" --locked
cargo tauri dev          # run the app (serves frontend/ statically)
cargo tauri build        # release bundle (installer per platform)

Core library tests (no GUI needed — 60 tests):

cargo test -p noteblock-gen

Golden snapshots (regenerate after intentional changes, review diffs):

UPDATE_GOLDEN=1 cargo test -p noteblock-gen --test golden_tests

Usage

The steps below describe the redesigned prototype UI, which currently runs against a mock backend — export produces no real files yet.

1. Drop a base noteblock texture (PNG) onto the landing drop zone, or click "Use a sample texture". The window switches to the full-bleed preview.
2. Pan/zoom the preview: scroll to zoom toward the cursor, middle-drag (or drag empty space) to pan; "Reset view" is in the right-click menu.
3. Click a note cell to assign that single noteblock a color (overrides the gradient). Click the first cell of a row for that instrument's menu: edit gradient, tint/shift strength, per-instrument glow, and enable/disable.
4. Right-click the preview for Export…, Show powered state (on by default), and Show instrument state (on by default; turn it off to focus the preview on a single instrument's row).
5. The Export dialog asks for a save path and hides advanced options (description, target version, max resolution, instrument set) behind "Show advanced options".

How it works

• Vanilla's blockstates/note_block.json maps every state to one model. Packs must enumerate the states they differentiate: N instruments × 25 notes × 2 powered variants (800 or 1350), each pointing at a small model that references a precomputed texture.
• All color math lives in the Rust core (crates/noteblock-gen); the UI preview is a sprite-sheet PNG rendered by the same code, so preview and export can never drift. (The current mock-backed prototype renders its own approximate sprite sheet instead — see the Status note above.)
• Generated packs include an optional "" catch-all variant so unmapped states (e.g. instruments added by future versions) fall back to the vanilla look instead of the missing-texture checkerboard.
• Identical textures/models are deduped by content hash; blockstates reference canonical paths, keeping packs small when differentiation is disabled.
• LabPBR emission color comes from the albedo, but shaders look _s/_n maps up by path convention, so each unique albedo gets its own _s.png (uniform content — compresses ~99% in the zip).
• Zips are deterministic: fixed timestamps, fixed compression, sorted entries (byte-identical across runs, test-enforced).

LabPBR notes

• Emissive lives in the alpha channel of _s.png: 0 = off … 254 = max, 255 = off (an RGB image with no alpha defaults to 255, so opaque images never glow by accident).
• Emission is only visible with a shader pack configured for LabPBR (Settings → Materials → PBR mode: LabPBR, Emissive Textures: ON).
• The tool's emissive slider is clamped to 254 for you, and unit tests enforce the 254/255 rule on every generated _s file.

Manual verification checklist (in-game)

1. Shaders: load the pack with Iris/OptiFine + a LabPBR shader. Power a noteblock with a lever — it should emit light in the albedo's colors. Toggle Emissive Textures off and the glow disappears.
2. Vanilla: with shaders off, powered blocks show the brightness/border variant instead.
3. Redstone: power via torch/lever and via adjacent blocks; unpower ↔ powered texture swaps each time.
4. States: spot-check one state per instrument with /setblock ~ ~ ~ minecraft:note_block[instrument=bell,note=12,powered=true].
5. Back-compat: load a 27-instrument pack on 1.19/1.21 — no errors; unknown instruments fall back to the vanilla look (fallback on) or checkerboard (fallback off).
6. Zip: unzip the generated zip — contents must match the folder form exactly; load the zip directly in Minecraft.

Project layout

• crates/noteblock-gen/ — generation core, zero GUI deps, fully unit-tested
• src-tauri/ — Tauri 2 shell + IPC commands
• frontend/ — plain HTML/CSS/JS (no build step); currently a mock-backed UI prototype
• examples/sample.nbgproj — sample project (File → Load project)
• AGENTS.md — working rules for AI agents / contributors
• docs/architecture.md — deep design notes

Reference material

XK-redstone-display/ in the repo root is the reference pack that inspired this project's research (multipart icon bands, multi-version pack.mcmeta pattern). It is CC BY-NC-ND licensed — structure-only reference, never committed, never copied.

License

TBD