详细介绍

MapArt - Minecraft 地图画插件

一个适用于 Purpur/Paper 服务器的地图画插件，允许玩家将自定义图片转换为游戏中的地图画。

功能特性

支持 PNG、JPG、GIF、BMP 格式图片
自动缩放和裁剪图片适配地图尺寸
大图片自动分割为多张地图
异步处理，不阻塞服务器
支持 Folia 架构

安装方法

将 MapArt-1.1.2.jar 放入服务器的 plugins 目录
重启服务器
玩家通过 /mapart upload 上传图片（默认保存到 plugins/MapArt/images/<玩家UUID>/）
或手动将图片放入 plugins/MapArt/images/ 目录

使用方法

命令	说明
`/mapart`	打开 GUI（展示当前玩家图片）
`/mapart gui`	打开 GUI
`/mapart upload`	获取网页上传链接（按玩家隔离）
`/mapart apply <图片文件名> [scale\|tile]`	将图片转换为地图画（scale: 缩放, tile: 切分）
`/mapart clear`	清除所有地图画
`/mapart info`	查看持有的地图数量
`/mapart list`	列出当前玩家可用的图片文件

示例:

/mapart apply myimage.png        # 缩放到单张地图
/mapart apply myimage.png tile   # 切分为多张地图（大图拼接）

两种模式

模式	命令	说明
缩放 (scale)	`/mapart apply <图片>`	默认模式，将图片缩放到 128x128 像素，输出 1 张地图
切分 (tile)	`/mapart apply <图片> 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 上传服务器

控制内置网页上传服务器的行为。

配置项	类型	默认值	说明
`web-server.enabled`	boolean	`true`	是否启用 Web 上传服务器。关闭后玩家只能通过命令行手动放图
`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`	玩家浏览器访问的地址。本机测试用 `http://127.0.0.1:端口`，外网需改为服务器公网 IP 或域名

注意：public-url 必须使用 http://（非 https://），除非你配置了反向代理提供 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/<玩家UUID>/
每个玩家只能看到和使用自己上传的图片

权限

权限节点	说明	默认
`mapart.use`	使用地图画命令	成员
`mapart.admin`	管理员权限	成员

构建

mvn clean package

构建产物位于 target/MapArt-1.1.2.jar

依赖

Purpur 1.21+ 或 Paper 1.21+
Java 21+

MapArt