PaintedPixels

A Minecraft plugin for Paper/Spigot that allows players to create map art from images via URL.

Description

PaintedPixels enables players to upload an image through an online URL and receive a Minecraft map art that replicates the image. The plugin automatically converts the image colors to match Minecraft's map color palette for a near 1:1 replica.

Features

• URL to Map Art: Convert any image URL into Minecraft map art
• Automatic Resizing: Images are automatically resized while maintaining aspect ratio
• Multi-Map Support: Large images are automatically split across multiple maps
• Color Matching: Advanced color conversion to match Minecraft's map palette
• Async Processing: Downloads and processes images asynchronously to prevent server lag
• Queue System: Maps are stored in a queue to prevent floor clutter (NEW!)
• Permission Based: Full permission system for control
• Configurable: Customize max dimensions, delivery methods, and other settings

Commands

Command	Description	Permission	Aliases
/paint <url>	Create map art from an image URL	paintedpixels.use	/mapimage, /imagemap, /paintpixels
/paint next	Get the next map from your queue	paintedpixels.use	-
/paint all	Get all remaining maps from your queue	paintedpixels.use	-
/paint status	Check how many maps are waiting	paintedpixels.use	/paint queue
/paint help	Show help message	paintedpixels.use	-

Permissions

Permission	Description	Default
paintedpixels.use	Allows using the /paint command	true
paintedpixels.admin	Admin permissions	op

Configuration

The config.yml file allows you to customize:

# Maximum image dimensions (in pixels)
max-width: 512
max-height: 512

# Delivery method for created maps
# Options: queue, immediate
delivery-method: queue

# Enable debug logging
debug: false

# Cache settings
cache:
  clear-on-restart: true
  max-cached-images: 100

Delivery Methods:

• queue (default) - Maps are stored in a queue, retrieved with /paint next or /paint all
• immediate - Maps are given directly

Usage Example

1. Find an image URL (e.g., from Imgur, Discord, etc.)
2. Run the command: /paint https://example.com/image.png
3. Wait for the plugin to download and process the image
4. Maps are added to your queue - use /paint next to get them one at a time!

Note: Large images will be split into multiple maps. For example, a 256x256 image will create 4 maps (2x2 grid).

• /paint next - Get one map at a time
• /paint all - Get all maps at once
• /paint status - Check how many maps are waiting
• /paint all - Get all maps at once
• /paint status - Check how many maps are waiting

Supported Image Formats

• PNG (recommended)
• JPEG/JPG
• GIF (first frame only)
• BMP
• Any format supported by Java's ImageIO

Technical Details

Map Colors:

Minecraft maps use a limited color palette based on block colors. The plugin uses the MapPalette API to match colors as closely as possible. Some color information may be lost in the conversion, which is normal and expected.

Map Dimensions:

• Each Minecraft map is 128x128 pixels
• Images larger than 128x128 are split into multiple maps
• Maximum configurable size is 512x512 (16 maps)

Performance:

• Image downloading is done asynchronously to prevent server lag
• Processing is also asynchronous until the final map creation
• Map creation is done on the main thread (required by Bukkit API)
• Images are cached to the plugins/PaintedPixels/cache/ directory

Limitations

• Maximum file size: 10 MB (hardcoded for security)
• Timeout for downloads: 10 seconds
• Color palette is limited to Minecraft's map colors
• Animated images (GIF, etc.) will only use the first frame

Troubleshooting

"Failed to download image":

• Check that the URL is valid and publicly accessible
• Ensure the URL points directly to an image file
• Check your server's firewall settings

"Your inventory is full":

• The map will be dropped at your location
• Pick it up or make space in your inventory

Maps appear as empty/blank:

• This may be a client-side issue
• Try relogging or reloading resource packs