自定义特征

特征（Feature）是一组方块的组合体，例如矿脉、树木、湖泊等，在地形生成后放置到世界中。特征规则（Feature Rule）则控制特征在哪些群系、以何种密度和分布方式生成。通过在行为包的 netease_features/ 和 netease_feature_rules/ 目录中添加 JSON 文件，你可以为自定义维度添加丰富的地形装饰。

前置条件

请先阅读 自定义维度概述 了解维度系统，并阅读 自定义生物群系 了解群系标签的概念（特征规则通过群系标签过滤放置位置）。

概述

自定义特征分为两部分：

• 特征 JSON — 定义"放什么"，放在 behavior/netease_features/ 目录
• 特征规则 JSON — 定义"在哪放、放多少"，放在 behavior/netease_feature_rules/ 目录

自 1.21 版本起，特征的 identifier 必须包含命名空间（如 mymod:pumpkin_patch），format_version 使用 "1.14.0"。标识符只允许小写字母、数字和下划线。

限制

• 下界和超平坦世界无法生成自定义特征
• 结构特征的最大尺寸为 16 x 255 x 16（一个区块范围内）
• 结构方块导出的结构中不支持包含实体

特征类型

除原版 addon 支持的特征类型外，网易中国版额外提供了 netease:structure_feature（结构特征），允许使用结构方块导出的模板文件作为特征。

原版特征类型（部分）

类型	说明
minecraft:ore_feature	矿物特征
minecraft:tree_feature	树木特征
minecraft:single_block_feature	单方块特征
minecraft:scatter_feature	分散放置特征
minecraft:aggregate_feature	聚合多个子特征

netease:structure_feature

结构特征使用结构方块（Structure Block）导出的 .mcstructure 文件，在世界生成时将整个结构放置到地形中。

工作流程：

1. 在游戏中使用结构方块保存结构模板
2. 将导出的 .mcstructure 文件放到行为包的 structures/ 目录
3. 在 netease_features/ 中编写特征 JSON 引用该结构
4. 在 netease_feature_rules/ 中编写规则控制放置逻辑

特征 JSON 格式：

{
  "format_version": "1.14.0",
  "netease:structure_feature": {
    "description": {
      "identifier": "mymod:pumpkin_patch"
    },
    "places_structure": "mymod:pumpkin_structure",
    "rotation": 0
  }
}

字段	类型	默认值	说明
description.identifier	string	—	必填，特征标识符，需包含命名空间
places_structure	string	—	必填，引用的结构文件标识符（structures/ 目录下的文件名，不含扩展名）
rotation	int	0	放置时的旋转角度，可选 0、90、180、270

特征规则 JSON

特征规则控制特征在世界中的放置条件和分布方式。

{
  "format_version": "1.14.0",
  "minecraft:feature_rules": {
    "description": {
      "identifier": "mymod:pumpkin_patch_rule",
      "places_feature": "mymod:pumpkin_patch"
    },
    "conditions": {
      "placement_pass": "surface_pass",
      "minecraft:biome_filter": {
        "test": "has_biome_tag",
        "operator": "==",
        "value": "plains"
      }
    },
    "distribution": {
      "iterations": 1,
      "x": {
        "distribution": "uniform",
        "extent": [0, 16]
      },
      "y": "query.heightmap(variable.worldx, variable.worldz)",
      "z": {
        "distribution": "uniform",
        "extent": [0, 16]
      }
    }
  }
}

description 字段

字段	类型	说明
identifier	string	特征规则的唯一标识符
places_feature	string	要放置的特征标识符

conditions 字段

字段	类型	说明
placement_pass	string	放置阶段，决定特征在地形生成的哪个时机放置
minecraft:biome_filter	object	群系过滤器，决定特征在哪些群系中放置

placement_pass 可用值

值	说明
first_pass	最早阶段
before_underground_pass	地下阶段之前
underground_pass	地下阶段
after_underground_pass	地下阶段之后
surface_pass	地表阶段（最常用）
after_surface_pass	地表阶段之后
final_pass	最终阶段

distribution 字段

字段	类型	说明
iterations	int 或 Molang	每个区块中尝试放置的次数
x	object 或 Molang	X 轴坐标分布
y	object 或 Molang	Y 轴坐标分布
z	object 或 Molang	Z 轴坐标分布

坐标分布对象支持以下格式：

{
  "distribution": "uniform",
  "extent": [0, 16]
}

Y 坐标通常使用 Molang 表达式获取地表高度：

query.heightmap(variable.worldx, variable.worldz)

也可以使用 math.random 或 uniform_distribution 来实现固定范围内的随机分布。

大型结构生成

结构特征的最大尺寸限制为一个区块（16 x 255 x 16）。如果需要放置超过一个区块的大型结构，可以将结构拆分为多个部分，并在特征规则中通过 iterations 和坐标偏移来拼接。

多部分拼接示例：

{
  "format_version": "1.14.0",
  "minecraft:feature_rules": {
    "description": {
      "identifier": "mymod:large_ruin_rule",
      "places_feature": "mymod:large_ruin_part"
    },
    "conditions": {
      "placement_pass": "surface_pass",
      "minecraft:biome_filter": {
        "test": "has_biome_tag",
        "operator": "==",
        "value": "plains"
      }
    },
    "distribution": {
      "iterations": 4,
      "x": "variable.iterindex % 2 * 16",
      "y": "query.heightmap(variable.worldx, variable.worldz)",
      "z": "math.floor(variable.iterindex / 2) * 16"
    }
  }
}

上面的示例将结构拆分为 2x2 的区块网格，variable.iterindex 从 0 递增到 3，通过取模和整除计算每个部分的 X/Z 偏移。

Python 脚本接口

特征系统提供了以下脚本事件和接口：

类型	名称	说明
服务端事件	PlaceNeteaseStructureFeatureEvent	结构特征放置时触发，可用于自定义逻辑或取消放置
服务端接口	PlaceStructure	手动在指定位置放置结构
服务端接口	PlaceNeteaseStructureFeature	手动触发网易结构特征的放置

import server.extraServerApi as serverApi

comp = serverApi.GetEngineCompFactory().CreateGame(levelId)
# 在指定位置放置结构
comp.PlaceStructure(
    (100, 65, 200),      # 放置坐标
    "mymod:ruins",        # 结构标识符
    dimensionId=0,        # 维度 ID
    rotation=0            # 旋转角度
)

完整示例

以下示例创建一个南瓜田结构特征，在平原群系的地表随机生成。

特征 JSON

文件路径：行为包/netease_features/pumpkin_patch.json

{
  "format_version": "1.14.0",
  "netease:structure_feature": {
    "description": {
      "identifier": "mymod:pumpkin_patch"
    },
    "places_structure": "mymod:pumpkin_field",
    "rotation": 0
  }
}

结构文件

确保 行为包/structures/mymod/pumpkin_field.mcstructure 文件存在。你可以在游戏中使用结构方块的"导出"功能来创建此文件。

特征规则 JSON

文件路径：行为包/netease_feature_rules/pumpkin_patch_rule.json

{
  "format_version": "1.14.0",
  "minecraft:feature_rules": {
    "description": {
      "identifier": "mymod:pumpkin_patch_rule",
      "places_feature": "mymod:pumpkin_patch"
    },
    "conditions": {
      "placement_pass": "surface_pass",
      "minecraft:biome_filter": {
        "test": "has_biome_tag",
        "operator": "==",
        "value": "plains"
      }
    },
    "distribution": {
      "iterations": 1,
      "x": {
        "distribution": "uniform",
        "extent": [0, 16]
      },
      "y": "query.heightmap(variable.worldx, variable.worldz)",
      "z": {
        "distribution": "uniform",
        "extent": [0, 16]
      }
    }
  }
}

文件目录结构

行为包/
├── netease_features/
│   └── pumpkin_patch.json
├── netease_feature_rules/
│   └── pumpkin_patch_rule.json
└── structures/
    └── mymod/
        └── pumpkin_field.mcstructure

常见问题

特征没有在世界中生成

排查步骤：

1. 确认维度不是下界或超平坦世界（这两种世界不支持自定义特征）
2. 确认特征规则中的 places_feature 与特征 JSON 中的 identifier 完全一致
3. 确认 minecraft:biome_filter 中的群系标签在目标群系上存在
4. 确认 placement_pass 设置合理（地表结构用 surface_pass，地下矿物用 underground_pass）

结构放置后部分方块缺失

结构特征的最大尺寸为 16 x 255 x 16。如果你的结构超过了一个区块的范围，超出部分会被截断。请将大型结构拆分为多个部分。

结构中的实体消失了

结构方块导出的模板不支持保存实体。如果需要在结构中包含实体，请在 PlaceNeteaseStructureFeatureEvent 事件中通过脚本手动生成。

identifier 报错

自 1.21 版本起，特征和特征规则的 identifier 必须包含命名空间前缀（如 mymod:feature_name），且 format_version 必须为 "1.14.0"。

下一步

• 自定义维度概述 — 维度系统全局介绍
• 自定义生物群系 — 配置特征放置的目标群系
• 自定义维度配置 — 使用 netease:ban_vanilla_feature 控制原版特征
• 自定义传送门系统 — 实现维度间的传送逻辑