Menu
为维度提供多方块结构装饰物快速注册的API。包含柱形、团块、尖刺、门框、散布、水下6种类型及自定义扩展，内置悬空检测/填充、占位检测、区域重叠、碎片散落、表面嵌入等逻辑。在需要为维度添加新的装饰性地物时调用。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | world-decoration-api |
| description | 为维度提供多方块结构装饰物快速注册的API。包含柱形、团块、尖刺、门框、散布、水下6种类型及自定义扩展，内置悬空检测/填充、占位检测、区域重叠、碎片散落、表面嵌入等逻辑。在需要为维度添加新的装饰性地物时调用。 |
WorldDecorationAPI 是 PasterDream 模组提供的多方块装饰物快速注册系统。通过流式 Builder API，你可以用寥寥几行 Java 代码定义一个复杂的装饰物结构，并自动生成对应的 configured_feature 和 placed_feature JSON 数据文件。
| 类 | 路径 | 作用 |
|---|---|---|
DecorationBuilder | worldgen/decor/DecorationBuilder.java | 流式 Builder，链式配置装饰物参数 |
DecorationType | worldgen/decor/DecorationType.java | 装饰物类型枚举 |
DecorationConfig | worldgen/decor/DecorationConfig.java | 统一配置记录（含 MapCodec 序列化） |
GenericDecorationFeature | worldgen/decor/GenericDecorationFeature.java | 统一 Feature 实现，按类型调度生成算法 |
DecorationRegistry | worldgen/decor/DecorationRegistry.java | 注册管理中心 + JSON 自动生成 |
WorldGenUtils | worldgen/WorldGenUtils.java | 共享工具方法（findGroundY、isSolidSurface 等） |
确保 PasterDreamMod.java 中已注册 DecorationRegistry.FEATURES：
// 注册通用装饰物特征（WorldDecorationAPI）
DecorationRegistry.FEATURES.register(modEventBus);
import com.pasterdream.pasterdreammod.worldgen.decor.DecorationBuilder;
import com.pasterdream.pasterdreammod.worldgen.decor.DecorationType;
import net.minecraft.world.level.block.Blocks;
import net.minecraft.world.level.levelgen.GenerationStep;
// 定义一个方解石柱
DecorationBuilder.create()
.type(DecorationType.PILLAR)
.body(Blocks.CALCITE)
.height(15, 20)
.width(2, 1)
.crystal(0.3f, BlockStateProvider.simple(Blocks.AMETHYST_BLOCK))
.debris(Blocks.CALCITE, 6, 3)
.checkHang(true)
.fillHang(false)
.biome("pasterdream:biome_dyedream_1")
.rarity(3)
.step(GenerationStep.Decoration.TOP_LAYER_MODIFICATION)
.register("calcite_pillar");
在开发环境的初始化阶段（如 FMLCommonSetupEvent）或测试主方法中调用：
// 生成所有已注册装饰物的 JSON 文件到 src/main/resources/data/pasterdream/worldgen/
DecorationRegistry.generateAllJson();
此操作会生成：
worldgen/configured_feature/<name>.json — 配置特征定义worldgen/placed_feature/<name>.json — 放置特征定义（含稀有度过滤、in_square、高度图、群系过滤）JSON 文件生成后，需要在 neoforge/biome_modifier/ 下创建对应的注入文件：
{
"type": "neoforge:add_features",
"biomes": "pasterdream:biome_dyedream_1",
"features": ["pasterdream:calcite_pillar"],
"step": "top_layer_modification"
}
或者通过 DecorationRegistry.register() 返回的 ResourceKey<PlacedFeature>，在 Java BiomeModifier 中动态注入。
DecorationType.PILLAR — 柱形参考: 方解石柱（CalcitePillarFeature）
锥形柱体，从地下延伸到地上，底部粗顶部细。
| 关键参数 | 说明 | 默认值 |
|---|---|---|
body() | 主体方块 | 必填 |
height(min, max) | 高度范围 | 3~8 |
width(base, top) | 底部宽度、顶部宽度（方块数） | 2, 1 |
checkHang(bool) | 悬空检测 | true |
crystal(chance, provider) | 表面嵌入晶体 | -- |
生成逻辑:
findGroundY + undergroundBias（地下部分更宽）halfWidth = baseWidth + (topWidth - baseWidth) * progresscrystalChance 概率替换为晶体crystalOnlyOnTop=true 时，检查 y+1 层的截面是否还包含 (dx,dz) 位置。上层还有结构 = 嵌入状态 → 不生成晶体；上层无结构 = 暴露在外 → 可生成晶体DecorationType.SPIKE — 尖刺参考: 冰刺（IceSpikeFeature）
底部粗尖端细的锥形尖刺，使用圆形截面而非方形截面。
| 关键参数 | 说明 | 默认值 |
|---|---|---|
body() | 主体方块 | 必填 |
top() | 顶部方块 | 同 body |
height(min, max) | 高度范围 | 8~16 |
radius(base, top) | 底部半径、顶部半径（0=尖顶） | 2, 0 |
regionCheck(bool, threshold) | 区域重叠检测 | false |
crystal(chance, provider) | 嵌入矿石概率 | -- |
生成逻辑:
isAreaOccupied）crystalOnlyOnTop=true 时，检查 y+1 层的圆形截面是否还包含 (dx,dz) 位置（判断方法：nextDistSq ≤ (nextR + 0.5)²）DecorationType.BLOB — 团块参考: 云坠堆（CloudBlobFeature）
不规则椭球状团块，使用随机游走算法。
| 关键参数 | 说明 | 默认值 |
|---|---|---|
body() | 主体方块 | 必填 |
clusterSize(size) | 总方块数 | 50 |
yRadius(radius) | 垂直半径 | 4 |
irregularity(0~1) | 不规则度 | 0.3 |
fillHang(bool) | 悬空填充（下坠+路径填充） | false |
生成逻辑:
findGroundY 找地面层clusterSize 次循环扩散dist²/noise + (relativeY²/yRadius²) ≤ 1fillHang=true：按 Y 排序后稳定化（下移到有支撑 + 填充路径）DecorationType.GATE — 门框参考: 冰之门（IceGateFeature）
双柱+顶部横梁组成的门框形结构。
| 关键参数 | 说明 | 默认值 |
|---|---|---|
body() | 主体方块 | 必填 |
gateWidth(min, max) | 门框间距 | 4~8 |
pillarRadius(radius) | 柱半径 | 2 |
beamThickness(thickness) | 横梁厚度 | 2 |
height(min, max) | 高度范围 | 5~10 |
生成逻辑:
findGroundYDecorationType.SCATTER — 散布地表随机散布的单个方块群。
| 关键参数 | 说明 | 默认值 |
|---|---|---|
body() | 散布的方块 | 必填 |
checkHang(bool) | 悬空检测 | true |
生成逻辑:
checkHang=true 时悬空跳过DecorationType.AQUATIC — 水下结构在水体中生成的结构，需要水环境。
| 关键参数 | 说明 | 默认值 |
|---|---|---|
body() | 主体方块 | 必填 |
height(min, max) | 高度范围 | 3~8 |
waterRequired(bool) | 是否需要水 | true |
生成逻辑:
DecorationType.CUSTOM — 自定义预留扩展点。需自行实现生成接口并注入。
// 暂未开放，当前 register 会返回 false
DecorationBuilder.create()
.type(DecorationType.CUSTOM)
.body(Blocks.STONE)
.register("my_custom");
| 方法 | 类型 | 默认值 | 说明 |
|---|---|---|---|
type(DecorationType) | enum | PILLAR | 结构类型 |
body(Block/BlockStateProvider) | 必填 | -- | 主体方块 |
top(Block/BlockStateProvider) | 可选 | body | 顶部方块 |
crystal(float, BlockStateProvider) | 可选 | -- | 表面嵌入晶体概率+方块 |
debris(Block/BlockStateProvider, int, int) | 可选 | -- | 碎片方块+数量+半径 |
height(int, int) | int | 3~8 | 高度范围 |
width(int, int) | int | 2, 1 | 柱形截面宽度 |
radius(int, int) | int | 2, 0 | 圆形截面半径 |
clusterSize(int) | int | 50 | 团块方块总数 |
yRadius(int) | int | 4 | 团块垂直半径 |
irregularity(float) | float | 0.3 | 团块不规则度 |
gateWidth(int, int) | int | 4~8 | 门框间距 |
pillarRadius(int) | int | 2 | 门框柱半径 |
beamThickness(int) | int | 2 | 横梁厚度 |
decorationChance(float) | float | 0.0 | 额外装饰概率（门框用） |
crystalOnlyOnTop(boolean) | bool | true | 晶体仅放置于最顶层（顶部高度打断） |
checkHang(boolean) | bool | true | 悬空检测 |
fillHang(boolean) | bool | false | 悬空填充 |
occupiedCheck(boolean) | bool | true | 占用检测 |
regionCheck(boolean, float) | bool | false, 0.3 | 区域重叠检测 |
waterRequired(boolean) | bool | false | 水环境要求 |
replaceable(BlockPredicate) | predicate | null (仅空气) | 可替换方块条件（null=仅空气可替换） |
biome(String) | string | "" | 目标群系 ID |
rarity(int) | int | 1 | 稀有度（1/N） |
step(GenerationStep.Decoration) | enum | TOP_LAYER_MODIFICATION | 生成阶段 |
根据特征类型选择合适的生成阶段：
| 阶段 | 适用场景 | 对应原版枚举 |
|---|---|---|
RAW_GENERATION | 基岩层特殊结构 | -- |
LAKES | 湖泊类 | -- |
LOCAL_MODIFICATIONS | 局部地形的修改 | -- |
UNDERGROUND_STRUCTURES | 地下结构 | -- |
SURFACE_STRUCTURES | 地表结构 | ✅ 一般结构默认 |
TOP_LAYER_MODIFICATION | 地表地形修改 | ✅ 柱子/尖刺/团块 |
UNDERGROUND_ORES | 矿石 | -- |
UNDERGROUND_DECORATION | 地下装饰 | -- |
FLUID_SPRINGS | 流体泉 | -- |
VEGETAL_DECORATION | 植被 | ✅ 水上植物等 |
TOP_LAYER_MODIFICATION | 地表地形修改 | ✅ 柱子/尖刺/团块 |
DecorationRegistry.generateAllJson() 会为每个已注册的装饰物生成：
{
"type": "pasterdream:generic_decor",
"config": {
"type": "pillar",
"body_block": { "type": "minecraft:simple_state_provider", "state": { "Name": "minecraft:calcite" } },
"min_height": 15,
"max_height": 20,
"base_width": 2,
"top_width": 1,
"crystal_chance": 0.3,
"check_hang": true
}
}
{
"feature": "pasterdream:calcite_pillar",
"placement": [
{ "type": "minecraft:rarity_filter", "chance": 3 },
{ "type": "minecraft:in_square" },
{ "type": "minecraft:heightmap", "heightmap": "MOTION_BLOCKING" },
{ "type": "minecraft:biome" }
]
}
replaceable 写成了 minecraft:always_true症状：世界加载时报错 Unknown registry key: minecraft:always_true，游戏闪退。
原因：Minecraft 1.21.1 没有注册 minecraft:always_true 这个 block_predicate_type。Builder 默认值是 null 不编码，手写 JSON 时写进去就炸。
修复：
replaceable()，自动不编码 ✅replaceable 字段 ✅config.type 写了大写症状：游戏崩溃 Unknown element name:SPIKE（或 GATE、PILLAR、AQUATIC 等）
原因：DecorationType 枚举实现 StringRepresentable，序列化用的是构造参数的小写（"spike"、"gate"、"pillar"、"aquatic"）。JSON 里写 "SPIKE" 解析器不认识。
修复：
"type": "spike"、"type": "pillar" ✅症状：Feature order cycle found, involved sources: [pasterdream:biome_dyedream_3]，世界无法生成区块。
原因：某个生物群系同时属于多个 tag（如 #is_dyedream 和 #is_dyedream_ocean），不同的 biome_modifier 通过不同 tag 往同一个生成阶段添加了同一个 placed_feature，造成循环依赖。
举个例子：
biome_dyedream_3 同时属于：
├── #is_dyedream → dyedream_vegetation.json 加了 lily_pad 到 step 8
└── #is_dyedream_ocean → water_vegetation_sparse.json 又加了 lily_pad 到 step 8
↓
同一特征在同一阶段出现两次 → Feature order cycle 💥
预防：
症状：Unbound values in registry worldgen/configured_feature 或 worldgen/placed_feature
原因：在一个 placed_feature/configured_feature 的 JSON 里引用了另一个 feature（如 "feature": "pasterdream:xxx"），但目标 JSON 文件不存在或注册名对不上。
预防：
症状：同一个区块内多个同类结构叠在一起，一个上面顶着另一个，显得很不自然。
原因：结构使用 rarity_filter + in_square + heightmap 放置，但没有区域重叠检查。同一个 chunk 的不同位置被选中后各自生成结构，如果彼此间距不够，就会叠在一起。
举个例子：
方解石柱 A 跟方解石柱 B 间距只有 2 格 →
柱B
柱A ← 叠罗汉 💥
预防：
regionCheck(true, 0.3)，生成前会检测区域是否被占用.regionCheck(true, 0.3f)症状：JSON 里写了 region_check: true，结构还是叠叠乐，拦不住。
血的教训 🩸：isAreaOccupied 内部有两种检测模式，天差地别：
有没有自定义 replaceable | 检测方式 | 效果 |
|---|---|---|
| ✅ 有（如方解石柱子把石头/泥土列为可替换） | 精确布尔检测：groundY ±2 层逐点排查，任何一个非可替换方块就阻止 | 100% 可靠，窄到 2×2 的结构也能发现 💯 |
| ❌ 无（仅认空气） | 退化为采样+阈值法：网格扫描后再算比率 vs 0.3 | 宽结构安全，窄结构（宽度≤3）可能漏检 ⚠️ |
根因：如果没有自定义 replaceable，isReplaceable 只认空气，所以自然地形（石头、冰块、草地）都会被算作「不可替换」。在采样+阈值模式下，自然地形会大幅稀释结构方块所占的比例，导致窄结构无法超过 0.3 阈值。
所以一定要给加了 regionCheck 的结构配 replaceable 谓词！
正确的 JSON 示例（给方解石柱加 replaceable）：
{
"type": "pasterdream:generic_decor",
"config": {
"type": "pillar",
"body_block": ...,
"region_check": true,
"region_threshold": 0.3,
"replaceable": {
"type": "minecraft:any_of",
"predicates": [
{
"type": "minecraft:matching_blocks",
"blocks": ["minecraft:stone", "minecraft:dirt", "minecraft:grass_block"]
},
{ "type": "minecraft:replaceable" }
]
}
}
}
用 Builder API 自动规避：.replaceable(BlockPredicate) → 自动走精确布尔检测 ✅
错误理解：crystalOnlyOnTop(true) = 只检查 y < topY → 只有结构最顶层能放晶体，中间层哪怕缩窄了暴露出来的表面也没有晶体。
正确实现：crystalOnlyOnTop(true) = 对每个表面方块，计算 y+1 层的截面是否还包含这个 (dx,dz) 位置。
举个例子——锥形柱子从宽 5 缩到宽 3 再缩到宽 1：
[*] ← y=topY：中心1块，暴露在外→长晶体✅
[ ][ ][*] ← y=mid：宽3，边缘暴露→长晶体✅（老逻辑只有topY有，完全暴殄天物！）
[ ][ ][ ][ ][ ] ← y=bottom：宽5，边缘上面还有结构→嵌入状态❌
PILLAR/AQUATIC 用方截面检测：hasBlockAbove = dx ∈ [-nextHalfSize, nextWidth - nextHalfSize) && dz ∈ [...]
SPIKE 用圆截面检测：hasBlockAbove = nextDistSq ≤ (nextR + 0.5)²
症状：通过 Builder API 创建的结构晶体很少（只在最顶层），但手写 JSON 的结构晶体看起来很多。
原因：Builder API 的 crystalOnlyOnTop 默认是 true（新装饰物默认晶体帽），但 JSON CODEC 解码时默认是 false（兼容旧 JSON）。这是有意设计的差异：
| 方式 | 默认值 | 说明 |
|---|---|---|
| Builder API 创建新结构 | true | 晶体=高度帽，仅暴露在外的表面出晶体 |
| 手写 JSON 旧结构 | false | 晶体=表面装饰，所有暴露面都可能出 |
修复：
.crystalOnlyOnTop(false) ✅"crystal_only_on_top": true ✅my_cool_pillarreplaceable + regionCheck：这是防叠罗汉的黄金组合！有自定义 replaceable 才能走精确布尔检测，100% 挡住叠叠乐。Builder API：.replaceable(predicate).regionCheck(true, 0.3f)crystalOnlyOnTop(true) 不是简单的 y < topY，而是检查 y+1 层截面是否包含 (dx,dz)。锥形柱变窄时暴露的表面也会长晶体TOP_LAYER_MODIFICATION，植被用 VEGETAL_DECORATIONrarity(5~10)，小型结构用 rarity(2~3)fillHang(true)，柱形/尖刺建议仅 checkHang(true)FMLCommonSetupEvent 中调用 generateAllJson()，然后去 worldgen/ 目录复制生成的 JSON 文件neoforge/biome_modifier/ 下的注入文件使用，或者通过代码注入Guides API-Split multi-module architecture decisions for NeoPasterDream (NeoForge 1.21.1). Invoke when deciding where to place new code (PasterDreamAPI vs PasterDream), creating Builder/Facade/Result/Config classes, or designing new registration systems.
PasterDream模组药水效果注册专用API，提供Facade+Builder模式一键注册自定义MobEffect。在需要创建新状态效果、配置效果属性/着色器/粒子/回调/药水酿造时调用。
PasterDream模组实体注册专用API，提供Facade+Builder模式一键注册自定义实体。在需要创建新实体、配置实体属性/AI/碰撞箱/追踪范围/生物技能、动画系统或注册渲染器时调用。
PasterDream NeoForge 1.21.1 模组开发指南。提供项目结构、注册系统、实体系统、物品系统等的开发规范，以及常见崩溃问题的解决方案。Invoke when developing or modifying PasterDream mod features, creating new items/blocks/entities, fixing crashes, or when needing to understand the mod's architecture.
PasterDream 物品移植 API —— 用于将原 FixPasterDream 模组（MCreator 生成）中的物品系统化移植到 NeoForge 1.21.1。提供 Builder 模式、批量注册、迁移追踪、配方生成、战利品表生成、方块数据生成、创造标签页生成、语言文件生成及超级快速导入器等一站式工具链。Invoke when needing to port items from the old FixPasterDream mod, register new items in PDItems.java, batch-create items with consistent patterns, generate recipes/loot tables/block tags, or create creative tab registration code.
Minecraft NeoForge 1.21.1 方块掉落问题诊断与修复指南。Invoke when user encounters block drop issues, missing loot drops, or needs to implement custom block drops. Covers getDrops() override, BlockItem registration, and loot table JSON troubleshooting.