Tutorial

This tutorial will guide you through creating a simple generator that generates a set of files.

You are recommended to read the Beginner's Guide first to understand the basic concepts of the generator.

You can try playground to create and test your generator easily, while reading this tutorial first is recommended.

1. Resource or Data?

First, you need to know whether you want to generate resource pack files or datapack files.

• Resource pack files are things like textures, models, blockstates, lang files, etc.
• Datapack files are things like recipes, loot tables, advancements, functions, etc.

If you are going to generate resource pack files, you need to create the generator under a file-pack provided by a resource pack handler. Croparia IF provide a resource pack handler croparia:resourcepack with file-pack located at ${game}/croparia/resourcepack by default.

If you are going to generate datapack files, you need to create the generator under a file-pack provided by a datapack handler. Croparia IF provide a datapack handler croparia:datapack with file-pack located at ${game}/croparia/datapack by default.

When decided, you need to create a file with sub-fix .toml(recommended), .cdg or .json under the generators folder under the path mentioned above. See details about the file types in the Generator File Types section.

2. Specify Some Fields

You need to specify some fields in the generator file so that pack handler knows what to do.

Now you need to be clear about the form of your generated files, which determines the type of the generator you are going to create.

i. Independent File

If you are going to generate unique files for each entry in a registry, for example, you want to create a shapeless crafting recipes that convert each crop fruit to the corresponding material item, you need to use croparia:generator.

Toml Example: Convert Crop Fruit to Material

# This is a default value, so you can omit it if you want.
type = "croparia:generator"
# Whether this generator is enabled, you can disable it to skip the generation.
# This is a default value, so you can omit it if you want.
enabled = true
# Whether to run this generator every time the pack is loaded, including the game startup.
# If you want to access the tag system, you need to set this to false.
# This is a default value, so you can omit it if you want.
startup = false
# Registry to get entries from, you can use any registry in the game, or a custom registry provided by a mod.
# "croparia:crops" means this generator will generate files for each crop in Croparia IF.
registry = "croparia:crops"
# Path relative to the root of the pack handler's file-pack to place the generated files.
path = "croparia/recipe/crafting/material/${id.namespace}/${id.path}.json"
# Template for the generated file.
template = """
{
  "type": "minecraft:crafting_shapeless",
  "ingredients": [
    "${fruit}"
  ],
  "result": {
    "id": "${result.id}",
    "count": ${result.amount},
    "components": ${result.components}
  }
}
"""

ii. Aggregated File

If the files you are going to generate are not independent, for example, you want to generate an item tag that contains all the crop seeds, you need to use croparia:aggregated.

Toml Example: Item Tag for All Crop Seeds

# The following fields are similar to the previous example.
type = "croparia:aggregated"
registry = "croparia:crops"
path = "croparia/tags/item/crop_seeds.json"

# This is the template of the unique content row for each entry.
# The final content of the generated file will be constructed by putting all the content rows together.
# The final content will not have indent, so you need to add indent spaces if necessary.
# The final content will have a comma and \n between each content row, so you don't need to add comma at the end of the content row.
content = '    "${seed}"'
# This is the template for the whole generated file.
# Note that you do not have access to the fields in the entry here, you can only use ${content} that represents the final content constructed by all the content rows.
template = """
{
  "replace": false,
  "values": [
${content}
  ]
}
"""

iii. Language File

If you want to generate a language file that contains translations for each entry in a registry, you need to use croparia:lang.

Note A: Language generator only support the entries that is translatable. For example, croparia:crops registry is translatable, but croparia:element registry is not.

Note B: You can use language generator for both resource pack handler and datapack handler, even though language files have no effect in datapack handler.

Toml Example: Language File for Crops

# The following fields are similar to the previous examples.
type = "croparia:lang"
registry = "croparia:crops"
startup = true

# You may use ${lang} to specify the language code. This is an additional placeholder field provided by language generator.
# You can generate multiple language files by specifying multiple languages separated by comma.
path = "${id.namespace}/lang/${lang}.json"
# This is the template for each translation entry.
# If you specify "_lang" in the placeholder, it will be replaced with the language code before the placeholder is handled with the entry.
template = '"${translation_key}": "${translations._lang}"'

3. Use Placeholders

You can use placeholders in some of the fields like path and template to replace them with values from the entry. They are defined based on the entries in the registry you specified.

For example, one of the entries in the croparia:crops registry contains information like:

For understanding only, actual implementation is more complicated

{
  "id": "croparia:coal",
  "fruit": "croparia:fruit_coal",
  "result": {
    "id": "minecraft:coal",
    "amount": 2,
    "components": []
  },
  // Other fields...
}

You can use JS style ${field.subField} to access the fields in the entry. For example, ${fruit} will be replaced with croparia:coal_fruit, and ${result.id} will be replaced with minecraft:coal.

If you are not using croparia:crops registry, you need to check the entries in the registry you are using to know what fields are available.

Refer to the Placeholder & Registry documentation for more details.

Besides, based on the type of generator you are using, there may be some additional placeholder fields available. We have talked about some of them (${lang} and _lang) in the previous sections.

4. Done!

That's it! You have created a generator that generates files based on the entries in a registry.

To make it work, you can reload the resource pack or datapack in the game, or restart the game.

In the end, let's see what you have created.

i. Independent File Example

The example of the independent generator means, for each crop as entry in the croparia:crops registry, it will generate a shapeless crafting recipe that converts the fruit of the crop to the material defined in the crop.

Taking the coal crop, it will generate a file at ${game}/croparia/datapack/data/croparia/recipe/crafting/material/croparia/coal.json in the datapack file-pack with the following content:

{
  "type": "minecraft:crafting_shapeless",
  "ingredients": [
    "croparia:fruit_coal"
  ],
  "result": {
    "id": "minecraft:coal",
    "count": 2,
    "components": {}
  }
}

ii. Aggregated File Example

The example of the aggregated generator means, it will generate an item tag that contains all the seeds of the crops in the croparia:crops registry.

It will generate a file at ${game}/croparia/datapack/data/croparia/tags/item/crop_seeds.json in the datapack file-pack with the following content:

{
  "replace": false,
  "values": [
    "croparia:seed_coal",
    "croparia:seed_iron",
    "croparia:seed_gold",
    "croparia:seed_diamond",
    "croparia:seed_emerald",
    "croparia:seed_lapis",
    "croparia:seed_redstone",
    "croparia:seed_quartz",
    "croparia:seed_copper",
    "croparia:seed_tin",
    "croparia:seed_silver",
    "croparia:seed_lead",
    "croparia:seed_nickel",
    "croparia:seed_aluminum",
    "croparia:seed_uranium",
    "croparia:seed_ruby",
    "croparia:seed_sapphire",
    "croparia:seed_peridot"
    // And so on...
  ]
}

iii. Language File Example

The example of the language generator means, it will generate language files that contains translations for all the crops in the croparia:crops registry.

It will generate files under ${game}/croparia/resourcepack/croparia/lang in the resource pack file-pack.

Taking en_us as an example, it will generate a file ${game}/croparia/resourcepack/croparia/lang/en_us.json with the following content:

en_us.json

{
  "item.minecraft.coal": "Coal",
  "item.croparia.iron_ingot": "Iron",
  "item.croparia.gold_ingot": "Gold",
  // And so on...
}

There would be more language files if a crop is specified with more translations.

Playground

Navigate to Generator Creator to create the generator easily. Note that you still need to test it in the game to ensure it works as expected.