Features and feature rules

Everything that decorates the land is a feature: ore veins, trees, flowers, grass, boulders, springs, coral. If it is not the basic terrain and not a mob, it is probably a feature.

To get a feature into the world you need two files:

• A feature says what to place: a vein of ore, a tree, a single block.
• A feature rule says where and how often: which biomes, how many times per chunk, at what height.

In this guide you will make ruby ore appear underground in every overworld biome.

The files

BP/
  blocks/
    ruby_ore.json
  features/
    ruby_ore_feature.json
  feature_rules/
    ruby_ore_rule.json

Step 1: the ore block

You need a block to place first. Make a normal custom block called wiki:ruby_ore with a texture and a loot table. If you have not made a block yet, follow Your first custom block.

Step 2: the feature

{
  "format_version": "1.13.0",
  "minecraft:ore_feature": {
    "description": {
      "identifier": "wiki:ruby_ore_feature"
    },
    "count": 6,
    "replace_rules": [
      {
        "places_block": "wiki:ruby_ore",
        "may_replace": [
          "minecraft:stone",
          "minecraft:granite",
          "minecraft:diorite",
          "minecraft:andesite"
        ]
      }
    ]
  }
}

• The root key, here minecraft:ore_feature, is the feature type. Each file has exactly one. The table at the bottom of this page lists them all.
• count is how many blocks one vein tries to place. Diamonds use small veins, coal uses big ones.
• replace_rules says which block goes where. The ore only replaces blocks listed in may_replace, so it never floats in caves or eats through dirt.

Naming rules

• One feature per file.
• The file name must match the name part of the identifier. wiki:ruby_ore_feature goes in ruby_ore_feature.json. The namespace is not part of the match.
• If two packs use the exact same identifier, the pack higher in the list wins. That is how you can replace a vanilla feature.

Step 3: the feature rule

A feature does nothing until a feature rule attaches it to biomes:

{
  "format_version": "1.13.0",
  "minecraft:feature_rules": {
    "description": {
      "identifier": "wiki:ruby_ore_rule",
      "places_feature": "wiki:ruby_ore_feature"
    },
    "conditions": {
      "placement_pass": "underground_pass",
      "minecraft:biome_filter": [
        {
          "test": "has_biome_tag",
          "operator": "==",
          "value": "overworld"
        }
      ]
    },
    "distribution": {
      "iterations": 4,
      "coordinate_eval_order": "zyx",
      "x": {
        "distribution": "uniform",
        "extent": [0, 16]
      },
      "y": {
        "distribution": "triangle",
        "extent": [-48, 16]
      },
      "z": {
        "distribution": "uniform",
        "extent": [0, 16]
      }
    }
  }
}

The rule has three parts.

description

• identifier names the rule. Like features, the name part must match the file name.
• places_feature is the feature this rule places. One rule controls one feature.

conditions

minecraft:biome_filter picks the biomes. It is a list of filter tests, and the one you will use almost every time is has_biome_tag. Every biome checks the filter: the ones that pass get the feature.

You can combine tests with all_of and any_of. This one picks warm overworld biomes that are not oceans:

"minecraft:biome_filter": [
  { "test": "has_biome_tag", "operator": "==", "value": "overworld" },
  {
    "any_of": [
      { "test": "has_biome_tag", "operator": "==", "value": "desert" },
      { "test": "has_biome_tag", "operator": "==", "value": "mesa" }
    ]
  },
  { "test": "has_biome_tag", "operator": "!=", "value": "ocean" }
]

To put ruby ore only in the Ruby Grove, test for its own tag: "value": "ruby_grove".

placement_pass says when the feature is placed compared to others. Passes run in this order:

Features in the same pass have no fixed order between them.

distribution

This decides how many copies try to generate in each chunk and where.

For a feature rule, x and z count from the corner of the chunk, so [0, 16] covers the whole chunk. y is the world height.

Each range has a distribution type that shapes where values land:

For things on the ground, like plants, set y with Molang so it lands on the surface:

"y": "query.heightmap(variable.worldx, variable.worldz)"

Testing

1. Turn the pack on in a new world.
2. Go into spectator mode with /gamemode spectator and fly underground near Y 0.
3. Look for the ruby texture in the stone. Too rare? Raise iterations or count.

If nothing appears, open the Content Log. The usual causes are a file name that does not match the identifier, a wrong places_feature name, or a block name typo in places_block.

Every feature type

Each feature file uses exactly one of these as its root key. Some place blocks, others only choose between, move or repeat other features. Most vanilla decorations chain several together: for example a scatter feature that runs a search feature that runs a tree.

Next steps

• Make a home for your ore: The biome file.
• Look up biome tags to filter on: minecraft:tags.