Pixel Painter Documentation

Pixel Painter

Pixel Painter turns an image into a wall or floor made from Minecraft blocks. Choose its height and direction, compare material counts, then paint with perceptual color matching and optional dithering. Transparent pixels can preserve the terrain behind the image. Persistent undo journals keep original block properties available after cancellation or a server restart.

The plugin requires Paper 1.21.11 or later and Java 25. All command permissions default to operators. This guide describes Pixel Painter 2.0.0; older builds use different commands, sizing and undo behavior. Spigot and Folia are not supported.

Start Painting

Getting Started Install the plugin, add an image and create your first painting.

Core Concepts Understand source pixels, block dimensions, palettes and recovery journals.

Creating Paintings Choose a wall or floor direction and preserve transparent areas.

Image Files and Downloads Manage PNG/JPEG sources and configure trusted download hosts.

Colors and Terrain

The bundled palette contains 335 different materials: concrete, wool, terracotta, logs, wood, ores, foliage, glass, stable ice, mushrooms and newer copper, cherry, bamboo, pale oak, resin and tuff families. Oklab matching chooses representative colors; Floyd-Steinberg dithering adds detail to gradients when enabled.

Painting runs one world job at a time with a configurable tick budget. The service validates build height, world borders, chunk count, journal capacity and region overlap, then saves its undo journal before placing any blocks.

Palettes and Dithering Choose block families, extend colors and understand texture differences.

Operations and Recovery Cancel jobs, restore terrain and resolve conflicting block edits.

Commands Complete syntax, defaults, aliases and runnable examples.

Permissions Separate trusted builder commands from cross-player administration.

Configuration and Reference

config.yml Image limits, processing budget, undo capacity, filters and trusted hosts.

messages.yml MiniMessage feedback, chat panels, hover descriptions and progress labels.

palette.yml Material-to-color mapping, validation and supported block families.

Developer Reference Explore implementation responsibilities, threading contracts and local Javadocs.

Troubleshooting Diagnose rejected dimensions, unavailable files, conflicts and failed reloads.

FAQ Version compatibility, source deletion, material costs and recovery questions.

Pixel Painter is licensed under GPL-3.0-or-later. See the developer reference for implementation details and local Javadoc generation.