教學:製作附加包/地物/地物檔案

概述

地物（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才強制要求開發人員必須為每個地物檔案的名稱定義命名空間，在此之前無需定義命名空間。
• 地物檔案必須依賴地物規則檔案才能在遊戲中發揮效用。