简体中文 | English

ReColorfulMap

Description

ReColorfulMap is a plugin that converts images into image maps, which can be hung on item frames to add decoration.

This is a remake of the original ColorfulMap plugin. Images are stored as PNG files in plugins/ReColorfulMap/maps, using the same layout as ColorfulMap 2.3. Each map item stores only its relative PNG path in PDC. Images load on demand, and there is no map ID index file.

Both ColorfulMap and ReColorfulMap's idea are from ImageFrame and ImageMaps. You can think it is a simplified version of ImageFrame and a high version remake of ImageMaps. Thanks for their great work.

Features

• Convert images into image maps;
• Image scaling;
• Automatic placement to item frame matrix;
• Charge once per image tile when generating artwork; retrieval and replacement are free (requires Vault and an economy plugin);
• Automatic get back maps from item matrix (new feature);
• Bounded generation queue, cancellation, and durable claims for results completed while offline;
• Download size, original pixel and timeout limits; reuse native map IDs already discovered during this server run;

Version Support

• 1.20.1+ (Paper、Folia)

Usage

1. First, you need to upload the image you want to convert to the image bed, so that this plugin can read the image content from the network. After uploading, you will get an url of the image, copy this address.

2. In the game, enter the command: /tomap <url-you-just-got> to get a map:

   

   Because one map can only hold an image at the most of 128 x 128 pixels, so ReColorfulMap will split your image into tiles automatically. Don't worry about handling the tiles, ReColorfulMap will tell you how many item frames you need to place this image maps and place them in the correct order automatically too.

   For this image shown above, it shows 8 x 13, which means you prepare a matrix of item frames 8 in width and 13 in height to place this image.

3. Place the map in the bottom-left corner of the item frame matrix, then the corresponding maps will be placed in the remaining item frames on the wall automatically.

   

4. If the image is too large or too small, you can try to add a scaling parameter after the command, for example, /tomap <url-you-just-got> 0.3 means rendering at 30% of the original size. If you want to fill the image without leaving any white space at the edges of all the maps, you need to ensure that the resolution of your image is a multiple of 128.

   

For Server Owners

Commands & Permissions

The angle brackets <> in the following commands indicate required parameters, and the square brackets [] indicate optional parameters.

Function	Command	Permission Node	Default
Generate	/tomap <image-url> [scale]	recolorfulmap.tomap	true
Reload	/reloadcolorfulmap	recolorfulmap.admin	op
Clean Temporary Files	/cleancolorfulmap	recolorfulmap.admin	op
Copy Held Map	/mapmanage copy	recolorfulmap.manage + recolorfulmap.copy	true
Generation Status / Cancel	/mapmanage status, /mapmanage cancel	recolorfulmap.manage	true
Pending Maps	/mapmanage list, /mapmanage claim <UUID>	recolorfulmap.manage	true
Inspect / Recover Delivery	/mapmanage inspect|recover|resolve ...	recolorfulmap.admin	op

/cleancolorfulmap removes temporary directories left by failed writes or deletions. Newly generated maps and command-created copies own separate artwork directories. Destruction cleans only that independent artwork; destroying a loose tile preserves other tiles. Legacy shared directories are retained. Placement, retrieval, pickups and chunk unloads preserve images. Results completed while the player is offline remain available through /mapmanage list and claim. The price is columns × rows × economy.cost-per-map, charged once when the generated result is first delivered. Offline results are charged when claimed. Retrieval, movement and replacement are always free; there is no alternative charging mode. See runtime and recovery documentation (Chinese) for administrator recovery commands and interrupted deliveries.

Copying image maps

Hold a whole image map or a loose tile and use /mapmanage copy. One free independent copy is added to an empty inventory slot; the original is unchanged. Whole maps copy their image files into a new UUID directory and receive new native map IDs. A loose tile becomes an independent 1×1 artwork. Copies use disk space; there is no shared-file reference counting.

Only command copying is supported. Workbench/cartography image-copy recipes are cancelled without consuming inputs. Creative duplication, cloned containers and other plugins directly cloning item data are unsupported and can still share paths; normal creative inventory movement is not intercepted. Plugins can use getArtworkCopyService() instead of cloning an ItemStack. See copy and lifecycle details.

Upgrading from ColorfulMap 2.3

1. Stop the server and back up worlds, player data, and plugins/ColorfulMap.

2. Copy this repository's entire scripts directory into your server directory and run:

   bash scripts/migrate-colorfulmap.sh --server-root . --apply

3. Replace the old plugin JAR with ReColorfulMap and start the server. Paper 26.2 requires Java 25.

The script copies PNG files to plugins/ReColorfulMap/maps and adds path PDC to existing items. Copying the maps directory alone is no longer sufficient. Omit --apply for a dry run. Existing complete arrays can still be retrieved from any tile and placed again without deleting their images. Legacy copied items may still share a directory after migration. Version 5.0.1 keeps those unmarked directories and does not automatically delete them. Do not manually mark old shared data as independent.

The script requires Linux/macOS or WSL and Python 3.10+. Observe the case of ReColorfulMap in the default path. See storage and migration documentation (Chinese) for backups, rollback, in-place migration, and the exact destruction events covered. Creative inventory deletion, /clear, and arbitrary plugin inventory changes do not have a universal destruction event and do not trigger automatic file deletion. The repository's previous PDC image-byte storage is discontinued and has no migration support.

Configuration Reference

# Do not modify this value.
version: 3
# The maximum size of item frame matrix.
# 32 x 18 means image can not be larger than 4096 x 2304 pixels.
# Don't set this value too large, it may cause lag.
max-frame-x: 32
max-frame-y: 18
# Language filename in plugins/ReColorfulMap/languages, without .yml.
language: en_us
# Enable economy system. (Require Vault and an economy plugin)
# Charge once per tile on first delivery of the generated artwork.
economy:
   enable: false
   cost-per-map: 100.0
# The whitelist of image url address, use this to prevent players from using inappropriate images.
# Leave it empty to allow all addresses.
address-white-list: []
# Original image limits, checked before decoding and resizing.
download:
   max-bytes: 33554432
   max-pixels: 16000000
   connect-timeout-millis: 10000
   read-timeout-millis: 15000
   total-timeout-millis: 60000
   max-redirects: 5
# Global generation workers and waiting capacity; restart required. Zero means no waiting queue.
generation:
   workers: 2
   queue-capacity: 16
# Debug mode, if report bugs turn this on.
debug: false

Existing configuration files are preserved; missing new fields use the defaults above. Invalid configuration or language files leave the previous valid settings active on reload and prevent initial startup. All settings except worker count and queue capacity support reload; running jobs keep their original settings. Whitelist rules match complete hosts, ports and path segments, and are checked on every redirect. For example, https://images.example.com/art permits images under that path, but excludes similar domains and /artwork.

Support

Mail: zhangyuheng@lunadeer.cn

GitHub: Issues

QQ群：309428300

bStats