特性类型

experimental

特性类型

内容特性

最后更新于1.17.10版本

WARNING

部分设计用于引用外部文档的链接暂不可用，后续将更新指向正确资源。

此处列出的许多特性类型将在后续提供截图和其他参考资料。

内容特性

内容特性是特性系统中定义方块放置的基础类型。它们不提供排列或组合功能，而是定义方块的基本布局，通常与代理特性结合使用或定位。

单方块特性

json

{
    "format_version": "1.13.0",
    "minecraft:single_block_feature": {
        "description": {
            "identifier": "wiki:pier_planks"
        },
        "places_block": "minecraft:planks",
        "enforce_placement_rules": true,
        "enforce_survivability_rules": true,
        "may_replace": ["minecraft:water"],
        "may_attach_to": {
            "top": "minecraft:air",
            "sides": ["minecraft:planks", "minecraft:water"]
        }
    }
}

单方块特性在世界中放置单个方块。单独使用时通常效果有限，其真正价值在于与代理特性结合构建复杂结构。

通过"places_block"属性指定目标方块（即要放置的方块）。当前定义中无法实现变体功能，必须改用加权随机特性组合多个单方块特性。

条件限制

可通过条件限制放置成功率。若任何条件不满足，方块将不会被放置。

WARNING

出于放置成功判定考虑，单方块特性若尝试替换自身会被视为失败。这对于聚合特性、条件列表等有重要影响。当仅考虑放置限制成功时，应使用搜索特性代理单方块特性。

固有方块条件

单方块特性可绕过方块固有放置限制。

当"enforce_placement_rules"为true时（必须指定），方块必须通过其固有放置检查；设为false则忽略此检查。例如种子通常只能种在耕地上，但禁用检查后可在任意位置生成。

同样，必须指定的"enforce_survivability_rules"布尔属性控制是否进行方块存活检查。若为false，则忽略方块的存活条件。例如活珊瑚需要邻近水源的存活条件。

注意

世界生成时忽略方块的存活检查，不意味着游戏过程中会保持无效状态。方块更新会修正无效的存活状态。

替换条件

json

"may_replace": [
    "minecraft:air",
    "minecraft:leaves",
    "minecraft:leaves2"
]

通过"may_replace"数组可指定替换列表，限制目标方块可替换的方块集合。若单方块特性输入位置的方块不在此列表中，放置将失败。

WARNING

与附着属性不同，"may_replace"必须声明为数组，不能直接引用单个方块。

附着条件

json

"may_attach_to": {
    "top": "minecraft:air",
    "sides": [
        "minecraft:planks",
        "minecraft:water"
    ]
}

通过可选的"may_attach_to"属性指定附着规范，限制方块的邻接关系。可为每个可附着面设置属性：

"top"
"bottom"
"north"
"south"
"east"
"west"

每个属性可接受单个方块引用或此类引用的数组：

json

"bottom": {
    "name": "minecraft:stone",
    "states": {
        "stone_type": "andesite"
    }
}

json

"top": [
    "minecraft:netherrack",
    "minecraft:soul_sand"
]

"sides"属性可作为通配项匹配"north"、"west"、"east"和"south"。此外，"all"属性匹配全部6个面。这8个属性均为可选，但至少应指定一个。

对于侧面附着（"north"、"south"、"east"、"west"），还有2个额外属性用于精细控制：

"min_sides_must_attach"设置需要成功附着的最小侧面数。若设为4，则必须全部四个侧面匹配；若设为2而只有1个侧面匹配，方块放置将失败。

"auto_rotate"使侧面定义被解释为相对关联而非严格方向。例如若需让方块在某一维度上夹在两个其他方块之间而不关心朝向，启用自动旋转并指定相对侧面即可实现任意朝向生效。

json

{
    "format_version": "1.13.0",
    "minecraft:single_block_feature": {
        "description": {
            "identifier": "wiki:force_conduit_block"
        },
        "places_block": "wiki:force_conduit",
        "enforce_placement_rules": true,
        "enforce_survivability_rules": true,
        "may_replace": ["minecraft:air"],
        "may_attach_to": {
            "north": "minecraft:glass",
            "south": "minecraft:glass",
            "auto_rotate": true
        }
    }
}

具体而言，上述代码会使力导管方块在任意朝向上夹在相邻玻璃之间。

矿石特性

json

{
    "format_version": "1.13.0",
    "minecraft:ore_feature": {
        "description": {
            "identifier": "wiki:starlite_ore_cluster"
        },
        "count": 4,
        "replace_rules": [
            {
                "places_block": "wiki:starlite_ore",
                "may_replace": ["minecraft:stone"]
            }
        ]
    }
}

矿石特性在目标位置周围放置方块簇。通过替换规则控制所放置方块的变体。只有矿石特性中的方块数量是全局控制的，由"count"属性决定。

注意

无法控制簇的形状；要实现此功能，需使用散布特性配合自定义分布系统。

替换规则

json

"replace_rules": [
    {
        "places_block": "infinitum:exposed_pylon",
        "may_replace": [
            "minecraft:air"
        ]
    },
    {
        "places_block": "infinitum:submerged_pylon",
        "may_replace": [
            "minecraft:water"
        ]
    }
]

在矿石特性中，替换规则将目标方块与限制其放置的替换列表绑定，通过"replace_rules"提供。目标方块由必需的"places_block"属性指定；替换列表（通过"may_replace"）是可选的数组，仅允许替换特定方块。对于簇中的每个位置，将选择第一个匹配规则的目标方块。若未提供替换列表，则该规则在其位置总会成功，后续规则将被忽略。

结构模板特性

json

{
    "format_version": "1.13.0",
    "minecraft:structure_template_feature": {
        "description": {
            "identifier": "wiki:blackmoor_castle_feature"
        },
        "structure_name": "wiki:blackmoor_castle",
        "facing_direction": "random",
        "constraints": {
            "block_intersection": {
                "block_allowlist": [
                    "minecraft:air",
                    "minecraft:stone",
                    "minecraft:dirt",
                    "minecraft:grass"
                ]
            },
            "unburied": {}
        },
        "adjustment_radius": 4
    }
}

结构模板特性通过引用保存的结构文件生成结构。这类特性以灵活性和功能性换取便利性。

WARNING

与数据驱动特性不同，结构特性中的方块若放置于水中_不会_自动变为含水状态。

通过"structure_name"字符串属性放置目标结构，其命名格式为命名空间:路径，用于从行为包中选择.mcstructure文件。结构文件必须放在顶级structures目录中，可在此目录下建立文件夹层级（非必需）。若直接放在structures目录中，则使用默认命名空间mystructure；若放在structures的子目录中，则使用该目录名作为命名空间。任何嵌套路径都会反映在路径中，最后省略文件扩展名（.mcstructure）。

示例：

结构文件位置	对应的`"structure_name"`
`/structures/well.mcstructure`	`"mystructure:well"`
`/structures/farmstead/silo.mcstructure`	`"farmstead:silo"`
`/structures/campsites/taiga/rustic/tents/wool.mcstructure`	`"campsites:taiga/rustic/tents/wool"`

WARNING

由于特性系统限制，大型结构可能需要预切割为较小结构并通过定位组合。

旋转

json

"facing_direction": "south"

通过"facing_direction"属性进行结构旋转，接受四个横向方向："north"、"south"、"east"和"west"，以及额外的"random"属性实现每次实例随机旋转。南方是"默认"方向；使用此方向时结构向正_x_和正_z_方向延伸。

WARNING

对于非南向结构，并非所有方块状态都会更新以适应旋转，导致某些可旋转方块（如藤蔓）悬挂在无效位置。

旋转从俯视视角顺时针进行。旋转围绕结构原点而非中心进行，因此大型结构在随机旋转时可能因特性限制被截断。但使用固定旋转会以可靠（尽管不便）的方式定向。所有旋转从特性原点开始包含性地生成，具有以下方向：

旋转	x 投影	z 投影	俯视顺时针旋转角度
`"east"`	正	负	270°
`"south"`	正	正	0°
`"west"`	负	正	90°
`"north"`	负	负	180°

因此，若7×6的特性从原点(64, 64)生成，东向旋转将占据横向区域(64, 58)到(70, 65)。

WARNING

由于旋转处理方式，结构特性通常需要通过加权随机特性和散布代理进行代理以偏移位置。

约束

json

"constraints": {
    "block_intersection": {
        "block_whitelist": [
            "minecraft:sand",
            "minecraft:sandstone",
            "minecraft:stone"
        ]
    },
    "unburied": {},
    "grounded": {}
}

结构特性可通过必需的"constraints"属性强制执行约束，限制方块交叉、调整放置位置并用空气清除特性上方空间。虽然该属性及其对象（{}）是必需的，但所有子属性均为可选。

方块交叉

json

"block_intersection": {
    "block_whitelist": [
        "minecraft:end_stone"
    ]
},

结构可替换的方块集合由方块白名单指定，通过"block_whitelist"给出。若结构尝试占据的体积中有任意方块不在白名单中，结构将不会在该位置放置。若未提供方块交叉约束，则结构可替换所有方块。

注意

奇怪的是，"block_whitelist"属性也可用"block_allowlist"表示，两者功能相同。

地面附着

json

"grounded": {}

可选的"grounded"组件确保结构底部不会悬空于空气、水或熔岩中。考虑结构底层所有非结构虚空、非空气方块；若任意此类方块下方为空气、水或熔岩，生成将失败。

顶部 clearance

json

"unburied": {}

"unburied"组件确保结构顶部暴露于空气中才能成功生成。仅考虑结构顶层非结构虚空、非空气方块，且所有此类方块上方必须暴露于空气。

注意

与地面附着不同，不考虑水的暴露。

放置调整

json

"adjustment_radius": 4

为适应可能的严格约束，提供可选的"adjustment_radius"属性；接受0（默认）到16的值。放置时，Minecraft会从输入位置开始，在横向向外径向搜索此属性指定的方块数；不尝试垂直调整。检查每个对应体积的有效性；考虑方块交叉、地面附着和[顶部 clearance](#顶部 clearance)。使用第一个成功的（若存在）。

TIP

若需使用垂直调整，应通过搜索特性代理结构特性。

生长植物特性

json

{
    "format_version": "1.13.0",
    "minecraft:growing_plant_feature": {
        "description": {
            "identifier": "wiki:bulbous_cerulon"
        },
        "body_blocks": [
            ["wiki:bulbous_cerulon_stem", 1],
            ["wiki:bulbous_cerulon_spiked_stem", 1]
        ],
        "head_blocks": [
            ["wiki:bulbous_cerulon_bulb", 1],
            ["wiki:bulbous_cerulon_bulb_exposed", 1]
        ],
        "age": { "range_min": 1, "range_max": 15 },
        "growth_direction": "up",
        "height_distribution": [[{ "range_min": 4, "range_max": 12 }, 1]]
    }
}

生长植物特性放置由末端带有头部方块的体部方块组成的列。两者均可按方块随机化以实现精细定制。

TIP

对于高级柱状生成，使用散布特性配合固定网格分布。

柱状方块

json

"body_blocks" : [
    ["arctica:ice", 4],
    ["arctica:ice_crystallized", 1]
],
"head_blocks" : [
    ["arctica:growing_ice", 1]
],
"age": 3

生长植物分为体部方块（构成大部分特性）和头部方块（仅作为植物最后生成的方块）。两者均作为方块条目数组给出。每个方块条目是将方块引用与整数权重绑定的数组：

json

["crestfallen:fungi_stem", 2]

体部和头部的每个方块均独立选择。无法使用生长植物特性使所有体部方块相同。

可选的"age"属性用于设置头部方块的年龄方块状态。接受两种形式：整数和范围对象。使用范围对象时，年龄在每次特性实例时均匀随机选择给定整数边界之间的值。

整数形式：

json

"age": 12

范围对象：

json

"age": {"range_min": 4, "range_max": 8}

WARNING

当前年龄配置仅适用于洞穴藤蔓。

柱状生成

json

"growth_direction": "down",
"height_distribution":  [
    [{"range_min": 8, "range_max": 12}, 4],
    [{"range_min": 4, "range_max": 8}, 2],
    [2, 1]
],
"allow_water": true

柱状从特性原点沿"growth_direction"属性指定的垂直方向生成，接受"up"或"down"。

生长植物特性的_最大_可能长度由"height_distribution"数组给出。与之前的方块声明类似，高度分布中的每个条目是将高度与权重绑定的高度条目。高度可作为固定整数或范围对象给出。

整数形式：

json

[6, 3]

范围对象：

json

[{ "range_min": 2, "range_max": 8 }, 1]

根据权重从高度分布中选择一个条目，若提供范围，则在给定限制之间均匀随机选择值。

生长植物特性从输入位置开始沿正确方向向上或向下进行。默认仅替换生成列中的空气。若非始于空气，柱状生成从沿正确方向的第一个可用空气方块开始。因非空气方块阻挡而错过的方块机会不会重新尝试。这意味着若特性原点必须穿过两个非空气方块才能到达空气，高度将减少2。

到达（或始于）空气后，柱状生成体部方块直至遇到非空气方块，此时永久停止柱状生成。当然，从特性原点开始遍历确定高度时也会停止柱状生成。无论如何，列的最后一个方块将是头部方块，即使列最终高度仅为1个

贡献者

编辑特性类型

特性类型

内容特性 ​

单方块特性 ​

条件限制 ​

固有方块条件 ​

替换条件 ​

附着条件 ​

矿石特性 ​

替换规则 ​

结构模板特性 ​

旋转 ​

约束 ​

方块交叉 ​

地面附着 ​

顶部 clearance ​

放置调整 ​

生长植物特性 ​

柱状方块 ​

柱状生成 ​

贡献者

内容特性

单方块特性

条件限制

固有方块条件

替换条件

附着条件

矿石特性

替换规则

结构模板特性

旋转

约束

方块交叉

地面附着

顶部 clearance

放置调整

生长植物特性

柱状方块

柱状生成