自定义维度配置

自定义维度允许你在游戏中创建全新的平行世界。通过在行为包的 netease_dimension/ 目录中添加维度 JSON 文件，你可以声明新维度、选择地形生成器、配置出生群系，并精细控制原版结构的生成。本文将完整介绍维度 JSON 的所有可用组件及其配置方法。

前置条件

阅读本文前，请确保你已了解 Addon 开发基础 中行为包的目录结构，以及 自定义维度概述 中维度系统的基本概念。

概述

原版基岩版包含三个内置维度：

维度	ID	文件名
主世界（Overworld）	0	overworld.json
下界（Nether）	1	nether.json
末地（The End）	2	the end.json

除此之外，ModSDK 支持两种自定义维度方案：

• 旧版自定义维度：ID 范围 3 ~ 20，多 Mod 之间容易冲突，不推荐新项目使用
• 新版自定义维度：ID 范围 22 ~ 2147483647，范围极大，推荐使用

维度 ID 21 不可用

维度 ID 21 为系统保留，请勿使用。新建自定义维度时，建议使用随机数生成器在 22 ~ 2147483647 范围内选取一个 ID，以避免与其他 Mod 冲突。

生成随机维度 ID（Python 2）：

import random, sys
print random.randint(22, sys.maxint)

文件结构

在行为包的 behavior 目录下新增 netease_dimension/ 文件夹，创建以维度 ID 命名的 JSON 文件。例如，要声明 ID 为 23333 的维度，文件路径为：

行为包/netease_dimension/dm23333.json

如果需要修改内置维度的行为（例如清除主世界的原版结构），可以使用对应的内置维度文件名：overworld.json、nether.json、the end.json。

JSON 基础结构

{
  "format_version": "1.14.0",
  "netease:dimension_info": {
    "components": {
      // 在此添加维度组件
    }
  }
}

组件一览

以下是维度 JSON 中所有可用的组件：

组件	类型	默认值	说明
netease:dimension_type	string	"minecraft:overworld"	维度类型，可选 minecraft:overworld、minecraft:nether、minecraft:the_end。不可用于内置维度
netease:generator_noise	empty object	不设置任何生成器时默认使用	噪声地形生成器，产生随机起伏的自然地形。不可用于内置维度
netease:generator_flat	empty object	—	超平坦生成器，仅 overworld/nether 类型维度可用。不可用于内置维度
netease:generator_legacy	empty object	—	旧版（经典）地形生成器，仅 overworld 类型维度可用。不可用于内置维度
netease:ban_vanilla_feature	empty object	—	清除该维度中的所有原版特征（矿物、植被等）。可用于任何维度（包括内置维度）
netease:spawn_biomes	array(string)	["forest", "forest_hills", "plains", "taiga", "taiga_hills", "jungle", "jungle_hills"]	玩家可出生的群系列表
netease:biome_source	array(dict)	—	群系源配置，控制维度中群系的分布方式。仅 overworld 类型维度可用。不可用于内置维度
netease:ban_vanilla_structure	object	默认屏蔽所有原版结构	通过白名单/黑名单方式控制原版结构的生成
netease:ban_vanilla_mineshaft	empty object	—	屏蔽废弃矿井
netease:ban_vanilla_stronghold	empty object	—	屏蔽要塞
netease:ban_vanilla_village	empty object	—	屏蔽村庄
netease:ban_vanilla_monument	empty object	—	屏蔽海底神殿
netease:ban_vanilla_temple	empty object	—	屏蔽神殿（沙漠/丛林/女巫小屋/雪屋）
netease:ban_vanilla_mansion	empty object	—	屏蔽林地府邸
netease:ban_vanilla_shipwreck	empty object	—	屏蔽沉船
netease:ban_vanilla_ruined_portal	empty object	—	屏蔽废弃传送门
netease:ban_vanilla_buried_treasure	empty object	—	屏蔽埋藏的宝藏
netease:ban_vanilla_pillager_outpost	empty object	—	屏蔽掠夺者前哨站
netease:ban_vanilla_bastion_remnant	empty object	—	屏蔽堡垒遗迹
netease:ban_vanilla_fortress	empty object	—	屏蔽下界要塞
netease:ban_vanilla_end_city	empty object	—	屏蔽末地城
netease:ban_vanilla_ruins	empty object	—	屏蔽海底废墟
netease:ban_vanilla_ancient_city	empty object	—	屏蔽远古城市
netease:ban_vanilla_trail_ruins	empty object	—	屏蔽古迹废墟
netease:ban_vanilla_trial_chambers	empty object	—	屏蔽试炼密室

netease:ban_vanilla_structure 详解

默认情况下，自定义维度会屏蔽所有原版结构。如果你希望在自定义维度中保留部分结构，可以使用 allowlist（白名单）或 blocklist（黑名单）进行精确控制。

注意

allowlist 与 blocklist 不可同时使用，只能二选一。

白名单模式

只允许指定的结构生成，其余全部屏蔽：

"netease:ban_vanilla_structure": {
  "allowlist": ["ancient_city", "stronghold"]
}

黑名单模式

屏蔽指定的结构，其余照常生成：

"netease:ban_vanilla_structure": {
  "blocklist": ["ruined_portal", "monument"]
}

可用结构标识符

标识符	对应结构
end_city	末地城
fortress	下界要塞
mineshaft	废弃矿井
monument	海底神殿
ruins	海底废墟
stronghold	要塞
temple	神殿
village	村庄
mansion	林地府邸
shipwreck	沉船
ruined_portal	废弃传送门
buried_treasure	埋藏的宝藏
pillager_outpost	掠夺者前哨站
bastion_remnant	堡垒遗迹
ancient_city	远古城市
trail_ruins	古迹废墟
trial_chambers	试炼密室
netease_large_feature	网易大型特征

完整 JSON 示例

以下示例声明一个 ID 为 23333 的自定义维度，使用主世界类型 + 噪声生成器，指定出生群系为平原和森林，并屏蔽所有原版结构。

文件路径：行为包/netease_dimension/dm23333.json

{
  "format_version": "1.14.0",
  "netease:dimension_info": {
    "components": {
      "netease:dimension_type": "minecraft:overworld",
      "netease:generator_noise": {},
      "netease:spawn_biomes": [
        "plains",
        "forest"
      ],
      "netease:ban_vanilla_structure": {},
      "netease:ban_vanilla_feature": {}
    }
  }
}

修改内置维度示例

清除主世界中的所有原版特征，但保留村庄和要塞：

文件路径：行为包/netease_dimension/overworld.json

{
  "format_version": "1.14.0",
  "netease:dimension_info": {
    "components": {
      "netease:ban_vanilla_feature": {},
      "netease:ban_vanilla_structure": {
        "allowlist": ["village", "stronghold"]
      }
    }
  }
}

常见问题

自定义末地维度中生成了末影龙

如果你创建了一个 minecraft:the_end 类型的自定义维度，末影龙可能会在默认群系中生成。你需要为该维度配置自定义群系源（netease:biome_source），确保不包含会触发末影龙生成的群系。

地形没有按预期生成

确认你只选择了一个生成器组件（netease:generator_noise、netease:generator_flat 或 netease:generator_legacy），不要同时配置多个。同时注意：

• netease:generator_flat 仅支持 overworld 和 nether 类型
• netease:generator_legacy 仅支持 overworld 类型

修改维度配置后存档中的地形没有变化

维度配置只影响新生成的区块，已保存的地形不会自动更新。如果你需要重置已有区块的地形，可以调用 UpgradeMapDimensionVersion API 来重置指定维度的存档数据。

数据丢失风险

UpgradeMapDimensionVersion 会清除目标维度中所有已保存的区块数据。请在操作前做好存档备份。

多个 Mod 使用了相同的维度 ID

新版自定义维度支持 22 ~ 2147483647 的 ID 范围，使用随机生成的大数值可以极大降低冲突概率。如果仍然出现冲突，需要手动修改其中一个 Mod 的维度 ID。

下一步

• 自定义维度概述 — 维度系统全局介绍
• 自定义生物群系 — 配置维度中的群系环境
• 自定义特征 — 在维度中放置矿物、树木等结构
• 自定义传送门系统 — 实现维度间的传送逻辑
• 自定义传送门方块 — 创建传送门方块