nx_palette.nx

nx_palette.nx -- sub-byte voxel/pixel palette encoder. THE unlock primitive for Minecraft-equivalent on $5 ESP32-class hardware. At 3 bits per voxel and an 8-color palette, a full 32x32x32 chunk fits in 12288 bytes (12 KiB). Pair with chunk paging from flash and the entire walkable world streams within the working RAM of an RP2040 / Cortex-M0+ class part. This is what makes a true Minecraft demo on $5 of silicon feasible -- without sub-byte packing, the same chunk needs 32 KiB minimum (one byte per voxel) which blows past most MCU SRAM budgets. Composes: nx_tier -- packing density scales naturally with NX_TIER_*; MCU tier uses 1-3bpp, workstation tier may stay at 8bpp for cache reasons nx_budget -- the saved RAM bytes flow directly into the cell's ram budget headroom V1 supports 1bpp (2-color), 2bpp (4-color), 3bpp (8-color), 4bpp (16-color), and 8bpp pass-through. Bit-level packing is LSB-first within each byte so unpack is a small shift + mask, friendly to embedded targets without barrel shifters. Gap list (V1 honest perf verdict): - no RLE compression on top of packing (queued for chunk save format) - no dithering helper for 1bpp displays (caller's responsibility) - palette index lookup not included (caller supplies palette) - no SIMD unpack on workstation tier (scalar only) - no compile-time-specialized variants per bpp (one function with branch; per-bpp specialization queued behind benchmark gate) genealogy_id: classic_video_indexed_color + minecraft_chunk_format lineage_id: substrate_palette_v1 nx_safety_envelope: intended_use: "Sub-byte palette index packing/unpacking for memory-constrained voxel/pixel data" sil_target: SIL1 evidence: [bit_alignment_correct, lossless_roundtrip, bpp_validated_at_entry]