自定义结构

结构（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格式

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

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

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

    若无法成功生成，将会再去尝试该列表中的其他元素，如果全部都无法成功生成，将尝试使用回落池。
    • ：一个元素。
      •  weight：值越大，该元素就越有可能被优先选中。取值为1到150的闭区间。
      •  element：该元素的属性
        •  projection：可为rigid或terrain_matching。决定生成的高度是否匹配地形高度。
        •  element_type：必须为以下列出的类型之一，也可为empty_pool_element以不生成任何内容。

          如果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。
        •  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被用于远古城市，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：成群生成时的最低数量。
          •  maxCount：成群生成时的最高数量。

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

  •  start_pool：拼图结构的起始结构池ID，或者一个模板池对象。
  •  size：拼图结构的生成深度，取值为0到7的闭区间。
  •  start_height：如果未指定project_start_to_heightmap，结构会在此高度开始生成。否则，结构在高度图的基础上偏移此高度后生成。
    • 高度提供器
  •  project_start_to_heightmap：（可选）结构生成时使用的高度图。必须为WORLD_SURFACE_WG、WORLD_SURFACE、OCEAN_FLOOR_WG、OCEAN_FLOOR、MOTION_BLOCKING或MOTION_BLOCKING_NO_LEAVES。
  •  start_jigsaw_name：（可选）连接起始模板的拼图方块的名称。
  •  max_distance_from_center：拼图的方块距离结构起始点的最大三维切比雪夫距离。取值为1到128的闭区间。当 terrain_adaptation不为none时，取值为1到116的闭区间。
  •  use_expansion_hack：仅用于村庄。
  •  pool_aliases：（可选）定义模板池映射。^{[新增：JE 1.20.3]}
    • ：一个模板池映射对象。
      •  type：映射类型。可以为direct（一对一映射）、random（随机挑选映射）和random_group（随机挑选一组映射）。

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

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

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

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

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

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

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

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

    若type是nether_fossil：

  •  start_height：结构起始点的高度。
    • 高度提供器

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

  •  biome_temp：必须为warm或cold。用以决定使用哪一种结构变种。
  •  large_probability：使用大型变种的概率。取值为0.0到1.0的闭区间。
  •  cluster_probability：生成一簇海底废墟（而不是一个）的概率，取值为0.0到1.0的闭区间。

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

  •  setups：（不能为空）多个废弃传送门的设置。将会从中依据权重随机选取一项。
    •  weight：该项设置的权重。
    •  placement：必须为on_land_surface、partly_buried、on_ocean_floor、in_mountain、underground或in_nether。决定该废弃传送门如何放置。
    •  air_pocket_probability：废弃传送门周围带有空气空腔的几率，取值为0.0到1.0的闭区间。
    •  mossiness：决定该废弃传送门生苔的程度。作为minecraft:block_age处理器的参数。取值为0.0到1.0的闭区间。
    •  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：权重。取值为正整数。
  •  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时的偏移量（单位为区块）。
      • ：x。取值为-16到16的闭区间。
      • ：y。取值为-16到16的闭区间。
      • ：z。取值为-16到16的闭区间。
    •  type：必须是minecraft:concentric_rings或minecraft:random_spread其中之一。

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

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

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

    •  spread_type（可选，默认为linear）：linear或triangular。
    •  spacing：两个结构之间的平均距离（单位为区块），取值为0到4096的闭区间。
    •  separation：两个结构之间的最小距离（单位为区块），必须小于等于 spacing，取值为0到4096的闭区间。两次结构之间的最大距离则为2*spacing - separation。

处理器列表

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

JSON格式

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

• ：处理器的列表。
  • 处理器对象

或者是：

• ：“处理器列表”对象。
  •  processors：处理器的列表。
    • ：一个处理器对象。
      • 处理器对象

语言

• English
• 日本語