UserGuide.Configuration.en

English | 简体中文

Configuration Reference

This document is the complete technical reference for the Ultimate Scaler configuration system (config version 4). It is intended for advanced users who want to understand how the mod works, for non-standard setups, for developers and contributors, and for users who need to look up a specific option.

If you are looking for a quick start, use the in-game configuration screen: it provides labels, tooltips, input validation and block selection. This document is the reference manual behind that screen.

Opening and Editing the Configuration

• If Cloth Config is installed, press the hotkey (default Ctrl+U) or click the mod's icon in Mod Menu to open the new configuration screen.
• Holding Shift while clicking the mod's icon opens the old configuration screen. The old screen has been deprecated and is retained to provide a transitional option for users unfamiliar with the new screen. Future new options will not be added to the old screen and it will be removed in future versions. This reference describes the new screen.
• The configuration file is located at .minecraft/config/ultimate_scaler.toml. It can be edited directly.
• After editing the file, run /reload in-game to apply the changes. Options marked [ReS] only take effect after restarting the game; options marked [ReE] may require re-entering the world (or restarting the server).
• The configuration file is TOML. The top level contains CONFIG_VERSION; all options are grouped into tables such as [general] and [worldGen.reposition].

It is highly recommended that new users use the configuration screen. It offers a more intuitive layout, tooltips, input validation, and a block picker, and it writes the file for you.

Configuration File Layout

A default configuration file looks like this:

# 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

The GUI categories correspond to the file as follows:

GUI category / subcategory	Configuration table
General Settings	[general]
World Generation Settings → Reposition	[worldGen.reposition]
World Generation Settings → Fluid Replacement	[worldGen.fluidReplace]
World Generation Settings → Far Lands Control	[worldGen.farLandsControl]
Fixes And Expansion	[fixesAndExpansion]
Utilities	[utilities]
Hints	Not saved

The Hints category is informational only. It contains a short introduction, a link to this Wiki, a note about the old screen, and the legend for the general labels.

Labels and Metadata

The new screen uses short labels (tags) to describe an option's status and side effects. A tag is prefixed to the option's display name, and hovering over the option shows the full label descriptions under a [Labels Description] heading.

The Hints category contains the legend for the general labels. Fixes And Expansion contains a separate legend for the distance-effect labels used by its options.

General Labels

Tag	Name	Meaning
[Exp]	Experimental	Still in the testing phase; may be unstable or risky.
[Fau]	Faultable	The effects of this feature may not work as expected.
[Rad]	Radical	Powerful, but may have side effects.
[ReS]	Requires restart	Changes may require restarting the game to take effect.
[ReE]	Requires re-enter	Changes may require re-entering the world (restarting the server).
[LoP]	Low performance	High performance cost; may cause lag.
[Opt]	Optimization	Helps optimize performance or improve stability.
[Cln]	Client-only	Only affects local display/operation.
[Dual]	Dual environment	Requires both the client and the server to be enabled.
[Srv]	Server-only	Server-side feature; the client does not need to enable it.
[SPO]	Singleplayer only	Only works properly in singleplayer mode.

Distance-Effect Labels

Options in Fixes And Expansion also carry a distance-effect tag. The tag is a colored geometric symbol: the shape describes the cause of the problem, and the color describes the type of effect. For example, a blue ■ means "integer overflow that can cause a crash or freeze".

The Fixes And Expansion legend lists the following symbols and colors.

Symbols (cause):

Symbol	Name	Meaning
■	Integer overflow	The problem is caused by integer overflow.
●	Precision loss	The problem is caused by floating-point precision loss.
▲	Both	The problem involves both integer overflow and precision loss.
◆	Intended restriction	The problem is most likely due to an intended restriction.

Colors (effect):

Color	Name	Meaning
Blue	Crash or freeze	The problem can cause the game to freeze or crash.
Gold	Client rendering	The problem can cause the client to render abnormally.
Dark green	Game logic	The problem can cause other game logic errors.
Yellow	World generation	The problem can cause world generation to behave abnormally.

---

In the sections below, each option is identified by its configuration path and its GUI display name. The type and default value describe the configuration file; labels are shown next to the display name.

General Settings

• general.configScreenKeybind — Open Config Menu Key [Cln]

  • Type: int
  • Default: 682 (Ctrl+U)

  The keybinding that opens the new configuration screen. In the screen, click the button and press the desired key combination; Ctrl, Alt, and Shift are supported. The screen is client-side, hence the [Cln] label.

  The value is a packed integer: (keyCode << 3) | modifier. The low three bits are the modifier bits, from lowest to highest: Alt, Ctrl, Shift. The remaining bits are the GLFW key code of the main key. For example, the default 682 is (85 << 3) | 2: key code 85 is U, and modifier 2 is Ctrl. A complete list of GLFW key codes can be found in the GLFW documentation.

  In V2/V3 this was split into optionMenuKeyCode and optionMenuModifierValue; the migration packs the two old values into this single field.

• general.showTerrainPos — Show Terrain Position in Debug Screen [Cln]

  • Type: boolean
  • Default: true

  If enabled, adds a TerrainXYZ line to the left side of the debug screen (F3), between the XYZ line and the Block line. It displays the terrain (world generation) coordinates corresponding to the player's position after shift and scaling, formatted similarly to the vanilla XYZ line. The double-precision display may lose precision.

  If High Precision Mode (worldGen.reposition.highPrecisionMode) is enabled, the main TerrainXYZ line uses a high-precision decimal value, and an additional TerrainXYZ (double) line shows the double-precision representation.

  Example debug screen with showTerrainPos enabled. The left side shows the display with High Precision Mode enabled; the right side shows it with High Precision Mode disabled.

World Generation Settings

The whole World Generation Settings category is server-side ([Srv]). Its options are grouped into three subcategories: Reposition, Fluid Replacement, and Far Lands Control.

Reposition

Both shift and scale are arrays of exactly three decimal values, corresponding to the X, Y, and Z axes. In the file they are stored as quoted strings, for example ["0", "0", "0"]. The quotes are intentional: they let the mod preserve BigDecimal precision instead of letting the TOML parser convert the values through Long or Double. Unquoted arrays from older V4 files are still accepted and are quoted automatically before parsing.

• worldGen.reposition.shift — Shift (X, Y, Z)

  • Type: array of 3 decimal strings (BigDecimal[3] after loading)
  • Default: ["0", "0", "0"]

  Translates world generation by the specified distance, in blocks. The three elements correspond to the X, Y, and Z axes (top to bottom in the GUI). In the GUI, each element accepts a plain number (e.g., 123.123) or scientific notation (e.g., 1.23e4).

  For details, see Worldgen Reposition Explanation.

• worldGen.reposition.scale — Scale (X, Y, Z)

  • Type: array of 3 decimal strings (BigDecimal[3] after loading)
  • Default: ["1", "1", "1"]

  Scales world generation by the specified factor, centered on the world origin. The three elements correspond to the X, Y, and Z axes (top to bottom in the GUI). The accepted formats are the same as for shift.

  For details, see Worldgen Reposition Explanation.

• worldGen.reposition.highPrecisionMode — High Precision Mode [Exp] [Rad] [LoP]

  • Type: boolean
  • Default: false

  If enabled, high-precision data types are used for coordinate calculations during shift and scaling, preventing precision loss. It also allows shift and scaling to be applied to more generators.

  This option may significantly increase CPU load and memory consumption. Enable it only when necessary (for example, when the absolute shift value exceeds 2^53).

  This option was called BigInteger Rewrite in older versions. When enabled, it also changes the debug screen display as described under general.showTerrainPos.

  For details, see Worldgen Reposition Explanation.

• worldGen.reposition.extendedYAxisEffect — Extra Y-axis Effect [Exp] [Fau]

  • Type: boolean
  • Default: false

  If enabled, shift and scaling also affect terrain generation algorithms that are closely related to the Y-axis, such as terrain height, sea level, and underground lava layers.

  This option was called Extra Y-axis Offset in older versions.

  For details, see Worldgen Reposition Explanation.

Fluid Replacement

In V4, the old boolean + block ID pairs are merged into a single block ID field per feature. An empty string means "disabled"; a non-empty value is the block ID to place. In the GUI, each feature is a toggle plus a block dropdown; when the toggle is off, the field is written as an empty string. The dropdown defaults to Air, so enabling a toggle and leaving Air selected writes "minecraft:air".

• worldGen.fluidReplace.defaultFluid — Replace Default Fluid

  • Type: String (block ID)
  • Default: "" (disabled)

  If non-empty, the default fluid in each dimension (water in the Overworld, lava in the Nether) is replaced with the specified block. This is commonly set to air to prevent excessive fluid generation from causing lag. Currently, this only replaces fluids in oceans and aquifers.

  The value is a block ID, e.g., "minecraft:water". The "minecraft:" prefix can be omitted. Invalid block IDs are reset to an empty string when the configuration is loaded.

  In V2/V3 this was split into replaceDefaultFluid (boolean) and replaceDefaultFluidBlock (string).

• worldGen.fluidReplace.undergroundLava — Replace Underground Lava [Exp] [Fau]

  • Type: String (block ID)
  • Default: "" (disabled)

  During aquifer generation, air blocks below Y = -54 and below the dimension's sea level are filled with lava. This lava is referred to as "underground lava". Both the coordinates and the filled block are hardcoded.

  If non-empty, the underground lava is replaced with the specified block. The value is a block ID, with the same format and validation as defaultFluid. Due to the complexity of aquifer generation, this feature currently has several bugs and should be used with caution.

  In V2/V3 this was split into replaceUndergroundLava (boolean) and replaceUndergroundLavaBlock (string).

Far Lands Control

• worldGen.farLandsControl.farLandsPos — Far Lands Position

  • Type: String (enum)
  • Default: "DEFAULT"
  • Accepted values: BETA, RELEASE, DEFAULT, REMOVED

  This option controls the position of the Far Lands by modifying the maintainPrecision method, which affects the overflow coordinates for noise sampling:

  Value	GUI name	Description	Noise overflow coordinates	Far Lands position (hover for full value)
  BETA	Pre Beta 1.7.3	The "classic" Far Lands position from Java Edition Infdev 20100327 to Beta 1.7.3, as well as Bedrock Edition.	231	12550824
  RELEASE	Beta 1.8 ~ 1.13.2	The Far Lands position from Java Edition Beta 1.8 to 1.13.2.	263	5.3905e+16
  DEFAULT	Default	The Far Lands position from Java Edition 1.14 onwards. The divisor can be changed with customDivisor.	288	1.8088e+24
  REMOVED	Removed	Removes the traditional Far Lands and all noise overflow.	21024	N/A

  The old CUSTOM value no longer exists. It was misleading: it did not move the Far Lands to an arbitrary chosen position, but changed the maintainPrecision divisor, altering terrain generation and shifting the Far Lands as a side effect. Advanced users can still change customDivisor while DEFAULT is selected; a customDivisor of 33554432 reproduces the vanilla 1.14+ behavior. Old V3 configurations with CUSTOM migrate to DEFAULT with the old divisor preserved; old V3 DEFAULT configurations migrate with 33554432.

  For DEFAULT, the position of the various Far Lands layers is (2^63 * divisor + 2^31) / coordinate scale, where divisor is customDivisor. If the divisor is less than 2^9, greater than 2^32, or not an integer multiple of 2, it will affect normal terrain generation.

  For in-depth research on this option and the maintainPrecision method, see maintainPrecision Method.

• worldGen.farLandsControl.customDivisor — maintainPrecision Divisor

  • Type: double
  • Default: 33554432 (written as 3.3554432E7 in the TOML file)
  • Shown when: farLandsPos == "DEFAULT"

  The divisor used by the maintainPrecision method. The GUI displays it as 33554432; the TOML file writes the double value as 3.3554432E7. Changing it alters the method's behavior and can also affect normal terrain generation, so it is not a direct "move the Far Lands to a chosen position" control. A customDivisor of 33554432 reproduces the vanilla 1.14+ behavior. The old CUSTOM option is equivalent to DEFAULT plus a non-default divisor.

  In V2/V3 this field was called maintainPrecisionCustomDivisor.

• worldGen.farLandsControl.limitReturnValue — Limit maintainPrecision Return Value [Fau]

  • Type: boolean
  • Default: false

  If enabled, limits the return value range of the maintainPrecision method. See the next option for details.

• worldGen.farLandsControl.maxLogarithmValue — Max Return Value (10^n)

  • Type: int
  • Default: 7
  • Shown when: limitReturnValue == true

  If limitReturnValue is enabled, limits the absolute value of the maintainPrecision return value to not exceed 10^maxLogarithmValue.

  Setting this value below 26 prevents the Edge Lands from generating (its designed purpose). Setting it below 9 prevents noise overflow entirely (meaning the Far Lands will no longer generate). Values that are too small will also cause issues with normal terrain generation. See the maintainPrecision method for details.

Fixes And Expansion

The options in this category are related to distance effects. Each option carries a distance-effect tag; see Distance-Effect Labels for the symbol and color legend. The category also contains a Labels Legend subcategory that shows the same legend in-game.

• fixesAndExpansion.endRings — End Rings [Srv] ■ (yellow)

  • Type: boolean
  • Default: false

  "End Rings" are a distance effect present in the End dimension. Due to integer overflow, terrain in the End is missing within several circular rings centered on the world origin (MC-159283). These missing areas are called "End Rings". The phenomenon first appears between X/Z = ±370,720 and 524,287, and occurs 6,549 times in total, with the final occurrence at X and Z = ±30,000,317 within the world border limit.

  (Excerpt adapted from the Minecraft Wiki.)

  Enabling this option repairs the End Rings (they will no longer generate).

• fixesAndExpansion.worldBorder — World Border [Dual] [ReS] ◆ (dark green)

  • Type: boolean
  • Default: true

  Removes the invisible wall at X/Z = ±30000000, allowing players to explore further out and enabling world generation beyond this point. It also removes coordinate limits for commands such as /tp and /worldborder.

  The world border itself still exists, but its size can be set to very large values with the /worldborder command, effectively making it irrelevant.

  This option requires both the client and the server to be enabled, and changes may require restarting the game.

• fixesAndExpansion.chunkGenerationOutOfBound — Chunk Generation Crash at Distance [Srv] ◆ (blue)

  • Type: boolean
  • Default: true

  Starting from version 1.21.2, Minecraft introduced an artificial limit that checks whether the X/Z coordinates of a chunk to be generated exceed ±33552992 (block coordinates). If they do, it throws IllegalStateException("Trying to create chunk out of reasonable bounds: " + pos) and crashes the game.

  Enabling this option removes this restriction, allowing the generator to create chunks further away.

• fixesAndExpansion.mineShaftCannotGenerate — Mineshaft Generation Crash [Srv] ■ (blue)

  • Type: boolean
  • Default: true

  Starting from version 1.21.x, due to integer overflow, attempting to generate mineshafts at X/Z coordinates exceeding ±1073741824 causes the game to crash. Enabling this option extends the valid generation range for mineshafts to the full 32-bit integer range.

Utilities

• utilities.expandDatapackValueRange — Expand Datapack Value Range [Srv] [ReS]

  • Type: boolean
  • Default: true

  In datapack density function definition files, the range of many literal values is artificially limited, including constant values and the arguments of the density function minecraft:old_blended_noise. Enabling this option removes these restrictions. Changes may require restarting the game.

Options Not in the GUI

• CONFIG_VERSION

  • Type: int
  • Default: 4

  Configuration file version number. Used to check whether an update or migration is needed. Do not modify it manually.

• general.publicTerrainPos

  • Type: boolean
  • Default: true
  • Not implemented; currently has no effect.

  This option is not shown in the GUI. If it is implemented on a server, all players on that server would be able to see the TerrainXYZ line in their debug screen, synchronized from the server.

Loading, Saving, and Migration

Loading and Fallback Behavior

The configuration is loaded at startup and whenever /reload is executed. On first launch, if no configuration file exists, a default file is created. A new configuration only replaces the active one after it has been read, migrated, and validated successfully.

If loading fails at any point (a read error, a V2/V3 migration error, or a validation error), the mod keeps the configuration that was active before the reload and writes it back to the file. If there is no previous configuration — for example, on the first load at startup — the mod uses default values. This also applies when the file is missing during a reload: the previously loaded configuration is kept and written back instead of immediately resetting to the defaults.

Before overwriting an existing file with the fallback configuration, the mod creates a backup at ultimate_scaler.toml.bak. If the backup cannot be created, the existing file is left untouched; the in-memory fallback configuration is still used. If writing the fallback itself fails, the in-memory configuration is still used as well. The backup is overwritten on each failure, so it is a safety net rather than a full version history.

Saves use a temporary file followed by a replacement. When the filesystem supports atomic moves, the replacement is atomic; otherwise a normal replace is used. This prevents a failed write from truncating the existing file.

Migrating from V2/V3

V2 and V3 files are migrated automatically to V4. The V2 file is config/ultimatescaler.toml; it is deleted only after the V4 file has been saved successfully. A V3 file is replaced by the V4 file after a successful migration. If migration fails, the fallback behavior above keeps the previous configuration and backs up the old file. If saving the migrated file fails, the old file is kept so the migration can be retried on the next load.

V2/V3 field	V4 field	Notes
optionMenuKeyCode + optionMenuModifierValue	general.configScreenKeybind	Packed as (keyCode << 3) | modifier.
showTerrainPos	general.showTerrainPos
publicTerrainPos	general.publicTerrainPos
globalBigDecimalOffset	worldGen.reposition.shift	Stored as quoted decimal strings in V4; unquoted legacy arrays are converted automatically.
globalBigDecimalScale	worldGen.reposition.scale	Same rule as above.
bigIntegerRewrite	worldGen.reposition.highPrecisionMode
extraYOffset	worldGen.reposition.extendedYAxisEffect
replaceDefaultFluid + replaceDefaultFluidBlock	worldGen.fluidReplace.defaultFluid	Empty if the old toggle was off; otherwise the old block ID.
replaceUndergroundLava + replaceUndergroundLavaBlock	worldGen.fluidReplace.undergroundLava	Same rule as above.
farLandsPos	worldGen.farLandsControl.farLandsPos	CUSTOM becomes DEFAULT; the old divisor is preserved.
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	Automatic.