Repository navigation
UserGuide.Configuration.zh
English | 简体中文
本文档是 Ultimate Scaler 配置系统（配置版本 4）的完整技术参考。它面向希望深入理解模组工作机制的高级用户、需要进行复杂或非标准配置的用户、开发者与潜在贡献者，以及需要查阅某个具体配置项的用户。
如果你需要快速上手，请直接使用游戏内的配置界面：它提供了标签、悬浮提示、输入校验和方块选择器。本文档是配置界面背后的参考手册。
- 如果安装了 Cloth Config，按下快捷键（默认是
Ctrl+U），或在 Mod Menu 中点击本模组的图标，即可打开新版配置界面。 - 在 Mod Menu 中按住
Shift再点击模组图标，可以打开旧版配置界面。旧版界面已弃用，保留为不熟悉新版界面的老用户提供过渡选择，未来的新选项将不会加入旧版配置界面，将在未来版本中移除；本文档描述的是新版界面。 - 配置文件位于
.minecraft/config/ultimate_scaler.toml，可以直接编辑。 - 修改配置文件后，在游戏内执行
/reload即可应用。带有[ReS]标签的选项需要重启游戏才能生效；带有[ReE]标签的选项可能需要重进世界（或重启服务端）才能生效。 - 配置文件使用 TOML 格式。顶层是
CONFIG_VERSION，其余选项按表（table）分组，例如[general]和[worldGen.reposition]。
强烈推荐新手使用配置界面。它的布局更直观，带有悬浮提示和输入校验，并提供方块选择器，而且会自动把配置写入文件。
默认配置文件如下：
# Check out our GitHub Wiki for detailed explanations of all the configuration options:
# https://github.com/INF32768/UltimateScaler/wiki/UserGuide.Configuration.en
CONFIG_VERSION = 4
[general]
configScreenKeybind = 682
showTerrainPos = true
publicTerrainPos = true
[worldGen.reposition]
shift = ["0", "0", "0"]
scale = ["1", "1", "1"]
extendedYAxisEffect = false
highPrecisionMode = false
[worldGen.fluidReplace]
defaultFluid = ""
undergroundLava = ""
[worldGen.farLandsControl]
farLandsPos = "DEFAULT"
customDivisor = 3.3554432E7
limitReturnValue = false
maxLogarithmValue = 7
[fixesAndExpansion]
endRings = false
worldBorder = true
chunkGenerationOutOfBound = true
mineShaftCannotGenerate = true
[utilities]
expandDatapackValueRange = true配置界面中的分类与配置文件中的表对应关系如下：
| 界面分类 / 子分类 | 配置表 |
|---|---|
| 常规设置 | [general] |
| 世界生成设置 → 重定位 | [worldGen.reposition] |
| 世界生成设置 → 流体替换 | [worldGen.fluidReplace] |
| 世界生成设置 → 边境之地控制 | [worldGen.farLandsControl] |
| 修复与扩展 | [fixesAndExpansion] |
| 实用工具 | [utilities] |
| 提示 | 不写入配置文件 |
提示分类只用于展示信息，不写入配置文件。它包含简短的欢迎语、指向本 Wiki 的链接、关于旧版界面的提示，以及通用标签的图例。
新版配置界面使用简短的标签（labels）来描述配置项的状态和可能的影响。标签会显示在配置项显示名称的开头；将鼠标悬停在配置项上时，会在“【标签说明】”标题下显示完整的标签描述。
提示分类中包含通用标签的图例；修复与扩展分类中则单独包含该分类所使用的距离现象标签图例。
| 标签 | 名称 | 含义 |
|---|---|---|
[Exp] |
实验性（Experimental） | 仍处于测试阶段，可能不稳定或存在风险。 |
[Fau] |
可能不符合预期（Faultable） | 此功能导致的现象可能不符合预期。 |
[Rad] |
激进（Radical） | 功能可能很强大，但可能具有副作用。 |
[ReS] |
需要重启（Requires restart） | 更改可能需要重启游戏才能生效。 |
[ReE] |
需要重进世界（Requires re-enter） | 更改可能需要重进世界（重启服务端）才能生效。 |
[LoP] |
低性能（Low performance） | 性能开销较高，可能导致卡顿。 |
[Opt] |
优化（Optimization） | 有助于优化性能或提高稳定性。 |
[Cln] |
仅客户端（Client-only） | 只影响本地显示或操作。 |
[Dual] |
双端（Dual environment） | 需要客户端和服务端同时开启才能生效。 |
[Srv] |
仅服务端（Server-only） | 服务端功能，客户端无需开启。 |
[SPO] |
仅单人（Singleplayer only） | 仅在单人游戏中才能正常生效。 |
修复与扩展中的配置项还会带有一个距离现象标签。标签是一个带颜色的几何符号：形状表示问题的成因，颜色表示问题的影响类型。例如，蓝色的 ■ 表示“可能导致卡死或崩溃的整数溢出”。
修复与扩展分类的标签图例会列出以下符号和颜色。
符号（成因）：
| 符号 | 名称 | 含义 |
|---|---|---|
■ |
整数溢出 | 该问题由整数溢出导致。 |
● |
精度损失 | 该问题由浮点数精度损失导致。 |
▲ |
两者兼有 | 该问题同时存在整数溢出和精度损失的因素。 |
◆ |
人为限制 | 该问题很可能是人为限制导致的。 |
颜色（影响）：
| 颜色 | 名称 | 含义 |
|---|---|---|
| 蓝色 | 卡死或崩溃 | 该问题会导致游戏卡死或崩溃。 |
| 金色 | 客户端渲染 | 该问题会导致游戏客户端渲染出现异常。 |
| 深绿色 | 游戏逻辑 | 该问题会导致其他游戏逻辑出错。 |
| 黄色 | 世界生成 | 该问题会导致世界生成出现异常。 |
在下面的章节中，每个配置项都以配置文件路径和界面显示名称标识，并列出文件中的类型、默认值以及显示名称旁的标签。
-
general.configScreenKeybind—— 配置界面快捷键[Cln]- 类型：
int - 默认值：
682（Ctrl+U）
打开新版配置界面的快捷键。在配置界面中点击对应按钮，然后按下想要的按键组合即可修改，支持
Ctrl、Alt和Shift。该快捷键只在客户端生效，因此带有[Cln]标签。该值是一个打包后的整数：
(keyCode << 3) | modifier。低三位是修饰键位，从低位到高位依次为Alt、Ctrl、Shift；其余高位是主按键的 GLFW 键控代码。例如，默认值682等于(85 << 3) | 2：键控代码85对应U，修饰键2对应Ctrl。完整的 GLFW 键控代码列表可以在 GLFW 文档 中找到。在 V2/V3 中，该设置被拆分为
optionMenuKeyCode和optionMenuModifierValue；迁移时会把这两个旧值打包成这个字段。 - 类型：
-
general.showTerrainPos—— 在调试屏幕中显示地形坐标[Cln]- 类型：
boolean - 默认值：
true
若开启，则会在调试屏幕（F3）左侧的
XYZ行和Block行之间添加一行TerrainXYZ，显示玩家所在位置经过缩放和偏移后对应的地形（世界生成）坐标，格式与原版XYZ行类似。该显示使用双精度浮点数，可能存在精度损失。若同时开启了高精度模式（
worldGen.reposition.highPrecisionMode），则主TerrainXYZ行会使用高精度十进制值，并额外显示一行TerrainXYZ (double)来展示双精度表示。
showTerrainPos开启时的调试屏幕示例。左侧为开启高精度模式时的显示，右侧为关闭时的显示。 - 类型：
整个世界生成设置分类都是服务端功能（[Srv]），其中的选项分为三个子分类：重定位、流体替换和边境之地控制。
shift 和 scale 都是恰好包含三个十进制值的数组，分别对应 X、Y、Z 轴。在配置文件中，它们以带引号的字符串保存，例如 ["0", "0", "0"]。这些引号是有意保留的：这样可以让模组保留 BigDecimal 的精度，而不是让 TOML 解析器先经过 Long 或 Double 转换。旧版 V4 文件中不带引号的数组仍然可以读取，模组会在解析前自动为它们补上引号。
-
worldGen.reposition.shift—— 偏移 (X, Y, Z)- 类型：3 个十进制字符串组成的数组（加载后为
BigDecimal[3]） - 默认值：
["0", "0", "0"]
将世界生成平移指定的距离，单位为方块。三个元素分别对应 X、Y、Z 轴（在配置界面中从上到下）。在配置界面中，每个元素都可以填写普通数字（如
123.123）或科学计数法（如1.23e4）。详细说明请参阅世界生成重定位功能详解。
- 类型：3 个十进制字符串组成的数组（加载后为
-
worldGen.reposition.scale—— 缩放 (X, Y, Z)- 类型：3 个十进制字符串组成的数组（加载后为
BigDecimal[3]） - 默认值：
["1", "1", "1"]
以世界原点为中心，将世界生成缩放指定的倍数。三个元素分别对应 X、Y、Z 轴（在配置界面中从上到下），支持的格式与
shift相同。详细说明请参阅世界生成重定位功能详解。
- 类型：3 个十进制字符串组成的数组（加载后为
-
worldGen.reposition.highPrecisionMode—— 高精度模式[Exp][Rad][LoP]- 类型：
boolean - 默认值：
false
若开启，则在重定位时使用高精度数据类型来计算坐标，以避免精度损失。同时，偏移和缩放功能可以应用到更多的生成器上。
该选项可能显著增加 CPU 运算负荷和内存消耗，建议仅在必要时开启（例如偏移量绝对值超过 2^53 时）。
该选项在旧版本中名为 BigInteger 重写。开启后，调试屏幕中
TerrainXYZ行的显示方式也会发生变化，详见general.showTerrainPos的说明。详细说明请参阅世界生成重定位功能详解。
- 类型：
-
worldGen.reposition.extendedYAxisEffect—— Y 轴重定位扩展[Exp][Fau]- 类型：
boolean - 默认值：
false
若开启，则偏移和缩放功能还会影响更多与 Y 轴密切相关的地形生成算法，例如地形海拔、海平面和地底熔岩层。
该选项在旧版本中名为 Y 轴扩展偏移。
详细说明请参阅世界生成重定位功能详解。
- 类型：
在 V4 中，旧版的“布尔开关 + 方块 ID”成对字段被合并为每个功能一个方块 ID 字段。空字符串表示“禁用”；非空字符串表示要放置的方块 ID。在配置界面中，每个功能都是一个开关加一个方块下拉框；关闭开关时，该字段会写为空字符串。下拉框默认为空气，因此开启开关并保持空气选中时，会写入 "minecraft:air"。
-
worldGen.fluidReplace.defaultFluid—— 替换默认流体- 类型：
String（方块 ID） - 默认值：
""（禁用）
若非空，则将各维度的默认流体（主世界的水、下界的熔岩）替换为指定的方块。通常替换成空气，以防止流体过多导致游戏卡顿。目前仅能替换海洋和含水层中的流体。
该值是一个方块 ID，例如
"minecraft:water"，可以省略前缀"minecraft:"。加载配置时，无效的方块 ID 会被重置为空字符串。在 V2/V3 中，该设置被拆分为
replaceDefaultFluid（布尔值）和replaceDefaultFluidBlock（字符串）。 - 类型：
-
worldGen.fluidReplace.undergroundLava—— 替换地底熔岩[Exp][Fau]- 类型：
String（方块 ID） - 默认值：
""（禁用）
在生成含水层时，所有位置高度低于 Y = -54 并且低于本维度海平面高度的空气都会被填充为熔岩。这些熔岩被称为“地底熔岩”，其坐标和填充的方块都是硬编码的。
若非空，则会将地底熔岩替换为指定的方块。该值是一个方块 ID，格式和校验规则与
defaultFluid相同。由于含水层生成机制复杂，本功能目前存在较多 bug，请谨慎使用。在 V2/V3 中，该设置被拆分为
replaceUndergroundLava（布尔值）和replaceUndergroundLavaBlock（字符串）。 - 类型：
-
worldGen.farLandsControl.farLandsPos—— 边境之地位置- 类型：
String（枚举） - 默认值：
"DEFAULT" - 可选值：
BETA、RELEASE、DEFAULT、REMOVED
该选项通过更改
maintainPrecision方法来控制边境之地的位置，进而影响允许的噪声采样溢出坐标：值 界面显示名称 描述 噪声溢出坐标 边境之地位置（鼠标悬停以显示完整坐标） BETABeta 1.7.3 前 Java 版 Infdev 20100327 至 Beta 1.7.3 以及基岩版的“经典的”边境之地位置。 231 12550824 RELEASEBeta 1.8 ~ 1.13.2 Java 版 Beta 1.8 至正式版 1.13.2 的边境之地位置。 263 5.3905e+16 DEFAULT默认 Java 版 1.14 至今的边境之地位置。可以通过 customDivisor修改除数。288 1.8088e+24 REMOVED移除 移除传统意义上的边境之地和所有噪声溢出。 21024 N/A 旧版的
CUSTOM值已不存在。它之所以被移除，是因为它带有误导性：它并不能把边境之地移动到任意指定位置，而是修改maintainPrecision的除数，在改变地形生成行为的同时，使边境之地作为连带结果发生移动。需要调整这一行为的高级用户，仍然可以在选择DEFAULT后修改customDivisor；customDivisor为33554432时，行为与原版 1.14+ 一致。旧版 V3 配置中的CUSTOM会迁移为DEFAULT，并保留原来的除数；旧版 V3 配置中的DEFAULT会迁移为DEFAULT，除数为33554432。选择
DEFAULT时，各层边境之地的位置为(2^63 * 除数 + 2^31) / 坐标比例，其中“除数”就是customDivisor。若除数小于 2^9、大于 2^32 或不是 2 的整数倍，都会影响正常地形生成。关于此配置项和
maintainPrecision方法的深入研究，请参考文章 maintainPrecision 方法。 - 类型：
-
worldGen.farLandsControl.customDivisor—— maintainPrecision 方法除数- 类型：
double - 默认值：
33554432（在 TOML 文件中写作3.3554432E7） - 显示条件：
farLandsPos == "DEFAULT"
maintainPrecision方法使用的除数。配置界面显示为33554432，TOML 文件则把这个 double 值写作3.3554432E7。修改该值会改变方法的行为，也可能影响正常地形生成，因此它并不是一个直接“把边境之地移动到指定位置”的选项。customDivisor为33554432时，行为与原版 1.14+ 一致。旧版的CUSTOM选项等价于DEFAULT加上一个非默认的除数。在 V2/V3 中，该字段名为
maintainPrecisionCustomDivisor。 - 类型：
-
worldGen.farLandsControl.limitReturnValue—— 限制 maintainPrecision 方法返回值[Fau]- 类型：
boolean - 默认值：
false
若开启，则会限制
maintainPrecision方法的返回值范围，详见下一项。 - 类型：
-
worldGen.farLandsControl.maxLogarithmValue—— 最大返回值（10^n）- 类型：
int - 默认值：
7 - 显示条件：
limitReturnValue == true
若
limitReturnValue开启，则会限制maintainPrecision方法返回值的绝对值，使其不超过10^maxLogarithmValue。此值小于 26 将阻止边缘之地生成（这是其设计用途），小于 9 则会阻止噪声溢出（即边境之地不再生成）。过小的值同样会导致正常地形出现问题，详见 maintainPrecision 方法 中的“限制返回值范围”部分。
- 类型：
该分类中的选项都与距离现象有关。每个选项都带有一个距离现象标签；符号和颜色的图例见距离现象标签。该分类在配置界面中还包含一个标签图例子分类，用于展示同一份图例。
-
fixesAndExpansion.endRings—— 末地环[Srv]■（黄色）- 类型：
boolean - 默认值：
false
“末地环”是一种存在于末地中的距离现象。由于整数溢出，末地的地形会在以世界原点为中心的若干个圆形区域中缺失（MC-159283），这些区域被称为“末地环”。该现象从 X/Z = ±370,720 至 524,287 开始出现，直到 X 和 Z 都为 ±30,000,317 时在世界界限范围内发生最后一次，共发生 6,549 次。（本段摘自 Minecraft Wiki）
开启此选项后，“末地环”将被修复（不再生成）。
- 类型：
-
fixesAndExpansion.worldBorder—— 世界边界[Dual][ReS]◆（深绿色）- 类型：
boolean - 默认值：
true
移除 X/Z = ±30000000 处的空气墙，玩家可以在更远处进行探索，世界生成也可以在这之外进行。同时，
/tp、/worldborder等命令中坐标参数的范围限制也会被移除。世界边界本身仍然存在，但可以通过
/worldborder命令将其边长设置为非常大的值，效果类似于移除。该选项需要客户端和服务端同时开启，并且更改可能需要重启游戏才能生效。
- 类型：
-
fixesAndExpansion.chunkGenerationOutOfBound—— 远处生成区块崩溃[Srv]◆（蓝色）- 类型：
boolean - 默认值：
true
从 1.21.2 开始，Minecraft 添加了一个人为的限制，在生成区块前会检查将要生成的区块的 X/Z 坐标是否超过 ±33552992（方块坐标）。若是，则会抛出
IllegalStateException("Trying to create chunk out of reasonable bounds: " + pos)异常并导致游戏崩溃。开启此选项后，该限制将被移除，生成器可以在更远处生成区块。
- 类型：
-
fixesAndExpansion.mineShaftCannotGenerate—— 生成废弃矿井崩溃[Srv]■（蓝色）- 类型：
boolean - 默认值：
true
从 1.21.x 开始，由于整数溢出，试图在 X/Z 坐标超过 ±1073741824 的位置生成废弃矿井时，会导致游戏崩溃。开启此选项后，废弃矿井的正常生成范围将被扩展到 32 位整数的范围。
- 类型：
-
utilities.expandDatapackValueRange—— 扩展数据包字面量取值范围[Srv][ReS]- 类型：
boolean - 默认值：
true
在数据包的密度函数定义文件中，许多字面量的取值范围都受到人为限制，包括常数取值以及密度函数
minecraft:old_blended_noise中各参数的取值。开启此选项后，这些限制将被解除。更改可能需要重启游戏才能生效。 - 类型：
-
CONFIG_VERSION- 类型：
int - 默认值：
4
配置文件版本号，用于检查是否需要更新或迁移。请勿手动修改。
- 类型：
-
general.publicTerrainPos- 类型：
boolean - 默认值：
true - 尚未实现，目前没有任何效果。
该选项不在配置界面中显示。如果将来在服务端实现，服务器内的所有玩家都可以在调试屏幕中看到
TerrainXYZ行，其数据由服务端同步。 - 类型：
配置会在启动时加载，并在每次执行 /reload 时重新读取。首次启动时，如果配置文件不存在，模组会创建一个默认配置文件。只有在新配置被完整读取、迁移并校验成功之后，才会替换当前正在使用的配置。
如果加载过程中出现任何错误（读取错误、V2/V3 迁移错误或校验错误），模组会继续使用重载前正在使用的配置，并将它写回文件。如果此前没有成功加载过配置（例如启动时的第一次加载），才会使用默认值。重载时配置文件不存在也属于这种情况：模组会保留重载前的配置并写回，而不是立即重置为默认值。
在用兜底配置覆盖现有文件之前，模组会先把它备份为 ultimate_scaler.toml.bak。如果备份创建失败，则不会覆盖现有文件，但内存中仍会继续使用兜底配置；如果兜底配置写回也失败，内存中同样会继续使用它。每次失败都会覆盖这个备份文件，因此它只是一个安全网，而不是完整的历史版本记录。
保存配置时，模组会先写入一个临时文件，再替换目标文件。文件系统支持原子移动时，替换是原子的；不支持时则退化为普通替换。这样可以避免写入中途失败把原文件截断。
V2 和 V3 配置文件会自动迁移到 V4。V2 文件为 config/ultimatescaler.toml；只有在 V4 文件成功保存后，旧的 V2 文件才会被删除。V3 文件在迁移成功后会由 V4 文件替换。如果迁移失败，上述兜底行为会保留旧配置并备份旧文件；如果迁移结果保存失败，旧文件会被保留，以便下次加载时重试迁移。
| V2/V3 字段 | V4 字段 | 说明 |
|---|---|---|
optionMenuKeyCode + optionMenuModifierValue
|
general.configScreenKeybind |
打包为 (keyCode << 3) | modifier。 |
showTerrainPos |
general.showTerrainPos |
|
publicTerrainPos |
general.publicTerrainPos |
|
globalBigDecimalOffset |
worldGen.reposition.shift |
V4 中保存为带引号的十进制字符串；旧版不带引号的数组会自动转换。 |
globalBigDecimalScale |
worldGen.reposition.scale |
规则同上。 |
bigIntegerRewrite |
worldGen.reposition.highPrecisionMode |
|
extraYOffset |
worldGen.reposition.extendedYAxisEffect |
|
replaceDefaultFluid + replaceDefaultFluidBlock
|
worldGen.fluidReplace.defaultFluid |
旧开关关闭时为空字符串，否则为旧的方块 ID。 |
replaceUndergroundLava + replaceUndergroundLavaBlock
|
worldGen.fluidReplace.undergroundLava |
规则同上。 |
farLandsPos |
worldGen.farLandsControl.farLandsPos |
CUSTOM 会变为 DEFAULT，并保留旧除数。 |
maintainPrecisionCustomDivisor |
worldGen.farLandsControl.customDivisor |
|
limitReturnValue |
worldGen.farLandsControl.limitReturnValue |
|
maxNoiseLogarithmValue |
worldGen.farLandsControl.maxLogarithmValue |
|
fixEndRings |
fixesAndExpansion.endRings |
|
expandWorldBorder |
fixesAndExpansion.worldBorder |
|
fixChunkGenerationOutOfBound |
fixesAndExpansion.chunkGenerationOutOfBound |
|
fixMineshaftCannotGenerate |
fixesAndExpansion.mineShaftCannotGenerate |
|
expandDatapackValueRange |
utilities.expandDatapackValueRange |
|
CONFIG_VERSION = 3 |
CONFIG_VERSION = 4 |
自动完成。 |