📄 Template System

Introduction

The plugin boasts an exceptionally high degree of customization, but it's impossible to configure it without providing any settings. Even a very brief option requires a line in your YAML file. With numerous such options, a configuration file can become excessively long. Therefore, the plugin has introduced a template system, allowing you to define a base template and use parameters and overrides to fill in or overwrite certain parameters, significantly simplifying the process and reducing the time spent on repetitive configurations.

How it works?

To configure a template, you need to use templates as the root key in your YAML file. The first thing under templates is your template's name. In the example below, the template is called namespace:my_first_template. Everything under that name is the actual template content.

templates:
  namespace:my_first_template:
    option_1: true
    option_2: false
    option_3: 
      - hello
    option_4: 20.25
    option_5:
      hello: world

Check out this quick animation to see how the plugin applies the template:

info

namespace:template_id serves as the unique identifier for your template. This name must be used whenever referencing or invoking this template elsewhere.

tip

The configuration area under namespace:template_id is entirely customizable, as long as it adheres to YAML syntax. You have complete freedom to define it according to your needs.

Multiple Templates

You can combine multiple templates by setting up the template as a list.

items:
  craftengine:custom_item:
     template:
       - namespace:my_first_template
       - namespace:my_second_template

warning

Heads up: If two templates have the same setting, the one below will overwrite the one above. But if the setting is a list, they’ll merge into one combined list instead.

Arguments

You can define parameters in template using ${xxx}, like ${nutrition} or ${saturation}. Then, when calling the template, use the arguments section to set the parameter values. Here's a quick example:

templates:
  craftengine:apple_template:
    material: apple
    data:
      food:
        nutrition: "${nutrition}"
        saturation: "${saturation}"
items:
  craftengine:custom_apple:
    template: craftengine:apple_template
    arguments:
      nutrition: 1
      saturation: 2.5

info

If you need to use curly braces {} as normal text (not as parameters), just escape them with a backslash like \{ or \}.

\${Hello world}

tip

To set default values for parameters, add :- after the parameter name - for example:

• ${nutrition:-1}
• ${saturation:-2.5d}
• ${map:-{aa:bb,cc:ddd}}
• ${string:-"1234"}

The default values follow Minecraft's SNBT format (the same format used when specifying NBT data in commands).

Overrides

Overrides completely replace whatever's in the specified config path—including lists and maps. No merging, just a full swap.

items:
  craftengine:custom_bread:
    template: craftengine:apple_template
    arguments:
      nutrition: 1
      saturation: 2.5
    overrides:
      material: bread

Merges

Merges deeply combines two config sections, including all lists - nothing gets left behind. Basically, merges function almost exactly like multiple templates.

items:
  craftengine:custom_bread:
    template: craftengine:apple_template
    arguments:
      nutrition: 1
      saturation: 2.5
    merges:
      data:
        food:
          can-always-eat: true

Tips

tip

You can use parameters within configuration keys despite the feature being rarely needed.

templates:
  craftengine:example:
    "${argument}": value

You can also use parameters within template lists, overrides, and merges.

templates:
  default:settings/ore:
    template:
      - default:sound/stone
      - default:pickaxe_power/level_${break_power}
    overrides:
      push-reaction: NORMAL
      is-redstone-conductor: true
      is-suffocating: true
      instrument: BASEDRUM
      can-occlude: true
      map-color: ${map_color}
      tags:
        - minecraft:mineable/pickaxe
    merges:
      hardness: ${hardness}
      resistance: 3.0