PaintedPixels

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

- Configurable: Convert any image URL into Minecraft map art - Configurable: Images are automatically resized while maintaining aspect ratio - Configurable: Large images are automatically split across multiple maps - Configurable: Advanced color conversion to match Minecraft's map palette - Configurable: Downloads and processes images asynchronously to prevent server lag - Configurable: Maps are stored in a queue to prevent floor clutter (NEW!) - Configurable: 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:

```yaml

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