MapArt - Minecraft 地图艺术插件
适用于 Purpur/Paper 服务器的地图艺术插件,允许玩家将自定义图片转换为游戏内的地图画作。
功能
- 支持 PNG、JPG、GIF、BMP 图像格式
- 自动缩放和裁剪图像以适配地图尺寸
- 大图像自动拆分为多张地图
- 异步处理,无服务器卡顿
- 支持 Folia 架构
安装
- 将
MapArt-1.1.2.jar 放入服务器的 plugins 目录
- 重启服务器
- 玩家使用
/mapart upload 上传图像(保存至 plugins/MapArt/images/<playerUUID>/)
- 或手动将图像放置到
plugins/MapArt/images/ 目录
用法
| 命令 |
描述 |
/mapart |
打开 GUI(显示当前玩家的图像) |
/mapart gui |
打开 GUI |
/mapart upload |
获取网页上传链接(针对特定玩家) |
/mapart apply <image file> [scale|tile] |
将图像转换为地图艺术(scale:适配单张地图,tile:拆分为网格) |
/mapart clear |
清除所有地图艺术 |
/mapart info |
查看你持有的地图数量 |
/mapart list |
列出当前玩家可用的图像文件 |
示例:
/mapart apply myimage.png # 缩放到单张地图(默认)
/mapart apply myimage.png tile # 拆分多张地图以显示大图像
两种模式
| 模式 |
命令 |
描述 |
| Scale |
/mapart apply <image> |
默认。将图像缩放到 128x128,输出 1 张地图 |
| Tile |
/mapart apply <image> tile |
不缩放。将图像拆分为 128x128 的图块,输出多张地图以组成马赛克 |
推荐图像尺寸
标准单张地图
- 推荐尺寸:128x128 像素
- 完全匹配一张地图的 128x128 像素显示区域,一对一像素映射,无缩放失真
尺寸对比
| 图像尺寸 |
地图数量 |
描述 |
| 128x128 |
1 张地图 |
推荐,像素完美映射 |
| 256x256 |
1 张地图 |
自动缩小至 128x128 |
| 512x512 |
1 张地图 |
自动缩小至 128x128 |
| 1024x1024 |
1 张地图 |
自动缩小至 128x128 |
| 2048x2048 |
1 张地图 |
自动缩小至 128x128 |
| 256x128 |
2 张地图 |
水平拆分,自动分割 |
| 512x256 |
8 张地图 |
4x2 地图网格 |
重要说明
- Minecraft 地图仅拥有 128x128 像素 的显示区域
- 使用 128x128 的图像可提供精确的逐像素控制,所见即所得
- 大于 128x128 的图像会自动拆分为多张地图
- 小于 128x128 的图像会自动缩放以填满
颜色限制
- Minecraft 地图仅有 128 种可用颜色
- 使用高色彩对比度的图像可获得最佳效果
- 避免使用过多渐变的图像
- 像素艺术风格的图像效果最佳
配置
plugins/MapArt/config.yml:
网页上传服务器
控制内置的网页上传服务器。
| 配置项 |
类型 |
默认值 |
描述 |
web-server.enabled |
boolean |
true |
启用/禁用网页上传服务器。关闭后,玩家必须手动放置图像 |
web-server.host |
string |
0.0.0.0 |
监听地址。0.0.0.0 = 所有接口,127.0.0.1 = 仅限本地 |
web-server.port |
int |
8080 |
监听端口。确保防火墙允许流量通过 |
web-server.public-url |
string |
http://127.0.0.1:8080 |
玩家访问的 URL。本地测试请使用 http://127.0.0.1:端口,远程访问请使用服务器公网 IP |
注意:除非你有提供 HTTPS 的反向代理,否则 public-url 必须使用 http://(而非 https://)。
图像限制
| 配置项 |
类型 |
默认值 |
描述 |
max-image-width |
int |
2048 |
允许的最大图像宽度(像素) |
max-image-height |
int |
2048 |
允许的最大图像高度(像素) |
超出这些限制的图像将在上传时被拒绝。
地图设置
| 配置项 |
类型 |
默认值 |
描述 |
map-size |
int |
128 |
单张地图的像素尺寸。标准 Minecraft 地图为 128x128 |
性能设置
| 配置项 |
类型 |
默认值 |
描述 |
async-processing |
boolean |
true |
异步处理图像(推荐) |
max-concurrent-tasks |
int |
4 |
最大并发处理任务数 |
完整配置示例
web-server:
enabled: true
host: 0.0.0.0
port: 8080
public-url: "http://127.0.0.1:8080"
max-image-width: 2048
max-image-height: 2048
map-size: 128
async-processing: true
max-concurrent-tasks: 4
公网服务器示例
如果你的服务器公网 IP 是 1.2.3.4,端口是 8080:
web-server:
enabled: true
host: 0.0.0.0
port: 8080
public-url: "http://1.2.3.4:8080"
然后设置端口转发:外部 8080 → 内部服务器 8080。
玩家图像隔离
- 上传的文件保存在以下路径:
plugins/MapArt/images/<playerUUID>/
- 每位玩家只能查看和使用自己上传的图像
权限
| 权限 |
描述 |
默认值 |
mapart.use |
使用地图艺术命令 |
OP |
mapart.admin |
管理员权限 |
OP |
构建
mvn clean package
构建输出位于 target/MapArt-1.1.2.jar
依赖
- Purpur 1.21+ 或 Paper 1.21+
- Java 21+
遥测数据
本插件收集匿名使用数据以帮助改进项目。首次启动时会生成一个唯一的 UUID 并存储在 DreamArk/server-uuid.txt 中。心跳数据每 60 秒发送一次至我们的遥测服务器。不会收集任何个人或服务器内容数据。
使用本插件即表示您同意我们的 隐私政策 和 服务条款。
致谢
由 DreamArk Studio 开发
MapArt - Minecraft Map Art Plugin
A map art plugin for Purpur/Paper servers that allows players to convert custom images into in-game map paintings.
Features
- Supports PNG, JPG, GIF, BMP image formats
- Auto-scales and crops images to fit map dimensions
- Large images automatically split into multiple maps
- Async processing, no server lag
- Folia architecture support
Installation
- Place
MapArt-1.1.2.jar into your server's plugins directory
- Restart the server
- Players use
/mapart upload to upload images (saved to plugins/MapArt/images/<playerUUID>/)
- Or manually place images into
plugins/MapArt/images/ directory
Usage
| Command |
Description |
/mapart |
Open GUI (shows current player images) |
/mapart gui |
Open GUI |
/mapart upload |
Get a web upload link (player-specific) |
/mapart apply <image file> [scale|tile] |
Convert image to map art (scale: fit single map, tile: split into grid) |
/mapart clear |
Clear all map art |
/mapart info |
View number of maps you hold |
/mapart list |
List current player's available image files |
Example:
/mapart apply myimage.png # Scale to single map (default)
/mapart apply myimage.png tile # Split into multiple maps for large image
Two Modes
| Mode |
Command |
Description |
| Scale |
/mapart apply <image> |
Default. Scales image to 128x128, outputs 1 map |
| Tile |
/mapart apply <image> tile |
No scaling. Splits image into 128x128 tiles, outputs multiple maps for mosaic |
Recommended Image Size
Standard Single Map
- Recommended size: 128x128 pixels
- Exactly matches one map's 128x128 pixel display area, one-to-one pixel mapping with no scaling distortion
Size Comparison
| Image Size |
Map Count |
Description |
| 128x128 |
1 map |
Recommended, pixel-perfect mapping |
| 256x256 |
1 map |
Auto-scaled down to 128x128 |
| 512x512 |
1 map |
Auto-scaled down to 128x128 |
| 1024x1024 |
1 map |
Auto-scaled down to 128x128 |
| 2048x2048 |
1 map |
Auto-scaled down to 128x128 |
| 256x128 |
2 maps |
Horizontal split, auto-divided |
| 512x256 |
8 maps |
4x2 map grid |
Important Notes
- Minecraft maps only have a 128x128 pixel display area
- Using a 128x128 image gives you precise pixel-by-pixel control, WYSIWYG
- Images larger than 128x128 are automatically split into multiple maps
- Images smaller than 128x128 are auto-scaled to fill
Color Limitations
- Minecraft maps only have 128 available colors
- Use images with high color contrast for best results
- Avoid images with excessive gradients
- Pixel art style images work best
Configuration
plugins/MapArt/config.yml:
Web Upload Server
Controls the built-in web upload server.
| Config |
Type |
Default |
Description |
web-server.enabled |
boolean |
true |
Enable/disable the web upload server. When off, players must place images manually |
web-server.host |
string |
0.0.0.0 |
Listen address. 0.0.0.0 = all interfaces, 127.0.0.1 = local only |
web-server.port |
int |
8080 |
Listen port. Ensure firewall allows traffic |
web-server.public-url |
string |
http://127.0.0.1:8080 |
URL opened by players. Use http://127.0.0.1:port for local testing, server public IP for remote |
Note: public-url must use http:// (not https://) unless you have a reverse proxy providing HTTPS.
Image Limits
| Config |
Type |
Default |
Description |
max-image-width |
int |
2048 |
Maximum allowed image width (pixels) |
max-image-height |
int |
2048 |
Maximum allowed image height (pixels) |
Images exceeding these limits will be rejected on upload.
Map Settings
| Config |
Type |
Default |
Description |
map-size |
int |
128 |
Pixel size of a single map. Standard Minecraft maps are 128x128 |
Performance Settings
| Config |
Type |
Default |
Description |
async-processing |
boolean |
true |
Process images asynchronously (recommended) |
max-concurrent-tasks |
int |
4 |
Max concurrent processing tasks |
Full Config Example
web-server:
enabled: true
host: 0.0.0.0
port: 8080
public-url: "http://127.0.0.1:8080"
max-image-width: 2048
max-image-height: 2048
map-size: 128
async-processing: true
max-concurrent-tasks: 4
Public Server Example
If your server's public IP is 1.2.3.4 and port is 8080:
web-server:
enabled: true
host: 0.0.0.0
port: 8080
public-url: "http://1.2.3.4:8080"
Then set up port forwarding: external 8080 → internal server 8080.
Player image isolation
- Uploaded files are saved under:
plugins/MapArt/images/<playerUUID>/
- Each player can only see and use their own uploaded images
Permissions
| Permission |
Description |
Default |
mapart.use |
Use map art commands |
OP |
mapart.admin |
Admin permissions |
OP |
Building
mvn clean package
Build output is located at target/MapArt-1.1.2.jar
Dependencies
- Purpur 1.21+ or Paper 1.21+
- Java 21+
Telemetry
This plugin collects anonymous usage data to help improve the project. A unique UUID is generated on first launch and stored in DreamArk/server-uuid.txt. Heartbeat data is sent every 60 seconds to our telemetry server. No personal or server content data is collected.
By using this plugin, you agree to our Privacy Policy and Terms of Service.
Credits
Developed by DreamArk Studio
评论 0
登录后参与评分
还没有评论,来抢沙发吧