纹理缩放器

Texture Scaler — 在低限制 GPU 上杜绝字体损坏和图集崩溃。

问题所在

某些 GPU 报告的最大纹理尺寸（GL_MAX_TEXTURE_SIZE）相对较小：AMD RX 580 和大多数 Intel 集成显卡报告为 16384，较老的集成显卡仅为 8192。当资源包或其他模组提供的方块或物品纹理为 1024–4096 px 时，Minecraft 的方块图集——即容纳所有方块纹理的单张图集——将无法拼接：

java.lang.RuntimeException: Requested atlas size 32768 exceeds maximum 16384
net.minecraft.client.renderer.texture.StitcherException

资源重载被中止。字体纹理（包括所有 CJK 字形）永远不会加载：所有文本渲染为空方块，游戏通常随后不久即崩溃。

本模组的作用

Texture Scaler 在启动时读取你的 GPU 限制，并在加载时通过运行时覆盖资源包，仅对会溢出图集的纹理进行降采样：

• 不会修改任何内容。 不编辑或替换任何模组 jar、资源包或磁盘文件。覆盖包位于所有其他包之上，仅为需要降采样的纹理提供降采样副本。
• 按比例降采样，保持宽高比，双线性过滤。
• 自动阈值： cap = clamp(GL_MAX_TEXTURE_SIZE / 32, 256, 2048) —— NVIDIA（限制 32768）上为 1024，AMD RX 580 / Intel UHD（16384）上为 512，较老的集成显卡（8192）上为 256。可手动覆盖。
• 模型 UV 安全： 会检测通过绝对像素 UV（texture_size）引用纹理的模型 JSON，并跳过这些纹理，因此不会出现渲染错位。
• 对启动友好： 结果按每次重载缓存在内存中，并缓存到磁盘（键 = 路径 + 原始尺寸 + 上限），带有持久化的尺寸清单和重载间的增量重新检查。即使在非常大的模组包上，典型开销也只有 2–3 秒。

要求

• Minecraft 1.20.1，Forge 47+
• Java 17
• 仅客户端。 在服务器上安装毫无作用——服务器不渲染纹理。

配置

config/texturescaler-client.toml：

选项	含义
enabled	总开关（默认 true）
capOverride	以像素为单位强制设置像素上限；0 = 自动（默认）
capDivisor / capMin / capMax	自动公式的参数
diskCacheEnabled	将降采样结果缓存到磁盘（默认 true）
cacheDir	缓存目录
skipNamespaces	保持不变的命名空间（默认 ["minecraft", "texturescaler"]）
extraTextureDirs	为方块图集提供纹理的额外目录（例如 ["blocks"]）
debugLog	详细日志（默认 false）

缓存位于 .minecraft/texturescaler/cache/。更新模组后，或者如果你怀疑某个条目已过期，只需删除该文件夹——它会在下次启动时自动重建（之后的首次启动会较慢）。

注意事项

• 本模组是为当前会失败的机器构建的。在限制较大的 GPU 上，自动上限为 1024，因此 2048/4096 px 的纹理仍会被降采样；如果你希望在此类设备上保持完整质量，请提高 capOverride（例如 2048）或设置 enabled = false。
• 如果你的日志中包含 StitcherException 或 Requested atlas size ... exceeds maximum，那正是本模组所修复的故障。
• 欢迎提交错误报告——请附上 latest.log 和你的 GPU 型号。

许可证与源码

依据 Mozilla Public License 2.0 授权。源代码和问题追踪器：请参见本项目页面上的链接。

（AI 翻译）