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