教程:制作附加包/地物/地物文件

概述

地物（features）文件存放于行为包的 features 文件夹下，用于定义某个地物的生成结构。

地物文件可以单独存在，也可由多个子地物文件组合而成。事实上，在Minecraft中，大多数地物都是由多个子地物链式组合而成的（如带有蜂巢的树是由树的地物文件与生成蜂巢的地物文件组合而成）。

添加地物

开发者可在行为包的 features 文件夹下新建 json 文件用于储存单个地物，游戏引擎在加载地物配置时，会默认强制将单个 json 文件识别为一个地物配置。

所有的地物都应当在 format_version 字段内指定对应的版本，开发者需为每个地物定义一个形如 namespace:identifier 的标识符，其中 namespace 为其命名空间，用于鉴别该地物归属于哪个行为包，命名空间的缺失会导致游戏报错，同时可能出现未知的错误；identifier 为该地物的名称。同时，地物文件名称必须与其ID相同（不含命名空间）

Json结构

地物文件的json结构如下

{
  "format_version": "1.13.0", //适配的游戏版本，最低为1.13.0
  "<预制的地物配置类型>": {
    "description": {
      "identifier": <自定义地物的标识符>
    },
    //...其他属性
  }
}

官方为开发者提供了如下9种不同类型的地物配置：

minecraft:single_block_feature

单方块地物（Single Block Feature）用于在特定位置生成单个方块。

成功条件：方块被成功放置

失败条件：方块放置失败

数据结构

属性名称	变量类型	描述
minecraft:single_block_feature	对象	单方块地物 属性名称 变量类型 描述 description 对象  属性名称 变量类型 描述 identifier 字符串  该地物的标识符，形如："namespace:feature_name" places_block 字符串  放置的方块ID enforce_placement_rules 布尔值 （可选）是否强制执行放置规则判定 enforce_survivability_rules 布尔值 （可选）是否强制执行存留规则判定 may_attach_to 数组 （可选）定义可依附的方块清单 属性名称 变量类型 描述 min_sides_must_attach 整型 （可选）需附着有方块的面数最小值（1-4） auto_rotate 布尔值 （可选）附着时是否自动旋转，智能调节方向 top 数组 （可选）顶部可依附的方块清单 bottom   数组 （可选）底部可依附的方块清单 west   数组 （可选）西向可依附的方块清单 east   数组 （可选）东向可依附的方块清单 south   数组 （可选）南向可依附的方块清单 north   数组 （可选）北向可依附的方块清单 当此属性省略时，被放置的方块可依附于任意方块。 may_replace 数组 （可选）定义可覆盖的方块清单。 当此属性省略时，被放置的方块将可覆盖任意方块。

范例

放置单个南瓜方块

{
  "format_version": "1.13.0",
  "minecraft:single_block_feature": {
    "description": {
      "identifier": "example:single_pumpkin_feature"
    },
    "places_block": "minecraft:pumpkin",
    "enforce_placement_rules": true,
    "enforce_survivability_rules": true,
    "may_place_on": [
      "minecraft:grass"
    ],
    "may_replace": [
      "minecraft:air"
    ]
  }
}

minecraft:ore_feature

矿石地物（Ore Feature）用于生成脉状方块群以模拟矿藏。尽管其名称为“矿石地物”，但实际上，任何方块都可以作为此地物的组成方块。

成功条件：至少一个方块被成功放置

失败条件：所有方块都放置失败

数据结构

属性名称	变量类型	描述
minecraft:ore_feature	对象	矿石地物 属性名称 变量类型 描述 description 对象  属性名称 变量类型 描述 identifier 字符串  该地物的标识符，形如："namespace:feature_name" places_block 字符串  矿石的方块ID count 整型  矿脉大小 may_replace 数组  （可选）矿物生成时可能覆盖的方块清单。当此属性省略时，矿石将可覆盖任意方块。

范例

沙子与安山岩中的油藏

{
  "format_version": "1.13.0",
  "minecraft:ore_feature": {
    "description": {
      "identifier": "example:oil_deposit_feature"
    },
    "places_block": "example:oil_block",
    "count": 12,
    "may_replace": [
      "minecraft:sand",
      {
        "name": "minecraft:stone",
        "states": {
          "stone_type": "andesite"
        }
      }
     ]
  }
}

minecraft:structure_template_feature

结构模板地物（Structure Template Feature）可用于放置以 .mcstructure为后缀的结构。结构文件可由结构方块导出得到，放置于行为包的 structures 文件夹下；引用来自其他包的结构文件也是可行的。

成功条件：结构被成功放置

失败条件：结构放置失败

数据结构

属性名称	变量类型	描述
minecraft:structure_template_feature	对象	结构模板地物 属性名称 变量类型 描述 description 对象  属性名称 变量类型 描述 identifier 字符串  该地物的标识符，形如："namespace:feature_name" structure_name 字符串  被放置结构的名称 adjustment_radius 整型  搜索有效位置时允许的偏移量。设定范围为0-16。搜索是径向的，在找到最近的有效位置时停止。默认值为 0 facing_direction 数组  结构放置时的朝向。可设置的值有："north"（北）, "south"（南）, "east"（东）, "west"（西）, "random"（随机）。默认值为"random"。 constraints 对象  放置此结构时必须满足的特定约束。 属性名称 变量类型 描述 grounded 对象 要求结构在地面上。 unburied 对象 要求结构上方有空气 block_intersection 对象 要求结构仅允许与列出的方块相交。 属性名称 变量类型 描述 block_allowlist/block_whitelist 数组  允许与结构相交的方块清单。

范例

放置一个“漂浮”于空气中的热气球结构

{
  "format_version": "1.13.0",
  "minecraft:structure_template_feature": {
    "description": {
      "identifier": "example:hot_air_balloon_feature"
    },
    "structure_name": "example:hot_air_balloon",
    "adjustment_radius": 8,
    "facing_direction": "random",
    "constraints": {
      "unburied": {},
      "block_intersection": {
        "block_allowlist": [
          "minecraft:air"
        ]
      }
    }
  }
}

minecraft:aggregate_feature

聚合地物（Aggregate Feature）用于以任意顺序放置一个地物集合，集合中所有子地物的输入坐标都相同。由于无法保证所有地物一定都能被放置，其子地物不应互相依赖。

成功条件：至少一个地物被成功放置

失败条件：所有地物都放置失败

数据结构

属性名称	变量类型	描述
minecraft:aggregate_feature	对象	聚合地物 description 对象  属性名称 变量类型 描述 identifier 字符串  该地物的标识符，形如："namespace:feature_name" features 数组  储存了所有待放置地物的标识符

范例

在神殿周围散布多种不同植物

{
  "format_version": "1.13.0",
  "minecraft:aggregate_feature": {
    "description": {
      "identifier": "example:monument_with_flowers_feature"
    },
    "features": [
      "monument_feature",
      "scatter_white_flowers_feature",
      "scatter_yellow_flower_feature"
    ]
  }
}

minecraft:sequence_feature

序列地物（Sequence Feature）用于按顺序放置多个地物，这里的顺序取决于它们在数组中的先后。放置过程中，上一个地物的输出位置为下一个地物的输入位置，例如：一颗树被放置于 (0, 0, 0) ，并且该地物最后一个方块被放置于 (0, 10, 0) ，则序列中的下一个地物的输入坐标为 (0, 10, 0) 。

成功条件：序列中所有地物被成功放置

失败条件：序列中任一地物放置失败。后续未被放置的地物将会被跳过。

数据结构

属性名称	变量类型	描述
minecraft:sequence_feature	对象	序列地物 description 对象  属性名称 变量类型 描述 identifier 字符串  该地物的标识符，形如："namespace:feature_name" features 数组  储存了所有被放置地物的标识符

范例

在树冠上散布水果

{
  "format_version": "1.13.0",
  "minecraft:sequence_feature": {
    "description": {
      "identifier": "example:oak_tree_then_apples_feature"
    },
    "features": [
      "oak_tree_feature",
      "scatter_apples_feature"
    ]
  }
}

minecraft:scatter_feature

分散地物（Scatter Feature）可通过设置地物生成位置相对输入位置的偏移量和地物的生成概率来实现将地物分散到区块中的效果。

成功条件：至少放置成功了一个地物。

失败条件：未能成功放置任何地物。

数据结构

属性名称	变量类型	描述
minecraft:scatter_feature	对象	分散地物 description 对象  属性名称 变量类型 描述 identifier 字符串  该地物的标识符，形如："namespace:feature_name" places_feature 字符串 被放置地物的ID名称 project_input_to_floor 布尔值 （可选）若为 true，则放置地物时的 y 值会被设定为地形高度图计算值；若为 false ，则放置地物时的 y 值不变。默认值为 false 。 iterations molang 应当执行多少次放置行为。 scatter_chance molang/对象 （可选）决定了所有放置行为发生的概率。在执行放置行为前调用此判定，若判定失败，则所有放置行为都不会执行。若为对象，则数据结构如下： 属性名称 变量类型 描述 numerator 整型 分子。最小值为 1。 denominator 整型 分母。最小值为 1。 coordinate_eval_order 字符串 （可选）决定了计算坐标的顺序。可设置的值有："xyz", "xzy", "yxz", "yzx", "zxy", "zyx"。应当在一个坐标依赖于另一个坐标时设置此属性。默认值为"xzy"。 属性名称 x y z molang；对象 （可选）坐标的表达式。若为对象，则数据结构如下： 属性名称 变量类型 描述 distribution 字符串 分布类型。可设置的值有："uniform"（均匀随机分布）, "gaussian"（高斯分布）, "inverse_gaussian"（逆高斯分布）, "fixed_grid"（固定步长的网格分布）, "jittered_grid"（抖动的网格分布）。其中（逆）高斯分布均以设定的范围为中心。 step_size 整型 （可选）设定分布类型为网格时轴向的分布步长，最小值为 1。 grid_offset 整型 （可选）设定分布类型为网格时轴向的偏移量，最小值为 0。 extent 数组  数组索引 变量类型 描述 0 molang   地物放置位置相对于输入位置的偏移量下限（含此值） 1 molang   地物放置位置相对于输入位置的偏移量上限（含此值）

范例

在海平面上散布花朵

{
  "format_version": "1.13.0",
  "minecraft:scatter_feature": {
    "description": {
      "identifier": "example:scatter_flowers_feature"
    },
    "places_feature": "example:flower_feature",
    "iterations": 10,
    "scatter_chance": 50.0,
    "x": {
      "distribution": "uniform",
      "extent": [ 0, 15 ]
    },
    "y": 64,
    "z": {
      "distribution": "uniform",
      "extent": [ 0, 15 ]
    }
  }
}

minecraft:search_feature

搜寻地物（Search Feature）可为指定的地物在指定范围内遍历搜寻一个有效的放置位置。搜寻地物会遵从 "search_axis" 属性所设定的轴向顺序在 "search_volume" 所设定的范围内进行遍历搜寻。例如，当 "search_axis" 值为 "-x" ，"search_volume" 在[0, 0, 0]与[5, 5, 5]之间时，该地物将会从x轴坐标值较大的位置开始沿x轴坐标值减小的方向遍历搜寻，即从x=5的层级开始搜寻，当搜寻范围内所有符合x=5的位置都检测完毕后，它才会开始检测所有符合x=4的搜寻范围内的位置，以此类推，直至搜寻范围内所有位置都被检测完毕。其余轴向条件下同理。

成功条件：有效的放置位置数与 "required_successes" 指定的数量相等。

失败条件：有效的放置位置数少于 "required_successes" 指定的数量。

数据结构

属性名称	变量类型	描述
minecraft:search_feature	对象	搜寻地物 属性名称 变量类型  描述 description 对象  属性名称 变量类型 描述 identifier 字符串  该地物的标识符，形如："namespace:feature_name" places_feature 字符串 被放置地物的ID名称 search_volume 对象 地物放置位置的搜寻范围。通过相对输入位置的偏移量表示。 属性名称 变量类型 描述 min 数组 x、y、z三个轴向的最小偏移量。数据结构如下： 数组索引 变量类型 描述 0 整型 x轴方向最小偏移量 1 整型 y轴方向最小偏移量 2 整型 z轴方向最小偏移量 max 数组 x、y、z三个轴向的最大偏移量。数据结构如下： 数组索引 变量类型 描述 0 整型 x轴方向最大偏移量 1 整型 y轴方向最大偏移量 2 整型 z轴方向最大偏移量 search_axis 字符串  遍历搜索所沿的轴向。可设置的值如下表： 枚举值 描述 "-x" 沿x轴坐标减小方向 "+x" 沿x轴坐标增加方向 "-y" 沿y轴坐标减小方向 "+y" 沿y轴坐标增加方向 "-z" 沿z轴坐标减小方向 "+z" 沿z轴坐标增加方向 required_successes 整型  （可选）要求的有效放置位置数，最小值为 1。

范例

将苹果附着到树上

{
  "format_version": "1.13.0",
  "minecraft:search_feature": {
    "description": {
      "identifier": "example:find_valid_apples_feature"
    },
    "places_feature": "example:apple_feature",
    "search_volume": {
      "min": [ -3, -3, -3 ],
      "max": [ 3, 3, 3 ]
    },
    "search_axis": "-y",
    "required_successes": 3
}

minecraft:weighted_random_feature

加权随机地物（Weighted Random Feature）可根据权重随机选择并放置地物。每个地物的权重等于其权重值占所有地物权重值总和的百分比，权重越高，该地物被放置的可能性就越大。

成功条件：选中的地物成功被放置。

失败条件：未能成功选中的地物。

数据结构

属性名称	变量类型	描述
description	对象	属性名称 变量类型 描述 identifier 字符串  该地物的标识符，形如："namespace:feature_name"
features	数组	储存了所有[地物标识，权重]数组，其子元素数据结构如下： 数组索引 变量类型 描述 0 字符串 地物的标识符 1 整型 该地物的权重值

范例

选择并放置花的变种

{
  "format_version": "1.13.0",
  "minecraft:weighted_random_feature": {
    "description": {
      "identifier": "example:select_flower_feature"
    },
    "features": [
      [ "example:white_flower_feature", 1 ],
      [ "example:red_flower_feature", 2 ],
      [ "example:blue_flower_feature", 1 ],
      [ "example:yellow_flower_feature", 4 ]
    ]
  }
}

方块指定

在地物中可通过如下两种数据结构来指定方块

变量类型	描述
字符串	方块ID
对象	属性名称 变量类型 描述 name 字符串  方块ID states 对象 方块数据类型

你知道吗

• 自1.16版本开始mojang才强制要求开发者必须为每个地物文件的名称定义命名空间，在此之前无需定义命名空间。
• 地物文件必须依赖地物规则文件才能在游戏中发挥效用。