什么是模块化地牢？
模块化地牢是 BetterStructures 2.0.0 及更高版本中引入的地牢系统。 与作为单个固定原理图生成不同，模块化地牢是由较小的、手工制作的模块动态组装而成的。 这种方法可以创建大型、多层的地牢，在每个世界中都有独特的感觉，同时仍然与原版 Minecraft 无缝融合。
模块化地牢是如何生成的
-
模块 每个模块通常以可配置的尺寸构建（默认 16x16x16 方块，但某些内容包使用 32x16x32 或其他尺寸）。模块使用边界标签系统设计标准化的连接点，以便它们可以与其他模块连接，不会产生间隙或重叠。地牢的尺寸使用模块生成器配置中的
moduleSizeXZ和moduleSizeY配置选项来设置。 模块可以包含走廊、房间、楼梯或特殊遭遇空间。 -
生成过程 当模块化地牢在新区块中生成时，BetterStructures 使用波函数坍缩（WFC）算法从可用池中程序化地组装模块。系统根据边界标签匹配随机选择兼容的模块，并将它们"缝合"在一起形成完整的地牢。 生成时间取决于服务器性能、地牢大小（半径）、垂直范围、模块数量和约束复杂度。系统使用负载分配来防止生成期间的服务器卡顿。
-
地牢大小 地牢可以通过半径参数配置为各种大小。较大的半径值会创建明显更大的地牢，可以跨越数百个方块。 大多数地牢包括多个楼层，通过楼梯模块或垂直竖井连接。楼层之间的垂直连接通过模块
borders边界标签映射中的up/down条目实现：当一个模块的顶面与其上方相邻模块的相对边界标签匹配时，二者便会连接。
多样性和内容包集成
-
免费包 Dungeoneering Modules Free Pack 包含 15 个模块。它本身就可以作为一个完整的可玩地牢。
-
高级包 Dungeoneering Modules Premium Pack 额外增加了 38 个模块。与免费包结合使用时，两个包会交织成一个拥有更大模块池的单一地牢系统。 这减少了重复并增加了生成布局的多样性。
-
道具集成 如果你还安装了 BetterStructures Prop Pack（通过 FreeMinecraftModels），模块化地牢将在建筑中显示自定义模型道具，如我们的展示截图所示。 没有道具包，地牢仍然可以正常运行，但不会显示装饰模型。
EliteMobs 集成
虽然大部分地牢仅依赖 BetterStructures 和原版 Minecraft 怪物，但某些地牢会有 Boss 遭遇：
- 如果同时安装了 EliteMobs 和 FreeMinecraftModels → 带有模型的完整自定义 Boss 战。
- 如果仅安装了 FreeMinecraftModels → Boss 模型作为装饰道具出现。
- 如果两者都未安装 → Boss 房间将为空。
系统使用基于告示牌的生成系统，通过特殊标签在指定区域放置实体和容器。Boss 等级根据与地牢中心的距离进行缩放，在整个结构中提供适当的挑战。
模块告示牌类型
| 告示牌标签 | 第 1 行 | 附加行 | 描述 |
|---|---|---|---|
[spawn] | [spawn] | 第 2 行为实体类型 | 在告示牌位置生成原版实体 |
[pool: poolname] | [pool: poolname] | — | 从指定生成池中随机生成一个 Boss |
[chest] | [chest] | — | 在告示牌位置放置箱子 |
[trapped_chest] | [trapped_chest] | — | 在告示牌位置放置陷阱箱 |
[barrel] | [barrel] | — | 在告示牌位置放置木桶 |
[exit] | [exit] | 第 2-3 行为电梯原理图文件名 | 标记带有上/下电梯原理图的出口点 |
如果未安装 EliteMobs 但内容包需要它，管理员将收到警告消息。
这种设计使模块化地牢与原版风格的设置保持兼容，同时仍为使用额外插件的用户提供更深层次的集成。
生成池
[pool: poolname] 告示牌从 spawn_pools/ 文件夹中的生成池配置文件读取。每个生成池文件都是一个小型 YAML 配置，包含以下字段：
| 字段 | 默认值 | 描述 |
|---|---|---|
isEnabled | true | 此生成池是否启用 |
poolStrings | [] | 符合此池条件的 EliteMobs Boss 文件名列表 |
minLevel | -1 | 从此池生成的实例化 Boss 的最小等级（-1 = 未指定） |
maxLevel | -1 | 从此池生成的实例化 Boss 的最大等级（-1 = 未指定） |
当处理 [pool: poolname] 告示牌时，BetterStructures 会查找 poolname.yml（可选附加生成器的 spawnPoolSuffix），并从该池的 poolStrings 中随机选择一个 Boss。对于实例化的 Boss，生成等级会根据 Boss 与地牢中心的距离在 minLevel 和 maxLevel 之间缩放。
MythicMobs 集成
BetterStructures 还支持 MythicMobs 集成，用于在模块化地牢中创建自定义怪物遭遇。
当安装了 MythicMobs 时，结构包可以在地牢生成过程中生成自定义 MythicMobs。这允许创建超越原版 Minecraft 或 EliteMobs 所提供内容的更复杂的怪物遭遇和 Boss 战。
如果未安装 MythicMobs，插件将通知拥有适当权限的管理员并提供下载链接。
FMM 集成
模块化地牢还可以在创建过程中利用 FreeMinecraftModels (FMM) 道具。
- 如果安装了 FMM，模块创建者或建造者放置的任何道具都会出现在生成的地牢中。
- 道具纯粹是装饰性的，不会影响游戏玩法，但它们增强了环境的视觉保真度和沉浸感。
- 如果未安装 FMM，地牢仍然会正常生成，但这些自定义道具将不会显示。
这确保了创作者可以设计具有额外细节的地牢，同时为未安装 FMM 的玩家保持兼容性。
模块尺寸
重要： 模块大小是可配置的，不是固定的。
每个模块生成器使用以下选项定义其标准模块大小：
moduleSizeXZ：宽度和深度（方块），默认值：16moduleSizeY：高度（方块），默认值：16
默认大小： 16×16×16 方块 常见替代： 32×16×32 方块（用于某些内容包）
对于模块创作者：
- 检查你的生成器配置中的
moduleSizeXZ和moduleSizeY值 - 为该生成器构建的所有模块都必须匹配这些精确尺寸
- 尺寸不匹配将导致连接失败
设置自定义尺寸： 在你的模块生成器配置文件中：
moduleSizeXZ: 32 # 宽度和深度
moduleSizeY: 16 # 高度
注意：同一生成器中的所有模块必须使用相同的尺寸。你不能在同一个地牢系统中混合使用 16×16×16 和 32×16×32 的模块。
模块生成器配置字段
除了 moduleSizeXZ 和 moduleSizeY 之外，模块生成器配置还支持以下字段：
| 字段 | 默认值 | 描述 |
|---|---|---|
radius | 1 | 地牢半径（区块） |
edges | false | 是否生成边缘模块 |
startModule | — | 生成起始模块列表 |
minChunkY | 0 | 最小垂直区块边界 |
maxChunkY | 0 | 最大垂直区块边界 |
moduleSizeXZ | 16 | 模块的宽度和深度（方块） |
moduleSizeY | 16 | 模块的高度（方块） |
debug | false | 启用生成调试模式以进行故障排查 |
useGradientLevels | false | 为生成的实体启用基于梯度的等级缩放 |
spawnPoolSuffix | — | 附加到此生成器生成池名称的后缀 |
isWorldGeneration | false | 此生成器是否用于世界生成 |
treasureFile | — | 此地牢中箱子的宝藏配置文件 |
generateLootInBarrels | true | 模块中的木桶是否应填充战利品 |
barrelTreasureFilename | treasure_barrel_food.yml | 用于填充此地牢中木桶的宝藏配置文件 |
validWorlds | 空（所有世界） | 地牢可以生成的有效世界名称列表 |
validWorldEnvironments | 空（所有环境） | 有效世界环境列表（NORMAL、NETHER、THE_END、CUSTOM）。随插件附带的 dungeoneering 生成器显式写入了 [NORMAL, CUSTOM]，因此开箱即用时地牢只会在主世界类型的世界中生成。关于该键缺失时会发生什么，请见下方说明。 |
centerModuleAltitude | 0 | 中心模块的高度 |
关于缺失键的说明：上表的「默认值」一列列出的是 BetterStructures 写入自动生成的生成器文件中的值。如果你手写一个模块生成器文件并完全省略某个键，那么本次运行实际使用的值来自 Java 字段而不是这一列 —— 对 radius、moduleSizeXZ 和 moduleSizeY 而言是 0，对 validWorlds 和 validWorldEnvironments 而言则是「完全不限制」。因此缺失的 validWorldEnvironments 不会把生成器限制在 NORMAL/CUSTOM；它会让地牢在所有环境中生成。请始终显式写出这些键，而不要依赖省略；如果不确定，先让插件为你生成一个文件。
单个模块配置字段
每个单独的模块可以定义以下配置字段：
| 字段 | 默认值 | 描述 |
|---|---|---|
isEnabled | true | 此模块是否启用 |
weight | 100 | 生成期间此模块的选择权重 |
repetitionPenalty | 0 | 当此模块被多次选择时应用的惩罚 |
noRepeat | false | 防止此模块重复 |
enforceVerticalRotation | false | 强制垂直旋转约束 |
enforceHorizontalRotation | false | 强制水平旋转约束 |
minY | -4 | 此模块的最小 Y 高度 |
maxY | 20 | 此模块的最大 Y 高度 |
biome | default | 此模块的生物群系要求 |
minecraftBiome | null | 此模块的 Minecraft 生物群系要求 |
treasureFile | — | 此模块中箱子的宝藏配置文件 |
generateLootInBarrels | true | 此模块中的木桶是否应填充战利品 |
barrelTreasureFilename | treasure_barrel_food.yml | 用于填充此模块中木桶的宝藏配置文件 |
borders | — | 定义连接兼容性的边界标签映射 |
cloneConfig | — | 从另一个模块配置文件克隆设置 |
compoundModule | — | 将此模块链接为复合（多部分）模块的一部分 |
isAutomaticallyPlaced | true | 此模块是否在生成期间自动放置 |
注意：模块的哪些面可以与相邻模块连接，完全由 borders 边界标签映射控制。当两个模块某一面的相对边界标签匹配时，它们便会在该面连接。
关于 cloneConfig 的说明：把它指向另一个模块的 .yml 文件名，这个模块就会从那个文件读取所有被克隆的设置，而不是使用自己的。当克隆目标解析成功时，BetterStructures 会从磁盘上这个模块的文件中删除那些已经多余的键 —— treasureFile、barrelTreasureFilename、generateLootInBarrels、borders、minY、maxY、weight、repetitionPenalty、两个旋转开关、noRepeat、六个 *IsPassable 键以及 isAutomaticallyPlaced。只有 isEnabled、biome、minecraftBiome、cloneConfig 和 compoundModule 会保留在本地。如果指定的文件不存在，克隆设置会被忽略并给出警告，模块保留自己的值。
你还会在生成的模块配置中看到 northIsPassable、southIsPassable、eastIsPassable、westIsPassable、upIsPassable 和 downIsPassable。它们默认为 true，而生成器中没有任何代码读取它们 —— 修改它们不会产生任何效果。请改用 borders。
使用 /bs generateModules 手动生成地牢
/bs generateModules <ModuleGeneratorsConfigFile.yml> 会按需运行一个模块生成器，而不必等待它在世界生成过程中出现。Tab 补全会列出所有已加载的模块生成器文件。
具体行为取决于生成器的 isWorldGeneration 设置：
isWorldGeneration: true—— BetterStructures 会为该地牢创建一个全新的世界。世界以生成器文件命名并追加_0、_1、_2… 后缀，取第一个其文件夹尚不存在的后缀，因此重复运行永远不会覆盖之前的结果。它是一个NORMAL环境的平坦虚空世界，不会把出生点区块常驻内存，并且关闭了自动保存；运行该命令的玩家会被切换到旁观者模式。isWorldGeneration: false—— 生成会在你当前所处的世界中进行。
在晶格坍缩和模块粘贴的过程中，会有一条 Boss 血条显示进度。如果生成器没有任何可用的 startModule 条目，该命令会提示你需要先安装或构建模块，然后停止。
在内容重载进行期间，该命令会被拒绝执行。
模块文件存放位置
模块放在 plugins/BetterStructures/modules 中，该目录会被递归扫描 —— 内容包可以把它的 .schem 文件放在子文件夹里，对应的 .yml 配置会在同级位置生成。
模块原理图的文件名在整个 modules 目录树中必须唯一。位于不同文件夹但同名的两个 .schem 文件会让配置查找产生歧义，此时 BetterStructures 会拒绝启动，而不是随便挑一个。若某个已启用的模块配置对应的 .schem 无法读取，同样会被视为致命错误，这样一个损坏的模块包会明确地报错失败，而不是悄无声息地生成出带窟窿的地牢。