Pixel Gallery（MITE）

Pixel Gallery 是一个面向 MITE 1.6.4 / FishModLoader 的自定义画作模组。它会从本地目录读取像素画图片，将其注册进原版画作池，并在多人游戏中把贴图同步到客户端。

功能概览

• 从 pixel_gallery/paintings/ 自动扫描自定义画作。
• 按 NxM 文件夹名注册不同尺寸的画作，例如 1x1、2x2、4x3。
• 支持 .png、.jpg、.jpeg 源图片，网络同步时统一使用 PNG 数据。
• 多人模式下服务端发送画作清单，客户端只请求缺失或过期的贴图。
• 客户端贴图写入本地缓存，并通过 DynamicTexture 绑定到对应的 EnumArt。
• 提供 /pixel_gallery 命令用于查看状态、重载配置、重新同步贴图。

目录规则

把图片放到以下目录：

pixel_gallery/paintings/<宽度>x<高度>/你的图片文件

示例：

pixel_gallery/paintings/1x1/example.png  -> 图片尺寸必须是 16x16
pixel_gallery/paintings/2x2/example.png  -> 图片尺寸必须是 32x32
pixel_gallery/paintings/4x3/example.png  -> 图片尺寸必须是 64x48

规则：

• 文件夹名必须是 NxM 格式，例如 2x2、4x3。
• 文件夹名不能使用 *。
• 每格画作对应 16x16 像素，所以 NxM 的图片尺寸必须是 N*16 x M*16。
• 源图片支持 .png、.jpg、.jpeg。
• 单张图片最大像素总数为 256*256。
• 文件名应保持简单稳定，避免使用游戏或文件系统不兼容的特殊字符。

运行流程

启动前注册

在 PreLaunch 阶段，模组会扫描 pixel_gallery/paintings/，并把符合规则的图片注册进 EnumArt。这是 MITE 1.6.4 画作实体所需的限制。

这一阶段不会生成资源包，也不会写入 resourcepacks/。

玩家进入后同步

玩家进入世界后，服务端会发送画作清单元数据：

artTitle / textureFileName / sha256 / size

客户端会把清单和本地缓存进行比较，只请求缺失或哈希不一致的贴图。服务端收到请求后，将对应 PNG 数据分片发送给客户端。

客户端加载贴图

客户端接收完整 PNG 数据后，会执行以下操作：

• 合并分片数据。
• 校验尺寸和 SHA-256。
• 写入 pixel_gallery/cache/<server_key>/。
• 通过 DynamicTexture 加载贴图。
• 绑定到对应 EnumArt.special_texture。

配置文件

配置文件路径：

pixel_gallery/config.properties

可用配置项：

verbose_logs=true|false
allow_jpg=true|false
allow_jpeg=true|false
whitelist=...
blacklist=...
auto_resync_after_reload=true|false
max_requests_per_player=<int>
request_queue_timeout_ms=<long>
payload_cache_max_entries=<int>
payload_cache_max_bytes=<long>

说明：

• verbose_logs：是否输出更详细的日志。
• allow_jpg / allow_jpeg：是否允许读取 JPG / JPEG 源图片。
• whitelist：白名单过滤规则，只加载匹配的画作。
• blacklist：黑名单过滤规则，跳过匹配的画作。
• auto_resync_after_reload：执行重载后是否自动向在线玩家重新同步。
• max_requests_per_player：单个玩家可同时请求的贴图数量上限。
• request_queue_timeout_ms：请求队列超时时间，单位为毫秒。
• payload_cache_max_entries：服务端贴图载荷缓存条目上限。
• payload_cache_max_bytes：服务端贴图载荷缓存字节上限。

游戏内命令

/pixel_gallery status
/pixel_gallery reload
/pixel_gallery resync
/pixel_gallery config

命令说明：

• status：查看已注册画作、待处理玩家、请求队列和载荷缓存状态。
• reload：重新读取配置和已有画作贴图。
• resync：向在线玩家重新发送同步清单。
• config：输出当前生效配置快照。

构建项目

本项目使用 Gradle 和 fml-loom 构建，Java 版本目标为 17。

FishModLoader jar 的查找顺序如下：

1. fml_jar，来自命令行 -Pfml_jar=... 或 gradle.properties。
2. gradle-local.properties 中的 fml_jar_local。
3. 环境变量 FML_JAR。
4. fml_jar_bundled，默认值为 libs/FishModLoader-v3.4.2.jar。

构建命令：

.\gradlew.bat build

如果本机 FishModLoader 路径不适合提交到仓库，推荐写入 gradle-local.properties：

fml_jar_local=F:/mitemod/fml/FishModLoader-v3.4.2.jar

gradle-local.properties 已作为本地私有配置处理，不应放入发布包。

验证命令

校验语言资源：

.\gradlew.bat validateLangResources

日常开发验证：

.\gradlew.bat verifyProject

发布前推荐验证：

.\gradlew.bat releasePrep verifyProject build

verifyProject 会执行 JSON 资源校验、语言资源校验、测试以及发布内容检查。

发布整理

可安全清理的本地构建产物：

build/
.gradle/
tmp_*_javap.txt

应保留为本地运行数据，但不要放入发布包：

run/

推荐发布内容：

src/
gradle/
gradlew
gradlew.bat
build.gradle
settings.gradle
gradle.properties
README.md
libs/ 下发布所需的依赖 jar

发布准备命令：

.\gradlew.bat releasePrep verifyReleaseContents build

verifyReleaseContents 会检查暂存发布内容和构建出的 jar，避免把 run/、.gradle/、gradle-local.properties、日志文件等本地运行产物打进去。

本地化资源规则

• src/main/resources/assets/pixel_gallery/lang/*.json 必须保持 UTF-8 编码。
• 各语言文件的翻译键应保持一致。
• %s 等格式占位符数量必须与 en_US.json 对齐。
• 非英文语言文件中不要出现乱码文本。

排查问题

1. 启动日志中应出现类似 Registered N custom paintings. 的注册信息。
2. 确认画作目录使用 NxM 格式，而不是 N*M。
3. 确认图片尺寸严格等于 N*16 x M*16。
4. 多人游戏进入后等待几秒，让客户端完成贴图同步。
5. 检查客户端缓存目录：pixel_gallery/cache/<server_key>/。
6. 修改图片或配置后，先执行 /pixel_gallery reload，必要时再执行 /pixel_gallery resync。
7. 如果新增了全新的画作条目，需要重启游戏；单纯替换已有画作贴图通常可以通过重载和重同步生效。

MITE 1.6.4 限制

MITE 1.6.4 的画作实体依赖本地 EnumArt 条目，因此服务端和客户端必须在启动时拥有一致的画作注册结果。

/pixel_gallery reload 目前只更新已有 EnumArt 条目的贴图。新增画作条目需要重启游戏后才能注册。