企业官网建设流程全解析

• 低代码
• 代码生成
• 桌面应用
• 游戏开发

本篇指南围绕 MCreator「结构（Structure）」元素中的Jigsaw Pools（拼图池）配置展开。Jigsaw 是 Minecraft 用于把多个小型结构部件（Part）按规则拼接成大型结构的生成系统，MCreator 在结构生成界面中提供了可视化配置入口。读完本文你将掌握：如何用 Pool 对结构部件分组、如何按${modid}:${registryname}_<pool_name>规范让部件中的 Jigsaw Block 指向目标池、如何配置池条目权重与回退池，以及 Size、Max Distance From Center 等参数对生成结果的影响。

什么是 Jigsaw 结构与 Jigsaw Pools

MCreator 的帮助文档（见 jigsaw_pools.md）对 Jigsaw Pools 的定位给出了最核心的说明：

在这里列出你拼图结构的各个部分。使用 Pool（池）来对要放置在相似位置的部件进行分组。

这意味着：一个大型结构（例如村庄、地牢）不需要在单个.nbt文件中全部画好，而是拆成若干小部件，每个部件内放置 Jigsaw Block，由游戏在生成时把部件像拼图一样拼接起来。Pool 的作用就是把"应当出现在同一类位置"的部件归为一组——例如"入口部件池""塔楼部件池""装饰部件池"——生成时游戏从对应池中随机挑选一个部件来填充该位置。

在 MCreator 的数据模型中，这一关系被建模在 Structure.java 内：结构元素持有一个List<JigsawPool> jigsawPools，每个JigsawPool包含poolName、fallbackPool与poolParts（一组JigsawPart）；而每个JigsawPart则包含weight（权重）、structure（指向哪个结构文件）、projection（投影模式）与ignoredBlocks（忽略的方块列表）。可见"结构 → 池 → 部件"的三级结构正是 Jigsaw 生成的骨架。

目标池（Target Pool）命名规则：${modid}:${registryname}_<pool_name>

这是 Jigsaw Pools 配置中最关键、也最容易被忽略的约束。帮助文档明确指出（jigsaw_pools.md）：

确保你的部件中的 Jigsaw Block 的目标池名称设置为${modid}:${registryname}_<pool_name>，如果它们应该放置下方列出的拼图部件。

也就是说，命名不是随意的。你在部件（.nbt结构文件）里放置的 Jigsaw Block 的 Target Pool 字段，必须精确写成：

<modid>:<registryname>_<pool_name>

其中：

组合出来的目标池全名即example:my_tower_towers。只有当部件内 Jigsaw Block 的目标池指向这个全名时，生成器才会把该池下列出的部件放置到这个 Jigsaw Block 的位置上；否则部件将无法被拼接到主结构上。

这一命名逻辑在 UI 层有直接印证：在 JJigsawPool.java 中，回退池下拉框的候选项正是由代码拼接生成的——它遍历当前列表里所有校验通过的池，逐个生成${modid}:${registryname}_<pool_name>形式的完整资源位置供你选择，避免手工拼写出错。同时，池名称输入框本身受 RegistryNameValidator 与唯一性校验约束，保证pool_name段本身是一个合法、不重复的注册名片段。

Jigsaw 池配置面板实战

在 MCreator 中打开「结构（Structure）」元素的生成界面，找到Jigsaw Pools分区（对应 StructureGUI.java），点击添加按钮即可新建一个池。每个池由"池名称 + 回退池 + 若干条目"构成，底层 UI 实现在 JJigsawPool.java 中。

池名称（Pool Name）

该参数控制当前池的名称，也就是上文目标池命名规则中的_pool_name段。帮助文档（jigsaw_pool_name.md）说明：

该参数控制当前 Jigsaw 池的名称，当无法在指定位置生成时，该池可能被当前使用的池作为回退引用。

若部件中 Jigsaw Block 的 Target Pool 设为${modid}:${registryname}_<pool_name>，游戏就会把这些池中的部件放置到它们旁边。命名时注意：

• 必须符合注册名（Registry Name）规范（小写、下划线分隔）；
• 在同一结构的池列表中必须唯一（由UniqueNameValidator强制，见 JJigsawPoolsList.java）。

回退池（Fallback Pool）

每个池可以额外指定一个回退池。帮助文档（jigsaw_fallback_pool.md）给出了精确定义：

该参数决定当前池在无法于指定位置生成部件（空间不足或达到深度上限）时，可以回退使用哪个 Jigsaw 池来挑选一个"终结者（terminator）"部件。 如果设置为${modid}:${registryname}_<pool_name>，游戏将从本列表中名为<pool_name>的池中选择 Jigsaw 部件。 也可以使用同一个池，但如果它与其他同结构的 Jigsaw 部件重叠，将被忽略。

这里有几个要点：

1. 回退池的核心价值是兜底：当主池中的部件因空间不足、深度达到上限（受size限制）而无法生成时，生成器不会中断整条拼接链，而是从回退池里挑一个部件（通常是一个空白的"终结者"部件）来收尾，让结构"优雅地结束"；
2. 回退池可以指向任意一个已配置的池，包括当前池自身（fallbackPool下拉框允许输入任意合法资源位置，并可在当前池列表中选择，见 JJigsawPool.java）；
3. 自引用有代价：如果回退部件与其他同结构的 Jigsaw 部件发生重叠，它将被忽略，因此自回退通常配合极小的"终止部件"使用；
4. 回退池字段允许留空（setAllowEmpty(true)），表示不启用回退。

池条目（Jigsaw Part）配置：权重、结构与投影

添加池后，默认会附带一个初始条目，你也可以通过"添加池条目"按钮追加更多。每个条目对应一个可放置的结构部件，其字段定义于 Structure.java 中的JigsawPart类，UI 实现在 JJigsawPart.java。

其中结构选择器会在运行时加载工作区全部已导入结构（reloadDataLists()调用mcreator.getFolderManager().getStructureList()，见 JJigsawPart.java），并强制要求必须选中一个结构，否则该校验失败（error_select_structure_spawn）。

结构级 Jigsaw 参数：Size 与 Max Distance From Center

除池本身的配置外，结构元素还提供两个直接影响 Jigsaw 生成范围的结构级参数，二者在 StructureGUI.java 中与 Jigsaw Pools 列表同屏展示，底层定义在 Structure.java。

Size（拼图深度）

帮助文档（jigsaw_size.md）的定义：

该参数定义可以生成多少个相互连接、并连接到主结构的 Jigsaw 部件。 使用回退池可以在指定位置多放置一个 Jigsaw 部件来补全结构。

它本质上限制了整条 Jigsaw 拼接链的最大深度：size越大，允许向外扩展的部件层数越多，结构整体规模越大。源码中其范围为0–20（@Numeric(init = 1, min = 0, max = 20)，见 Structure.java），即最多允许 20 层部件向外延伸。当拼接到达深度上限且当前位置无法继续时，触发前文所述的回退池逻辑。

Max Distance From Center（距中心最大距离）

帮助文档（jigsaw_max_distance_from_center.md）的定义：

该选项控制 Jigsaw 部件可以生成在距主结构多远的范围内。 除非设置为 "none"，否则允许的最大值还会被地形自适应（terrain adaptation）进一步限制，因为游戏需要一些空间来将地面调整到与生成的结构匹配。

源码中该参数范围为1–128（@Numeric(init = 64, min = 1, max = 128)）。一个容易被忽略的联动细节在 StructureGUI.java：当"地形自适应（Terrain Adaptation）"不为none时，此参数的上限会被动态收窄为 116，同时当前值若超限会被自动截断。这一约束同样体现在生成模板中（见下文 JSON 模板的?min计算），保证地形调整有足够的操作空间。

从配置到生成：Jigsaw 结构 JSON 模板

MCreator 为数据包（datapack）生成器提供了 Jigsaw 结构的 JSON 模板 structure.json.ftl，把上述配置直接映射为原版 Jigsaw 结构定义：

{ "type": "minecraft:jigsaw", "start_pool": "${modid}:${registryname}", "size": ${data.size}, "max_distance_from_center": ${(data.terrainAdaptation != "none")?then([data.maxDistanceFromCenter, 116]?min, data.maxDistanceFromCenter)}, "spawn_overrides": {}, "step": "${data.generationStep}", "terrain_adaptation": "${data.terrainAdaptation}", "start_height": { "absolute": 0 }, "biomes": "...", "use_expansion_hack": false }

模板中几个关键字段与上文配置一一对应：

• start_pool被固定写为${modid}:${registryname}——这正是 Jigsaw 的起始池命名，而池列表中各池则遵循${modid}:${registryname}_<pool_name>规则，二者共同构成完整的 Jigsaw 池命名空间；
• size直接使用界面中的 Size 参数；
• max_distance_from_center体现了"地形自适应收窄上限"的实现：当terrainAdaptation != "none"时取min(maxDistanceFromCenter, 116)，否则直接使用配置值；
• terrain_adaptation支持none/beard_thin/beard_box/bury/encapsulate（见 Structure.java 的@LimitedOptions注解）。

Jigsaw 池与部件本身则随结构数据一起保存并被生成器消费（jigsawPools字段同时带有@ModElementReference与@ResourceReference("structure")注解，见 Structure.java），确保结构引用关系在工作区中被正确追踪。

常见问题与最佳实践

1. 部件没有被拼接上去：优先检查 Jigsaw Block 的 Target Pool 是否严格等于${modid}:${registryname}_<pool_name>，特别是modid是否与工作区设置一致、registryname是否与结构注册名完全一致。可借助回退池下拉框自动生成的候选项核对格式。
2. 结构生成到一半中断：通常是主池部件在某位置放不下且未配置回退池。为每个池配置一个包含空白"终结者"部件的回退池，可让拼接链完整收尾。
3. 同池回退被忽略：回退池引用自身时，若回退部件与其他已生成的同结构部件重叠则会被忽略，应避免大体积自引用。
4. max_distance_from_center最大值被"变小"：这是正常行为——当地形自适应非none时上限从 128 收窄为 116，无需强行调回。
5. 权重设计：同一池内多个部件通过weight（1–150）控制出现概率，希望某部件更常出现就调高其权重，这与原版 Jigsaw 的加权随机语义一致。

延伸阅读

• 结构元素数据模型：Structure.java
• Jigsaw 池列表与池 UI 实现：JJigsawPoolsList.java、JJigsawPool.java
• 池条目 UI 实现：JJigsawPart.java
• 结构生成界面（含 Jigsaw 分区布局）：StructureGUI.java
• 数据包 Jigsaw 结构生成模板：structure.json.ftl
• 配套帮助文档（默认英文版）：jigsaw_pool_name.md、jigsaw_fallback_pool.md、jigsaw_size.md、jigsaw_max_distance_from_center.md

• 低代码
• 代码生成
• 桌面应用
• 游戏开发