主题

自定义生物群系 ​

生物群系（Biome）定义了维度中不同区域的环境特征，包括温度、降雨、地形高度和地表方块。通过在行为包的 netease_biomes/ 目录中添加群系 JSON 文件，你可以创建全新的自定义群系，并结合维度配置中的 netease:biome_source 组件控制群系在维度中的分布。

前置条件

请先阅读 自定义维度概述 了解维度系统的基本概念，并阅读 自定义维度配置 了解如何声明自定义维度。

概述 ​

群系决定了一个区域的"气候"和"外貌"——它影响地形高度、地表材质、天气、雾色和水色。原版包含数十种群系（如 plains、desert、jungle 等），你可以在自定义维度中完全替换或补充这些群系。

关键概念：

  • 行为包群系 JSON — 定义群系的气候参数、地形高度和生成规则
  • 资源包 biome_client.json — 定义群系在客户端的雾色、水色等显示效果
  • 维度配置 netease:biome_source — 控制群系在维度中的空间分布

术语表 ​

术语说明
基础生物群系世界生成第一阶段分配的群系，后续会分化出变种
山地生物群系基础群系在高地形区域的变种
突变生物群系较低概率出现的基础群系变异版本
河流生物群系河流穿过该基础群系时替换使用的群系
海岸生物群系陆地与海洋交界处的过渡群系
陆地群系生成在海平面以上的群系
海洋群系生成在海平面处的群系
深海群系生成在深海区域的群系

文件结构 ​

群系 JSON 文件放在行为包的 netease_biomes/ 目录下，文件名可自由命名：

行为包/netease_biomes/my_ice_plains.json

群系 JSON 格式 ​

json
{
  "format_version": "1.14.0",
  "minecraft:biome": {
    "description": {
      "identifier": "mymod:ice_plains"
    },
    "components": {
      // 群系组件
    }
  }
}

组件一览 ​

组件类型说明
minecraft:climateobject气候参数：温度、降雨、积雪
minecraft:overworld_heightobject地形高度配置
minecraft:surface_parametersobject地表方块配置（表层、填充层、底层）
minecraft:overworld_generation_rulesobject群系变种生成规则（山地、突变、气候适配）
tagsarray(string)群系标签，用于特征规则的群系过滤
netease:heightobject网易扩展高度系统，提供更精细的高度控制节点

minecraft:climate ​

控制群系的气候特征：

字段类型默认值说明
temperaturefloat0.5温度值。影响降雪/降雨判定和草方块颜色
downfallfloat0.5降雨量。影响植被颜色和天气
snow_accumulationarray [min, max][0.0, 0.0]积雪厚度范围

minecraft:overworld_height ​

控制群系地形的基础高度和起伏：

字段类型说明
noise_typestring预设噪声类型（如 "default"、"ocean"、"mountains" 等），与 noise_params 二选一
noise_paramsarray [depth, scale]自定义高度参数：depth 控制基础海拔，scale 控制地形起伏

minecraft:surface_parameters ​

定义群系的地表方块材质：

字段类型说明
top_materialstring最上层方块（如 "minecraft:grass")
mid_materialstring填充层方块（如 "minecraft:dirt")
floor_materialstring底层方块（如 "minecraft:stone")
foundation_materialstring基岩上方的填充方块
sea_materialstring海平面方块（如 "minecraft:water")

minecraft:overworld_generation_rules ​

控制群系在原版生成管线中的变种关系：

字段类型说明
hills_transformationstring 或 array对应的山地群系标识符
mutate_transformationstring 或 array对应的突变群系标识符
generate_for_climatesarray该群系适配的气候类型及权重，如 [["medium", 3], ["cold", 1]]

气候类型

原版气候类型包括：frozen（冰冻）、cold（寒冷）、medium（温和）、lukewarm（微温）、warm（温暖）。每种气候类型有一组对应的候选群系，权重越高被选中的概率越大。

客户端显示（biome_client.json） ​

群系在客户端的雾色、水色等视觉效果需要在资源包中配置 biome_client.json：

文件路径：资源包/biome_client.json

json
{
  "biomes": {
    "mymod:ice_plains": {
      "fog_identifier": "mymod:ice_plains_fog",
      "water_surface_color": "#3F76E4",
      "water_fog_color": "#050533",
      "water_surface_transparency": 0.65
    }
  }
}

同时需要在资源包的 fogs/ 目录下定义对应的雾效果文件。

netease:height 扩展高度系统 ​

原版 minecraft:overworld_height 只能指定一个固定的 depth/scale 参数对。网易扩展的 netease:height 组件支持通过控制节点定义更复杂的高度曲线：

json
"netease:height": {
  "height_node": [
    { "x": 0, "y": 60 },
    { "x": 50, "y": 80 },
    { "x": 100, "y": 120 }
  ]
}

每个节点定义了一个水平位置 x 到高度 y 的映射，引擎会在节点之间进行插值以生成平滑的地形过渡。

netease:biome_source（维度配置中） ​

netease:biome_source 是维度 JSON 中的组件，控制群系在维度中的空间分布。它是一个数组，包含多个节点配置。

节点类型 ​

节点类型说明
constant固定群系，整个维度只有一种群系
weighted_list加权随机列表，按权重选择群系
checkerboard棋盘格分布，群系按规则交替排列
climate基于温度/湿度的气候分布
continent大陆/海洋分布

constant 示例 — 整个维度使用单一群系：

json
"netease:biome_source": [
  {
    "type": "constant",
    "biome": "mymod:ice_plains"
  }
]

weighted_list 示例 — 按权重混合多个群系：

json
"netease:biome_source": [
  {
    "type": "weighted_list",
    "entries": [
      { "biome": "mymod:ice_plains", "weight": 3 },
      { "biome": "plains", "weight": 2 },
      { "biome": "forest", "weight": 1 }
    ]
  }
]

原版群系生成管线 ​

原版主世界的群系生成经过 6 个阶段：

  1. 基础岛屿 — 生成大陆/海洋的基础噪声
  2. 缩放 — 放大地图分辨率
  3. 添加岛屿 — 在海洋中随机生成陆地
  4. 温度分配 — 为每个区域分配气候类型
  5. 群系分配 — 根据气候类型从候选群系中选取
  6. 缩放/河流/海岸 — 最终细化：添加河流、海岸、山地和突变变种

自定义群系通过 generate_for_climates 参与第 5 阶段的选取过程。

生成模式 ​

群系支持两种生成模式：

  • 2D 模式（默认）：群系仅在水平方向变化，同一 XZ 坐标的整个 Y 轴使用同一群系
  • 3D 模式：群系在三个方向上变化，可实现洞穴群系等效果

完整 JSON 示例 ​

以下示例创建一个名为 mymod:frozen_highlands 的自定义群系，模拟冰雪覆盖的高原环境。

文件路径：行为包/netease_biomes/frozen_highlands.json

json
{
  "format_version": "1.14.0",
  "minecraft:biome": {
    "description": {
      "identifier": "mymod:frozen_highlands"
    },
    "components": {
      "minecraft:climate": {
        "temperature": 0.0,
        "downfall": 0.5,
        "snow_accumulation": [0.5, 1.0]
      },
      "minecraft:overworld_height": {
        "noise_params": [1.0, 0.5]
      },
      "minecraft:surface_parameters": {
        "top_material": "minecraft:snow",
        "mid_material": "minecraft:dirt",
        "floor_material": "minecraft:stone",
        "foundation_material": "minecraft:stone",
        "sea_material": "minecraft:ice"
      },
      "minecraft:overworld_generation_rules": {
        "hills_transformation": "mymod:frozen_highlands_hills",
        "generate_for_climates": [
          ["frozen", 5]
        ]
      },
      "tags": [
        "frozen",
        "highlands",
        "mymod"
      ]
    }
  }
}

在维度中使用此群系 ​

在维度 JSON 的 netease:biome_source 中引用：

json
{
  "format_version": "1.14.0",
  "netease:dimension_info": {
    "components": {
      "netease:dimension_type": "minecraft:overworld",
      "netease:generator_noise": {},
      "netease:biome_source": [
        {
          "type": "weighted_list",
          "entries": [
            { "biome": "mymod:frozen_highlands", "weight": 3 },
            { "biome": "plains", "weight": 2 }
          ]
        }
      ],
      "netease:spawn_biomes": [
        "mymod:frozen_highlands",
        "plains"
      ],
      "netease:ban_vanilla_structure": {}
    }
  }
}

客户端效果配置 ​

文件路径：资源包/biome_client.json

json
{
  "biomes": {
    "mymod:frozen_highlands": {
      "fog_identifier": "mymod:frozen_fog",
      "water_surface_color": "#2B4A8C",
      "water_fog_color": "#050533",
      "water_surface_transparency": 0.5
    }
  }
}

常见问题 ​

自定义群系没有在维度中生成 ​

排查步骤：

  1. 确认群系 JSON 文件放在 netease_biomes/ 目录下
  2. 确认维度配置中的 netease:biome_source 正确引用了群系标识符
  3. 如果使用原版生成管线，检查 generate_for_climates 中的气候类型和权重是否正确

群系的地表方块没有生效 ​

确认 minecraft:surface_parameters 中的方块标识符拼写正确，使用完整的命名空间格式（如 minecraft:grass）。

群系在客户端没有自定义雾色/水色 ​

检查资源包中是否配置了 biome_client.json，以及 fog_identifier 是否指向了有效的雾效果文件。

如何使用开发模板快速上手 ​

官方提供了 CustomBiomesMod 示例工程，其中包含 tools/template 目录，可以帮助你快速生成群系配置文件的模板。

参考资源

下一步 ​