minecraft-world-generation

Minecraft 世界生成

在处理生物群系、维度、特征或结构数据及其注册时使用此技能。对于非世界生成数据，请使用 minecraft-datapack；对于非世界生成游戏玩法代码，请使用 minecraft-modding。

路由边界

• Use when：任务会更改世界生成数据、注册或注入。
• Do not use when：任务涉及非世界生成的数据包工作（minecraft-datapack）。
• Do not use when：任务涉及非世界生成的模组系统（minecraft-modding）。

选择交付路径

方法	最适用场景	平台
Datapack JSON	更改数据包提供的数据	Vanilla，任意服务端
Mod + Datagen	注册新生物群系／维度，以代码驱动	NeoForge / Fabric
Biome Modifier (NeoForge)	向现有生物群系添加特征／生物生成	NeoForge
BiomeModification API (Fabric)	向现有生物群系添加特征／生物生成	Fabric

世界生成注册表属于数据包注册表：其文件会在世界加载时加载，注册表路径决定了数据路径。选择特定于模组的注册表路径前，请阅读 NeoForge 注册表指南。

版本边界

新工作使用 Minecraft 26.x。使用 Java 25，并从目标版本的原版数据或生成输出开始编写每个 JSON 模式。不要仅仅因为 1.21 格式可以解析为 JSON，就将其复制到 26.x 数据包中。

除非任务明确包含升级，否则已有的 1.21.x 项目应保留 Java 21 和对应的模式。确保示例与项目版本相符。

26.1 迁移指南移除了 minecraft:random_patch 和 minecraft:no_bonemeal_flower。它将随机斑块模式替换为独立的 minecraft:simple_block 配置特征，以及用于计数、随机偏移和方块谓词过滤的放置项。迁移代码或数据前，请检查相关的迁移指南章节。

仅当项目目标版本为 1.21 时，才阅读旧版 1.21 JSON 模式。这些示例不是 26.x 的发行产物。

---

数据布局和引用关系图

data/<namespace>/
├── worldgen/
│   ├── biome/
│   │   └── my_biome.json
│   ├── configured_feature/
│   │   └── my_ore.json
│   ├── placed_feature/
│   │   └── my_ore_placed.json
│   ├── noise_settings/
│   │   └── my_dimension_noise.json
│   ├── structure/
│   │   └── my_structure.json
│   ├── structure_set/
│   │   └── my_structures.json
│   ├── processor_list/
│   │   └── my_processors.json
│   ├── template_pool/
│   │   └── my_pool.json
│   └── carver/
│       └── my_carver.json
├── dimension/
│   └── my_dimension.json
├── dimension_type/
│   └── my_type.json
├── tags/
│   └── worldgen/
│       └── biome/
│           └── is_forest.json
└── neoforge/
    └── biome_modifier/      (NeoForge mod only)
        └── add_ores.json

从叶节点向上构建并审查关系图：

1. 定义一个配置特征，然后定义其放置特征。
2. 在预期的装饰步骤中，从生物群系或生物群系修改器引用放置特征。
3. 定义一个结构，然后定义其结构集；拼图结构还需要模板池、处理器列表和结构模板。
4. 在定义引用它们的维度之前，先定义维度类型和噪声设置。

在不同命名空间之间使用完全限定标识符。外部的 minecraft: 或依赖项引用是有效的，前提是相应依赖项提供该注册表条目；不要仅为满足静态检查而创建本地副本。如果同一数据包包含该外部命名空间和注册表目录，则将其视为本地内容，并确认目标存在。

---

生物群系和维度

对于 26.x 的生物群系和维度数据，请使用目标版本的原版数据或数据生成输出作为模式来源。较旧的 effects 和维度类型字段无法表示较新的环境行为。11 个装饰步骤仍用于组织放置特征；请选择语义上合适的步骤，并将矿石放置保留在 underground_ores 中。

标注为 1.21 版本的生物群系和维度示例位于旧版 1.21 JSON 模式中。

26.x 特征模式

对于 26.1 中简单随机斑块的替代方案，迁移指南展示了一个 simple_block 配置特征，以及一个带有计数、随机偏移和方块谓词筛选器的放置特征。请根据目标版本生成的数据调整具体数值和方块状态。

位于 data/<namespace>/worldgen/configured_feature/my_plant.json：

{
  "type": "minecraft:simple_block",
  "config": {
    "to_place": {
      "type": "minecraft:simple_state_provider",
      "state": { "Name": "minecraft:sweet_berry_bush", "Properties": { "age": "3" } }
    }
  }
}

位于 data/<namespace>/worldgen/placed_feature/my_plant.json：

{
  "feature": "<namespace>:my_plant",
  "placement": [
    { "type": "minecraft:count", "count": 96 },
    {
      "type": "minecraft:random_offset",
      "xz_spread": { "type": "minecraft:trapezoid", "min": -7, "max": 7, "plateau": 0 },
      "y_spread": { "type": "minecraft:trapezoid", "min": -3, "max": 3, "plateau": 0 }
    },
    {
      "type": "minecraft:block_predicate_filter",
      "predicate": {
        "type": "minecraft:all_of",
        "predicates": [
          { "type": "minecraft:matching_block_tag", "tag": "minecraft:air" },
          { "type": "minecraft:matching_blocks", "blocks": "minecraft:grass_block", "offset": [0, -1, 0] }
        ]
      }
    }
  ]
}

---

NeoForge 生物群系修饰器

生物群系修饰器从 data/<modid>/neoforge/biome_modifier/<path>.json 加载。它们可以按生物群系 ID 或标签指定目标，并添加或移除已放置特征等。生物群系修饰器指南 介绍了其模式、装饰步骤和数据生成。

对于 neoforge:add_features，features 接受已放置特征 ID、列表或 标签。可以在生物群系 JSON 中引用原版已放置特征，也可以通过修饰器添加，但 NeoForge 警告不要同时使用这两种方式，因为特征顺序循环可能会导致世界加载崩溃。如果注入原版特征会带来这种风险，最好在模组命名空间下创建副本。

如果目标是来自可选依赖的生物群系，请将目标放入带有 required: false 的生物群系标签条目中，然后在修饰器中使用该标签。这样，即使缺少依赖，数据包也能加载。

---

结构与维度

对于任何当前版本，请根据该版本的原版数据或数据生成输出，生成结构、模板池、维度和维度类型 JSON。在启动测试世界前，请确认引用关系：

• structure_set 引用 structure。
• 拼图结构的 start_pool 引用 template_pool；每个单池元素都引用其结构模板和处理器列表。
• dimension.type 引用 dimension_type；噪声生成器的字符串 settings 引用 worldgen/noise_settings。

对于 Fabric 注册或模组数据生成，请使用与确切加载器和 API 版本相匹配的文档，不要将 1.21 代码复制到 26.x 项目中。

详细的 1.21 结构和维度示例见 旧版 1.21 JSON 模式。

---

开发工作流

1. 在 data/<namespace>/worldgen/（或等效的模组资源路径）中创建或编辑世界生成 JSON 文件。
2. 加载前运行附带的验证器，以发现 JSON 和交叉引用错误：

   ./scripts/validate-worldgen-json.sh --root /path/to/datapack-or-mod-resources
   # Strict mode treats warnings as failures:
   ./scripts/validate-worldgen-json.sh --root /path/to/datapack-or-mod-resources --strict
   

3. 修复所有报告的错误，并重复验证直至通过。验证器会检查：
   • worldgen/** 和 neoforge/biome_modifier/** 的 JSON 有效性
   • placed_feature -> configured_feature 的交叉引用完整性
   • structure_set -> structure 以及生物群系／biome_modifier 特征目标的交叉引用完整性
   • jigsaw structure -> start_pool 和 template_pool -> structure template / processor_list 的交叉引用完整性
4. 在游戏内测试前，将生物群系和维度类型 JSON 与确切目标版本的原版注册表结构进行比较。该辅助工具不会运行 Mojang 编解码器：JSON 有效且本地引用无误，并不能证明 carvers、effects 或维度设置等字段符合该版本的模式。
5. 在游戏内测试生物群系和结构：

   /locate structure <namespace>:my_structure
   /locate biome <namespace>:my_biome
   /place feature <namespace>:my_ore
   

   place feature 接受的是已配置特征 ID，而不是其已放置特征包装项。 请参阅 Mojang 的 1.19 版本说明中的 place 命令参考。
6. 测试维度时，使用 /execute in（维度必须在世界加载时存在，不能通过 /reload 添加）：

   execute in <namespace>:my_dimension run tp @s 0 100 0
   

7. 检查 latest.log 中的世界生成错误（缺少生物群系引用、噪声设置格式错误）。
8. 注意：/reload 会刷新数据包 JSON，但不会重新生成已生成的区块。请在新世界或新生成的区块中测试新的世界生成内容。对于现有测试世界，请使用可丢弃的副本和专门的区块重置／重新生成工作流；/fill 只会替换方块，不能替代世界生成。

---

参考资料

• Minecraft Wiki — 世界生成：https://minecraft.wiki/w/Custom_world_generation
• Minecraft Wiki — 生物群系：https://minecraft.wiki/w/Biome/JSON_format
• Minecraft Wiki — 特征：https://minecraft.wiki/w/World_generation/Configured_feature
• NeoForge 生物群系修改器：https://docs.neoforged.net/docs/worldgen/biomemodifier/
• Fabric 生物群系修改：https://wiki.fabricmc.net/tutorial:biomemodification
• misode 的数据包生成器（世界生成 UI）：https://misode.github.io/worldgen/