我的世界Java版1.21.4的Fabric模组开发教程(十七)自定义维度

这是适用于Minecraft Java版1.21.4的Fabric模组开发系列教程专栏第十七章——自定义维度。想要阅读其他内容，请查看或订阅上面的专栏。

维度(Dimension) 是Minecraft中平行世界的称谓，它指的是一个独立且具有特定的环境、生物群系、生成规则、地理坐标和物理特性的世界空间。目前，原版游戏中有主世界(Overworld)、下界(The Nether)和末地(The End)三大维度。

相比之前章节中提到的“创建支援(irongolem_support_effect)附魔”、“创建烫手马铃薯(hot_potato)”以及“创建狗粑粑(dog_poo)”等以相当具体的目标为导向来行文，本章不在以创建自己的维度为目标，而是通过数据包中维度文件的定义，来详细解读创建各种类型自定义维度的步骤。

自1.16版本起，维度定义开始以数据驱动的方式完成。换言之，想要创建自定义维度，需要在项目中添加一些JSON文件。这些文件至少包括：

• 维度定义JSON；
• 维度类型定义JSON；

如果使用了噪声型区块生成器，还需要创建：

• 噪声设置JSON

这些文件可以通过数据生成器生成，同时也可以通过在线网站的方式生成，如有需要请访问数据包生成器。

创建维度类型定义JSON

维度类型(Dimension Type) 定义JSON用于定义维度的基础环境属性。在维度定义JSON中需要用到此文件的命名空间ID(标识符)，因此可以在创建维度定义JSON之前先完成维度类型定义JSON的创建。

维度类型定义JSON应当位于(generated)/data/{mod-id}/dimension_type目录中，文件名作为维度类型的命名空间ID，符合命名空间ID要求的文件名可以为new_dimension.json；

整个文件中的配置项应当包含在一个根对象{}内，它们包括：

• “ambient_light”：指定维度环境光照，取值范围在0~1之间，例如0.6；
• “bed_works”：指定床在此度是否能够正常使用，只能提供true，代表能够正常使用床；或者false，代表使用床时会发生爆炸；
• “coordinate_scale”：指定维度的坐标缩放值，也就是以主世界为基准，在该维度移动一格对应主世界移动的格数，需要提供一个正整数，最大值不超过30,000,000；
• “has_ceiling”：指定维度是否有天花板，例如下界顶部的基岩层，提供一个布尔值；
• “has_raids”：指定维度内是否可以触发袭击(劫掠)事件，提供一个布尔值；
• “has_skylight”：指定维度是否具有天空光照，提供一个布尔值；
• “height”：指定维度可以存在方块的总高度，提供一个整数，取值范围在16~2032-min_y之间，且给定值必须为16的倍数；
• “infiniburn”：指定维度内火能在哪些方块上永久燃烧，提供一个方块标签，通常以#开头，例如#minecraft:infiniburn_overworld代表主世界中带有此标签的方块，火在这些方块上可以永久燃烧；
• “logical_height”：指定维度的逻辑高度，一般与height字段的值相同；
• “min_y”：指定维度可以存在方块的最低高度，提供一个整数，取值范围在-2032~2031之间，且给定值必须为16的倍数；
• “monster_spawn_block_light_limit”：指定维度中怪物生成位置的最大方块光照，提供一个整数，取值范围在0~15之间；
• “monster_spawn_light_level”：指定维度中怪物生成位置的最大光照，提供一个整数，取值范围在0~15之间；也可以写成一个对象，其中添加一个整数提供器；
• “natural”：指定维度是否为自然维度，提供一个布尔值；
• “piglin_safe”：指定维度内的猪灵和疣猪兽是否不会僵化，提供一个布尔值；
• “respawn_anchor_works”：指定重生锚在此维度是否能够正常使用，只能提供true，代表能够正常使用重生锚；或者false，代表使用重生锚时会发生爆炸；
• “ultrawarm”：指定维度是否为超高温维度，提供一个布尔值；
• “effects”：非必选项。指定维度的环境效果，提供一个命名空间ID；
• “fixed_time”：非必选项。指定维度时间的固定值；
• “cloud_height”：非必选项。指定维度中云层的高度，提供一个整数，取值范围在-2032~2031之间。

关于部分配置项的详细信息，可以参考维度类型 - 中文 Minecraft Wiki。

创建噪声设置定义JSON

噪声设置(Noise Settings) 定义JSON用于在维度使用噪声型区块生成器时使用。如果需要使用噪声型区块生成器，可以提前创建噪声设置定义JSON备用。关于噪声(Noise) 这一概念的更多信息，可以参考下文噪声型区块生成器小节。

噪声设置定义JSON应当位于(generated)/data/{mod-id}/worldgen/noise_settings目录中，文件名为噪声设置定义JSON的命名空间ID；

同样地，整个文件中的配置项应当包含在一个根对象{}内，它们包括：

• “sea_level”：指定维度的海平面高度，提供一个整数，取值范围应在维度最小和最大高度之间；
• “aquifers_enabled”：指定维度是否启用含水层，提供一个布尔值；
• “ore_veins_enabled”：指定维度是否启用矿脉，提供一个布尔值；
• “disable_mob_generation”：指定维度是否禁止初始生物生成，提供一个布尔值；
• “legacy_random_source”：指定维度是否使用1.18版本前旧随机数生成器，提供一个布尔值；
• “default_block”：指定维度的默认方块，需要写成一个对象，其中的配置项包括：
  • “Name”：指定方块的命名空间ID；
  • “Properties”：非必选项。指定方块状态，需要写成一个对象；
• “default_fluid”：指定维度的默认流体，需要写成一个对象，其中的配置项包括：
  • “Name”：指定方块的命名空间ID；
  • “Properties”：非必选项。指定方块状态，需要写成一个对象；
• “spawn_target”：指定一个生物群系参数区间的列表，用于决定玩家出生点的环境条件，需要写成一个数组。必选项，但该项可以为空；
• “noise”：指定世界噪声参数，需要写成一个对象，其中必选的配置项包括：
  • “min_y”：指定地形生成的最低高度，取值范围在-2032~2031之间，且必须为16的倍数；
  • “height”：指定地形生成的总高度，取值范围在0~2032-min_y之间，且必须为16的倍数；
  • “size_horizontal”：指定水平噪声缩放值，取值范围在1~4之间；
  • “size_vertical”：指定垂直噪声缩放值，取值范围在1~4之间；
• “noise_router”：指定噪声路由，需要写成一个对象，其中的每个配置项都代表地形生成不同阶段的密度函数，作为控制噪声生成地形的重要参数。更多信息请访问噪声设置 - 中文 Minecraft Wiki；
• “surface_rule”：指定表面规则，需要写成一个对象，根据不同条件、固定模式或顺次应用的表面规则类型控制地表方块的生成。更多信息请访问噪声设置 - 中文 Minecraft Wiki。

噪声路由和表面规则是相当复杂的配置项，为了更快速的完成维度的创建，下面给出一个可用的噪声设置JSON，以便选择了噪声型区块生成器的开发者更快速的完成自定义维度的创建；

{"sea_level": 63,"aquifers_enabled": false,"ore_veins_enabled": false,"disable_mob_generation": false,"legacy_random_source": false,"default_block": {"Name": "minecraft:dirt"},"default_fluid": {"Name": "minecraft:air"},"noise": {"min_y": 0,"height": 256,"size_horizontal": 1,"size_vertical": 1},"noise_router": {...},"spawn_target": [],"surface_rule": {...}
}

部分内容已省略，请参考文章顶部绑定的资源或私信。

创建维度定义JSON

维度(Dimension) 定义JSON用于定义维度的核心属性，是创建维度的核心文件。通常在创建维度类型JSON后开始创建。

维度定义JSON应当位于(generated)/data/{mod-id}/dimension目录中，文件名作为维度的命名空间ID，可以在整个项目中使用。

与维度类型相比，维度定义JSON中的配置项较少，但始终应当包含在一个根对象{}内。维度定义JSON中配置项的修改会对世界外观和生成逻辑产生重大影响，它们包括：

• “type”：指定维度类型，应当使用维度类型定义JSON的命名空间ID；
• “generator”：指定此维度的区块生成器，需要写成一个对象，其中必选的配置项有：
  • “type”：指定区块生成器类型，可以提供的值有“debug”、“flat”和“noise”；
  • ...：其他配置项，接下来的配置项会根据区块生成器的类型而发生改变。

关于区块生成器，下面我们将展开讲解。同样地，可以提前参考维度定义格式 - 中文 Minecraft Wiki。

区块生成器(Chunk Generator) 是控制维度中地形、结构和生物群系生成的核心逻辑组件。具体地讲，它会将一个区块(Chunk) 填充为具体的地形并生成特定的结构和生物群系。

调试型区块生成器“minecraft:debug”

调试型区块生成器用于生成调试模式世界的网格状方块集合。与创建世界时按住alt键创建的“调试模式”类型的世界完全相同。

如果一个维度的区块生成器为调试型，则不需要任何其他的配置项，其维度定义JSON应当如下：

{"type": "test:new_dimension","generator": {"type": "minecraft:debug"}
}

启动游戏，创建新的世界，进入主世界后执行以下命令：

/execute in test:new_dimension run tp Player574 ~ ~ ~

test:new_dimension是自定义维度的命名空间ID，Player457是玩家名，这条指令可以将玩家传送到指定维度。

在模组开发中，自定义维度大概率不会使用调试型区块生成器。

平坦型区块生成器“minecraft:flat”

平坦型区块生成器会在维度中生成完全平坦的地形，与创建世界时选择“超平坦”世界类型生成的世界大致相同。

如果一个维度的区块生成器为平坦型，其维度定义JSON的“generator”配置项中可以添加以下内容：

• type：“minecraft:flat”；
• “setttings”：指定平坦型世界生成器生成设置，需要写成一个对象，其中的配置项有：
  • “layers”：指定层设置，需要写成一个数组，其中每一项都要写成一个对象，代表维度中的一个层。这样表示一个层的对象可以有多个，世界生成时此列表的内容会自上而下依次从世界底部向上生成。其中的配置项有：
    • “block”：指定该层使用的方块，需要提供一个方块的命名空间ID；
    • “height”：指定该层的高度(厚度)，取值范围在0~4064之间；
  • “biome”：非必选项。指定维度的生物群系，需要提供一个生物群系的命名空间ID，不提供此配置项时该项的值默认为“minecraft:plain”，即平原生物群系；
  • “lakes”：非必选项。指定维度是否生成湖泊，提供一个布尔值；
  • “features”：非必选项。指定维度是否生成生物群系的地物，提供一个布尔值；
  • “structure_overrides”：非必选项。指定维度生成的结果集，不提供此配置项时会尝试生成所有结构集，提供一个结构集的ID、多个结构集ID的数组或一个结构集标签。

相关配置项的详细描述，请参考前文提到的Wiki官网。

下面这个例子会生成厚度为1、方块为test:ice_wood、区块生成器为平坦型的维度：

{"type": "test:new_dimension","generator": {"type": "minecraft:flat","settings": {"layers":[{"block": "test:ice_wood","height": 1}]}}
}

启动游戏后，传送到自定义维度，可以看到完全平坦的维度。

在模组开发的生产环境中，平坦型区块生成器使用依然较少。

噪声型区块生成器“minecraft:noise”

噪声型区块生成器是模组开发中最常用的区块生成器类型。大多数带有自定义维度的模组都会使用噪声型区块生成器完成维度的生成。此外，原版游戏的三大维度也同样使用了噪声型区块生成器。

噪声(Noise) 是原版游戏中用于生成地形的数学算法，确切地讲，游戏中使用的是柏林噪声(Perlin Noise)。其原理是为2D正方形网格中的所有顶点添加随机方向的梯度向量，然后在正方形中随机添加一个输入点，为输入点所属正方形的四个顶点添加指向输入点的距离向量，接着对每个顶点的梯度向量和距离向量做点乘加权运算，计算出影响值并绘制噪声图；

最后，为了改进噪声效果，对影响值进行更加平滑的线性插值计算，用于生成更好的地形。

如果一个维度的区块生成器为噪声型，其维度定义JSON的“generator”配置项中可以添加以下内容：

• type：“minecraft:noise”；
• “biome_source”：指定维度的生物群系源，需要写成一个对象，其中必选的配置项有：
  • “type”：指定生物群系源类型，可以提供的值有“checkerboard”、“fixed”、“multi_noise”和“the_end”；
  • ...：其他配置项，接下来的配置项会根据生物群系源类型而发生改变；
• “settings”：指定噪声设置，需要提供噪声设置JSON的命名空间ID。

关于生物群系源，下面我们将展开讲解。同样地，可以提前参考世界生成 - 中文 Minecraft Wiki。

生物群系源(Biome Source) 决定了世界生成中游戏如何放置生物群系，且只有噪声型区块生成器可以设置生物群系源。

棋盘型生物群系源“minecraft:checkerboard”

使用棋盘型生物群系源作为维度噪声生成的预设，意味着整个维度的生物群系将以棋盘的形式放置。

棋盘型生物群系源对应的维度定义JSON的“biome_source”配置项中可以添加以下内容：

• “type”：“minecraft:checkerboard”；
• “biomes”：指定要生成的生物群系，提供的值可以为一个生物群系ID、一个生物群系标签或一个生物群系ID的列表；
• “scale”：非必选项。指定棋盘格的大小(边长)，取值范围在0~62之间，默认值为2，值为0时表示每个棋盘格都是一个区块宽。

下面这个例子会生成棋盘格大小为1并包含竹林(minecraft:bamboo_jungle)、玄武岩三角洲(minecraft:basalt_deltas)、雪林(minecraft:grove)和蘑菇岛(minecraft:mushroom_fields)四种生物群系的维度：

{"type": "test:new_dimension","generator": {"type": "minecraft:noise","biome_source": {"type":"minecraft:checkerboard","biomes":["minecraft:bamboo_jungle","minecraft:basalt_deltas","minecraft:grove","minecraft:mushroom_fields"],"scale": 0},"settings": "test:new_dimension"}
}

启动游戏，传送到自定义维度，可以看到维度的生物群系以棋盘的形式放置。

固定型生物群系源“minecraft:fixed”

使用固定型生物群系源作为维度噪声生成的预设，代表整个维度都将使用同一个生物群系。与创建世界时选择“单一生物群系”的世界类型创建的世界完全相同。

固定型生物群系源对应维度定义JSON的“biome_source”配置项中可以添加以下内容：

• “type”：“minecraft:fixed”；
• “biome”：指定维度的生物群系，提供一个生物群系ID；

下面这个例子会生成生物群系为疏林恶地(minecraft:wooded_badlands)的维度：

{"type": "test:new_dimension","generator": {"type": "minecraft:noise","biome_source": {"type": "minecraft:fixed","biome": "minecraft:wooded_badlands"},"settings": "test:new_dimension"}
}

启动游戏，传送到自定义维度，可以看到维度的生物群系固定为疏林恶地。

多噪声型生物群系源“minecraft:multi_noise”

多噪声型生物群系源是噪声型区块生成器的噪声预设中最常用的生物群系源，它通过指定每个生物群系的噪声值参数，使维度生成的生物群系更加多样化。在原版游戏中，多噪声型生物群系源同样用于主世界和下界两个维度的生成。

多噪声型生物群系源对应的维度定义JSON的“biome_source”配置项中可以添加以下内容：

• “type”：“minecraft:multi_noise”；
• “biomes”：指定生物群系参数特征列表，需要传递一个数组，其中的每一项都要写成一个对象，代表一个生物群系的参数特征，其中必选的配置项有：
  • “biome”：指定一个需要在维度中添加的生物群系，提供一个生物群系命名空间ID；
  • “parameters”：指定该生物群系的参数特征，用于其在维度的生成，需要写成一个对象，其中的配置项包括：
    • “temperature”：温度；
    • “humidity”：湿度；
    • “continentalness”：大陆性；
    • “erosion”：侵蚀度；
    • “weirdness”：怪异度；
    • “depth”：深度；
    • “offset”：偏移，取值范围在0~1之间；
      其中，除偏移“offset”外，其他配置项的取值范围在-2~2之间。所有配置项的类型均为单精度型，即float。

关于生物群系参数特征的更多信息，可以参考维度定义格式 - 中文 Minecraft Wiki。

下面这个例子会在维度中生成樱花树林(minecraft:cherry_grove)和疏林恶地(minecraft:wooded_badlands)两种生物群系，且所有生物群系都会根据特定的生物群系参数特征值进行生成：

{"type": "test:new_dimension","generator": {"type": "minecraft:noise","biome_source":{"type": "minecraft:multi_noise","biomes": [{"biome": "minecraft:cherry_grove","parameters": {"temperature": 0.7,"humidity": 0.4,"continentalness": 0.3,"erosion": 0.0,"weirdness": 0.5,"depth": 2,"offset": 0.0}},{"biome": "minecraft:wooded_badlands","parameters": {"temperature": 0.0,"humidity": 0.2,"continentalness": 0.2,"erosion": 0.1,"weirdness": 1.0,"depth": 2,"offset": 0.0}}]},"settings":"test:new_dimension"}
}

启动游戏，进入自定义维度，可以看到生成的两种生物群系。

在噪声型区块生成器中使用多噪声生物群系源来完成维度的生成是模组开发中大多数自定义维度的解决方案。

末地型生物群系源“minecraft:the_end”

末地型生物群系源仅在原版游戏的末地维度中使用，且末地型生物群系源对应的维度定义JSON的“biome_source”配置项中没有任何其他配置项。

在自定义维度的噪声预设中依然可以使用，其维度定义JSON只有下面一种写法：

{"type": "test:new_dimension","generator": {"type": "minecraft:noise","biome_source":{"type": "minecraft:the_end"},"settings":"test:new_dimension"}
}

启动游戏，传送到自定义维度，可以看到天空变成黑色，雾气变成紫色，与末地的颜色相同；

属于末地的结构黑曜石柱和末地城等会在维度生成。但由于噪声设置JSON中的表面规则替换了末地原本的噪声预设，维度表面始终为草方块，而不是末地石；

在绝大多数情况下，模组开发中不会使用到末地型生物群系源。

本章小结

本章详细讲述了通过数据包创建自定义维度的方法，并根据不同的设置演示了各种维度的创建过程，是维度创建的入门级教程。本文篇幅较长，内容较多，有一定难度。感谢各位的阅读，有兴趣可以订阅此专栏！