ArtChanger (Paper 1.21.10) by bdiev_

Custom internet images in item frames with automatic grid sizing, high-quality rendering, persistence, and anti-dup protections.

Demo Video

Youtube: https://youtu.be/ugDvkMoEF-0?si=oQdBODK7AI3Ired-

Key Features

• Load images from URLs (Instagram, Discord CDN, Telegram, Imgur, ImgBB, any direct link)
• Auto grid sizing by aspect ratio (e.g., 1:1 → 3x3, 16:9 → 4x2, 4:3 → 4x3; manual 3x2 / 5x5 also supported)
• Rectangular grids with placement validation and chunk-load restoration (tile metadata stored)
• High-quality pipeline: multi-step downscale, sharpening, Floyd–Steinberg dithering, palette mapping to Minecraft maps
• Rotate with right-click; delete with left-click (clears group, keeps main frame)
• Anti-dup: auto-created frames do not drop; only one frame drops per grid
• Persistence across restarts (image ID + grid metadata stored in frames)
• Asynchronous downloads (non-blocking for the server)

Requirements

• Java 21+
• Paper 1.21.10
• Maven (for building)

Installation

1. Build or use the provided JAR

mvn clean package

JAR: target/ArtChanger-1.0.0.jar

2. Drop into plugins/ on your Paper server

3. Restart the server (recommended) or /reload confirm

Commands

• /artchanger set <url> [size]
  • size formats: 3 (square), 3x2 (rectangular). If omitted → auto-sized by aspect ratio.
• /artchanger help — show help

Usage

1. Run /artchanger set <url> [size]
2. Right-click an item frame to place the image
3. Right-click again to rotate
4. Left-click to remove the picture (main frame stays; grid auto-frames are removed without drops)

Grid Sizing

• Auto: aspect-ratio based (1:1→3x3, 16:9→4x2, 4:3→4x3, 3:2→3x2, 2:3→2x3, 9:16→2x4, panorama>2.5→5x2)
• Manual: /artchanger set <url> 4x3 or /artchanger set <url> 5
• Max recommended grid: 10x10

Rendering Quality

• Multi-step downscale for large images → avoids blur
• Bicubic interpolation + render quality hints
• Sharpen (configurable strength in code, default 0.3)
• Floyd–Steinberg dithering to official Minecraft map palette

Persistence & Recovery

• Each frame stores: image_id, group_id, grid_width, grid_height, tile_x, tile_y, auto_created
• On chunk load, the correct tile of the original image is restored (no “9 tiny copies” issue)

Anti-Dup Behavior

• Auto-created frames: no item drops
• Main frame: drops only the frame (map cleared first)
• Destroying any frame in a grid removes the whole grid safely

Supported Formats & Sources

• Formats: jpg/jpeg, png, webp, bmp, gif, tiff
• Sources handled: instagram.com, cdn.discordapp.com, telegram/t.me, imgbb.com (/download), imgur.com (auto .png), plus any direct link

Troubleshooting

• Invalid URL → ensure http/https and a reachable link
• Image not loading → check server internet access; try another link
• After restart tiles look wrong → ensure you use the latest build (tile metadata now stored)
• Frames duping → fixed by anti-dup logic (only one frame drops per grid)

Build & Project Structure

ArtChanger/
├── pom.xml
└── src/main/java/com/artchanger/
    ├── ArtChangerPlugin.java        # Main plugin
    ├── ArtCommandExecutor.java      # /artchanger commands
    ├── PaintingListener.java        # frame interaction, grids, anti-dup
    ├── ImageDownloader.java         # download + scaling
    ├── ImageStorageManager.java     # persistence metadata
    ├── WorldLoadListener.java       # chunk-load restoration
    ├── MinecraftColorPalette.java   # dithering + palette mapping
    └── CustomMapRenderer.java       # map rendering

License & Author

• Created by bdiev_
• Open source; use and modify freely

Version

• 1.0.0 — December 2025