Data Generators

Jump to navigation Jump to search

Data Generators are a tool added in 1.13 that can export reports about various parts of the game, and additionally are used internally by Mojang to generate various json files.

Command line

The main entry point for data generators is instead of net.minecraft.client.main.Main or net.minecraft.server.MinecraftServer. This is present on both the client and the server, but since the server includes all needed libraries to run it while the client has them in separate jars, it is much easier to use the server. Since this isn't the main class, the game must be ran using a different command line than normal:

java -cp minecraft_server.jar

Starting in 1.18, this command is used instead due to the server jar bundling libraries instead of merging them into a single file:

java -jar minecraft_server.jar

There are several arguments:

Show the help menu (same as running with no arguments)
Specify an input folder for the converters. Can be specified multiple times, as in --input folder1 --input folder2.
Output folder (defaults to generated)
Specifies which generators to run; see the table below.
Same as --client --dev --reports --server.


There are several different generators, which are controlled via the arguments above.

Name --client --dev --reports --server
SNBT -> NBT Yes No No Yes
Fluid Tags No No No Yes
Block Tags No No No Yes
Item Tags No No No Yes
Recipes No No No Yes
Advancements No No No Yes
NBT to SNBT No Yes No No
Block List No No Yes No
Item List No No Yes No
Command List No No Yes No

Blocks report

A report that contains all block states in the block state registry. Notably, this contains numeric IDs as used on the protocol, so it can be used to get the proper IDs for a version. The report is saved in reports/blocks.json.

A few sample entries:

  "minecraft:air": {
    "states": [
        "id": 0,
        "default": true
  "minecraft:oak_sapling": {
    "properties": {
      "stage": [
    "states": [
        "properties": {
          "stage": "0"
        "id": 21,
        "default": true
        "properties": {
          "stage": "1"
        "id": 22

The key of the object is the block ID. Within it, the properties tag contains all properties within the state, where the key within that is the property name and the value is an array of allowed property values. This tag will not be present if there are no properties. The states tag is a list of different states for the block. Within each state, the properties tag maps each property to the value on that state (which, again, will not be present if there are no properties); the id tag gives the numeric state ID (as used over the network); and the default tag indicates if the state is the default one for the block (there should be only one such state).

This report does not contain numeric block IDs, only state IDs. Block IDs only remain in use on the Block Action packet; they can be inferred by the position in the report.

Warning.png Due to MC-131740, the blocks report will delete its results if run twice in the same location. (This was fixed in 18w50a)

Items report

Warning.png Replaced in 18w50a with the registries report

The items report contains a list of all items, and their network IDs.

  "minecraft:air": {
    "protocol_id": 0
  "minecraft:stone": {
    "protocol_id": 1

Note that item IDs are no longer related to block IDs or block state IDs. They all start out in the same sequence, but some blocks do not have items and items do not include block states (by design).

Warning.png Due to MC-131740, the items report will delete its results if run twice in the same location.

Registries report

Warning.png Added in 18w50a

Contains IDs from all registries, including block and item IDs.

  "minecraft:sound_event": {
    "protocol_id": 0,
    "entries": {
      "minecraft:ambient.cave": {
        "protocol_id": 0
      "minecraft:ambient.underwater.enter": {
        "protocol_id": 1
  "minecraft:fluid": {
    "default": "minecraft:empty",
    "protocol_id": 1,
    "entries": {
      "minecraft:empty": {
        "protocol_id": 0
      "minecraft:flowing_water": {
        "protocol_id": 1
  "minecraft:mob_effect": {
    "protocol_id": 2,
    "entries": {
      "minecraft:speed": {
        "protocol_id": 1
      "minecraft:slowness": {
        "protocol_id": 2

The key within the root object is the registry's own ID, and the protocol_id there is the ID for the registry over the network (is this used?). default indicates a default value to be used when one is needed or an unknown value is used. entries is the actual content of the registry; keys in it are the name of the element and protocol_id is the actual relevant ID.

The different registries (ordered by their protocol ID):

Name Meaning
minecraft:sound_event Sounds and their numeric IDs, for the sound effect packet.
minecraft:fluid Fluids.
minecraft:mob_effect Actual potion effects. Includes effects such as nausea, absorption, and saturation that don't have actual potions associated with them.
minecraft:block Blocks. Note that the block ID is only used in a few places and is separate from the block state ID.
minecraft:enchantment Enchantments.
minecraft:entity_type Entities.
minecraft:item Items.
minecraft:potion IDs for potion items. Note that these have "long" and "strong" variants, as would be seen on brewing.
minecraft:biome Biome IDs.
minecraft:particle_type Particle effect IDs.
minecraft:block_entity_type Block/tile entity IDs.
minecraft:dimension_type Overworld/Nether/End.
minecraft:motive Painting images.
minecraft:custom_stat Stats that are not associated directly with using a block or item.
minecraft:chunk_status States a chunk can be in during generation.
minecraft:structure_feature Various generated structures.
minecraft:structure_piece IDs for components of structures themselves; see Generated structures data file format (possibly outdated). These IDs are extremely terse; as an example "nesclt" means something like "nether fortress small corridor left turn.
minecraft:menu Different inventory windows.
minecraft:recipe_type Not used for anything over the network or in recipe JSON files. Internally indicates the device with which a recipe can be used. For instance, minecraft:crafting.
minecraft:recipe_serializer Indicates the format of a recipe when serialized to JSON or over the network; also controls the actual behavior. For instance, minecraft:crafting_shaped and minecraft:crafting_shapeless.
minecraft:attribute Attributes for mobs and players.
minecraft:stat_type Statistics category.
minecraft:villager_type Villager types, i.e. the type/biome of the village they came from.
minecraft:villager_profession Professions used by villagers.

Commands report

This report contains the Command Graph. The format matches information described in that article, except that name is the key for an object, and suggestions are not present in the report.

Warning.png Due to MC-131740, the commands report will delete its results if run twice in the same location. (This was fixed in 18w50a)

NBT converters

There are two NBT-related data generators. One converts "SNBT" (stringified NBT - the same NBT format used in commands) to NBT; the other converts NBT into SNBT. Both look for files of the appropriate extension (.nbt or .snbt) in the input folder(s), and output them at the same relative location in the output folder.

Warning.png Due to MC-131740, the NBT to SNBT converter will delete its results if run twice in the same location.

Tag providers

The tag providers are used to create tag JSON files based off of data stored in code. As such, they aren't directly useful to people who are not writing mods. They can be used by subclassing, overriding the appropriate methods, and changing the data within.

Advancement provider

The advancement provider is used to generate advancement JSON files based off of data stored in code. It works off of nested consumers, where one layer of consumers contains the actual data (split between the different advancement categories), and that consumer takes a consumer that is actually responsible for saving the advancement. It can be used by subclassing only.

Recipes provider

The recipe JSON file creates recipes based on data in code. It can't be used directly.