自定义结构

结构（Structure），或称为结构地物（Structure feature），是一种特殊的用于生成结构的地物。

结构地物类型

结构地物类型（Structure Feature Type）决定了生成的方式与内容。

结构地物类型列表

以下列出了地物类型的所有有效ID及其作用：

• buried_treasure
  • 硬编码生成一个埋藏的宝藏。
• desert_pyramid
  • 硬编码生成一个沙漠神殿。
• end_city
  • 使用结构模板生成有一个末地城。
• fortress
  • 硬编码生成一个下界要塞。
• igloo
  • 使用结构模板生成一个雪屋。
• jigsaw
  • 使用自定义的结构模板生成结构地物。通常使用多个结构模板，通过拼图方块进行连接，以生成大型结构。
• jungle_temple
  • 硬编码生成一个丛林神庙。
• mineshaft
  • 硬编码生成一个废弃矿井。
• nether_fossil
  • 使用结构模板生成一个下界化石。
• ocean_monument
  • 硬编码生成一个海底神殿。
• ocean_ruin
  • 使用结构模板生成一个海底废墟。
• ruined_portal
  • 使用结构模板生成一个废弃传送门。
• shipwreck
  • 使用结构模板生成一个沉船。
• stronghold
  • 硬编码生成一个要塞。
• swamp_hut
  • 硬编码生成一个沼泽小屋。
• woodland_mansion
  • 使用结构模板生成一个林地府邸。

结构模板

结构模板（Structure Template）即结构文件，存储用于生成结构地物的模板。jigsaw类型的结构地物，可以自定义所使用的结构模板。而其他结构地物，如末地城、雪屋等，使用的结构模板的文件路径是硬编码的。

结构池

结构池（Structure Pool），或称为拼图池（Jigsaw Pool）、模板池（Template Pool）将多个结构模板或已放置的地物组合在一起，以从中随机选取一个生成。在jigsaw类型的结构地物中使用。其以JSON文件的形式存储在数据包的data/<命名空间>/worldgen/template_pool目录下。

JSON格式

• 根标签
  • *fallback：回落池，可以被设定为另一模板池。回落池中定义的模板会在以下两种情况下生成：
    1. 当拼图方块生成达到预定层数时，回落池会生成在最后一层的末尾。
    2. 当拼图方块试图加载的结构池中所有元素都无法成功生成。

    以上两种情况下，游戏会试图从回落池加载一个模板来替代原先的模板进行生成。当回落池中的模板尝试生成时，如果该回落池中任意一个元素也都无法成功生成，则不会生成任何东西。否则，回落池中的模板将成功生成。
  • *elements：一个可供选择的元素列表。
    在拼图结构地物的起始结构池中，随机选取一个元素，若指定了起始拼图方块名称，但该元素没有找到对应名称的拼图方块，结构地物将生成失败。在非起始结构池中，随机选取一个元素，满足以下条件才能成功生成：

    1. 存在对应名称、对应方向（水平的拼图方块相互对应、朝上和朝下的拼图方块相互对应）的拼图方块。
    2. 将生成的该元素方块与结构起始点的三维切比雪夫距离不会超过该已配置结构地物中指定的最大距离，或使用命令或拼图方块GUI生成时不超过128。
    3. 将生成的该元素不会与生成的其他拼图发生重叠，除非拼图方块指向的方块位于当前拼图内部。
    4. 拼图方块指向的方块位于当前拼图内部，则该元素与之后生成的所有拼图都必须完全位于该拼图方块所在拼图的内部。

    若无法成功生成，将会再去尝试该列表中的其他元素，如果全部都无法成功生成，将尝试使用回落池。
    • ：一个元素。
      • *weight：（1≤值≤150）值越大，该元素就越有可能被优先选中。
      • *element：该元素的属性。
        • *element_type：必须为以下列出的类型之一。

          如果element_type是empty_pool_element，则什么也不生成，没有附加参数。

          剩余元素类型共通字段：

        • *projection：可为rigid或terrain_matching。决定生成的高度是否匹配地形高度。

          如果element_type是feature_pool_element，则生成一个地物，附加的参数如下：

        • *feature：（命名空间ID）一个已放置的地物。

          如果element_type是list_pool_element，则按照列表顺序依次生成元素，使其重叠生成，附加的参数如下：

        • *elements：一个结构元素列表。
          • ：一个元素，与该元素属性的格式相同。

          如果element_type是legacy_single_pool_element或single_pool_element，则生成一个结构模板，附加的参数如下。两者的区别在于，legacy_single_pool_element不会生成结构模板中的空气方块，就如同空气方块是结构空位一样。

        • *location：（命名空间ID）要放置的结构模板。
        • override_liquid_settings：（默认为apply_waterlogging）用于覆盖父模板池的液体设置。可以为apply_waterlogging（将可含水方块转换为含水方块）和ignore_waterlogging（直接替代液体方块）。
        • *processors：“处理器列表”的命名空间ID，或一个“处理器列表”对象，或者一个处理器的列表。

已配置的结构地物

结构地物类型决定了生成的方式，而具体的生成细节需要额外配置。为结构地物类型添加配置后，称为已配置的结构地物（Configured Structure Feature），简称为结构（Structure）。

已配置的结构地物以JSON文件的形式存储在数据包的data/<命名空间>/worldgen/structure目录下。

JSON格式

• 根对象。
  • *type：（命名空间ID）结构地物类型。
  • *biomes：一个生物群系ID或一个生物群系标签，或者一个生物群系ID的列表。该结构只允许生成在指定的生物群系中。
  • *step: 该结构生成所在的步骤。参见生物群系数据格式中的features字段，在同一步骤里的结构地物比地物优先生成。可以为raw_generation、lakes、local_modifications、underground_structures、surface_structures、strongholds、underground_ores、underground_decoration、fluid_springs、vegetal_decoration或top_layer_modification。
  • terrain_adaptation：（默认为none）该已配置的结构地物的地形调整方式。可以为none（无调整）、beard_thin（在结构下方添加地形，并移除结构体内部地形，原版用于掠夺者前哨站和村庄）、beard_box（beard_thin的增强版，原版用于远古城市）、bury（围绕结构添加地形使其被掩埋，原版用于要塞和古迹废墟）和encapsulate（bury的增强版，原版用于试炼密室）。
  • *spawn_overrides：（可以为空。若不包含某个生物种类，则不覆写该种类的生物设置，依据生物群系生成。）覆写该结构内可以生成的生物。例如，在下界要塞中，生成烈焰人和凋灵骷髅；在远古城市中，没有生物生成。
    • <生物种类>：键名可以是monster、creature、ambient、water_creature、underground_water_creature、water_ambient、misc或axolotls。
      • *bounding_box：可以是piece或full。如果为full，覆写结构的整个轮廓内的生成设置。如果是piece，则只覆写各个结构片段的轮廓内的生成设置。
      • *spawns：（可以为空。若为空，则不生成此类生物）一个生成数据的对象的列表，列表的每一项都对应一种应该在该生物群系生成的生物。
        • ：单个生物的生成数据。
          • *type：该生物的命名空间ID。
          • *weight：该生物的生成权重，更高的值代表更多的生成。
          • *minCount：（值>1）成群生成时的最低数量。
          • *maxCount：（值>1）成群生成时的最高数量。

    若type是jigsaw，附加的参数如下：

  • dimension_padding：（值≥0，默认为0）指定结构的垂直内边距，防止结构因为太靠近基岩层而切入或穿过基岩层。当类型为时上下内边距都被设定为指定值。
    • bottom：（值≥0，默认为0）结构下内边距。
    • top：（值≥0，默认为0）结构上内边距。
  • liquid_settings：（默认为apply_waterlogging）结构生成时内部的液体将如何处理。可以为apply_waterlogging（将可含水方块转换为含水方块）和ignore_waterlogging（直接替代液体方块）。
  • *max_distance_from_center：拼图的方块距离结构起始点的最大三维切比雪夫距离。取值为1到128的闭区间。当terrain_adaptation不为none时，取值为1到116的闭区间。
  • project_start_to_heightmap：结构生成时使用的高度图。必须为WORLD_SURFACE_WG、WORLD_SURFACE、OCEAN_FLOOR_WG、OCEAN_FLOOR、MOTION_BLOCKING或MOTION_BLOCKING_NO_LEAVES。
  • *size：（1≤值≤20）拼图结构的生成深度。
  • start_jigsaw_name：连接起始模板的拼图方块的名称。
  • *start_height：如果未指定project_start_to_heightmap，结构会在此高度开始生成。否则，结构在高度图的基础上偏移此高度后生成。
    • 高度提供器，见自定义世界生成/height provider[显示]
  • *start_pool：拼图结构的起始结构池ID，或者一个模板池对象。
  • *use_expansion_hack：仅用于村庄和掠夺者前哨站。设置为false会导致村庄道路阻碍房屋等生成。
  • pool_aliases：定义模板池映射。
    • ：一个模板池映射对象。
      • *type：映射类型。可以为direct（一对一映射）、random（随机挑选映射）和random_group（随机挑选一组映射）。

        如果type是direct，附加的参数如下：

      • *alias：模板池的映射名称。
      • *target：映射到的目标模板池。

        如果type是random，附加的参数如下：

      • *alias：模板池的映射名称。
      • *targets：候选的模板池，当解析此映射时将按照权重随机挑选内部定义的模板池。
        • ：一个候选的模板池项。
          • *data：一个模板池的命名空间ID。
          • *weight：此模板池项的权重。

        如果type是random_group，附加的参数如下：

      • *groups：候选的映射。
        • ：一个候选的映射项。
          • *data：一个模板池映射对象。
            • 结构与外层相同。
          • *weight：此映射项的权重。

    若type是mineshaft，附加的参数如下：

  • *mineshaft_type：必须为normal或mesa。mesa用于生成深色橡木组成的矿井，normal用于生成橡木组成的矿井。

    若type是nether_fossil，附加的参数如下：

  • *start_height：结构起始点的高度。
    • 高度提供器，见自定义世界生成/height provider[显示]

    若type是ocean_ruin，附加的参数如下：

  • *biome_temp：必须为warm或cold。用以决定使用哪一种结构变种。
  • *large_probability：（0≤值≤1）使用大型变种的概率。
  • *cluster_probability：（0≤值≤1）生成一簇海底废墟（而不是一个）的概率。

    若type是ruined_portal，附加的参数如下：

  • *setups：多个废弃传送门的设置。将会从中依据权重随机选取一项。
    • ：一项设置。
      • *weight：该项设置的权重。
      • *placement：必须为on_land_surface、partly_buried、on_ocean_floor、in_mountain、underground或in_nether。决定该废弃传送门如何放置。
      • *air_pocket_probability：（0≤值≤1）废弃传送门周围带有空气空腔的概率。
      • *mossiness：（0≤值≤1）决定该废弃传送门生苔的程度。作为minecraft:block_age处理器的参数。
      • *overgrown：决定废弃传送门周围是否生成丛林树叶。
      • *vines：决定废弃传送门上是否生成藤蔓。
      • *can_be_cold：决定是否尽量把熔岩和岩浆块替换为下界岩。
      • *replace_with_blackstone：决定是否把石砖替换成黑石砖。

    若type是shipwreck，附加的参数如下：

  • is_beached：（默认为false）沉船是否在岸上。

结构集

结构集（Structure set）用于在给定位置上放置结构，其以JSON文件的形式存储在数据包的data/<命名空间>/worldgen/structure_set目录下。

JSON格式

• 根标签
  • *structures：（可以为空）要放置的已配置结构地物列表。两个结构集不应包含同一已配置结构地物。
    • 要被放置的已配置结构地物。
      • *structure：一个已配置结构地物ID或一个已配置结构对象。
      • *weight：（值≥1）权重。
  • *placement：结构地物的放置方式。
    • *salt：影响随机数的数字；见盐 (密码学)。取值为非负整数。
    • frequency：（默认为1.0）在满足其他条件的情况下尝试生成的概率。取值为0.0到1.0的闭区间。将其设置为一个数字并不意味着结构会生成得如同这个值一般频繁，仅仅是游戏会尝试去如此生成而已；生物群系和地形都会阻止一些结构生成。
    • frequency_reduction_method：（默认为default）为frequency提供随机数算法。必须为default（概率的随机数取决于世界种子、坐标和盐）、legacy_type_1（概率的随机数仅取决于世界种子和坐标，且仅在坐标差异较大时才表现出随机性）、legacy_type_2（与default相同，但使用固定的盐：10387320）或legacy_type_3（概率的随机数仅取决于世界种子和坐标）。
    • exclusion_zone：指定不能放置在某些结构地物附近。
      • *chunk_count：（1≤值≤16）在这个结构地物附近不能放置的区块范围。
      • *other_set：（命名空间ID）一个结构集。
    • locate_offset：（默认为[0,0,0]）使用 /locate structure时的偏移量（单位为区块）。
      • ：（-16≤值≤16）X。
      • ：（-16≤值≤16）Y。
      • ：（-16≤值≤16）Z。
    • *type：必须是minecraft:concentric_rings或minecraft:random_spread其中之一。

      如果type是concentric_rings（分布方式类似于要塞），附加的参数如下：

    • *distance：（1≤值≤1023）每一环的宽度加上每环间的间隙宽度（单位为6区块）。
    • *count：（1≤值≤4095）该维度尝试生成的总次数。
    • *spread：（1≤值≤1023）最中心一环的结构尝试生成次数。第n环中的尝试生成次数为：第n环的次数 = spread * (n^2 + 3n + 2) / 6，直到次数达到总次数count。
    • *preferred_biomes：一个生物群系ID或一个生物群系标签，或者一个生物群系ID的列表。此结构更倾向于生成于的生物群系。

      如果type是random_spread（分布方式类似于沼泽小屋、堡垒遗迹），附加的参数如下：

    • spread_type：（默认为linear）可以为linear或triangular。
    • *spacing：（1≤值≤4096）两个结构之间的平均距离（单位为区块）。
    • *separation：（1≤值≤spacing）两个结构之间的最小距离（单位为区块）。两次结构之间的最大距离则为2*spacing - separation。

处理器列表

处理器列表（Processor list）是用于影响结构中的方块的处理器的列表，以JSON文件的形式存储在数据包的data/<命名空间>/worldgen/processor_list目录下。

JSON格式

处理器列表的JSON可以是一个列表，也可以是包含有一个列表的对象。

• ：处理器的列表。
  • ：一个处理器对象。
    • 处理器对象，见自定义世界生成/processor[显示]

或者是：

• ：“处理器列表”对象。
  • processors：处理器的列表。
    • ：一个处理器对象。
      • 处理器对象，见自定义世界生成/processor[显示]

历史

Java版
1.16.2			20w28a				为数据包中结构定义加入了实验性支持。
			20w30a				将结构地物的类型字段name重命名为type。
			pre1				结构相关文件从data/minecraft/<类型>/<命名空间>/<路径>移动到data/<命名空间>/<类型>/<路径>。
1.17			21w20a				加入了处理器类型protected_blocks。
			pre1				向nether_fossil类型结构地物加入height配置字段。
1.18			21w37a				暂时中止了对自定义结构生成的支持。
			pre1				现在结构池元素类型为feature_pool_element时的feature字段改为引用已放置的地物，而不是已配置的地物。
1.18.2			22w06a				现在处理器类型protected_blocks的value字段需要#前缀。
			22w07a				向结构地物加入了biomes字段。
			pre1				向结构地物加入了spawn_overrides和adapt_noise字段。
							加入了结构集，文件路径为worldgen/structure_set。
							重新加入了对自定义结构生成的支持。
1.19			22w11a				向结构集加入frequency和preferred_biomes字段。
							结构地物从worldgen/configured_structure_feature再次移动到worldgen/structure。
							加入了结构地物类型jigsaw，取代了bastion_remnant、​pillager_outpost和village类型。
							向结构地物加入了project_start_to_heightmap、step和use_expansion_hack字段。
							将结构地物的额外字段从config移动到根标签，并更改了一些字段： ruined_portal类型的config.portal_type字段重做为setups。 mineshaft类型的config.type字段重命名为mineshaft_type。 config.probability字段被移除，其功能被结构集的frequency代替。
			22w13a				移除了结构地物的adapt_noise字段，由新加入的terrain_adaptation字段替代。
							jigsaw类型的结构除type外的字段被移到value子对象中。
							向处理器类型block_rot加入新字段rottable_blocks，值为不带#前缀的标签。
			22w14a				撤销了上个快照对jigsaw类型结构的更改。
							现在处理器类型block_rot的rottable_blocks字段接受命名空间ID、带#前缀的标签或数组，同其他字段一致。
			22w17a				向jigsaw类型结构地物加入start_jigsaw_name字段。
1.19.3			22w44a				移除了结构池的name字段，此前为必填项但无任何作用。
1.20			23w12a				加入了处理器类型capped。
							现在处理器类型rule的由新加入的block_entity_modifier字段处理方块实体数据，此前由output_nbt处理静态字段，格式见NBT格式 § JSON和NBT。
1.20.3			23w42a				向jigsaw类型结构地物加入pool_aliases字段。
1.20.5			pre1				向结构地物terrain_adaptation字段加入可选值encapsulate。
1.21			24w19a				向结构地物加入dimension_padding字段。
			24w20a				现在dimension_padding还可以为对象格式，分别指定bottom和top参数。
			pre1				向结构池元素加入了override_liquid_settings字段。
							向jigsaw类型结构地物加入liquid_settings字段。