Foreground items#

This section describes all kinds of the “foreground” items that you can put into your templates. The foreground items are the objects that define the images pasted on top of the background of the image. They are the building blocks of the templates.

You can learn more about the structure of the template files in the Templates article.

Syntax:

{
    "item_type": "image",
    // The rest of the properties depend on the type of the foreground item
}

Every foreground item has the “item_type” property. This property defines what kind of item it is. The specific types of the foreground items are described below.

Image Foreground Item#

The purpose of the image foreground item is to paste an image on top of the background image. You can use the image items to compose more complex images from smaller images.

Syntax:

{
    "item_type": "image",
    "image": "example_image.png",
    "offset": [165, 230],
    "size": [70, 70]
}

image#

The image property defines the path to the image file. The path is relative to the images folder (either the images of the project or from the data repository).

The image property can use variables. You can read more about the variables in the Using variables article.

offset#

The offset property defines where to paste the image. It’s a vector of the UV coordinates (in pixels) of the base image starting from the top left corner.

size#

This property defines the size of the image. It’s optional and if it’s not provided, the size of the pasted image will be the same as the size of the original image.

If the source image has a different aspect ratio than the ratio defined in the size property, it will be resized to fit inside the bounding box defined by the size and offset properties without stretching it.

Text Foreground Item#

The text foreground item is used to add text to your generated images.

Syntax:

{
    "item_type": "text",
    "text": "Example",
    "offset": [25, 15],
    "scale": 20,
    "color": [148, 116, 90, 255],
    "font": "plexi 1.2.ttf",
    "spacing": 1.0,
    "anti_alias": false,
    "line_length": 80,
    "alignment": "left",
    "anchor": "la"
}

Note that a lot of the text foreground item properties are optional and you can omit them to use the default values.

text#

The text property defines the content of the text to be added to the image. It can be a string or a list of strings. If the text is a list, the items of that list will be separated with new lines.

The text property can use variables. You can read more about the variables in the Using variables article.

offset#

The offset property defines where to paste the image. It’s a vector of the UV coordinates (in pixels) of the base image starting from the top left corner.

scale#

The scale property defines the size of the font. The default value is 12.

color#

The color the color of the text in RGBA fromat. The default value is white [255, 255, 255, 255].

font#

This is the path to the font file relative to the fonts folder.

spacing#

Spacing defines the amount of space between the lines. The default value is 1.0. It accepts any float value.

anti_alias#

It defines if the text should be anti-aliased. The default value is false.

line_length#

Line length is an optional property that limits the number of characters in a line. By default it’s undefined and the layout manager doesn’t do any wrapping on it’s own.

alignment#

Defines text alignment. The default value is “left”. The accepted values are “left:, “right” and “center”.

anchor#

The anchor property is an advanced feature that defines the anchor type of the text. The value of this property is passed directly to the Python’s Pillow library.

You can read more about the text-anchors in the Pillow documentation:

https://pillow.readthedocs.io/en/stable/handbook/text-anchors.html

The default anchor is “la” (left-ascender), this is the most common value.

If you need to center the text, you can use the “ma” (middle-ascender) anchor. The

The difference between the alignment and anchor is that the alignment defines the alignemnt of the lines of multi-line text in relation to one another while the anchor defines the position of the text box.

Recipe Shaped Foreground Item#

The recipe_shaped foreground item is used to add a shaped or shapeless crafting recipe to the image. It adds any recipe that can be crafted in the crafting table.

{
    "item_type": "recipe_shaped",
    "background": "crafting_full_background.png",
    "offset": [25, 107],
    "recipe_pattern": ".+",
    "items": {
        "0,0": {"size": [16, 16], "offset": [2, 2]},
        "1,0": {"size": [16, 16], "offset": [2, 20]},
        "2,0": {"size": [16, 16], "offset": [2, 38]},
        "0,1": {"size": [16, 16], "offset": [20, 2]},
        "1,1": {"size": [16, 16], "offset": [20, 20]},
        "2,1": {"size": [16, 16], "offset": [20, 38]},
        "0,2": {"size": [16, 16], "offset": [38, 2]},
        "1,2": {"size": [16, 16], "offset": [38, 20]},
        "2,2": {"size": [16, 16], "offset": [38, 38]},
        "result": {"size": [16, 16], "offset":[96, 21]}
    }
}

background#

The background image of the recipe works like the main background. It defines the size of the recipe image unless you provide the size property. The recipe images can also be scaled using the scale property.

offset#

The offset property defines where to paste the image. It’s a vector of the UV coordinates (in pixels) of the base image starting from the top left corner.

recipe_pattern#

The recipe_pattern property is a regex pattern matched against recipe identifiers to determine if they’re suitable for this foreground item.

You can read about the regular expresssions here:

https://en.wikipedia.org/wiki/Regular_expression

For basic usage, you can use the .+ pattern which matches any recipe. If you want to match only specific recipe names you can list them and separate them with a pipe | character. For example, if you want to match only the minecraft:stone and minecraft:stone_slab recipes, you can use the following pattern: minecraft:stone|minecraft:stone_slab.

items#

The items dictionary that define the position and size of the items. All of the keys are optional. For example you can define a recipe_shaped object that only shows the result item or only the input items.

The keys with the numbers define the items in the crafting grid where "0,0" is the top left corner and "2,2" is the bottom right corner. The "result" key defines the position of the result item.

Recipe Furnace Foreground Item#

The recipe_furnace foreground item is used to add a furnace recipe to the generated image.

{
    "background": "furnace_full_background.png",
    "item_type": "recipe_furnace",
    "offset": [25, 178],
    "recipe_pattern": ".+",
    "items": {
        "input": {"size": [16, 16], "offset":[20, 2]},
        "output": {"size": [16, 16], "offset":[96, 21]}
    }
}

Furnace recipe uses the same properties as the recipe_shaped except that the “items” dictionary has a “input” and “output” keys.

Recipe Brewing Foreground Item#

The recipe_brewing foreground item is used to add a brewing recipe to the generated image.

{
    "background": "brewing_full_background.png",
  "item_type": "recipe_brewing",
  "offset": [0, 0],
  "recipe_pattern": ".+",
  "items": {
      "reagent": {"size": [16, 16], "offset": [53, 3]},
      "input": {"size": [16, 16], "offset": [53, 37]},
      "output": {"size": [16, 16], "offset": [100, 20]}
  }
}

Brewing recipe uses the same properties as the recipe_shaped except that the “items” dictionary has a “reagent”, “input” and “output” keys.

Recipe Any Foreground Item#

Recipe any is a combination of all of the other recipe types. This foreground item requires 3 separate recipe types to be defined in it to cover all the possible cases - shaped, brewing and furnace.

{
    "item_type": "recipe_any",
    "recipe_pattern": ".+",
    "recipe_shaped": {
        "background": "crafting_full_background.png",
        "offset": [25, 249],
        "items": {
            "0,0": {"size": [16, 16], "offset": [2, 2]},
            "1,0": {"size": [16, 16], "offset": [2, 20]},
            "2,0": {"size": [16, 16], "offset": [2, 38]},
            "0,1": {"size": [16, 16], "offset": [20, 2]},
            "1,1": {"size": [16, 16], "offset": [20, 20]},
            "2,1": {"size": [16, 16], "offset": [20, 38]},
            "0,2": {"size": [16, 16], "offset": [38, 2]},
            "1,2": {"size": [16, 16], "offset": [38, 20]},
            "2,2": {"size": [16, 16], "offset": [38, 38]},
            "result": {"size": [16, 16], "offset":[96, 21]}
        }
    },
    "recipe_furnace": {
        "background": "furnace_full_background.png",
        "offset": [0, 0],
        "items": {
            "input": {"size": [16, 16], "offset":[20, 2]},
            "output": {"size": [16, 16], "offset":[96, 21]}
        }
    },
    "recipe_brewing": {
      "background": "brewing_full_background.png",
      "offset": [0, 0],
      "items": {
        "reagent": {"size": [16, 16], "offset": [53, 3]},
        "input": {"size": [16, 16], "offset": [53, 37]},
        "output": {"size": [16, 16], "offset": [100, 20]}
      }
    }
}

recipe_shaped#

The recipe_shaped property is a dictionary that defines the properties of the shaped recipe. It uses the same properties as the recipe_shaped foreground item.

The only exception is that the recipe_pattern property is on the outer level of the recipe_any item.

recipe_furnace#

The recipe_furnace property is a dictionary that defines the properties of the furnace recipe. It uses the same properties as the recipe_furnace foreground item.

The only exception is that the recipe_pattern property is on the outer level of the recipe_any item.

recipe_brewing#

The recipe_brewing property is a dictionary that defines the properties of the brewing recipe. It uses the same properties as the recipe_brewing foreground item.

The only exception is that the recipe_pattern property is on the outer level of the recipe_any item.

Foreground items

Contents

Foreground items#

Image Foreground Item#

image#

offset#

size#

Text Foreground Item#

text#

offset#

scale#

color#

font#

spacing#

anti_alias#

line_length#

alignment#

anchor#

Recipe Shaped Foreground Item#

background#

offset#

recipe_pattern#

items#

Recipe Furnace Foreground Item#

Recipe Brewing Foreground Item#

Recipe Any Foreground Item#

recipe_shaped#

recipe_furnace#

recipe_brewing#